Retire a repo
1. Update the README
Add a note to the top of the README explaining that the repo has been retired and, if applicable, what has replaced it.
In some cases it may be appropriate to skip this step if:
- the repo is already disused and has been for a long time
- the repo is private and not widely known within the organisation
- there isn’t a replacement, so there’s no need to point the reader towards something else
2. Close all issues and pull requests
This is necessary because GitHub does not automatically close or archive PRs/issues when archiving a repo. For example, if an old PR is still open when the repo is archived, its author will be unable to close it and it will forever remain on their github.com/pulls page.
If there are more than a handful of open issues/PRs, consider using the GitHub CLI tool (gh pr, gh issue).
3. Unpublish the GitHub pages site (if it has one)
Archiving a repo does not remove its GitHub Pages site (if any). The site stays up but the settings become read-only.
⚠️ Take care when unpublishing a GitHub Pages site which has a custom domain. If you leave a dangling DNS record pointing at GitHub, it will likely be hijacked by spammers (or worse).
- Check whether the site has any custom domains configured. This is under Settings, Pages, Custom domain in the GitHub web UI. Do not remove the custom domain.
- Remove any DNS records that point to the site, if the site uses a custom domain.
- Unpublish the GitHub Pages site.
4. Archive the repo
Go into the repository settings in GitHub, and archive the repo.
5. Update the Developer Docs
If the repo is listed in govuk-developer-docs, mark the application as retired.
If the repo wasn’t already listed in Developer Docs then don’t add it.
(#4259 would eliminate this toil if fixed.)
6. Remove references
Search GitHub for any references to the repository and update or remove them as appropriate.
You should search for:
- the repo name
- links to the GitHub Pages site, if there was one