Merge pull request #1458 from alphagov/document-removing-repos

Document how to remove repo from GitHub config

terraform/deployments/github/README.md

@@ -42,3 +42,34 @@ Our intent is to replace govuk-saas-config with Terraform configuration.
   ```shell
   GITHUB_TOKEN=<token> gds aws govuk-production-poweruser -- terraform apply
   ```
+
+## Removing repositories
+
+Before an archived repository can be removed from GOV.UK GitHub configuration, it needs to be manually removed from terraform state. 
+
+> Failing to do so will result in repository being deleted (rather than archived). If a repository is not removed by following those steps, it will be un-archived when the GitHub configuration is applied. 
+
+### 1. Remove relevant resource instances from terraform state
+
+Run the following commands to remove resource instances relevant to the retired repository:
+
+```
+cd terraform/deployments/github
+terraform login
+terraform init
+terraform state rm 'github_branch_protection.govuk_repos["repo-name"]' &&
+terraform state rm 'github_team_repository.govuk_repos["repo-name"]' &&
+terraform state rm 'github_team_repository.govuk_production_admin_repos["repo-name"]' &&
+terraform state rm 'github_team_repository.govuk_ci_bots_repos["repo-name"]' &&
+terraform state rm 'github_repository.govuk_repos["repo-name"]' &&
+terraform state rm 'aws_codecommit_repository.govuk_repos["alphagov/repo-name"]'
+```
+
+You can verify what other instances need to be removed by running:
+```
+terraform state list | grep repo-name
+```
+
+### 2. Raise a PR to remove repo from `deployments/github/repos.yml`
+
+Ensure terraform plan shows "No changes" before merging the PR.