Skip to main content
Last updated: 29 Apr 2021

Get started on GOV.UK

This is the guide for new technical staff working on GOV.UK in GDS. If you just joined, πŸ‘‹ welcome!

If they haven’t done so yet, ask your tech lead to take you through the overview slides.

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

1. Install the Homebrew package manager (on macOS or Linux)

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

2. Set up your GitHub account

  1. Set up a GitHub account. Existing personal accounts are fine to use.
  2. Ask your tech lead to add you to the alphagov organisation. You will have to be added to the GOV.UK team to get access to repos & CI. Remember to click accept in the GitHub email invitation.
  3. Ask somebody with access to add your GitHub username to the user monitoring system.
  4. Generate and register an SSH key pair for your laptop for your GitHub account. You should use a 4096 bit key.
  5. Import the SSH key into your keychain. Once you’ve done this, you’ll be able to clone repos over SSH.

    $ /usr/bin/ssh-add -K your-private-key
  6. Add the above line into your ~/.bash_profile or equivalent so that it is persistent between restarts.

  7. Test that it all works by running ssh -T

  8. While you’re here, associate your name and email to your git commits:

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

3. Install GDS tooling

On GOV.UK we use two command-line tools day-to-day: govuk-connect and the gds-cli for AWS, SSH and VPN access.

To install these, run:

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

The GDS CLI repository is private, so you’ll need to follow the GitHub setup instructions above for the download to work.

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

If you see fatal: no such path in the working tree, it’s because you’re using ZSH, which has gds set up as a Git alias. You can either remove that alias by adding unalias gds to your ~/.zshrc, or use gds-cli instead of gds for all the relevant commands.

The GDS CLI requires some initial configuration:

gds config email
gds config yubikey false # If you type MFA codes from your phone

4. Connecting to the GDS VPN

Access to our infrastructure and internal services is controlled by IP safelisting. If you’re outside of the office or not on the Brattain network (ie, you’re on GovWiFi), you’ll need to connect to the GDS VPN to access our stuff.

To do this, read the GDS Wiki page about the VPN to ensure you have the required pre-requisites, for example the Cisco AnyConnect software installed on your computer, and an MFA token given to you when you arrived by GDS IT. If you don’t have these, contact the IT helpdesk.

5. Set up govuk-docker

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

πŸ‘‰ Learn about how we use Docker

πŸ‘‰ Get setup with govuk-docker

6. Get SSH access to integration

Get access

Ask somebody with access to add your SSH username (firstnamelastname) to the user monitoring system.

Create a user to SSH into integration

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

mkdir ~/govuk
cd ~/govuk
git clone

Now create a user manifest in ~/govuk/govuk-puppet/modules/users/manifests with your username and the public key you created when you set up your GitHub account above. Your file should use the firstnamelastname.pp format.

class users::johnsmith {
  govuk_user { 'johnsmith':
    fullname => 'John Smith',
    email    => '',
    ssh_key  => 'this public key will be a few lines long (copy the output from `more ~/.ssh/`). It should begin with `ssh-rsa AAA` and end with `==`. You may need to add the email address to the end of your public key manually.',

Add the name of your manifest (your username) into the list of users::usernames in hieradata_aws/integration.yaml.

Create a pull request with these changes. Once it has been reviewed by a member of the GOV.UK team, you can merge it and it will automatically deploy to the integration environment.

Access remote environments

Your pull request from earlier will hopefully have been merged by now. If it’s been longer than 30 minutes since the merge, it would have been deployed, too. It’s time to test your access to servers via SSH.

If you’re not in the office right now, you’ll need to be connected to the GDS office VPN for SSH access to integration.

Test that it works by running:

gds govuk connect --environment integration ssh backend

The commands can be shortened to gds govuk c -e integration ssh backend if you wish.

Running a console

Once you have SSH’d into a machine, you can also open a console for a particular application so you can execute commands, for example:

govuk_app_console transition

7. Get AWS access

To work with govuk-aws and govuk-aws-data, you will require an account in AWS.

Request a GDS AWS account

GDS maintains a central account for AWS access. You will need to request an account from the Technology and Operations team.

πŸ‘‰ Request an AWS account

You’ll want to click “Request user access” - NOT “Request an account”. 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. You can then move onto step 2.

Sign in to AWS

To sign in, go to the GDS AWS Sign page, and use the following credentials:

  • “Account ID or alias”: gds-users
  • Username: your email address
  • Password: your password

Set up your MFA

You have to set up Multi-Factor Authentication (MFA).

  1. Sign in to AWS GDS account
  2. Select or go to IAM service.
  3. Click on “Users” in the menu bar on the left hand side
  4. Enter your name
  5. Click on the link for your email address
  6. Click on the security credentials tab
  7. Click on the “Manage” link next to “Assigned MFA device”
  8. Follow the steps to set up your MFA device

If you have a GDS-issued Yubikey, follow the cross-GDS Yubikey docs.

Generate a pair of access keys

You have to generate an AWS Access Key and Secret Key to be able to perform operations with AWS on the command-line.

  1. Sign in to the gds-users AWS Console.
  2. Click on your email address in the top right.
  3. Click ‘My Security Credentials’.
  4. Click ‘Create access key’.
  5. Copy/paste them into the inputs that the gds-cli provides for you, if you’re following the setup instructions.

Changing your MFA device

  1. Follow steps 1 to 7 in set up your MFA
  2. Choose one of the two options (Remove or Resync)

Get the appropriate access

An account in AWS doesn’t give you access to anything, you’ll need to be given rights.

Add yourself to a lists of users found in the data for the infra-security project. There are 5 groups:

  • govuk-administrators: people who are working on GOV.UK infrastructure
  • govuk-internal-administrators: people in GOV.UK who are working on GOV.UK infrastructure including Architects, Lead Developers and anyone else working on the AWS migration
  • govuk-powerusers: anyone else who can have production access on GOV.UK
  • govuk-platformhealth-powerusers: as above but for members of the GOV.UK Platform Health team. (Same access rights as above, we just have limits on the number of users per role).
  • govuk-users: anyone else who needs integration access on GOV.UK

Note: There is a limit on the number of people that can be in each group. If you find that the limit has been hit, try and identify any users who no longer need access and can be removed. Otherwise, a new group will need to be created.

The identifier you need to add is called the “User ARN”. You can find this by going to the users page in AWS IAM and selecting your profile.


After your PR has been merged, someone from the govuk-administrators or govuk-internal-administrators group needs to deploy the infra-security project.

Assuming all roles for users with production access

In addition to the previous section’s named roles, anyone with production access can assume admin, poweruser and user roles. For example, if you want to assume a poweruser role in integration, the role you would specify would be:

  • govuk-integration-poweruser if using the GDS CLI
  • if going directly through the AWS Console

More generally, to assume a role directly through the AWS Console, the role you specify should be of the form<role>, where role is either admin, poweruser or user.

8. Use your AWS access

First run

Here, you will use the GDS CLI you installed and set up earlier. You’ll be asked for AWS credentials on the first run:

$ gds aws govuk-integration-poweruser -l
Welcome to the GDS CLI! We will now store your AWS credentials in the keychain using aws-vault.
Enter Secret Access Key: blah blah
Added credentials to profile "gds-users" in vault
Successfully initialised gds-cli
Enter token for arn:aws:iam::123456789012:mfa/ 123456

Your (Secret) Access Key is from the AWS console. Follow the instructions to generate one. The token requested at the end is the MFA token. If you have a GDS-issued Yubikey (you probably don’t at this stage), set gds config yubikey true and the GDS CLI will automatically pull the MFA code from your Yubikey.

You’ll be prompted to save credentials to your Mac’s Keychain as aws-vault and set a password for it. Save that password somewhere safe, like a password manager.

If you have bash-completion installed and configured, the gds-cli tab completions will work out of the box. They’re especially useful for long commands like AWS account names.


If you forget your aws-vault password:

  1. Delete the aws-vault keychain with rm ~/Library/Keychains/aws-vault.keychain-db
  2. Re-initialise the gds-cli by changing initialised: true in ~/.gds/config.yml to initialised: false.
  3. Then re-run the “First run” commands above.

Get Your Role

Work out which list of users you’re part of in govuk-aws-data. If you’re not part of any lists, add yourself to the appropriate list (or get someone in your team to do it). You’re about to use it in the ‘Web Console’ section below.


Web Console

If you want to look around in integration:

gds aws govuk-integration-readonly -l

If you’re new to GOV.UK you’ll only be able to use the readonly role.

Users with production access can choose to use more privileged roles:

gds aws govuk-integration-readonly -l  # Read only access
gds aws govuk-integration-poweruser -l # Full access, except for Identity Access Management (IAM)
gds aws govuk-integration-admin -l     # Full access, including Identity Access Management (IAM)

It is best practice to use the least privileged role you need for your task. This reduces the impact if your credentials or session are somehow compromised.

-l opens the web browser and logs you in. For a full list of CLI parameters, consult the gds-cli README.


πŸ‘‰ Deploy AWS infrastructure with Terraform

Terminal commands

You can also chain commands, like this one to list S3 buckets in integration:

gds aws govuk-integration-poweruser aws s3 ls

You’re all done!

You’re set up and ready to go. It might be worth reading and bookmarking the architectural deep-dive of GOV.UK to familiarise yourself with how things fit together.