Skip to main content

The GDS Way and its content is intended for internal use by the GDS and CO CDIO communities.

Use Github

GDS uses GitHub as its code repository.

Put new repositories for GDS services in the alphagov organisation on GitHub.

You can use your personal GitHub account to access alphagov but please ensure that you also link your GDS email address to your account. Ask your tech lead or technical architect to invite you. GDS will revoke your access to alphagov when you leave GDS.

To secure your Github repository, make sure you:

  • configure two-factor authentication for your account
  • have considered encrypting your repository contents
  • consider protecting your main branch to prevent changes being committed without a suitable review

You can also consider backing up your Git repositories to another location (this should be a team responsibility). If you are using AWS to host your service AWS CodeCommit is one option.

How to retire applications

If an application is no longer used in production, you should archive its repository.

Update the application’s README to explain why the repository has been archived, and link to a new location if the application has been superseded.

Using Github Actions and workflows

Alphagov repositories can be configured to use GitHub Actions for CI/CD jobs, for example running unit tests or deploying a static site.

Actions and workflows can be powerful, so take care to follow best security practice.

Ensure the repository permissions follow the principle of least privilege by:

If your repository has external contributors, ensure they do not have permissions to add workflows or trigger workflow runs.

If your workflow interacts with another resource (for example AWS or DockerHub), consider setting up a dedicated account or role, with permissions limited to the scope of the action. Use temporary credentials in preference to storing long-lived credentials in a secret. In particular, when accessing AWS you must [authenticate using the OpenID Connect token][GHA-AWS-OIDC] and not using an IAM User’s access key and secret access key. You should also specify the branch you expect to be deploying from (for example, main) in your IAM role to make sure code cannot be deployed from untrusted branches.

Consider protecting the .github/workflows folder by using a CODEOWNERS file and requiring review from CODEOWNERS for merges into protected branches.

Consider creating a Workflow Template in the alphagov workflow folder if you need to share a similar workflow between many repositories.

Create your own local actions wherever possible. If using GitHub-owned actions, pin to a specific version. Third-party actions should only be used if:

  • The provider is verified by GitHub (for example, aws-actions)
  • The action is complex enough that you cannot write your own local action
  • You have fully reviewed the code in the version of the third-party action you will be using
  • You have pinned the specific version in your workflow and in the repository settings, using a Git commit SHA
  • The third-party action is actively maintained, well-documented and tested (follow the guidance on third party dependencies).

You can enforce this in the settings for Actions by choosing ‘Allow select actions’ and then ‘Allow actions created by GitHub’ and ‘Allow Marketplace actions by verified creators’ as required.

Note that for public repositories, the output of workflow runs is visible to everyone. Do not use workflows if this output could be considered sensitive.

See also

This page was last reviewed on 21 March 2022. It needs to be reviewed again on 21 September 2022 by the page owner #gds-way .
This page was set to be reviewed before 21 September 2022 by the page owner #gds-way. This might mean the content is out of date.