GitHub

Creating a new repository

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 than Internal or Private. Developing in the Open makes better software!
• Make sure you grant an appropriate focussed GitHub team full Admin access 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.

Repository Configuration

Visibility

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 and included in the README to reduce the chance of someone making the repo public in the future because they were not aware of the rationale for the more restrictive visibility.

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.

Branch Protection

Enable branch protection for the default branch.

Particularly when continuous deployment 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

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.)

Collaborators and CODEOWNERS

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.

Archiving

Repositories that are no longer used should be archived.

Environments

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

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.

Repository contents

See also the security recommendations for definitions of public, private and secret information.

• Never commit secret information.
• Avoid private information in public repositories.
• Private information is fine in private repositories.