# GitHub

URL: https://tfw.how/tools/github/
Description: How to set up and maintain one topic's code repository surface in a GitHub organization: repositories whose names start with the lowercase topic code and a hyphen, shared with teams that match the access groups.

Tool class: [Code repository](/tool-classes/code-repository/)

In GitHub, a topic's [code repository](/tool-classes/code-repository/) surface is the set of repositories in the organization's GitHub organization whose names start with the repository prefix: the lowercase [topic code](/glossary/#topic-code) and a hyphen, for example `exop-`.

## Set up the surface for one topic

These steps use the example topic Example Co Operations (topic code EXOP) and a new repository for its public website.

1. Confirm the topic in the [registry](/glossary/#registry). Use the exact topic code.
2. Search the organization's repositories for the prefix `exop-` and for the purpose. If a repository for the same purpose already exists, use it. If two exist, record a [provisioning gap](/glossary/#provisioning-gap).
3. Create the repository in the GitHub organization, not in a personal account. Name it with the prefix and the purpose: `exop-website`. GitHub repository names can contain letters, digits, hyphens, underscores, and periods. Use lowercase letters, digits, and hyphens only, so that the name matches the other surfaces.
4. Choose private visibility, or internal visibility where your GitHub plan provides it, according to the topic's [access boundary](/glossary/#access-boundary). Choose public only when the content is meant to be public, and record that choice in the [topic profile](/glossary/#topic-profile).
5. Write the description: one sentence that names the topic code and the purpose, for example "EXOP Example Co Operations: the public website."
6. Add the repository topic `exop`. GitHub repository topics are lowercase labels that people can search and filter by.
7. Add a README that states the purpose and links to the topic's `Space Purpose and Usage` page and its project.
8. Add a short agent instructions file at the root of the repository (see Settings).
9. Grant access to the teams that match the topic's access groups (see Permissions).
10. Protect the default branch, so that changes reach it through pull requests.
11. Add the repository link to the topic profile and to the Topic Surfaces table of the [purpose page](/glossary/#purpose-page).

## Settings

- **Name.** The prefix and the purpose: `exop-website`, `exop-inventory-sync`. Renaming a repository in GitHub redirects the old address, but a new repository created with the old name replaces the redirect. When you rename an older repository to add the prefix, record the old name as an [alias](/glossary/#alias) until links are updated.
- **Description and repository topics.** The description names the code and the purpose. The repository topic `exop` lets a person or an agent list every repository of the topic. If the organization uses custom properties for repositories, add the custom property `topic_code`, of the single select type, with the topic codes from the registry as its values, for example `EXOP`. Repository topics stay lowercase, for example `exop`, because GitHub requires lowercase repository topics.
- **Agent instructions file.** A short Markdown file at the root, for example `AGENTS.md`. Some agents read a file with their own name, such as `CLAUDE.md`; if you need one, keep it short and point it to the same content. The file states which topic the repository belongs to, what the repository is for, how to build and test it, where task status is kept, and where the topic's other records are. It links to those records. It does not copy them, and it contains no credentials.
- **Issues.** Task status for the topic is kept in [task management](/tool-classes/task-management/). If the repository does not use GitHub Issues, turn the feature off in the repository settings so that people do not file work in two places. If it does use them, for example for public bug reports, state in the README how an issue becomes an action record in the topic's project.
- **Links to task management.** Put the action record key in the branch name, the commit message, or the pull request title, for example `EXOP-42`. Integrations between GitHub and task management products use the key to link the change to the record. GitHub autolink references can also turn the key into a link.
- **Branch protection.** Use a branch protection rule or a ruleset on the default branch: require a pull request, require at least one approving review, and block force pushes. A `CODEOWNERS` file can name the team that reviews each part of the repository.
- **Secrets.** Store tokens and keys that automation needs as GitHub Actions secrets or in the organization's secrets manager. Turn on secret scanning and push protection where your plan includes them.

## Permissions

GitHub grants repository access through organization membership, teams, and repository roles. The repository roles are Read, Triage, Write, Maintain, and Admin.

- Create teams that match the topic's [access groups](/glossary/#access-group): the venture group, the unit group, and the topic group, for example `exampleco-venture`, `operations-unit`, and `exop-topic`. Membership in any one of them grants access. GitHub teams can be nested, so a team can be a child of another team.
- Grant each repository of the topic to those teams with the role they need, usually Write for the topic group and Read for the venture and unit groups. Do not add people to the repository one by one.
- Give the Admin role to the [maintainer](/glossary/#maintainer) and one backup.
- Set the organization's base permission for members to no access or Read, according to the organization's policy, so that access comes from the teams.
- Outside collaborators are an exception to the access boundary. Record each one in the topic profile with the reason and an end date.
- A GitHub App or a deploy key used by automation has access only to the repositories it needs.

## Maintenance

The maintainer checks the repositories of the topic on a regular schedule:

- Every repository of the topic has the prefix, the repository topic, and a description that names the code.
- Every repository with the prefix is listed in the topic profile. A repository with the prefix that is not listed is either added or renamed.
- The agent instructions file and the README still link to the current records.
- Team access still matches the access groups. No individuals or outside collaborators have access without a recorded exception.
- Branch protection is still in place on the default branch.
- Open secret scanning alerts are resolved. A token that was committed is revoked and replaced, because it stays in the change history.

When the topic becomes [inactive](/glossary/#inactive), or a repository is no longer used:

1. State in the README that the repository is no longer maintained, and link to any topic or repository that took over the work.
2. Remove automation that deploys from the repository, and revoke its tokens.
3. Archive the repository. An archived repository is read-only and keeps its history.
4. Update the topic profile and the purpose page.

## Agent notes

- Resolve the topic first. Find the repositories by the prefix `exop-`, the repository topic `exop`, or the topic profile. Do not assume a repository belongs to a topic only because the purpose sounds similar.
- Read the agent instructions file and the README before you change the repository.
- Put the action record key in the branch name, the commits, and the pull request title.
- Work on a branch and open a pull request. Do not push directly to the default branch, merge a pull request, or change repository settings without approval.
- Never commit credentials, keys, or tokens. If you find one, report it; do not copy it into a message.
- A pull request discussion is [conversation](/glossary/#conversation). Write a decision that must last to its source of truth and link to it from the pull request.