Skip to main content

Context​

The eigenoid org had 8 repositories with inconsistent names: some inherited from the original monorepo (SPIRE-A2A-Protocol), others with generic names (actions, settings) that did not communicate their purpose, and others following mutually incompatible patterns:

Previous nameProblem
github-org-settingsLegacy name, too long, does not follow convention
actionsGeneric name, ambiguous, collides with GitHub Actions
iac-org-shared-resourcesInconsistent with the 2-3 word pattern
public-docsInconsistent with the docs- category
access-block-pageNo category prefix
core / studioNo prefix, but legitimate exception (published packages)
internal-docsCorrect by accident, not by design

Without an explicit convention:

  • New repos were named ad-hoc with no clear guidance.
  • The repo creation issue template did not validate or suggest names.
  • safe-settings suborgs could not use predictable glob patterns.
  • Onboarding new members required explaining what each repo did on a case-by-case basis.

Decision​

We adopt a naming convention based on category prefixes for all repositories in the org:

Format​

<category>-<descriptive-name>
  • kebab-case required
  • Category prefix required (determines suborg)
  • Descriptive name concise: 2-3 words max

Categories​

PrefixDescriptionExample
iac-Infrastructure as Code (Terraform)iac-org-shared
app-Deployable applicationsapp-studio, app-block-page
docs-Documentationdocs-internal, docs-external
platform-Internal org toolingplatform-settings, platform-actions
tpl-Template repostpl-iac, tpl-app
svc-Microservicessvc-api, svc-auth

Documented exceptions​

  1. .github: GitHub convention for org-level defaults. Not modified.
  2. Published packages: use the package name as the repo name (e.g., eigenoid for the pip package). Rationale: the repo name is the public identifier of the package; renaming it would break PyPI URLs, import statements, and external references.

Renames executed​

Previous nameNew nameCategory
github-org-settingsplatform-settingsplatform
actionsplatform-actionsplatform
iac-org-shared-resourcesiac-org-sharediac
public-docsdocs-externaldocs
internal-docsdocs-internaldocs
access-block-pageapp-block-pageapp
coreeigenoidexception (package)
studioapp-studioapp

Automation​

The repo creation issue template ("Request new repository" in platform-settings) now:

  1. Category selection: dropdown with available categories + an exception option.
  2. Descriptive name: the user enters only the descriptive part; the prefix is added automatically.
  3. Validation: the workflow validates kebab-case format, allowed characters, topic length, label format, and duplicate names.
  4. Automatic suborg: the category determines the safe-settings suborg (e.g., category app → suborg app.yml).

Suborgs as a reflection of categories​

Each category with 2 or more repos has a file in .github/suborgs/ with shared configuration (labels, properties). Repos are assigned by glob pattern based on the category prefix:

# .github/suborgs/app.yml
suborgrepos:
  - "app-*"
yaml

Consequences​

  • Discoverability: any member can infer a repo's purpose from its name without consulting documentation.
  • Predictability: names of new repos are predictable before they are created.
  • Reliable globs: suborgs, CODEOWNERS, CI filters, and scripts can use <category>-* patterns with confidence.
  • GitHub redirects: the renames depend on GitHub redirects, which work for repos but not for webhooks. The safe-settings ADMIN_REPO env var had to be updated manually after the github-org-settings → platform-settings rename.
  • Rename cost: the renames required updating CI (workflows referencing repos by name), internal documentation, and Cloud Run configuration. The cost was one-time and acceptable.
  • Limited exceptions: only 2 documented exceptions (.github and published packages). Any new exception requires explicit justification.
  • Breaking change for bookmarks: old URLs redirect automatically (except for webhooks and hardcoded API calls).

Alternatives considered​

  • Prefixes only, no rename of existing repos: reduces the risk of breaking changes but leaves the historical inconsistency. Rejected: the naming debt is small (8 repos) and better to pay it now than with 50 repos.
  • Categories in topics instead of names: more flexible but less visible. A repo my-app with topic app is indistinguishable from a repo my-app with topic docs in a repo list. Topics complement, they do not replace the name.
  • Categories in GitHub custom properties: cleaner than topics but invisible in the main UI. Custom properties are useful for programmatic filters but not for human discoverability.
  • No categories, just kebab-case: simple but does not solve the discoverability problem and does not allow predictable globs for suborgs.

References​