Home
GitHub

Last updated: 7 Dec 2023

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
has Dependency Review and CodeQL 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-access topic to avoid this automation: you would then need to manually manage its collaborators.
It also gives permissions to push to the ECR registry, to repositories that have the container topic.

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.

GitHub