request-marketplace-action/README.md

request-marketplace-action

Background

In GitHub Enterprise Server you can allow access to marketplace actions by configuring GitHub Connect. However, controlling which actions can be used comes at a huge administrative cost, as you would need to configure each org to allow the actions you approve of. Sometimes org admins are not the appropriate people to decide what actions are allowed or not. You may want to control allowed action for the entire enterprise, which can be done through the Enterprise Settings>Policies>Actions. However, there is no API to automate updating this setting, and there is no way to stage actions and allow admins to evaluate them before approval for wider use within your enterprise. The same issue exists for managing access to marketplace actions in GitHub Enterprise Cloud. In these cases, you want to host the requested marketplace actions in an org within your enterprise as private repos, allowing admins to evaluate the actions prior to making them available within your enterprise. Upon approval, the visibility of the repo changes so that the action is available to users within your enterprise.

This project provides two actions workflows to help manage the process of requesting marketplace actions and approving or denying such requests: Initialize Marketplace Action Request and Approve or Deny Marketplace Action Request

Workflows

Initialize Marketplace Action Request is triggered when a user opens an issue requesting a specific marketplace action. The marketplace actions is "staged" as a private repo in your org where you intend to host the approved actions. Within this private repo, admins can review the marketplace action code and determine if it is appropriate for use within your enterprise. Actions are disabled on the newly created repo to prevent possible privilege escalation through self-hosted runners.

Approve or Deny Marketplace Action Request is triggered when a user comments on an issue. If the user commenting is a member of the approver's team, and the comment includes the word "approve", then the visibility of the repo created by the previous workflow is changed from "private" to "internal" (GHEC EMU and GHES >= 3.5, for GHES < 3.5 repos become "public" on approval) and the issue is closed. If the user commenting is a member of the approvers team, and the comment includes the word "deny", then the repo create by the previous workflow is put in "archive" mode and remains "private".

Requesting a marketplace action

To request a marketplace action, open an issue in this repo. Include in your issue, the following markdown...

    ```json request
    {
        "owner": "hashicorp-contrib",
        "repo": "setup-packer",
        "version": "latest"
    }
    ```

The example above refers to the repo https://github.com/hashicorp-contrib/setup-packer. The value of the version field needs to either match exactly a release in the repo, or be latest. The value of latest will cause the workflow to find the latest release available currently.
See examples.md for more examples.

Prerequisites

1. GitHub Enterprise Server v3.x or GitHub Enterprise Managed Users (EMU) Account on GitHub.com.
2. You must have enabled GitHub Actions for GitHub Enterprise Server.
3. You have an org created where you intend to host your approved actions. Let's call it actions-approved for now.
4. You have an org created where you intend to host the repos that will run these workflow. Let's call it admin-ops for now.
5. You have a team created within the admin-ops org. Members of this team will be able to approve or deny requests for marketplace actions. Let's call it actions-approvers for now.
6. You need runners available to the repo or org where you intend to run these workflows. Currently, the workflows are configured to use self-hosted runners.

Setup

1. Configure this repo with an actions secret named TOKEN with the value of a PAT that has admin:org, repo, and workflow scope on your GHEC server.
2. Configure this repo with the following actions repository variables, and note their values below so they are known to all who use this repo.
   ADMIN_OPS_ORG: admin-ops
   ACTIONS_APPROVED_ORG: actions-approved
   ACTIONS_APPROVERS_TEAM: actions-approvers
3. Configure the Enterprise Actions Policies to allow select actions. Allow specified actions as follows:
   • peter-murray/issue-body-parser-action@v1 (required by these workflows)

Installing these workflows into another repo

You may already have requests for marketplace actions occurring in another repo, and want to simply use these workflows in that repo.

1. Make sure the prerequisutes above are met.
2. Follow the setup instructions above on the repo you intent to use.
3. Move the contents of this repo's .github directory into the .github directory of the repo you intend to use. Be careful not to clobber any existing files in the .github repo!

Troubleshooting

When specifying the details of the actions repo you are requesting, if the release name and the tag name of the release in that repo do not match, you will need to use the tag name for the version. When specifying the version as latest the assumption is that the release name and the tag name of the release match. If this is not the case, you will need to specify the tag name as the vesion rather than using latest.