Skip to content

Latest commit

 

History

History
182 lines (152 loc) · 10.5 KB

SETUP.md

File metadata and controls

182 lines (152 loc) · 10.5 KB
Raw

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.

GitHub Organization

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

GitHub Management Sync Flow

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.

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.