Skip to main content

Quick reference​

  1. Issue → template "Request new repository"
  2. Review the summary table posted by the bot
  3. Add the approve-repo label
  4. safe-settings creates the repo (~10 sec)

If the repo already exists, the issue is automatically closed with an error.

When to use​

When a new repository is needed in the eigenoid org.

Preconditions​

Procedure​

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

  2. Fill out the form:

    • Category (determines the name prefix and suborg): iac, app, docs, platform, tpl, svc, or exception
    • Descriptive name (without the category prefix, in kebab-case — e.g., org-shared, studio)
    • Description
    • Topics (optional, comma-separated, lowercase)
    • Extra labels (optional, format name | color | description per line)
    • Visibility (private / public)

    The final repo name will be <category>-<descriptive-name> (e.g., iac-org-shared). For exceptions, the name is used as-is.

  3. Review the summary table — The new-repo.yml workflow posts a table with the parsed data as a comment. Verify that everything is correct.

    Duplicate detection

    If a file .github/repos/<name>.yml already exists, the workflow closes the issue automatically with an error message. The summary table is not shown.

  4. Approve the creation — Add the approve-repo label to the issue. The approve-repo.yml workflow generates the YAML and pushes it directly to main.

  5. Wait for creation — safe-settings receives the push and creates the repo with the specified configuration (~10 seconds).

  6. Issue closes automatically with a link to the created repo.

IaC repos — automatic state bucket bootstrap​

When the selected category is iac, the approve-repo.yml workflow runs additional steps before creating the repo:

  1. Creates 3 GCS buckets (dev, qa, prd) following the convention eigenoid-2cea55-{stack}-tfstate-{env}.
  2. Updates state-buckets.json (bucket registry in .github/).
  3. Comments on the issue with a table of the created buckets.

The repo is created from the iac-template template, which comes pre-configured with terraflow.yaml, backend configs, and the CI workflow. The first PR with Terraform works immediately — there are no manual bootstrap steps.

Stack naming

The stack name is derived from the repo name without the iac- prefix. Example: repo iac-distribution → stack distribution → bucket eigenoid-2cea55-distribution-tfstate-dev.

For more detail, see the IaC Bootstrap runbook and ADR-0012.

Verification​

# Verify the repo exists
gh repo view eigenoid/NAME

# Verify applied settings
gh api repos/eigenoid/NAME --jq '{private: .private, archived: .archived, description: .description}'

# IaC repos only — verify created buckets
for env in dev qa prd; do
  gcloud storage buckets describe gs://eigenoid-2cea55-STACK-tfstate-$env 2>&1 | head -3
done
bash

Emergency override​

Org owners can create repos manually (bypassing the repository lifecycle ruleset), but:

  1. safe-settings will apply the org defaults on the next CRON sync
  2. If the repo needs custom config, create the YAML manually in .github/repos/<name>.yml
warning

Repos created manually do not have an audit trail via issue. Always prefer the issue template flow.

Escalation​

If the workflow fails or the repo is not created after 5 minutes:

  1. Check the workflow logs in platform-settings → Actions
  2. Check the safe-settings logs in Cloud Run (see operational guide)
  3. Contact @shoootyou

References​