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 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 DSIT “developer build” laptop with the ability to gain full admin access. To find out, check the right hand side of the top Menu Bar, where you should see a padlock icon which opens a “Local Admin Management” window when clicked.
If you don’t have admin access to your laptop, file a Service Now ticket with the ICS helpdesk and copy your line manager.
1. Install the Xcode command-line tools
Open Cirrus Self Service (the app with a coat of arms, in your dock or app menu) and search for Xcode.
2. Install the Homebrew package manager
To install the Homebrew package manager, follow the instructions on their website. You will need to install this via the CLI rather than downloading the package.
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 / DSIT
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-usersAWS 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
digital.cabinet-office.gov.ukanddsit.gov.ukemail addresses to your GitHub account, which can be in addition to your personal email address.
Even though we are no longer employed by Cabinet Office and are using DSIT IT, the
digital.cabinet-office.gov.ukemail address must be added to your GitHub account to avoid triggering this leavers process whilst we migrate to DSIT.
- 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.comAdd your name and email to your git commits. For example:
git config --global user.email "friendly.giraffe@dsit.gov.uk" git config --global user.name "Friendly Giraffe"
Your
dsit.gov.ukemail addresses can be used for commits, provided both yourdigital.cabinet-office.gov.ukanddsit.gov.ukemail addresses are attached to your GitHub account.The email address used for commits is public and could result in spam. If you want to avoid tying your commits to your work email, you can use a generic one generated by GitHub in the email setting under “Keep my email addresses private”.
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
[!NOTE] You must be a member of the alphagov GitHub org (see previous step) to proceed.
On GOV.UK we use gds-cli for AWS access. Follow the instructions on the repo’s README to install/configure the tool.
8. 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.
9. Set up tools to use the GOV.UK Kubernetes clusters
Follow the instructions for getting started with the GOV.UK Kubernetes clusters.
10. 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.
11. 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.
12. 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.
- Terraform for reviewing and applying infrastructure changes.
Supporting information
Now you have completed the get started process, you should look at the following supporting information: