SETUP.md

Setup

NOTE: The following TODO list is complete - it contains all the steps you should complete to get GitHub Management up. You might be able to skip some of them if you completed them before.

• Create a repository from the template - this is the place for GitHub Management to live in

GitHub Organization

• Set base permissions for the organization to Read or None not to make all organization members de-facto admins through GitHub Management - gh api -X PATCH /orgs/$GITHUB_ORGANIZATION -f default_repository_permission=read
• If you plan to keep the GitHub Management repository private, allow forking of private repositories and enable workflows for private repository forks - gh api -X PATCH /orgs/$GITHUB_ORGANIZATION -f members_can_fork_private_repositories=true (enabling workflows for private repository forks is not possible through API)

AWS

NOTE: Setting up AWS can be automated with terraform. If you choose to create AWS with terraform, remember that you'll still need to retrieve AWS_ACCESS_KEY_IDs and AWS_SECRET_ACCESS_KEYs manually.

• Create a S3 bucket - this is where Terraform states for the organizations will be stored

• Create a DynamoDB table using LockID of type String as the partition key - this is where Terraform state locks will be stored

• Create 2 IAM policies - they are going to be attached to the users that GitHub Management is going to use to interact with AWS

  Read-only

  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Action": [
          "s3:ListBucket"
        ],
        "Effect": "Allow",
        "Resource": "arn:aws:s3:::$S3_BUCKET_NAME"
      },
      {
        "Action": [
          "s3:GetObject"
        ],
        "Effect": "Allow",
        "Resource": "arn:aws:s3:::$S3_BUCKET_NAME/*"
      },
      {
        "Action": [
          "dynamodb:GetItem"
        ],
        "Effect": "Allow",
        "Resource": "arn:aws:dynamodb:*:*:table/$DYNAMO_DB_TABLE_NAME"
      }
    ]
  }
  

  Read & Write

  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Action": [
          "s3:ListBucket"
        ],
        "Effect": "Allow",
        "Resource": "arn:aws:s3:::$S3_BUCKET_NAME"
      },
      {
        "Action": [
          "s3:PutObject",
          "s3:GetObject",
          "s3:DeleteObject"
        ],
        "Effect": "Allow",
        "Resource": "arn:aws:s3:::$S3_BUCKET_NAME/*"
      },
      {
        "Action": [
          "dynamodb:GetItem",
          "dynamodb:PutItem",
          "dynamodb:DeleteItem"
        ],
        "Effect": "Allow",
        "Resource": "arn:aws:dynamodb:*:*:table/$DYNAMO_DB_TABLE_NAME"
      }
    ]
  }
  

• Create 2 IAM Users and save their AWS_ACCESS_KEY_IDs and AWS_SECRET_ACCESS_KEYs - they are going to be used by GitHub Management to interact with AWS

  • one with read-only policy attached
  • one with read & write policy attached

• Modify terraform/terraform_override.tf to reflect your AWS setup

GitHub App

NOTE: If you already have a GitHub App with required permissions you can skip the app creation step.

• Create 2 GitHub Apps in the GitHub organization with the following permissions - they are going to be used by terraform and GitHub Actions to authenticate with GitHub:

  read-only

  • Repository permissions
    • Administration: Read-only
    • Contents: Read-only
    • Metadata: Read-only
  • Organization permissions
    • Members: Read-only
  read & write

  • Repository permissions
    • Administration: Read & Write
    • Contents: Read & Write
    • Metadata: Read-only
    • Pull requests: Read & Write
    • Workflows: Read & Write
  • Organization permissions
    • Members: Read & Write

• Install the GitHub Apps in the GitHub organization for All repositories

GitHub Repository Secrets

• Create encrypted secrets for the GitHub organization and allow the repository to access them (*replace $GITHUB_ORGANIZATION_NAME with the GitHub organization name) - these secrets are read by the GitHub Action workflows
  • Go to https://github.com/organizations/$GITHUB_ORGANIZATION_NAME/settings/apps/$GITHUB_APP_NAME and copy the App ID
    • RO_GITHUB_APP_ID
    • RW_GITHUB_APP_ID
  • Go to https://github.com/organizations/$GITHUB_ORGANIZATION_NAME/settings/installations, click Configure next to the $GITHUB_APP_NAME and copy the numeric suffix from the URL
    • RO_GITHUB_APP_INSTALLATION_ID (or RO_GITHUB_APP_INSTALLATION_ID_$GITHUB_ORGANIZATION_NAME for organizations other than the repository owner)
    • RW_GITHUB_APP_INSTALLATION_ID (or RW_GITHUB_APP_INSTALLATION_ID_$GITHUB_ORGANIZATION_NAME for organizations other than the repository owner)
  • Go to https://github.com/organizations/$GITHUB_ORGANIZATION_NAME/settings/apps/$GITHUB_APP_NAME, click Generate a private key and copy the contents of the downloaded PEM file
    • RO_GITHUB_APP_PEM_FILE
    • RW_GITHUB_APP_PEM_FILE
  • Use the values generated during AWS setup
    • RO_AWS_ACCESS_KEY_ID
    • RW_AWS_ACCESS_KEY_ID
    • RO_AWS_SECRET_ACCESS_KEY
    • RW_AWS_SECRET_ACCESS_KEY

GitHub Management Repository Setup

NOTE: Advanced users might want to modify the resource types and their arguments/attributes managed by GitHub Management at this stage.

NOTE: You can manage more than one organization from a single GitHub Management repository. To do so create more YAMLs under github directory. Remember to set up secrets for all your organizations.

• Clone the repository
• Replace placeholder strings in the clone - the repository needs to be customised for the specific organization it is supposed to manage
  • Rename the $GITHUB_ORGANIZATION_NAME.yml in github to the name of the GitHub organization
• Push the changes to $GITHUB_MGMT_REPOSITORY_DEFAULT_BRANCH

[!WARNING] Please note that until you synchronize GitHub Management with GitHub for the first time, the workflows that depend on Terraform state, like Fix, Plan or Apply, will fail. This is because the state is not yet initialized.

GitHub Management Sync Flow

• Follow How to synchronize GitHub Management with GitHub? to commit the terraform lock and initialize terraform state

GitHub Management Repository Protections

NOTE: Advanced users might have to skip/adjust this step if they are not managing some of the arguments/attributes mentioned here with GitHub Management.

NOTE: If you want to require PRs to be created but don't care about reviews, then change required_approving_review_count value to 0. It seems for some reason the provider's default is 1 instead of 0. The next Sync will remove this value from the configuration file and will leave an empty object inside required_pull_request_reviews which is the desired state.

NOTE: Branch protection rules are not available for private repositories on Free plan.

• Manually set values that are impossible to control this value via terraform currently
  • Set read repository contents permissions for GITHUB_TOKEN
  • If the repository is public, require approval for all outside collaborators
  • If the repository is private, disable sending write tokens or secrets to worfklows from fork pull requests
• Pull remote changes to the default branch
• Enable required PRs, peer reviews, status checks and branch up-to-date check on the repository by making sure github/$ORGANIZATION_NAME.yml contains the following entry:

  repositories:
    $GITHUB_MGMT_REPOSITORY_NAME:
      branch_protection:
        $GITHUB_MGMT_REPOSITORY_DEFAULT_BRANCH:
          required_pull_request_reviews:
            required_approving_review_count: 1
          required_status_checks:
            contexts:
              - Comment
            strict": true

• Push the changes to a branch other than the default branch

GitHub Management PR Flow

NOTE: Advanced users might have to skip this step if they skipped setting up GitHub Management Repository Protections via GitHub Management.

• Follow How to apply GitHub Management changes to GitHub? to apply protections to the repository