github-repository

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:

   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. Extend for a settings pass only when settings are in scope: the settings baseline appends merge policy, sidebar features, and secret scanning to the same args, then enables Dependabot security updates, hardens Actions, locks releases, and protects a public repository after the edit.

5. Apply once with gh repo edit "$repository" "${args[@]}".

6. Verify with the same gh repo view --json ... fields and report the ones that changed; a settings pass also runs the guide's read-back, which covers fields gh repo view does not expose.