diff --git a/source/manual/creating a prototype in alphagov and setting up heroku review apps.html.md b/source/manual/creating a prototype in alphagov and setting up heroku review apps.html.md new file mode 100644 index 00000000000..6243bbda7c7 --- /dev/null +++ b/source/manual/creating a prototype in alphagov and setting up heroku review apps.html.md @@ -0,0 +1,134 @@ +--- +owner_slack: "#govuk-developers" +title: Create an prototype in Alphagov and set up Heroku review apps +section: Deployment +layout: manual_layout +parent: "/manual.html" +--- + +This guide explains how to create a new repository in Alphagov for a [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk/docs/) prototype and configure Heroku review apps for deployments. + +**Note**: Other hosting options are available and some are covered in the [GOV.UK Prototype Kit publishing documentation](https://prototype-kit.service.gov.uk/docs/publishing). This guide focuses specifically on creating a repository in Alphagov and using Heroku review apps to deploy your prototype. + +## Create a new repository + +The following steps assume you are creating a prototype using the GOV.UK Prototype Kit. + +### 1. Create and configure the repository + +Follow the general steps for creating a new GOV.UK repository in the [Creating and configuring a new repository](https://docs.publishing.service.gov.uk/manual/github-new-repo.html#create-a-new-repository) guide. + +See the [example pull request](https://github.com/alphagov/govuk-infrastructure/pull/4489). + +### 2. Request a review + +Ask for a review in [#govuk-ask-platform-engineering](https://gds.slack.com/archives/C013F737737). + +Once your pull request has been approved, merge it. + +### 3. Request Terraform to be run + +After your pull request has been merged, post again in [#govuk-ask-platform-engineering](https://gds.slack.com/archives/C013F737737) to ask that Terraform is run to create the repository. + +### 4. Complete the repository setup + +Once the repository has been created: + +- Create a well-written README, following the GOV.UK guidance: https://docs.publishing.service.gov.uk/manual/github-new-repo.html#create-a-new-repository +- Add a licence following the [Licensing Guidelines](https://gds-way.digital.cabinet-office.gov.uk/manuals/licensing.html#specifying-the-licence). +- Add a CI workflow. + +The process for adding security scans to the CI pipeline is documented here: [Add security scans to the CI pipeline](https://docs.publishing.service.gov.uk/manual/github-new-repo.html#add-security-scans-to-the-ci-pipeline) + +See the [example workflow](https://github.com/alphagov/govuk-multiple-h1-headings-on-page-prototype/blob/main/.github/workflows/ci.yml). + +### 5. Branch protection rules + +You may need to configure branch protection rules to allow non-developer roles, such as interaction designers or content designers, to merge approved pull requests into main. + +To add someone: + +- Go to **Settings → Branches**. +- Under Restrict who can push to matching branches, search for the person you want to add and select them. +- Click **Save**. + +### 6. Manage access + +You may need to configure repository access for non-developer roles, such as interaction designers or content designers. + +To add someone: + +- Go to **Settings → Collaborators and teams**. +- Click **Add people**. +- Search for the person you want to add and select them. +- On the next page, choose the appropriate access level for the person. Write access is recommended for anyone who needs to push changes to the repository. +- Click **Add selection**. + +## Set up the Heroku pipeline + +- Log in to Heroku: https://docs.publishing.service.gov.uk/manual/heroku.html. +- Select **New → Create new pipeline**. +- Enter: + - **Pipeline name** (required) + - **Pipeline owner**: (leave unchanged – Alphagov – heroku@digital.cabinet-office.gov.uk) +- Under **Connect to GitHub**: + - Change the dropdown to Alphagov. + - Search for your repository. +- Click **Search**. +- When the correct repository is found, click **Connect**. +- Click **Create pipeline**. + +## Enable review apps + +After the pipeline has been created: + +- Open the **Settings** tab. +- Under **Review Apps**, click **Enable review apps**. + +Additional options will appear. + +Configure the following settings: + +- Enable **Create new review apps for new pull requests automatically**. +- Enable **Wait for GitHub checks to pass**. +- Enable **Destroy stale review apps automaticall** and set the expiry to **5 days**. +- Change the region to **Europe**. + +Click **Enable Review Apps** to save the configuration. + +## Create a permanent review app (in staging or production) + +For pipelines that are used exclusively for review apps, it is recommended to keep a placeholder app in the staging or production environment. This helps prevent the pipeline from being accidentally deleted. + +See the Heroku documentation for more details: [Why did my pipeline disappear?](https://help.heroku.com/R8AE3YBV/why-did-my-pipeline-disappear). + +To add a placeholder production app: + +- Under **Production**, click **Add app**. +- Click **Create new app**. +- Enter an **App name**. +- Set the **Location** to **Europe**. +- Ensure **Add this app to a pipeline** is selected. +- Select the pipeline you created above. +- Set **Choose a stage to add this app to** to **Production**. +- Click **Create app**. + +On the next page, configure automatic deploys: + +- Click the GitHub icon to connect the app to GitHub. +- Search for the repository you want to connect and click **Connect**. +- Under Automatic deploys, select the branch to deploy (this should usually be main). +- Click **Enable Automatic Deploys**. + +**Note**: You may need to manually deploy the main branch the first time you complete this setup. + +## Configure review app environment variables + +To password-protect your prototype, add the required environment variables to the review app config. + +Add the following variables: + +- **NODE_ENV**, and the value is **production** +- **PASSWORD**, and the value is whatever password you want to use + +For more information, see: [Setting a password](https://prototype-kit.service.gov.uk/docs/publishing#setting-a-password).