Skip to main content

Create a GOV.UK Prototype Kit site

The cloud platform makes it easy to set up and host a GOV.UK Prototype Kit website.

This guide will walk you through the process.

Pre-requisites

To complete the steps in this guide, you will need:

1. Clone the environments repository

To create resources on the Cloud Platform, you need to raise a pull request against the cloud-platform-environments repository.

Start by checking out a copy of the repository:

$ git clone git@github.com:ministryofjustice/cloud-platform-environments.git
$ cd cloud-platform-environments

2. Create your prototype kit site

To create your prototype kit site, run:

$ cloud-platform environment prototype create

You will be asked several questions, the most important of which is the name of your prototype kit project.

This name will be used as:

  • The name of the namespace which will be created on the cloud platform
  • The name of the GitHub repository which will be created, and which will contain your prototype kit source code
  • The hostname of your prototype kit website

You must ensure that there is not already a namespace or github repository with this name

For example, if you choose my-prototype as the name, you will create:

  • A namespace on the Cloud Platform called my-prototype
  • The github repository https://github.com/ministryofjustice/my-prototype

…and your prototype kit website will be available at the URL:

https://my-prototype.apps.live-1.cloud-platform.service.justice.gov.uk

3. Raise a PR

After you have answered all the questions, the cloud-platform CLI will create several files in a folder called:

namespaces/live-1.cloud-platform.service.justice.gov.uk/[name you chose]

Create a new branch, git add the new folder and then raise a pull request.

Once a member of the Cloud Platform team has approved your PR, merge it.

When you merge the PR, the Apply Pipeline will create your namespace and github repository. The github repository has a deployment workflow, implemented as a GitHub Actions workflow, which will continuously deploy any changes made to the main branch of the repository.

Caveats

There are a few things to be aware of, concerning your prototype kit site:

  • The deployment workflow usually takes around 5 minutes to run

  • The very first run of the deployment workflow will fail. This is because the github repository (and its deployment workflow) has to be created before some of the resources the workflow depends on. You can use the “re-run” button in the GitHub web interface, and the action should succeed.

GitHub Actions re-run button

You don’t have to do this - when you push changes to the repository, they will be deployed successfully - but you may want to confirm that your site works before making any changes.

  • The GitHub repository is created with branch protection applied to the default main branch. If you don’t want this, edit the github-repo.tf file in your namespace folder in the environments repository, and remove this stanza:
resource "github_branch_protection" "default" {
  repository_id          = github_repository.prototype.id
  pattern                = "main"
  enforce_admins         = true
  require_signed_commits = true
}

If you use the GitHub UI to disable branch protection, the Apply Pipeline will re-enable it shortly afterwards.

The only way to permanently disable it is to remove it from the terraform source code.

Deleting your Prototype Kit site

When you no longer need your prototype kit site, you can delete it as follows:

  1. Raise a PR removing your namespace folder from the cloud-platform-environments repository, and wait for it to be approved by a member of the Cloud Platform team

  2. Immediately before you merge the PR use the GitHub web interface to delete your repository

  3. Merge the PR

The Apply Pipeline has the GitHub privileges required to create repositories, but not to delete them. This is a deliberate safety feature.

Shortly after you merge the PR, your namespace will be removed from the Cloud Platform.

This page was last reviewed on 19 August 2021. It needs to be reviewed again on 19 November 2021 .
This page was set to be reviewed before 19 November 2021. This might mean the content is out of date.