GitHub
GOV.UK uses GitHub for version control, code deployments, authentication, CI, Dependabot and GitHub Pages. Read the “GOV.UK reliance on GitHub features doc” Google doc for more information.
GitHub organisation
Our GitHub organisation is called alphagov. We (GOV.UK) share it with other teams in the Government Digital Service (GDS).
The organisation is on the Enterprise Cloud plan, which grants us access to GitHub’s enterprise support. Only people with enterprise permissions can access enterprise support (limited to enterprise owners and up to 20 additional members).
GDS GitHub Owners have superadmin access to alphagov. You can contact them to request changes to organisation settings, or to request access to an inaccessible repository (e.g. one that was created by an ex-employee).
GOV.UK teams
There are several GOV.UK GitHub teams within alphagov, including:
GOV.UK. Grants write access to GOV.UK repos, as well as integration admin access to the CI environment.
GOV.UK Production Deploy. Grants the ability to merge PRs against continuously deployed apps, and the ability to deploy apps to staging and production
GOV.UK Production Admin. Grants admin access to GOV.UK repos, and admin access to a number of other tools.
GOV.UK Content Designers. This team allows the user to create a branch in a GOV.UK repository and open a pull request, but only a developer can merge the request. Only content designers should be added to this team.
Getting access to GitHub
Not everyone on GOV.UK requires GitHub access, as much of what we do is in the open. However, if your role requires it, you should be added to the org and the relevant team(s) through Terraform, in govuk-user-reviewer - not manually added through the GitHub UI itself, as this breaks the Terraform setup. Note that you will be sent an invitation email and will have to accept the invite before you are added to the organisation.
- If you’re a content designer, ask for GitHub access via Zendesk (see example ticket)
- If you’re an engineer or contractor, ask your tech lead to follow the instructions in govuk-user-reviewer to add you.
- If you don’t have a tech lead, ask someone in Senior Tech to add you. You must state
- your role
- which team you’re in
- your GitHub handle
- which GitHub team(s) you should join (see list)
- why you need access
Removing access to GitHub
Users are removed from the GitHub organisation when their entry in govuk-user-reviewer is deleted.
GOV.UK repos
Create and configure a new GOV.UK repo
When creating a new GOV.UK repo, you must ensure it:
- has a well written README (see READMEs for GOV.UK applications, or the GDS Way guidance for general repositories)
- is tagged with the
govuk“topic” - is added to the repos.yml file in the Developer Docs. We run a daily script to ensure that the Developer Docs’ config is in sync with GitHub.
- In Terraform Cloud start a new run and apply changes to grant access to the following GitHub teams:
- GOV.UK CI Bots: Admin access
- GOV.UK Production Admin: Admin access
- GOV.UK team: Write access
How GOV.UK automates its repository settings
We currently use two tools for this:
- govuk-saas-config. This runs every night and:
- Applies branch protection rules and configures PRs to be blocked on the outcome of the GitHub Action CI workflow (if one exists)
- Retricts the merging of PRs for continuously deployed apps, so that only those with Production Deploy or Production Admin access can merge
- Enables vulnerability alerts and security fixes
- Sets up the webhook for GitHub Trello Poster
- Sets some other default repo settings (e.g. delete branch on merge)
- govuk-infrastructure, which:
- Gives permissions (to push to the ECR registry) to repositories that have specific tags
The fact that we have two tools for managing GitHub resources is recognised as technical debt. The hope is to consolidate the GitHub code from govuk-saas-config into govuk-infrastructure.