Table of contents


Get SSH access to integration

1. Get access

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

2. Create a user to SSH into integration

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

mac$ mkdir ~/govuk
mac$ cd ~/govuk
mac$ git clone

To create a new account, start by creating an SSH key at least 4096 bits long. For example:

mac$ ssh-keygen -t rsa -b 4096 -C "" -f ~/.ssh/alphagov

Import the SSH key into your keychain.

mac$ /usr/bin/ssh-add -K ~/.ssh/alphagov

You’ll also want to add the above line into your ~/.bash_profile so that it is persistent between restarts.

Create a public key from this:

mac$ ssh-keygen -y -f ~/.ssh/alphagov > ~/.ssh/

Now create a user manifest in ~/govuk/govuk-puppet/modules/users/manifests with your username and the public key you just created. Your username 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 for integration and in hieradata/integration.yaml for CI.

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.

3. Access remote environments

Your pull request from earlier will hopefully have been merged by now. 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.

While the applications are available directly via the public internet, SSH access to remote environments is via a ‘jumpbox’. You’ll need to configure your machine to use this jumpbox and use govukcli to SSH into server.

  1. Copy the example SSH config file into the ~/.ssh/config file on your host machine.
  2. Run ln -s ~/govuk/govuk-aws/tools/govukcli /usr/local/bin/govukcli on your host machine to be able to use the govukcli tool from any directory.

Test that it works by running:

mac$ govukcli set-context integration
mac$ govukcli ssh backend

You should be able to do the same thing in your VM:

dev$ govukcli set-context integration
dev$ govukcli ssh backend

The built-in key-forwarding should mean that you don’t need to edit the ~/.ssh/config file inside the VM (it will default to your host machine’s config file instead).

This page was last reviewed on 10 May 2019. It needs to be reviewed again on 10 November 2019 by the page owner #govuk-2ndline .
This page was set to be reviewed before 10 November 2019 by the page owner #govuk-2ndline. This might mean the content is out of date.