Set Shared GitHub Defaults with a .github Repository¶

Every GitHub account, whether a personal profile or an organization with dozens of developers, eventually accumulates the same boilerplate problem. You add a CONTRIBUTING.md to one repository, a CODE_OF_CONDUCT.md to another, issue and pull request templates to a third, and none of them are consistent. When someone opens a new repository, they either copy files from an older one (hoping they are still current) or start from scratch.

GitHub has a solution to help set defaults: the .github repository. It is a specialized repository you create under your personal account or organization that acts as a default configuration layer for every repository that does not define its own. One place to maintain community health files, contribution guidelines, security policies, issue templates, and (for organizations) standardized workflow templates that appear in the Actions UI across every repository in the org.

This post covers what a .github repository is, what goes inside it, how to set one up, and an honest look at the benefits and the tradeoffs.

What Is a .github Repository?¶

The .github repository is a GitHub-recognized special repository. When you create a public repository named .github under your account or organization, GitHub treats the files inside it as defaults. Any repository under that account or org that does not have its own version of a supported file will fall back to the one in .github.

The scope depends on who owns it:

• Personal: Default files apply to all your public repositories that lack their own.
• Organization: Default files apply to all repositories in the organization, public or private, that lack their own version. Organizations also unlock two additional capabilities: a profile README and workflow starter templates.

It does not override anything. If a repository has its own CONTRIBUTING.md, that file is used. The .github repository only fills the gap when there is nothing else there.

What Goes Inside¶

Community Health Files¶

The primary purpose of a .github repository is to host community health files. These are the files GitHub surfaces during contributor interactions (issue creation, pull request submission, the repository's Insights > Community Standards page).

The supported default community health files are:

These files can be placed in the root of the .github repository, in a docs/ subdirectory, or in a .github/ subdirectory within the repository. The root is the most common location and the most straightforward to navigate.

A minimal .github repository for a personal account might look like this:

.github/
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── SECURITY.md
├── SUPPORT.md
└── ISSUE_TEMPLATE/
    ├── bug.yml
    └── feature.yml

Issue Templates¶

In a regular repository, issue templates live in .github/ISSUE_TEMPLATE/. In the .github repository itself, place them in ISSUE_TEMPLATE/ at the root, not inside a nested .github/ subdirectory. The directory tree shown above reflects this: ISSUE_TEMPLATE/ is a top-level entry in the .github repository.

Issue templates support two formats: the original Markdown style (.md files) and the newer YAML form style (.yml files). The YAML form style is recommended: it renders as a structured web form with labeled fields, dropdowns, and validation, rather than a freeform text block.

A basic bug report form:

name: Bug Report
description: Report a problem with the project
title: "bug: "
labels: ["bug", "triage"]
body:
  - type: markdown
    attributes:
      value: |
        Thanks for taking the time to report a bug. Please fill out the
        sections below as completely as you can.
  - type: textarea
    id: description
    attributes:
      label: What happened?
      description: A clear description of the bug.
    validations:
      required: true
  - type: textarea
    id: expected
    attributes:
      label: What did you expect to happen?
    validations:
      required: true
  - type: textarea
    id: reproduce
    attributes:
      label: Steps to reproduce
      placeholder: |
        1. ...
        2. ...
    validations:
      required: true
  - type: input
    id: version
    attributes:
      label: Version
      placeholder: "v1.0.0"
    validations:
      required: true

A config.yml file alongside the templates controls whether GitHub shows a link to open a blank issue or requires contributors to use a template:

blank_issues_enabled: false
contact_links:
  - name: Sponsor this Project
    url: https://github.com/sponsors/tenthirtyam
    about: Support this project by sponsoring it on GitHub.
  - name: Buy Me a Coffee
    url: https://buymeacoffee.com/tenthirtyam
    about: Support this project by buying me a coffee.

Setting blank_issues_enabled: false ensures every issue is structured. Combined with required fields in the YAML form, this produces dramatically more actionable bug reports with almost no extra friction on the contributor's side.

Pull Request Template¶

A pull request template pre-populates the description field when contributors open a new pull request. Place it at PULL_REQUEST_TEMPLATE.md in the root of the .github repository:

<!-- markdownlint-disable first-line-h1 no-inline-html -->

<!--
    In order to have the best experience with our community, we recommend that you read
    the code of conduct and contributing guidelines before submitting a pull request.

    By submitting this pull request, you confirm that you have read, understood, and
    agreed to the project's code of conduct and contributing guidelines.

    Please use conventional commits to format the title of the pull request and the
    commit messages. For more information, please refer to https://www.conventionalcommits.org.
-->

### Summary

<!--
    Please provide a clear and concise description of the pull request.
-->

### Type

<!--
    Please check the one(s) that applies to this pull request using "x".
-->

- [ ] Bugfix
- [ ] Enhancement or Feature
- [ ] Code Style or Formatting
- [ ] Documentation
- [ ] Refactoring
- [ ] Chore
- [ ] Other:

### Breaking Changes?

<!--
    Please check the one that applies to this pull request using "x".
-->

- [ ] Yes, there are breaking changes.
- [ ] No, there are no breaking changes.

### Test and Documentation

<!--
    Please check the one(s) that applies to this pull request using "x".
-->

- [ ] Tests have been completed.
- [ ] Documentation has been added or updated.

### Issue References

<!--
    Is this related to any GitHub issue(s)?
    Please use the 'Closes' keyword followed by the a hash and issue number.

    Example: Closes #000
-->

### Additional Information

<!--
    Please provide any additional information that may be helpful.
-->

This is useful even in solo projects. The act of filling out a template before merging forces you to articulate what you changed and why, which pays off when you review the pull request history six months later.

Security Policy¶

A SECURITY.md file tells users and researchers how to report vulnerabilities responsibly. GitHub surfaces a link to this file in the repository's Security tab under the Policy section and highlights it on the Community profile page (visible under the Insights tab).

# Security Policy

## Supported Versions

| Version | Supported |
|---------|-----------|
| 1.x     | :white_check_mark: |
| < 1.0   | :x: |

## Reporting a Vulnerability

Please do not report security vulnerabilities through public GitHub issues.

Instead, use [GitHub's private vulnerability reporting](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability).

You can expect an acknowledgment within 48 hours and a response within 7 days.
If the issue is confirmed, we will release a patch as soon as possible.

Funding¶

The FUNDING.yml file adds a Sponsor button to every repository. It supports GitHub Sponsors, Open Collective, Ko-fi, Liberapay, Patreon, Tidelift, and custom URLs:

github: [tenthirtyam]
ko_fi: tenthirtyam
custom:
  - https://buymeacoffee.com/tenthirtyam

If you have multiple repositories and want the same sponsorship options visible everywhere, a single FUNDING.yml in .github handles all of them.

Organization Profile README¶

For organizations, a profile/README.md file in the .github repository becomes the organization's GitHub profile page. When anyone visits https://github.com/<org>, GitHub renders this file in place of the default empty profile. It is visible to any signed-in or anonymous user who lands on the organization's page, making it a high-value, low-maintenance space to communicate who your organization is, what you build, and how to engage.

.github/
└── profile/
    └── README.md

A minimal organization profile:

## Office Space Example

We build open-source tools for enterprise workflow automation.

- **Documentation**: [docs.office-space-example.example](https://docs.office-space-example.example)
- **Community**: [GitHub Discussions](https://github.com/orgs/office-space-example/discussions)

This renders directly at https://github.com/office-space-example; no separate configuration is required beyond committing the file to the correct path.

The profile README supports all standard GitHub Markdown: badges, images, tables, and the full set of GitHub-flavored Markdown extensions. Organizations use this space for everything from mission statements and technology overviews to featured repositories and contributor statistics embedded via third-party badge services.

Workflow Starter Templates (Organizations Only)¶

This is the feature that makes the .github repository compelling beyond community health files. Organizations can define workflow starter templates that appear in the GitHub Actions UI when any repository member clicks Actions > New workflow.

The templates live in the workflow-templates/ directory at the root of the .github repository:

.github/
└── workflow-templates/
    ├── go-ci.yml
    ├── go-ci.properties.json
    ├── python-ci.yml
    └── python-ci.properties.json

Each workflow template is paired with a .properties.json file that defines its metadata:

{
  "name": "Go CI",
  "description": "Build, test, and lint Go projects.",
  "iconName": "octicon-mark-github",
  "categories": ["Go"]
}

And the template itself is a standard GitHub Actions workflow:

name: Go CI

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - name: Setup Go
        uses: actions/setup-go@4b73464bb391d4059bd26b0524d20df3927bd417 # v6.3.0
        with:
          go-version-file: go.mod
          cache: true
      - name: Download Dependencies
        run: go mod download
      - name: Build
        run: go build ./...
      - name: Test
        run: go test ./... -v -race -coverprofile=coverage.out
      - name: Lint
        uses: golangci/golangci-lint-action@1e7e51e771db61008b38414a730f564565cf7c20 # v9.2.0
        with:
          version: latest

When a developer in the organization opens a new repository and navigates to the Actions tab, the organization's custom templates appear alongside GitHub's own starter templates, clearly labeled with the organization's name. Clicking a template copies it into the repository's workflow file editor with the metadata pre-filled. No searching, no copying from another repo, no guessing at the correct pinned version.

For organizations running consistent CI/CD patterns (same lint tools, same test runners, same deployment targets), starter templates are the highest-leverage thing the .github repository enables.

Setting Up a .github Repository¶

For a Personal Account¶

1. Go to https://github.com/new.
2. Set the Repository name to .github.
3. Set the visibility to Public (required for the defaults to apply to your repositories).
4. Initialize with a README if you want, or skip it.
5. Click Create repository.

Then add the files you need. The repository can be as minimal as a single CONTRIBUTING.md or as comprehensive as the full set of community health files and issue templates.

For an Organization¶

The process is the same, but the repository must be created under the organization, not under your personal account:

1. Go to https://github.com/organizations/<org-name>/repositories/new.
2. Set the repository name to .github.
3. Set the visibility to Public (required).
4. Create the repository and add your files.

For organizations, this is also the right time to add the profile/README.md and to start building out workflow-templates/.

The Case For a .github Repository¶

Consistency Without Duplication¶

Without a .github repository, maintaining consistent community files across multiple repositories means one of three things: keeping them all manually in sync (tedious and error-prone), writing automation to push updates across repos (possible but complex), or accepting that each repository's files drift from the standard over time (almost always what happens in practice).

A .github repository makes consistency the default and deviation the explicit choice. Update CONTRIBUTING.md once, and every repository that uses the default picks up the change automatically.

Lower Barrier to Creating New Repositories¶

When every new repository inherits a complete set of community health files, issue templates, and (in organizations) CI starter templates, the cost of starting a new project drops significantly. You are not starting from nothing; you are starting from a known, established baseline.

This matters most in organizations where teams create repositories frequently and where inconsistency creates real coordination overhead: contributors confused about process, reviewers managing unstructured bug reports, security teams with no clear escalation path for vulnerabilities.

Professionalism in Open Source¶

For open-source projects, community health files signal that the project is organized and contributor-friendly. GitHub's Community Standards checklist (visible under a repository's Insights tab) grades repositories on whether they have a description, README, code of conduct, contributing guide, license, security policy, and other community health files. A .github repository gets you most of the way there for every repository without any per-repo effort.

Workflow Standardization at Scale¶

For organizations, the workflow templates feature is uniquely powerful. It is the difference between "we have a policy about how CI should work" and "the policy is the path of least resistance." When the correct workflow template is one click away in the Actions UI, teams use it because it is convenient, not because they were told to.

The Case Against¶

It Only Fills Gaps¶

The .github repository provides defaults, not mandates. Any repository with its own version of a file will use that version regardless of what is in .github. If your goal is to enforce standards across repositories (not just provide defaults), you need additional tooling: organization policies, Terraform to codify repository settings, or repository rulesets to enforce branch protection.

The .github repository handles the "nobody thought about it" case well. It does not handle the "someone intentionally diverged" case.

Visibility Without Discoverability¶

Contributors who visit a specific repository will see its community health files (whether defined locally or inherited from .github), but they may not immediately know that these files live in a separate repository. If they want to propose changes to CONTRIBUTING.md, they have to know to look in the .github repository rather than the one they are visiting.

This is usually a minor friction point, but it is worth noting. A comment at the top of default files pointing to the source can help:

<!-- This file is maintained in https://github.com/office-space-example/.github -->

The Repository Must Be Public¶

Default community health files only work if the .github repository is public. For organizations concerned about exposing internal process documentation, this means making decisions about what level of detail to include in files like CONTRIBUTING.md and SECURITY.md. Anything in the .github repository is visible to anyone on the internet.

Internal process details, escalation paths involving specific team members, or links to internal tooling are better kept in private wikis or internal documentation systems rather than in community health files.

Workflow Templates Do Not Enforce Anything¶

Starter workflow templates appear as suggestions in the Actions UI. They are not required. A developer can ignore them entirely and write their own workflow from scratch, or add an existing workflow from another source. Templates lower the friction for doing the right thing; they do not prevent doing something different.

If you need to enforce specific workflow steps (required security scans, mandatory deployment gates, specific environment configurations), required status checks on branch protection rules are the right mechanism, not starter templates.

Maintenance Is Still Required¶

A .github repository is not "set it and forget it." Tool versions get stale. Processes change. New file types get added. If you set up the repository and then ignore it for two years, contributors will find outdated instructions and issue templates that do not match the current project.

A quarterly review cycle is reasonable for most projects. For organizations, consider assigning ownership in a CODEOWNERS file and scheduling periodic audits as part of the team's maintenance calendar.

Putting It Together¶

A well-structured .github repository for an organization looks like this:

.github/
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── GOVERNANCE.md
├── FUNDING.yml
├── SECURITY.md
├── SUPPORT.md
├── CODEOWNERS
├── ISSUE_TEMPLATE/
│   ├── config.yml
│   ├── bug.yml
│   └── feature.yml
├── PULL_REQUEST_TEMPLATE.md
├── DISCUSSION_CATEGORY_FORMS/
│   └── general.yml
├── profile/
│   └── README.md
└── workflow-templates/
    ├── go-ci.yml
    ├── go-ci.properties.json
    ├── python-ci.yml
    └── python-ci.properties.json

A personal account repository starts smaller and grows as needed:

.github/
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── SECURITY.md
├── SUPPORT.md
├── FUNDING.yml
└── ISSUE_TEMPLATE/
    ├── config.yml
    ├── bug.yml
    └── feature.yml

Neither structure is a template to copy verbatim. Start with the files that solve the most immediate problem: a shared CONTRIBUTING.md if contributors keep asking the same process questions, a SECURITY.md if you have open-source projects with no vulnerability disclosure path, issue templates if you keep receiving reports without enough information to act on. Add the rest when it becomes useful.

Is It Worth It?¶

For a single personal repository: probably not. The overhead of maintaining a separate .github repository does not pay off if you only have a handful of repos that rarely receive outside contributions.

For a personal account with many active open-source projects: yes. The consistency benefit alone justifies the setup time, and updating a single file is significantly easier than updating a dozen.

For an organization of any size: yes, immediately. The combination of default community health files, standardized issue templates, and workflow starter templates addresses real coordination problems that every organization running multiple repositories encounters. The .github repository is not flashy, but it is the kind of infrastructure investment that quietly removes friction from every project it covers.

References¶

• CONTRIBUTING.md: Writing Practical Contribution Guidelines for GitHub Repositories
• CODEOWNERS: Automating Code Review Ownership
• Configuring the GitHub Issue Template Chooser
• Why You Should Pin GitHub Actions to Commit Hashes
• GitHub Docs: Creating a default community health file
• GitHub Docs: Configuring issue templates for your repository
• GitHub Docs: Creating starter workflows for your organization
• GitHub Docs: Customizing your organization's profile
• GitHub Docs: About security policies