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). Ensure to include
govuk_platform_supporttag. - 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
govuktopic - has Dependency Review, CodeQL and Snyk scans in its CI pipeline
- 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.
You’ll then need to plan and apply the GitHub workspace in Terraform Cloud:
- This updates the collaborators to the default teams and access levels.
- If your repository access is sensitive, it should be tagged with the
govuk-sensitive-accesstopic to avoid this automation: you would then need to manually manage its collaborators.
- If your repository access is sensitive, it should be tagged with the
- It also gives permissions to push to the ECR registry, to repositories that have the
containertopic.
Finally, you should run the “Configure GitHub” action in govuk-saas-config. This:
- Applies branch protection rules and configures PRs to be blocked on the outcome of the GitHub Action CI workflow (if one exists)
- Restricts 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)
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.