Get started developing on GOV.UK
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 runninggpg-agent
processes.Run
ssh-add -L
. This will output your public SSH key, which should endcardno: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
andgds govuk connect --help
.If you see a
fatal: no such path in the working tree
error, that’s because you’re using ZSH, which hasgds
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 ofgds
for all the relevant commands
- remove that alias by adding
Configure the GDS CLI by running:
gds config email <FIRSTNAME>.<LASTNAME>@digital.cabinet-office.gov.uk
Set up AWS credentials:
- Create an AWS access key via the console.
- Run a GDS CLI command to prompt for credentials. For example
gds aws govuk-integration-readonly -l
. - Enter your Access Key ID and Secret Access Key
- Enter your AWS MFA token
- 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 thegovuk-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 withssh-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 withssh-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 withcardno: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 ofusers::usernames
inhieradata_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: