Create a new application
This guide assumes the following:
- You have completed all the steps in the “get started” guide of the developer docs
- You are deploying an application named
example(make sure to replace this with your application name in all steps as needed)
- You have pushed the application source code to a Github repository under the
alphagovorganisation with the
containerlabels applied (this triggers setup of a number of Github Actions secrets from the organisation and permissions required for workflows)
- You have a Sentry project configured for your application (through
Allow your application to be built as a Docker image
Dockerfile to your application. If your application is written in Ruby, this should normally
be based on the GOV.UK Ruby Images. This should do everything necessary to create a
standalone image for your application.
Note The best way to establish what you need to do is to find an existing GOV.UK application similar to yours, and adapt its
Add Github Actions workflows
You will need to add (at least) the following workflows:
CI(to test your application)
release(to create new releases and version tags)
deploy(to build/push an image and trigger deployment by updating image tags)
Your Continuous Integration (CI) workflow will depend on the linting and testing needs of your application, but will act as a dependency for further workflows to block deployment in case of failure.
deploy workflows, you can copy the workflow definitions from an existing
GOV.UK application (in
Add image tag files to
GOV.UK Helm Charts uses image tag files to keep
track of the image tag deployed into each environment. Add an initial image tag file named after
your application into the
image-tags folder for each of the four environments, i.e.
Add initial secrets to AWS Secrets Manager
In order to set up Sentry for your app, you will need a DSN from the Sentry UI. This must be
manually added as a key/value pair to the
govuk/common/sentry secret in all three environments.
Add app to
app-config chart values
Start with integration
Start off by adding your app to the integration environment by adding it to the array of application
Helm chart values in
charts/app-config/values-integration.yaml. This can be as simple as:
- name: example
This will use the generic-govuk-app Helm chart to set up your application. You can
find the default values in
values.yaml in the chart folder, and amend your configuration’s
helmValues value to override them.
For example, if your app needs a
RETICULATE_SPLINES environment variable set to “1” in a given
environment, your integration configuration could look like this:
- name: example
- name: RETICULATE_SPLINES
There are configuration options available for a wide range of different needs your application may have, from mounting volumes to disabling the default asset upload.
Validate your deployment
You can now trigger your Deploy Github action to push an image to AWS ECS, and visit Integration Argo CD. After a short wait, your new application will be available to find on the dashboard.
Continue with the other environments
Repeat the steps above for the other environments’ values files (
You’ve deployed an application to the Kubernetes platform!