GitHub Repository Management: README, CODEOWNERS, Templates and Insights (GH-900)

A GitHub repository is a Git repository hosted on GitHub: the project's files and folders, their full commit history and branches, plus GitHub features around them such as issues, pull requests, settings and the Insights tab. A handful of conventionally named files tell visitors and contributors how the project works, and GitHub recognises them and surfaces them in its interface.

CONTRIBUTING, CODE_OF_CONDUCT, SUPPORT and SECURITY, together with issue and pull request templates and FUNDING.yml, are called community health files. Most of them can also be supplied once for a whole account or organization (see the default community health files section). The near-twins matter: each file answers one question, and picking the right one means matching the need to that question.

A README is the file GitHub renders automatically on a repository's main page, so it is where you explain what the project does, why it is useful, how to install and start using it, where to get help and who maintains it. It is usually written in Markdown (README.md), and GitHub builds an outline from its headings so readers can jump between sections. Very large READMEs are truncated when displayed.

Which README is shown when there are several

GitHub recognises a README in three places: the hidden .github folder, the repository root and the docs folder. If more than one exists, GitHub shows the first it finds in this order:

1. .github/README.md
2. README.md in the root
3. docs/README.md

So a README in .github wins over the root copy. When an edit to the root README "does nothing" on the main page, a second README in .github is the usual reason.

Profile READMEs

A README can also introduce a person or organization:

• Personal profile: create a repository whose name exactly matches your username (for user octo-dev, a repository named octo-dev), make it public, and add a non-empty README.md to its root. GitHub then shows that README at the top of your profile page; the repository must stay public for it to display.
• Organization profile: add profile/README.md to the organization's public .github repository.

LICENSE says what others may legally do with the code, CONTRIBUTING says how to contribute, CODE_OF_CONDUCT says how to behave, SUPPORT says where to get help and SECURITY says how to report a vulnerability: each file answers one question, and the right file is the one whose question matches the need.

LICENSE: what others may do with the code

A license grants permissions that copyright law otherwise withholds. Without a license, default copyright applies: the author keeps all rights, and nobody may reproduce, distribute or create derivative works from the code. Publishing a public repository does not change this. Under GitHub's Terms of Service, other users can still view and fork a public repository on GitHub, but that is not permission to reuse the code in their own product. GitHub applies no default license. You can choose one with the license picker when creating a repository, or add a LICENSE file later in the root, where GitHub detects it and shows it in the About sidebar.

CONTRIBUTING.md versus its neighbours

SECURITY.md: a policy, not a scanner

A security policy tells researchers which versions are supported with security updates and how to report a vulnerability instead of opening a public issue. It is documentation only: adding it does not turn on Dependabot, code scanning or any other feature. Like the other health files it can live in the root, docs or .github, and an account or organization can provide a default one.

A CODEOWNERS file assigns owners (users or teams) to paths in the repository, and GitHub automatically requests a review from those owners whenever a pull request changes matching files. Instructions in a pull request template or CONTRIBUTING.md rely on authors remembering; CODEOWNERS does not.

*            @northwind/core
/frontend/   @northwind/ui-team
*.css        @northwind/design

The rules that decide what happens:

• Location: .github/, the root or docs/; GitHub searches in that order and uses the first file it finds.
• Last matching pattern wins. For each changed file, only the owners on the last line that matches it are requested; lines are not merged. In the example, a change to /frontend/styles/theme.css matches all three lines, so only the owners on the *.css line are requested; a change to /frontend/app.js matches the first two, so the /frontend/ owners are requested. To give one path several owners, list them on one line.
• Base branch: each branch can have its own CODEOWNERS file, and requests come from the copy on the pull request's base branch. A CODEOWNERS file still sitting on an unmerged feature branch has no effect on pull requests into main.
• Write access: owners must have write permission to the repository, and a team must be visible and have write access.
• Drafts: owners are not requested while a pull request is a draft; requests go out when it is marked ready for review.

Requesting is not requiring. Review requests from CODEOWNERS happen automatically. Making a code owner's approval mandatory before merging is a separate, optional setting ("Require review from Code Owners") in a branch protection rule or ruleset.

An account or organization can provide default community health files from a public repository named .github. Every repository in that account that has no file of a given type uses the default automatically, so existing and future repositories are covered without copying files around.

• Supported defaults: CODE_OF_CONDUCT.md, CONTRIBUTING.md, SUPPORT.md, SECURITY.md, GOVERNANCE.md, FUNDING.yml, and issue and pull request templates (including .github/ISSUE_TEMPLATE and its config.yml).
• The .github repository must be public. A private .github repository does not supply defaults.
• No default LICENSE. License terms must be added to each repository individually.
• Defaults never merge with a repository's own files. A repository's own file of a type replaces the default for that type. For issue templates, if the repository's own .github/ISSUE_TEMPLATE folder contains any valid template or a config.yml, none of the default folder is used, so contributors see only the repository's own templates. Other types still fall back to the default independently.

A template repository is not a substitute: it only seeds files into repositories generated from it, once, and does nothing for repositories that already exist.

Community standards (community profile)

For public repositories, Insights > Community standards shows a checklist of recommended items (description, README, code of conduct, contributing guidelines, license, security policy, issue and pull request templates) and marks each as added or not yet added. Next to a missing item, a maintainer clicks Add to draft and commit the file. A contributor without write access clicks Propose instead, which drafts the file and sends it to the maintainers for approval. The checklist is informational: it never blocks merging.

You create a repository with New repository (the + menu or the Repositories tab), and the form asks for a few things: the owner (your personal account or an organization you can create repositories in), a name unique within that owner, an optional description, the visibility (public, private, or internal for enterprise organizations), and whether to initialize it with a README, a .gitignore template and a license. Instead of starting empty, you can also pick a template in the same form.

Template repositories

A template repository is a repository marked as a template in its settings, so that anyone with access can generate new repositories that start with the same files and folders but none of its history. It is the right tool when every new project should begin from the same skeleton (folders, workflow files, a README outline) and be fully independent.

Details about generated repositories:

• With Include all branches, every branch's files arrive, but each branch starts with its own unrelated history, so you cannot open pull requests between the template and the new repository.
• A template repository cannot include files stored with Git LFS; those must be added to the new repository another way.
• A template is a one-time copy: later commits to the template do not flow into repositories already generated from it.

The default branch

The default branch is the branch GitHub shows when someone opens the repository and the base that new pull requests target unless the author chooses another. New repositories use main unless the account or organization sets a different default name. A repository admin can switch it to another branch or rename it in the repository settings.

Renaming a branch on GitHub (for example master to main) automatically retargets open pull requests that use it as their base, moves branch protection to the new name and redirects web links to files under the old name. It cannot touch anyone's computer: each local clone keeps the old name until its owner updates it (GitHub shows the commands after a default-branch rename), and workflows or raw URLs that hard-code the old name need editing too.

You can add, edit, move and delete files directly on GitHub in the browser, without installing Git; every change becomes a commit in the repository's history.

• Add file > Create new file opens the editor for a new file; typing folder/ in the name creates folders.
• Add file > Upload files, or dragging files onto the page, uploads files from your computer (up to 100 files at a time).
• Move or rename a file by editing it and typing a folder name followed by / in front of the filename (a new folder is created if needed), then committing. GitHub shows this as a rename of one file, whereas deleting it and uploading a copy produces a separate deletion and addition. (Git itself stores no move record; it infers a rename from the content being the same.)
• Delete a file from its menu and commit.

Content attached to an issue, added as a release asset or written in the wiki is stored on GitHub but is not part of the repository's tracked files.

Commit directly or through a pull request

When committing in the browser you choose between committing directly to the current branch and creating a new branch for this commit and starting a pull request. The new-branch option keeps the default branch untouched until the change has been reviewed and merged, which is what a review-first policy expects. Committing in the browser at all requires write access to the repository; people without it edit a fork and propose the change from there.

File size limits

Pick the simplest method each file allows: a file over 25 MiB but under 100 MiB needs Git rather than the browser, and only files over 100 MiB need Git LFS.

The Insights tab is GitHub's built-in metrics dashboard for a repository: a set of graphs and pages that show activity, people, traffic and dependencies.

Plan limits: on GitHub Free (personal accounts and organizations), repository graphs are available only for public repositories. GitHub Pro, Team and Enterprise Cloud show them for private repositories too. Visibility of a graph therefore depends on two independent things: your permission on the repository and the plan of the account that owns it.

Dependency graph

The repository dependency graph (Insights > Dependency graph) is built from the repository's manifest and lock files. Its Dependencies view lists the packages the project uses, with versions, licenses and known vulnerabilities, and you can export it as a software bill of materials (SBOM). For public repositories, its Dependents view lists other public repositories and packages that use this one. It is about packages, not about people or commit history.

Organization dependency insights

Organizations on GitHub Enterprise Cloud get dependency insights on the organization's Insights tab: one view across the organization's repositories of open security advisories and licenses in the open source projects they depend on, with links to the repositories using each dependency. It relies on the dependency graph and is in maintenance mode (no new features), but it remains the organization-wide counterpart to each repository's dependency graph.

Starring a repository bookmarks it for you and shows appreciation to its maintainers; watching a repository subscribes you to notifications about its activity. They are independent: you can star without watching.

Starred repositories can be grouped into lists (for example "Rust tools"), created from your stars page or from the Star dropdown on a repository. Lists are public and appear on your stars page; a private repository in a list is visible only to people who can already read it. Topics, by contrast, are set by a repository's maintainers to describe that repository.

Feature preview and release stages

GitHub releases many features in stages:

• Private preview: available only to selected customers.
• Public preview: anyone can try it, but it may still change and comes without full support or SLAs.
• General availability (GA): fully released and supported.

Many interface features in public preview can be switched on or off for your own account from your profile picture menu > Feature preview, which also links to a feedback channel for each feature. This is a per-user choice, not a repository setting.

A well-maintained repository tells visitors what it is, how to use and contribute to it, and whether it is still active. The habits that make this happen:

• Make it discoverable: add a short description and topics in the About section, so people searching or browsing GitHub by topic can find and understand it.
• Keep the history clean: add a .gitignore listing build output, dependencies and local files so they are never committed. GitHub offers .gitignore templates when you create a repository.
• Publish the key files: README, LICENSE, CONTRIBUTING, CODE_OF_CONDUCT and SECURITY, plus issue and pull request templates; use the community standards checklist to spot gaps, and organization defaults from .github to cover many repositories.
• Route reviews: use CODEOWNERS so the right people are asked, and protect the default branch (branch protection is covered with security and administration).
• Retire projects by archiving, not deleting.

Archiving a repository

Archiving (repository Settings, Danger Zone) makes a repository read-only for everyone: no new issues, pull requests, comments or pushes. People can still view the code, fork it and star it, and an admin can unarchive it later. Before archiving, close open issues and pull requests and update the README and description to explain the project's status.