IssueOps for creating GitHub repositories

Motivation

Many enterprises struggle around repository creation, balancing best practices with developer experience:

• How visible should this be?
• Is access being only being granted to teams?
• Are branch protection rules in place?
• Is it clear who owns the repository?
• Can we satisfy regulatory requirements around controls?

For enterprises that cannot allow developers to create repositories directly, the following solution walks through a possible solution built around native GitHub functionality to provide a transparent, auditable, and minimal process to facilitate repository creation needs.

Overview

Like many internal GitHub processes, this solution is built leveraging issue forms and actions to facilitate requests for repository creation.

Upon filling out the issue form, a team of people can review and approve requests without having to be organization owners.

For faster response time, leverage Slack or Microsoft Teams integrations to notify responsible party when issues are created.

Benefits

1. Self-documenting process
2. Auditable as issues and comments are preserved in 1 place
3. Capable of notifying relevant parties in a timely manner
4. Leverages GitHub App for necessary elevated permissions
5. Assign people to review and approve from a designated team, no organization owner access needed

Prerequisites

1. GitHub issue forms access
2. Ability to setup one of supported mechanisms for escalated privileges:
   1. Enterprise Personal Access Token (PAT) (require enterprise owner access)
   2. GitHub App (requires organization owner access)

Setup

Step 1: Authentication setup

Choose one of the following based on your situation, both are equally valuable and supported

Option 1: GitHub App for organization-wide usage

The GitHub App route of gaining elevated access to an organization is that it is not tied to a user and does not cost a user license. The downside is that GitHub Apps are organization specific, so this approach can only managed the 1 organization.

1. Create new GitHub App with the following:

   • Homepage URL: URL of repository containing workflow and issue forms
   • Webhooks: disable
   • Repository permissions:
     • administration (read and write)
     • issues (read and write)
   • Organization permissions:
     • members (read-only)

2. Generate private key

   Note: we will need this and the App ID shortly in setting up GitHub Action secrets

3. Install newly created GitHub App into the organization

4. Create the following repository secrets:

   1. APP_ID: using the App ID from the General > About section of the GitHub App
   2. APP_PEM: using the downloaded private key from the General > Private keys section of the GitHub App

Option 2: Enterprise Personal Access Token (PAT) for enterprise-wide usage

The Enterprise PAT route of gaining elevated access to an organization is that it can manage multiple organization across an enterprise. The downside is that it is tied to a user account, which should be a machine user to avoid disturbances when people are offboarded.

1. Generate personal access token under the machine user account with the following permissions:

   • repo
   • read:org

2. Create the following repository secrets:

   1. ISSUEOPS_TOKEN: using personal access token of the machine user account

Step 2: Organization teams for review and approval

1. Create and populate organization teams with individuals for various roles:

   • lgtm: individuals who can approve requests
   • lgtm-reviewers: nested team of lgtm of individuals who will be assigned to review and approve requests

   

Step 3: GitHub Action workflow setup

1. Create repository containing the following issue labels:

   • administration
   • createrepo

2. Create .github directory containing issue forms and workflows from assets directory

   └── .github
       ├── ISSUE_TEMPLATE
       │   └── createrepo.yml
       └── workflows
           ├── createrepo_assign.yml
           ├── createrepo_fulfill.yml
           └── createrepo_validate.yml
   

3. Update the list of organizations in repository-owner field within .github/ISSUE_TEMPLATE/createrepo.yml:

   - type: dropdown
      id: repository-owner
      attributes:
         label: Repository owner
         description: Select an owner
         options:
         - tinyfists
         - visibilitysaurus

   Note For multiple organizations, an Enterprise PAT is required. Otherwise, limit this to the organization where GitHub App is installed.

4. Update the inputs for andyfeller/issueops-createrepo action(s) within the workflows based on your authentication setup:

   • Option 1: GitHub App for organization-wide usage

           - name: Assign
             uses: andyfeller/issueops-createrepo/assign@v1
             with:
               authentication: app
               application-id: ${{ secrets.APP_ID }}
               application-private-key: ${{ secrets.APP_PEM }}
               team-assign: ${{ env.LGTM_TEAM }}

   • Option 2: Enterprise Personal Access Token (PAT) for enterprise-wide usage

           - name: Assign
             uses: andyfeller/issueops-createrepo/assign@v1
             with:
               authentication: token
               github-token: ${{ secrets.ISSUEOPS_TOKEN }}
               team-assign: ${{ env.LGTM_TEAM }}

Alterations and Workarounds

Customizing approver and reviewer team names

You can choose different names by modifying the LGTM_TEAM value in respective workflows:

• .github/workflows/createrepo_assign.yml:

  name: Create Repo - Assign
  on:
     issues:
        types:
        - opened
  env:
     LGTM_TEAM: lgtm-reviewers

• .github/workflows/createrepo_fulfill.yml:

  name: Create Repo - Fulfill
  on:
     issue_comment:
        types:
        - created
  env:
     LGTM_TEAM: lgtm

• .github/workflows/createrepo_validate.yml:

  name: Create Repo - Validate
  on:
     issues:
        types:
        - opened
        - edited
  env:
     LGTM_TEAM: lgtm

Using issue template if issue forms are unavailable

For private repositories where GitHub issue forms are not available yet, GitHub issue templates are an alternative that can be parsed by zentered/issue-forms-body-parser.

---
name: Create Repo
description: Request creation of GitHub repository
title: "[Create Repo]: "
labels: administration, create_repo
---
### Repository name

<!-- Required.  Great repository names are short and memorable. -->

### Repository description

<!-- Optional.  Repository description -->

### Repository visibility

<!--
   Required.  Repository visibility including:

   Public
      Anyone on the internet can see this repository. You choose who can commit.

   Internal
      Enterprise members can see this repository. You choose who can commit.

   Private
      You choose who can see and commit to this repository.
-->

### Repository access

<!--
   Required.  Comma-separated list of teams and permissions to grant including:

   Read
      Can read and clone this repository. Can also open and comment on issues and pull requests.

   Triage
      Can read and clone this repository. Can also manage issues and pull requests.

   Write
      Can read, clone, and push to this repository.  Can also manage issues and pull requests.

   Maintain
      Can read, clone, and push to this repository.  They can also manage issues, pull requests, and some repository settings.

   Admin
      Can read, clone, and push to this repository.  Can also manage issues, pull requests, and repository settings including adding collaborators.

   Custom
      Name of custom repository role; permissions vary

   Examples:
      @org/teamslug,read
      @org/teamslug,triage
      @org/teamslug,write
      @org/teamslug,maintain
      @org/teamslug,admin
-->