GitHub Repository

Derive a repository's description, homepage, and topics from its codebase and apply the requested fields with gh repo edit. For a new solo-maintained repository or an explicitly requested settings pass, use the settings baseline; a metadata-only request does not include merge policy, sidebar features, or security settings.

Workflow

Use gh for account selection, repository identity without printing raw remote URLs, bounded API calls, and request serialization when needed.

1. Extract metadata from the codebase:
   • Project metadata: Python pyproject.toml ([project] name, description, and URLs).
   • README.md: the first paragraphs give a one-line description under ~140 characters.
   • Homepage: use the configured, verified canonical site; do not infer a live Pages site merely from the repository name.
   • Topics: 3 to 6 lowercase tags for language, frameworks, tools, or domain (agent, python, cli); letters, numbers, and hyphens only, 50 characters max, 20 per repository.

2. Inspect the current state so the edit stays idempotent; stop when there is no GitHub remote or gh is not authenticated. Shell variables do not persist between agent tool calls, so run this step and the edit as one script:

   state="$(gh repo view --json nameWithOwner,visibility,description,homepageUrl,repositoryTopics)"

3. Build one scoped edit: include only the requested metadata flags; add the desired topics and remove obsolete ones only when replacing the set:

   repository="$(jq -r .nameWithOwner <<<"$state")"
   desired_topics=(tag1 tag2 tag3)
   args=(--description "<description>" --homepage "<homepage-url>")
   for topic in "${desired_topics[@]}"; do args+=(--add-topic "$topic"); done
   while IFS= read -r topic; do
     [[ " ${desired_topics[*]} " == *" $topic "* ]] || args+=(--remove-topic "$topic")
   done < <(jq -r '(.repositoryTopics // [])[].name' <<<"$state")

4. Apply once with gh repo edit "$repository" "${args[@]}".
5. Verify with the same gh repo view --json ... fields and report the ones that changed.
6. Run the settings pass only when settings are in scope: the settings baseline script applies merge policy, sidebar features, secret scanning, Dependabot security updates, Actions hardening, immutable releases, and public-repository protection in its own run, then prints a read-back that covers fields gh repo view does not expose.

Task guides

• settings-baseline: Apply or check the solo-maintainer merge, feature, secret-scanning, Dependabot, Actions, immutable-release, and branch-protection baseline with one script.

Gotchas

• Avoid description truncation: keep the description single-line and under ~140 characters or the GitHub UI truncates it.
• Change visibility only on request: never pass --visibility or --accept-visibility-change-consequences unless the user explicitly asks.

Documentation

• gh repo edit manual
• Releases: GitHub CLI
• Companion skills: github-pull-request (PR titles feed the squash message), project-license (LICENSE), project-scaffolding (bootstrap).