GitHubの.githubリポジトリ完全ガイド：テンプレート一元管理

GitHubで複数のリポジトリを管理していると、イシューテンプレートやCONTRIBUTING.mdを各リポジトリにコピーする作業が面倒になります。

実は、.githubという名前のリポジトリを作成すると、これらのファイルを一箇所で管理できます。

この記事では、GitHubの公式ドキュメントを参照しながら、.githubリポジトリの機能を網羅的に解説します。

.githubリポジトリとは

.githubリポジトリは、デフォルトのCommunity Health Filesを保管するための特殊なリポジトリです。

基本的な仕組み

  1. username/.github（個人）または organization-name/.github（組織）という名前でリポジトリを作成
  2. その中にテンプレートやポリシーファイルを配置
  3. 他のリポジトリに該当ファイルがない場合、.githubリポジトリのファイルがフォールバックとして使われる
hasegawa496/.github/          ← 特殊リポジトリ
└── .github/
    ├── ISSUE_TEMPLATE/       ← イシューテンプレート
    ├── PULL_REQUEST_TEMPLATE.md
    └── CONTRIBUTING.md

hasegawa496/my-project/       ← 通常のリポジトリ（テンプレートなし）
└── （.githubフォルダなし）
    ↓
    .github リポジトリのテンプレートが自動適用される

PUBLIC必須

重要: .githubリポジトリはパブリックである必要があります。

プライベートに設定すると、フォールバック機能が動作しません。これは個人アカウントでもOrganizationでも同様です。

なお、GitHub、Microsoft、Googleなど主要な組織も.githubリポジトリを公開しています。Community Health Filesは機密情報を含まない前提で設計されているためです。

フォールバック対象ファイル一覧

公式ドキュメントによると、以下のファイルがフォールバック対象です。

対応ファイル

ファイル用途
ISSUE_TEMPLATE/イシュー作成時のテンプレート
PULL_REQUEST_TEMPLATE.mdPR作成時のテンプレート
CONTRIBUTING.mdコントリビューションガイド
CODE_OF_CONDUCT.md行動規範
SECURITY.mdセキュリティポリシー・脆弱性報告方法
SUPPORT.mdサポート情報・問い合わせ先
FUNDING.ymlスポンサーボタンの設定
GOVERNANCE.mdプロジェクトのガバナンス
Discussion category formsディスカッションのテンプレート

ファイルの配置場所

GitHubは以下の順序でファイルを検索します。

  1. .github/ フォルダ
  2. リポジトリのルート
  3. docs/ フォルダ

ただし、イシューテンプレートとその設定ファイル（config.yml）は.github/ISSUE_TEMPLATE/に配置する必要があります。

対象外: LICENSE

LICENSEファイルはフォールバック対象外です。

ライセンスはリポジトリのクローン、パッケージング、ダウンロード時に含まれる必要があるため、各リポジトリに個別に配置する必要があります。

イシューテンプレートの設定例

実際の設定例を示します。

ディレクトリ構成

.github/
└── .github/
    └── ISSUE_TEMPLATE/
        ├── bug.yml
        ├── feature.yml
        ├── task.yml
        └── config.yml

テンプレートファイルの例

# bug.yml
name: バグ報告
description: バグや不具合を報告する
labels: ["bug"]

body:
  - type: textarea
    id: summary
    attributes:
      label: 概要
    validations:
      required: true

  - type: textarea
    id: steps
    attributes:
      label: 再現手順
    validations:
      required: false

注意: name フィールドの文字数

テンプレートのnameフィールドは最低3文字必要です。

これは公式ドキュメントには明記されていませんが、GitHub UIで設定しようとすると「名前が短すぎます（最低3文字）」というエラーが表示されます。日本語2文字（例: バグ、機能）は使えないため、絵文字を追加するなどの対応が必要です。

# NG: 2文字
name: バグ

# OK: 絵文字 + 2文字 = 3文字以上
name: バグ報告

config.yml

空のイシュー（テンプレートなし）を許可するかどうかを設定できます。

blank_issues_enabled: true

フォールバックの優先順位

各リポジトリに.githubフォルダがある場合、そちらが優先されます。

# 優先順位
1. 各リポジトリの .github/ フォルダ内のファイル
2. .github リポジトリのファイル（フォールバック）

つまり、特定のリポジトリだけ異なるテンプレートを使いたい場合は、そのリポジトリに直接ファイルを配置すれば上書きできます。

Organization限定機能

以下の機能はOrganization（組織アカウント）でのみ利用可能です。個人アカウントでは使用できません。

profile/README.md（組織プロフィール）

公式ドキュメントによると、.githubリポジトリ内のprofile/README.mdは、組織のプロフィールページに表示されます。

organization-name/.github/
└── profile/
    └── README.md  ← 組織のOverviewページに表示

.github-private リポジトリ

組織メンバー限定のプロフィールREADMEを表示したい場合は、.github-privateというプライベートリポジトリを使用します。

organization-name/.github-private/
└── profile/
    └── README.md  ← メンバーのみに表示

メンバーは「member」と「public」のビューを切り替えて、それぞれ異なる内容を確認できます。

workflow-templates（ワークフローテンプレート）

公式ドキュメントによると、.githubリポジトリ内にworkflow-templates/フォルダを作成すると、組織メンバーが「Actions > New workflow」からテンプレートを選択できるようになります。

organization-name/.github/
└── workflow-templates/
    ├── ci.yml
    └── ci.properties.json  ← メタデータ（アイコン、カテゴリ等）

個人アカウントではこのUI機能は利用できません。テンプレートを共有したい場合は、手動でコピーする運用になります。

関連する特殊リポジトリ

.githubリポジトリ以外にも、GitHubには特殊な名前のリポジトリがあります。

username/username（個人プロフィールREADME）

公式ドキュメントによると、自分のユーザー名と同じ名前のリポジトリを作成し、README.mdを配置すると、GitHubプロフィールページに表示されます。

hasegawa496/hasegawa496/
└── README.md  ← プロフィールページに表示

要件:

  • リポジトリ名がユーザー名と完全に一致
  • リポジトリがパブリック
  • ルートにREADME.mdが存在

.githubリポジトリのprofile/README.mdとは別の機能です。こちらは個人アカウントでも使用できます。

まとめ

個人アカウントで使える機能

機能配置場所
イシューテンプレート.github/.github/ISSUE_TEMPLATE/
PRテンプレート.github/.github/PULL_REQUEST_TEMPLATE.md
Community Health Files.github/.github/ または .github/
個人プロフィールREADMEusername/username/README.md

Organization限定機能

機能配置場所
組織プロフィールREADME（公開）.github/profile/README.md
組織プロフィールREADME（メンバー限定）.github-private/profile/README.md
ワークフローテンプレートUI.github/workflow-templates/

注意点

  • .githubリポジトリはパブリック必須
  • LICENSEファイルはフォールバック対象外
  • 各リポジトリに直接ファイルがある場合はそちらが優先

複数リポジトリを管理している場合、.githubリポジトリを活用することで、テンプレートやポリシーの一元管理が可能になります。

参考リンク