|
| 1 | +--- |
| 2 | +title: GitHub Configuration |
| 3 | +parent: Developer Guides |
| 4 | +description: Configuring new GitHub repositories for use within NHS Notify |
| 5 | +summary: Configuring new GitHub repositories for use within NHS Notify |
| 6 | +last_modified_date: 2024-05-28 |
| 7 | +--- |
| 8 | + |
| 9 | +# GitHub Configuration |
| 10 | + |
| 11 | +When setting up a new GitHub repository for use with NHS Notify, we use a standard set of configuration options to |
| 12 | +ensure consistency and security. |
| 13 | + |
| 14 | +This guide follows the NHSE Software Engineering Quality Framework, in particular the following pages are useful: |
| 15 | + |
| 16 | +* [Securing Repositories](https://github.com/NHSDigital/software-engineering-quality-framework/blob/main/practices/securing-repositories.md#securing-repositories) |
| 17 | +* [Continuous Integration](https://github.com/NHSDigital/software-engineering-quality-framework/blob/main/practices/continuous-integration.md) |
| 18 | + |
| 19 | +## Codeowners |
| 20 | + |
| 21 | +Following |
| 22 | +the [SEQF guidance](https://github.com/NHSDigital/software-engineering-quality-framework/blob/main/practices/securing-repositories.md#teams-setup), |
| 23 | +the default codeowner should be the GitHub team with write access to the repository. |
| 24 | + |
| 25 | +In addition, due to the multi-repository structure of the codebase, the CODEOWNERS files themselves are protected by |
| 26 | +requiring approval from a project-wide nhs-notify-code-owners team. |
| 27 | + |
| 28 | +For example: |
| 29 | + |
| 30 | +``` |
| 31 | +# Default codeowner should be a team with write access |
| 32 | +* @NHSDigital/nhs-notify-amet |
| 33 | +
|
| 34 | +# Default protection for codeowners, must be last in file |
| 35 | +/.github/CODEOWNERS @NHSDigital/nhs-notify-code-owners |
| 36 | +/CODEOWNERS @NHSDigital/nhs-notify-code-owners |
| 37 | +``` |
| 38 | + |
| 39 | +Individual teams are encouraged to include additional codeowners for any sub-components of their repository which |
| 40 | +require additional scrutiny. |
| 41 | + |
| 42 | +## Runners |
| 43 | + |
| 44 | +- [Do not use private runners for public repos](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-security) |
| 45 | +- We will use GitHub hosted runners for CI in all public repos |
| 46 | +- We will also use GitHub hosted runners for private repos unless we have a good reason that a private runner is needed |
| 47 | + |
| 48 | +## Pull requests for public repos |
| 49 | + |
| 50 | +- [Pull requests from forked repos should be configured to require a maintainer to approve the workflow run for all outside contributors](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#controlling-changes-from-forks-to-workflows-in-public-repositories) |
| 51 | +- Workflow runs for PRs from forked repos run with READ_ONLY permission by default, which means they do not have access |
| 52 | + to secrets and cannot make any modifications to the base repo. |
| 53 | + |
| 54 | + |
| 55 | + |
| 56 | +## Bootstrapping CI/CD |
| 57 | + |
| 58 | +- Public repositories should not directly invoke CD workflows, and should delegate to a private deployment repository. |
| 59 | +- [CD workflows should be granted access to an AWS deployment role via OIDC](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services) |
| 60 | + - IAM allows a new OIDC identity provider to be registered with an account |
| 61 | + - A role must be created with a trust policy allowing the GitHub repo token to assume the role. |
| 62 | + - [Example of assuming a role using OIDC in an Actions workflow](https://medium.com/@thiagosalvatore/using-terraform-to-connect-github-actions-and-aws-with-oidc-0e3d27f00123) |
| 63 | + - The set up of the necessary OIDC provider can be applied via Terraform |
| 64 | + - This step is likely to require local deployment, although it's possible we could apply the changes from inside the AWS |
| 65 | + console using cloudshell - TBD |
| 66 | +- Workflow files should be protected by the CODEOWNERS file to prevent unexpected modifications |
| 67 | + |
| 68 | +## CI Workflows |
| 69 | + |
| 70 | +- CI workflows should not require access to secrets |
| 71 | +- CI workflows should not require access to AWS resources |
| 72 | +- Component tests should use locally provisioned resources (docker containers or similar) or in-process test harnesses |
| 73 | + to provide mock services |
| 74 | +- Contract tests should be implemented the same way |
| 75 | +- Micro-benchmarks on the service should be implemented the same way |
| 76 | + |
| 77 | +## CD Workflows |
| 78 | + |
| 79 | +- Deployment workflows may be triggered by users with appropriate access to the repository |
| 80 | +- Deployment workflows should be configured to work with the GitHub environments feature |
| 81 | +- [Deployment rules should be set appropriately for the environment being deployed](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules) |
| 82 | +- Any secrets required for deployment should be set at the environment level. These will not be made available to any |
| 83 | + workflows unless the deployment is approved |
| 84 | + |
| 85 | +## Post-deployment Workflows |
| 86 | + |
| 87 | +- Post-deployment workflows should be triggered after CD workflows or manually as needed |
| 88 | +- These workflows should be scoped to an environment in the same way as CD workflows |
| 89 | +- For individual services the post-deployment workflows should test behaviour at the domain boundary |
| 90 | +- E.g. the test should replay a scenario and subscribe to output events to ensure the behaviour is as expected |
| 91 | +- Service level benchmarking could be performed at this point in non-production environments |
| 92 | +- Full-platform end-to-end and performance tests should live in a separate repository |
| 93 | + |
| 94 | +## Artifacts and Releases |
| 95 | + |
| 96 | +- Artifacts for each build should be packaged and available from the CI pipeline output |
| 97 | +- These are available for 90 days in public repos (could be extended to 400 days in private repos) |
| 98 | +- When a tag is created, a release corresponding to that tag should publish the packaged artifacts |
| 99 | +- Deployment pipelines should either be triggered from a branch or a tag |
| 100 | +- When triggered from a branch, the most recent build for that branch should be used as the source of the artifacts |
| 101 | +- When triggered from a tag, the published release artifacts should be used |
0 commit comments