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
- Set base permissions for the organization to
Read
orNone
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)
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_ID
s and AWS_SECRET_ACCESS_KEY
s manually.
-
Create a S3 bucket - this is where Terraform states for the organizations will be stored
-
Create a DynamoDB table using
LockID
of typeString
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_ID
s andAWS_SECRET_ACCESS_KEY
s - 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
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
- 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 theApp ID
-
RO_GITHUB_APP_ID
-
RW_GITHUB_APP_ID
-
- Go to
https://github.com/organizations/$GITHUB_ORGANIZATION_NAME/settings/installations
, clickConfigure
next to the$GITHUB_APP_NAME
and copy the numeric suffix from the URL-
RO_GITHUB_APP_INSTALLATION_ID
(orRO_GITHUB_APP_INSTALLATION_ID_$GITHUB_ORGANIZATION_NAME
for organizations other than the repository owner) -
RW_GITHUB_APP_INSTALLATION_ID
(orRW_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
, clickGenerate 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
-
- Go to
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
ingithub
to the name of the GitHub organization
- Rename the
- Push the changes to
$GITHUB_MGMT_REPOSITORY_DEFAULT_BRANCH
- Follow How to synchronize GitHub Management with GitHub? to commit the terraform lock and initialize terraform state
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
- Set read repository contents permissions for
- 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
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