Adding a new repository


Introducing a new repository will increase the amount of maintenance for the dev team. Make sure the team has discussed and agreed whether a new repo is really necessary before following the steps below.


We publish code in the open, following the GDS Way guidance. Where this document is unclear, refer to GDS Way guidance. Where this document conflicts with GDS Way guidance, consult with team members.

We manage all code (and some other resources) using Git repositories on GitHub. Any new repository (repo) needs to have a couple of things included before it can be added to GitHub:

  • A LICENCE file containing the MIT licence

  • A README file using GitHub-flavoured Markdown syntax titled with the name of the repo and containing a description of what is in the repo.

You should also consider adding a .gitignore file that prevents build artifacts or temporary files from being committed accidentally; see the GitHub article on Ignoring files for guidance on how to do this.

Setting up a repo on GitHub

Any new repos should be created in the GDS GitHub org. Digital Marketplace GitHub teams should have access to the new repo (“Admin” permissions for digitalmarketplace team).

If you want to initially experiment locally before deciding whether to create a new repo you can create a repo under your own user but transfer ownership later (note that is different from forking).

The repo name should have the digitalmarketplace- prefix. Words in the name should be in all lower case letters, seperated by hyphens (kebab-case). Consult with the team before naming; naming is hard!

Make sure to add a description for the repo, something short that describes what the repo is for.

Once the repo is set up you should enable branch protection for the master branch:

  • Require 1 pull request review before merging

  • Require status checks to pass before merging

  • Require branches to be up to date before merging

  • Include administrators

You should also set the merge button options to automatically delete head branches to keep the number of branches in the repo managable over time.

Adding the repo to the world

Once your repo is on GitHub, you need to make other services we use aware of its existence.

You should create an AWS CodeCommit backup Jenkins pipeline for the repo following the steps in Code backups.

You should add the repo to the list of Digital Marketplace repos in alphagov/seal, so that notifications about open PRs get sent to the #dm-review Slack channel.

You should add the GitHub Trello Poster to the repos webhooks so that devs can attach a link to a Trello ticket in a PR and have the Trello ticket automatically updated with a link to the PR.

If the repo contains code you should:

  • add it to Snyk to have it regularly checked for security vulnerabilities

  • add it to Dependabot and add a .github/dependabot.yml file so that automatic PRs are generated weekly to update dependencies

It your repo has tests (it should!) you should add the repo to Travis and create a Travisfile.

Finally, you should consider throwing a birthday party 🎉.