Note These are also checked by gu-who.
- MFA must be enabled
- A human name should be added to your account
These requirements are intended to make it easier to manage user accounts and understand if they should be in the organisation or not.
The recommended method for spawning a new repository is using https://repo.new/ (which redirects to https://github.com/new/).
Bear in mind:
- The repository Owner should be
guardian - The best visibility for most repositories is
Public, rather thanInternalorPrivate. Developing in the Open makes better software! - Make sure you grant an appropriate focussed GitHub team full
Adminaccess to the repo - this should be the dev team that will be owning this project, not a huge team with hundreds of members! - For public repositories, we recommend using the Apache v2 license.
We're no longer using https://repo-genesis.herokuapp.com/, as there are many different aspects to setting a GitHub repo up in the best possible way, and repo-genesis only enforced a couple of them, and only at the point of creation. DevX have plans to enable a new repo-monitoring service which will ensure many more aspects of Guardian repos are checked and adhere to best practices.
The default should be Public.
In some cases it may be necessary to have a more restrictive visibility. Think carefully about the justification for making a repository non-public and make sure this justification is clear to the whole team.
If you need a non-public repository, the best visibility to choose is Internal. This makes the repository readable (but not writable) by all Guardian GitHub organisation members. (Typically you should also grant write access via the @guardian/guardian-developers-write team: see Access below.)
You can make a repository Private if you do not want it to be visible to the entire organisation. This should only be done in exceptional circumstances and your team should be clear about the justification.
Use main.
Words matter. See docs from the master-to-main tool for more information. This tool can also be used to rename the default branch.
Enable branch protection for the default branch.
Particularly when continuous delivery is configured, branch protection reduces risk as it means changes get reviewed before being deployed. The following settings are recommended:
- Require pull request reviews before merging
- Require review from Code Owners (see Codeowners)
- Require status checks to pass before merging
- Require branches to be up to date before merging
- Include administrators
If you need to disable branch protection, e.g. in order to use the Scala release workflow, you should re-enable protection via rulesets, which allow for protection to be bypassed in certain specific cases.
Access should be granted to GitHub teams. Avoid individual access.
Should an individual leave the GitHub organisation, they'll automatically lose access to all repositories when access is granted via teams. When individual access is granted, they'll retain access to a repository until manually removed.
Generally, new repositories should be open to the department via Internal visibility (for read access) and by granting write access to the @guardian/guardian-developers-write team.
(Existing Private repositories may achieve the same effect by additionally granting read access to @guardian/guardian-developers-read. This approach is not recommended since GitHub's introduction of Internal visibility.)
Include at least one GitHub team as a collaborator with admin access. At an organisational level, this identifies owners for every repository, so that we can better ensure security and maintenance work is under the remit of a team for all our (production) code.
In general, avoid giving individual access to repositories and prefer teams.
Include a CODEOWNERS file which references the GitHub team(s) responsible for different parts of the repository. This allows the responsible team to receive notifications of contributions and review changes.
Repositories that are no longer used should be archived.
GitHub environments can be configured with protection rules and secrets. Workflows that reference an environment will then be bound by its protection rules and, if allowed, get access to it's secrets. When configuring workflows that require secrets, consider whether an environment can be used in conjunction with the branch protection rules to limit the use of the secret.
For example, when configuring auto-publishing for an npm library it is recommended that you create a new environment for this purpose, containing the NPM and GitHub tokens and with the protection rules set so that it can only be used from the release branch. The release workflow should then reference this environment.
Topics must be used to categorise repositories that are, or are not, destined for production. These topics make it clear to others what the purpose of the repository is and allow projects to be filtered out of monitoring and searches where required. More than one topic can be added, and if both production and a non-production topic are combined, a repository will be assumed to contain production code.
| Topic | Description |
|---|---|
| prototype | Repositories that are used to prove a new concept |
| learning | Repositories that have been created as part of a learning exercise |
| hackday | Repositories that are created during hack days |
| testing | Repositories that are used for test purposes |
| documentation | Repositories that contain only documentation and no source code |
| production | Repositories that are deployed to production |
If none of the above topics fit your need, a PR should be opened to add the new topic to this list before use.
- Never commit secret information. See also the security recommendations.
- Avoid private information in public repositories
Things we could happily put on the front page of the Guardian.
Examples:
- source code
- diagrams
- architecture decision records
Things we do not want to be common knowledge, but knowing them does not directly compromise anything.
Generally this means that knowing that detail would make an exploit (technical or people-wise) easier to achieve, especially when combining a few of them.
Not for public repositories. Fine for private repositories.
Examples:
- AWS account IDs
- S3 bucket names
Information that directly causes problems! These should be kept out of VCS completely.
Secrets should be rotated regularly.
If leaked, it is a security incident and the incident doc should be followed.
Examples:
- API keys
- Passwords
- Authentication tokens