Sync Identity

Sync description, homepage URL, and topics to a GitHub repository from nova.config.json.

Summary

The sync-identity recipe pushes repository identity fields from nova.config.json to GitHub using gh repo edit and gh api -X PUT /repos/.../topics. It acts as the authoritative source for the repository's public description, homepage, and topic tags.

If all three fields (description, homepage, and topics) are undefined in the config, the recipe no-ops and emits a warning.

Why Use This Command?

1. Keeps the public repository description, homepage, and topics aligned with the same project metadata used elsewhere.
2. Normalizes derived topics so invalid GitHub topic values do not need manual cleanup.
3. Makes identity updates repeatable after branding or ownership changes.

Requirements

• gh CLI ≥ 2.40.0 — The GitHub CLI must be installed and authenticated.
• Repository write access — The authenticated user must have write access to the target repository.
• github.owner and github.repo — Both fields must be set in nova.config.json to identify the target repository.

Behavior

• description — Sourced from project.description.short in nova.config.json. If undefined, the field is skipped.
• homepage — Sourced from urls.homepage. If undefined, the field is skipped.
• topics — Sourced from github.topics if set. If github.topics is not defined, topics are derived from project.keywords using the normalization rules below. If github.topics is set to an empty array ([]), all topics are cleared on GitHub.

Topic normalization rules applied to project.keywords when github.topics is not set:

• Converted to lowercase.
• Spaces and underscores replaced with hyphens.
• Characters outside [a-z0-9-] are stripped.
• Duplicates are removed.
• Topics longer than 50 characters are dropped and a warning is emitted.
• Capped at 20 topics.

Settings

This project-scoped recipe is enabled under recipes.github in nova.config.json:

{
  "recipes": {
    "github": {
      "sync-identity": {
        "enabled": true
      }
    }
  }
}

Usage

Options