Skip to main content

When to use​

When a repository is no longer needed and should be removed from the eigenoid org.

tip

Deletion is a soft-delete with a 30-day retention period. The repo is archived first and permanently deleted afterward.

Preconditions​

  • Access to the eigenoid/platform-settings repo
  • Be a member of the @eigenoid/platform-lifecycle-approvers team (or have a member available to approve)

Procedure​

  1. Open an issue — Go to platform-settings → Issues → New Issue → select "Request repo deletion"

  2. Fill out the form:

    • Name of the repo to delete
    • Reason for deletion

  3. Notification — When the issue is opened, the notify-lifecycle-approvers.yml workflow automatically mentions @eigenoid/platform-lifecycle-approvers for review.

  4. Approval — A member of @eigenoid/platform-lifecycle-approvers reviews and adds the approved-deletion label.

    Authorization

    The workflow verifies that the person adding the label is a member of the platform-lifecycle-approvers team. If they are not, the label is automatically removed and the operation is cancelled with a comment on the issue.

  5. Phase 1 (automatic, immediate after approval):

    • The workflow verifies the repo exists and is not already archived
    • If the repo has open issues or PRs, a warning is posted on the issue (but archiving continues)
    • The repo is archived (archived: true)
    • The config YAML is moved from .github/repos/ to .github/archived-repos/
    • It is registered in .github/archived-repos.json with the archival date
    • The issue is closed automatically

  6. Phase 2 (daily CRON at 06:00 UTC):

    • The workflow checks archived-repos.json
    • Repos older than 30 days are permanently deleted
    • The entry is removed from the registry

Verification​

# After Phase 1: verify the repo is archived
gh repo view eigenoid/NAME --json isArchived
# Should show: {"isArchived": true}

# Verify the config YAML was moved
ls .github/archived-repos/NAME.yml

# Verify the registry
cat .github/archived-repos.json | jq '."NAME"'
bash

Recovery (before the 30-day mark)​

If a repo was archived by mistake, it can be recovered:

# 1. Un-archive the repo
gh api -X PATCH repos/eigenoid/NAME -f archived=false

# 2. Move the YAML back (in the admin repo)
cd platform-settings
git mv .github/archived-repos/NAME.yml .github/repos/NAME.yml

# 3. Remove the entry from archived-repos.json
# (manually edit the JSON file)

# 4. Commit and push
git commit -am "fix: restore NAME from soft-delete" && git push
bash
tip

The next CRON run will detect that the repo is no longer archived and skip it automatically. No further action is needed.

Escalation​

SituationAction
Archiving workflow failsCheck logs in Actions. Contact @shoootyou.
Repo permanently deleted (>30 days)Contact GitHub Support for possible restoration. Not guaranteed.
Need to delete a repo immediately (without waiting 30 days)An org owner can delete the repo manually via gh api -X DELETE repos/eigenoid/NAME.
Permanent deletion

If 30 days have passed and the repo was deleted by the CRON job, restoration depends on GitHub Support and is not guaranteed. Act quickly if an error is detected.

IaC repos — state bucket cleanup​

When the repo being deleted is in the iac category and has buckets registered in state-buckets.json, the deletion process includes automatic cleanup:

Phase 1 (archiving)​

The notify-lifecycle-approvers.yml workflow detects whether the repo has an entry in state-buckets.json and lists the associated buckets in the notification comment:

Warning: This repo has associated Terraform state buckets:
  - eigenoid-2cea55-{stack}-tfstate-dev
  - eigenoid-2cea55-{stack}-tfstate-qa
  - eigenoid-2cea55-{stack}-tfstate-prd

The buckets will be automatically deleted after 30 days.

Phase 2 (permanent deletion)​

The delete-archived-repos.yml workflow, in addition to deleting the repo:

  1. Deletes the 3 GCS buckets for the repo.
  2. Removes the entry from state-buckets.json.
  3. Comments with the deleted buckets on the original issue.
State data

The buckets contain the Terraform state for all environments. Once deleted, the infrastructure they managed becomes "unmanaged" in GCP. Make sure the resources have already been destroyed (terraform destroy) or transferred before deleting the repo.

References​