Get started developing on GOV.UK

Last updated: 22 Apr 2025

This getting started guide is for new technical staff (for example developers, technical architects) working on GOV.UK in GDS. Please note this guidance is only for the GOV.UK programme of GDS, it is not for Digital Identity, Digital Services Platforms or any other part of GDS.

If you’re having trouble with this guide, you can ask your colleagues on the #govuk-developers Slack channel.

Before you start

You will need to know who your tech lead is, as you will need them for some of these steps.

If you are on a team that does not have a tech lead, or you are the tech lead, please contact the Lead Developer in your area or email GOV.UK senior tech with details on who you are and what team you’ve joined, so that they can help.

You should have been given a GDS “developer build” laptop with full admin access. To find out, try running sudo whoami in your terminal. It should prompt for your local account password and print root if you entered your password correctly.

If you don’t have admin access to your laptop, file a ticket with the IT helpdesk and copy your line manager.

1. Install the Xcode command-line tools

Run the following in your command line to install the Xcode command line tools:

xcode-select --install

2. Install the Homebrew package manager

Run the following in your command line to install the Homebrew package manager:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

This command works for macOS or Linux.

3. Fill out your Slack profile

You should already have access to Slack. If not, please talk with your line manager.

Help others know who you are by updating your Slack profile’s ‘title’ field. This should include:

your job role
the team you’re working on
the name of your organisation, if you’re not directly employed by GDS / Cabinet Office

4. Set up your AWS IAM user account

Request a AWS user account.
You should receive an email when your account is created.
Follow instructions in the email to sign into the gds-users AWS account for the first time.
Enable Multi-factor Authentication (MFA) for your IAM User.

You must specify your email address as the MFA device name.

You should use your Yubikey as your MFA device if you have one.

5. Set up your GitHub account

Log into your existing GitHub account or create a new one.
Add your GDS email address to your GitHub account, which can be in addition to your personal email address.
Generate an SSH key.
Add the SSH key to your GitHub account.
Check that you can access GitHub using the new key:
```
ssh -T git@github.com
```

Add your name and email to your git commits. For example:

git config --global user.email "friendly.giraffe@digital.cabinet-office.gov.uk"
git config --global user.name "Friendly Giraffe"

6. Get permissions for AWS, GitHub and other third party services

Permissions to GOV.UK’s AWS, GitHub, Fastly and Pagerduty accounts are managed by the govuk-user-reviewer private repository. You won’t be able to see this repo until you are added to the alphagov GitHub organisation.

Ask your tech lead to follow the instructions in govuk-user-reviewer to grant you access.

For Sentry, your tech lead should manually add you via the Sentry UI. Once you’ve been added, you can sign in using your GDS Google account.

7. Install and configure the GDS CLI

On GOV.UK we use the gds-cli for AWS access.

You must be a member of the alphagov GitHub org (see previous step) to proceed.

Install GDS CLI:

brew tap alphagov/gds
brew install gds-cli
brew install --cask aws-vault

Run gds --help to check the installation.

If you see fatal: no such path in the working tree, that’s because you’re using ZSH, which has gds set up as a Git alias. To solve this, you can remove that alias by adding unalias gds to your ~/.zshrc:
```
echo unalias gds >>~/.zshrc
```

Configure your email address:

gds config email <FIRSTNAME>.<LASTNAME>@digital.cabinet-office.gov.uk

By default, GDS CLI will use a Yubikey as the MFA device. If you don’t have a Yubikey you must disable this:
```
gds config yubikey false
```

Set up AWS credentials:

Create an AWS access key via the console.
Run any gds aws command to start the first-time setup process:
```
gds aws govuk-integration-readonly -l
```
Enter your Access Key ID and Secret Access Key when prompted.
Enter your AWS MFA token when prompted.
When prompted, save credentials to your Mac’s keychain as aws-vault and set a password for the keychain. Save that password somewhere safe, for example in a password manager.

For example:

Welcome to the GDS CLI! We will now store your AWS credentials in the keychain using aws-vault.
Enter Access Key ID: <YOUR-ACCESS-KEY-ID>
Enter Secret Access Key: <YOUR-SECRET-ACCESS-KEY>
Added credentials to profile "gds-users" in vault
Successfully initialised gds-cli
Enter token for arn:aws:iam::123456789012:mfa/firstname.lastname@digital.cabinet-office.gov.uk: 123456

You can now use gds aws to run AWS CLI commands by prefixing them with gds aws <role>. You can use -- to avoid ambiguity between gds options and options for the wrapped command. For example:

gds aws govuk-integration-readonly -- aws s3 ls

8. Connect to the GDS VPN

This step might not be necessary if you are a contractor. Ask your tech lead.

If you’re outside of the office or on GovWiFi, you must connect to the GDS VPN to use some internal Cabinet Office services (e.g. SOP and the intranet).

For GDS issued MacBooks

Follow the GDS guidance on how to sign into the GDS VPN using Google credentials.

For Bring Your Own Devices (BYOD)

Follow the VPN guide for Bring Your Own Devices (BYOD)

9. Set up GOV.UK Docker

We use a Docker environment for local development, GOV.UK Docker.

To set up GOV.UK Docker, see the installation instructions in the govuk-docker GitHub repo.

If you are a frontend developer, you may be able to use alternative approaches to local development if you prefer to avoid GOV.UK Docker.

10. Set up tools to use the GOV.UK Kubernetes clusters

Follow the instructions for getting started with the GOV.UK Kubernetes clusters.

11. Get Signon accounts

Signon controls access to the GOV.UK Publishing applications.

Ask your tech lead for:

a ‘Superadmin’ privileged account in integration Signon
a ‘Normal’ account in production Signon with access to the ‘Release’ app only and no other apps

Production Signon accounts are copied automatically to the staging environment overnight, so you will have access to staging the next day.

12. Get familiar with the Release app

Release is the application we use to track deployments, work out which branch/tag is deployed to each environment.

Your tech lead will have granted access to the Release app in the step above.

13. Talk to your tech lead about supporting services you should have access to

Depending on your role and the team you’ve joined, you will likely need access to some other services. Your tech lead will know which ones you will need and can arrange access. For example:

Logit for reading application logs and request logs. New developers typically need access to logs for the integration environment.
Zendesk for working with user support tickets.
Google Analytics for analysing trends in user behaviour. Most new developers won’t need this at first.

Supporting information

Now you have completed the get started process, you should look at the following supporting information:

the architectural deep dive of GOV.UK
GOV.UK’s conventions for Rails applications