Configure a new GOV.UK repository

Last updated: 19 Dec 2025

Create a new repository

If you are creating a new rails app, there are tailored instructions to follow.

Otherwise these are the general steps to create when creating a new GOV.UK repository:

First create and configure it by following the “Creating and configuring a new repository” guidance in govuk-infrastructure repo.
- Note that when adding an existing repository (created in the GitHub UI) you will need to import it into terraform state.
Make a well-written README (see READMEs for GOV.UK applications, or the GDS Way guidance for general repositories)
Add a licence following Licensing Guidelines

Set up a GitHub repository for your App

All GitHub repositories belonging to GOV.UK must be created and managed by Terraform.

If you have a pre-existing Git repository that is not managed by Terraform, it is possible to import the repository to into Terraform so that it can be managed. To do that you’ll need to add an entry to terraform/deployments/github/import.tf in govuk-infrastructure with an entry similar to:

import {
  to = github_repository.govuk_repos["content-modelling-e2e"]
  id = "content-modelling-e2e"
}

If this file doesn’t exist, you’ll need to create it. See example commit.

Alternatively, you can push the commit from your existing repository to the new repository using Git:

cd existing-repository/
git checkout main
git remote add new-repo "git@github.com:alphagov/new-repo.git"
git push new-repo main

To reset your local repository to point to the new remote repository in alphagov, you’ll need to check out the new repository afresh and delete the original.

Run terraform to create your repository

The general instructions for creating a repository via terraform can be found here.

The key steps are:

Open a PR to add a new entry to the repos.yml file in govuk-infrastructure. This is where key metadata is defined, including any workflow jobs that must pass in order to merge/deploy.

For example, an entry for a new Ruby on Rails application using reusable workflows could be:

new-application:
   can_be_deployed: true
   required_pull_request_reviews:
     require_code_owner_reviews: true
   required_status_checks:
     standard_contexts: *standard_govuk_rails_checks
     additional_contexts:
       - Lint JavaScript / Run Standardx
       - Lint SCSS / Run Stylelint
       - Test JavaScript / Run Jasmine
       - Test Ruby / Run RSpec

[!IMPORTANT] The workflow names must match the names of the workflows in the ci.yml file inside your app. For example, if you have a testing workflow named Test Ruby / Run RSpec, that must exactly match the app workflow or that step won’t run.

contact #govuk-platform-engineering for a review and, after the changes have been merged, to run Terraform.

The repository will be created and populated with required permissions and secrets.

Add security scans to the CI pipeline

The following are mandatory for all repositories:

Rails apps also require:

Brakeman
- See Example

Add repository to GOV.UK Developer Docs

Add it to the repos.yml file in the GOV.UK Developer Docs

Managing Deployment Access

GOV.UK no longer relies on the use of Github “topic” tags as a way to select and configure Deployment access, to prevent the following situations:

Accidentally (or intentionally) granting Repositories access to deployment credentials.
Removing the Github Search API as a “SPoF” (Single Point of Failure) for configuration errors.

By “rationalising” our Repository configuration, we are reducing our reliance on “magic” or poorly-understood processes and thus reducing risk. Instead, granting access to things like Deployment secrets should always be done explicitly through our govuk-infrastructure repository.