Get started developing on GOV.UK

Last updated: 5 Sep 2023

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 should determine who your tech lead is in your team, as there are a number of steps that require their involvement.

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 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 https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

This command works for macOS or Linux.

2. Generate a SSH key

If you have a YubiKey

If you have a YubiKey, you will use gpg-agent in place of ssh-agent, which requires a GPG key to have been generated.

Create a GPG key as per the Create a GPG Key documentation.
Add the following to the ~/.gnupg/gpg-agent.conf file:

   enable-ssh-support
   pinentry-program /usr/local/bin/pinentry-mac
   default-cache-ttl 60
   max-cache-ttl 120

Add the following to your ~/.zprofile file:

   export GPG_TTY=$(tty)
   export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket)
   gpgconf --launch gpg-agent

Run killall gpg-agent to stop any running gpg-agent processes.
Run ssh-add -L. This will output your public SSH key, which should end cardno:000000000000 (indicating it is from a YubiKey).

If you do not have a YubiKey

Generate a new SSH key for your laptop and add it to the ssh-agent for your GitHub account.
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>

3. Set up your Slack profile

As part of your onboarding to GDS you will have been given access to Slack - if you’ve not got this please talk to your tech lead.

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
if relevant, the name of your supplier

4. Set up your AWS IAM User

GDS has a central gds-users AWS account where you create your IAM User. Your tech lead will then create IAM Roles that you can assume for access to GOV.UK’s AWS accounts. The reliability engineering site has more information on how AWS accounts are structured.

Request a AWS IAM User for the central gds-users AWS 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. If you were issued a Yubikey, you can use it as a MFA device.

5. Set up your GitHub account

Login into your existing GitHub account or create a new GitHub account.
Associate your GitHub account with your GDS email address, which can be in addition to your personal email address.
Add the SSH key to your GitHub account.
Test that the SSH key works by running 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, Sentry and Pagerduty accounts are managed by the govuk-user-reviewer repository. This is a private repository so will 404 before joining GOV.UK’s GitHub.

Ask your tech lead to follow the instructions in govuk-user-reviewer to grant you access. You must complete steps 1-5 first.

7. Install and configure the GDS CLI

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

Run the following install GDS CLI:
```
brew tap alphagov/gds
brew install gds-cli govuk-connect
brew install --cask aws-vault
```
The GDS CLI repository is private, so your tech lead must have first completed step 6 to provide you with the necessary access.
Test that installation was successful 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

Configure the GDS CLI by running:

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

Set up AWS credentials:
1. Create an AWS access key via the console.
2. Run a GDS CLI command to prompt for credentials. For example gds aws govuk-integration-readonly -l.
3. Enter your Access Key ID and Secret Access Key
4. Enter your AWS MFA token
5. 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.
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/firstname.lastname@digital.cabinet-office.gov.uk: 123456
```

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. You can now use gds aws to run generic aws CLI commands by prefixing them with gds aws <role>. For example:

gds aws govuk-integration-readonly aws s3 ls

8. 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 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, and you are working on GOV.UK’s frontend apps, there is documentation on alterntaive local development approaches that make low or no usage of GOV.UK Docker.

10. Get SSH access to integration

If you are a frontend developer you do not need to complete this step as part of your initial setup.

Create a user to SSH into integration

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

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 git@github.com:alphagov/govuk-puppet.git
```
Add your SSH key which you created in step 2.

If you do not have a YubiKey, run more ~/.ssh/id_ed25519.pub to retrieve your public key. The key should begin with ssh-ed25519 AAA. If you have an existing RSA public key you could add that instead, although ed25519 keys are preferable. An RSA public key will start with ssh-rsa AAA. You may need to manually add the email address to the end of your key.

If you have a YubiKey, run ssh-add -L to retrieve the key from your device. The key should end with cardno:000000000000.

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    => 'john.smith@digital.cabinet-office.gov.uk',
    ssh_key  => 'ssh-ed25519 AAAAC37eiue0923jfwnfwle93fnwefwn john.smith@digital.cabinet-office.gov.uk',
  }
}

Add the name of your user class (<firstnamelastname>) into the list of users::usernames in hieradata_aws/integration.yaml.
Create a pull request with these changes and ask your tech lead to review it.

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

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

If you see an error Permission denied, check the message shown later, similar to: The SSH username used was: jsmith - if this is not the user you specified in the puppet config above, you need to specify a username:

USER=jaysmith gds govuk connect --environment integration ssh backend

(or you can export USER=jaysmith separately to set it for a shell session)

If you see an error similar to no matching host key type found. Their offer: ssh-rsa,ssh-dss you will have to change your ssh configuration - this is an issue with OSX Ventura (and possibly other operating systems) - see this StackOverflow issue

You need to add the following into your ssh config (e.g. ~/.ssh/config):

Host *
  HostkeyAlgorithms +ssh-rsa
  PubkeyAcceptedAlgorithms +ssh-rsa

Note this may happen even if you don’t use an rsa ssh private key - it is caused by the host key which is defined by the server you connect to, not your user key which you have defined.

11. Set up tools to use the GOV.UK Kubernetes platform

Follow the instructions for setting up tools to use the GOV.UK Kubernetes platform.

12. Get a Signon account for integration

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

Ask your tech lead to create an account for the integration Signon, at ‘Superadmin’ level with permission to access the applications that your team are likely to work on.

13. Get access to the Release app

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

Ask your tech lead to create an account for the production Signon, at ‘Normal’ level with access to the ‘Release’ app only. No permissions should be given for other applications, until production access is granted.

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

Depending on the team you’ve joined, you will likely need access to other supporting services to fulfil your role. Talk to your tech lead about which ones you need as part of onboarding and they can arrange access. Services you may need access to are:

Logit - the software we use for access application logs, where new starters are given access to the integration environment
Google Analytics - the software we use to track user behaviour, typically only needed if you work on a team working frequently with analytics
Zendesk - the software we use for tracking support tickets, typically access isn’t needed until working as part of the 2nd line support team

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