Skip to main content
Last updated: 29 Nov 2021

Get started on GOV.UK

This getting started guide is for new technical staff (for example developers, technical architects) working on GOV.UK in GDS or CDDO.

Ask your tech lead to take you through the overview slides if they have not already done so.

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

Before you start

You must have a laptop with full admin access. To check if you have full admin access, run a sudo command in your command line. For example, sudo ls.

If you do not have full admin access to your laptop, ask your line manager to ask IT to provide you with a developer build on your laptop.

Once you have full admin access on your laptop, run the following in your command line to install the Xcode command line tool:

xcode-select --install

1. Install the Homebrew package manager

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

/bin/bash -c "$(curl -fsSL"

This command works for macOS or Linux.

2. Set up your GitHub account

  1. Set up a GitHub account. You can use your existing personal account.
  2. Ask your tech lead to add your GitHub username to the user monitoring system and seal.

    If your tech lead is not available, ask in the 2nd line support Slack channel for someone who has production access to add you.

  3. Ask in #govuk-tech-leads for someone to add you to the alphagov organisation and the GOV.UK team to get access to repos & CI.

    Select Accept in the GitHub email invitation when you receive this email. If your tech lead is not available, ask one of the GOV.UK GitHub owners.

  4. Generate a new SSH key for your laptop and add it to the ssh-agent for your GitHub account.

  5. Add the SSH key to your GitHub account.

  6. Add the following code into your .zshrc, ~/.bash_profile, or equivalent so that it is persistent between restarts:

    $ /usr/bin/ssh-add -K <YOUR-PRIVATE-KEY>
  7. Test that the SSH key works by running ssh -T

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

    $ git config --global ""
    $ git config --global "Friendly Giraffe"

3. Install GDS command line tools

On GOV.UK we use the following command-line tools for AWS and SSH access:

  1. To install these command line tools, run the following in the command line:

    brew tap alphagov/gds
    brew install gds-cli govuk-connect

    The GDS CLI repository is private, so you must first set up your GitHub account.

  2. Test that both tools work by running gds --help and gds govuk connect --help.

    If you see a fatal: no such path in the working tree error, that’s because you’re using ZSH, which has gds set up as a Git alias. To solve this, you can either:

    • remove that alias by adding unalias gds to your ~/.zshrc
    • use gds-cli instead of gds for all the relevant commands
  3. Configure the GDS CLI by running:

    gds config email <FIRSTNAME>.<LASTNAME>
  4. Run gds config yubikey false if you use your phone as an Multi-Factor Authentication (MFA) device.

    Run gds config yubikey true if you use a Yubikey.

4. Connect to the GDS VPN

If you’re outside of the office or on GovWiFi, you must connect to the GDS VPN to access to our infrastructure and internal services.

 For GDS issued MacBooks

Follow the Cabinet Office 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)

5. Set up GOV.UK Docker

We use a govuk-docker Docker environment for local development.

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

6. Get SSH access to integration

Get access

Ask your tech lead or GOV.UK 2nd line Support on Slack to add your SSH username (firstnamelastname) to the list of GOV.UK tech users in the user monitoring system.

Create a user to SSH into integration

User accounts in our integration environments are managed in the govuk-puppet repository.

  1. Run the following command to create a govuk folder in your home directory and clone the govuk-puppet GitHub repo:

    mkdir ~/govuk
    cd ~/govuk
    git clone
  2. Run more ~/.ssh/ and copy your outputted SSH public key value.

    The key should begin with ssh-rsa AAA and end with == <GITHUB EMAIL>. You may need to manually add the email address to the end of your key.

  3. Create a user manifest file at ~/govuk/govuk-puppet/modules/users/manifests/<FIRSTNAMELASTNAME>.pp with the following code:

    # Creates the <FIRSTNAMELASTNAME> user
    class users::<FIRSTNAMELASTNAME> {
      govuk_user { '<FIRSTNAMELASTNAME>':
        fullname => 'FIRSTNAME LASTNAME',
        email    => 'WORK EMAIL',
        ssh_key  => '<SSH-PUBLIC-KEY-VALUE>',

    Enter your information and SSH public key value into the file. For example:

    # Creates the johnsmith user
    class users::<johnsmith> {
      govuk_user { '<johnsmith>':
        fullname => 'John Smith',
        email    => '',
        ssh_key  => '<SSH-PUBLIC-KEY-VALUE>',
  4. Add the name of your user manifest file (<FIRSTNAMELASTNAME>.pp) into the list of users::usernames in hieradata_aws/integration.yaml.

  5. Create a pull request with these changes.

    Once the pull request has been reviewed, you can merge it and the pull request will automatically deploy to the integration environment.

    Your tech lead or any other developer with access can review this pull request.

Access remote environments and server

Once your pull request with your user manifest file is merged and deployed, you should test your SSH access to remote environments and servers.

If you are outside of the office or on GovWiFi, you must first connect to the GDS VPN.

Test your SSH access by running:

gds govuk connect --environment integration ssh backend

Running a console

Once you have SSH access into a remote environment or server, you can also open a Rails app console for a particular application so you can run commands.

For example, to open a console for GOV.UK Publisher, run the following on a backend machine:

$ govuk_app_console publisher

As a shortcut, to remove the need to look up the machine class for an application, you can use the following without SSHing first:

gds govuk connect --environment integration app-console publisher

7. Get AWS access

GDS maintains a central account for AWS access.

You must have access to this GDS account to work with govuk-aws and govuk-aws-data.

Request access to the GDS AWS account

You request access to the GDS AWS account through the Request an AWS account form.

Select Request user access to request access to the GDS AWS account and complete the form.

After submitting the form, you should receive an email to say your account creation is in progress, and later another email saying the work has been completed.

Sign in to AWS

To sign in, go to the gds-users AWS console, and enter:

  • gds-users in Account ID or alias
  • your email address in Username
  • your AWS account password in Password

Set up Multi-Factor Authentication

You must set up Multi-Factor Authentication (MFA) to access AWS.

How you set up MFA depends on whether you have a GDS-issued Yubikey or not.

If you have a Yubikey, follow the Reliability Engineering documentation on using YubiKey for 2FA in Amazon Web Services.

If you do not have a Yubikey, use the following instructions to set up your MFA device.

  1. Sign in to the gds-users AWS console.
  2. Select the IAM service.
  3. Select Users in the left hand menu and enter your name.
  4. Select the link for your email address.
  5. Select the Security credentials tab.
  6. Select Manage, which is next to Assigned MFA device.
  7. Follow the instructions to set up your MFA device.

Generate a pair of access keys

You must generate an AWS access key ID and secret access key to be able to perform operations with AWS on the command line.

  1. Sign in to the gds-users AWS console.
  2. Select your email address in the top right of the screen.
  3. Select My Security Credentials.
  4. Select Create access key.
  5. Make a note of your AWS access key ID and secret access key for when you access AWS for the first time.

Get access to integration infrastructure

You must get access to the integration infrastructure so you can deploy to integration.

To get access, you must add your email address to the list of role_user_user_arns users in the govuk-aws-data GitHub repo.

Open a pull request to add the following code to the role_user_user_arns section in the infra-security/integration/common.tfvars file in the govuk-aws-data repo.


Use the same <account-ID> as other entries in the role_user_user_arns section.

See this example pull request for more information.

After your pull request has been merged, someone with production access will need to deploy the infra-security project to integration, by assuming the govuk-integration-admin role. See Deploy Terraform to find out how to deploy infrastructure changes. The stackname is govuk and the project is infra-security.

See the AWS IAM users documentation for more information.

8. Access AWS for the first time

  1. Open the GDS CLI and run gds aws govuk-integration-readonly -l to open the AWS console in your web browser.
  2. In the GDS CLI, enter your AWS access key ID and secret access key.
  3. Enter your MFA token in the command line.

    Here is an example of the output you’ll see:

    $ gds aws govuk-integration-readonly -l
    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/ 123456
  4. 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.

If you have a GDS-issued Yubikey, you can run gds config yubikey true in the GDS CLI to set GDS CLI to automatically pull the MFA code from your Yubikey.

You have completed the get started process.

Reset your AWS vault password

If you forget your aws-vault password, you must reset that password.

  1. Delete the aws-vault keychain by running rm ~/Library/Keychains/aws-vault.keychain-db in the command line.
  2. Re-initialise the gds-cli by opening ~/.gds/config.yml and changing initialised: true to initialised: false.

9. Get a Signon account for integration

Signon is the application used to control access to the GOV.UK Publishing applications.

Ask someone with production access (e.g. your tech lead or buddy) to create an account for the integration Signon, with permission to access the applications that your team are likely to work on.

Supporting information

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