GitHub Projects

Posted at 2025-12-21

GitHub Projects

1. はじめに

GitHub Projectsは、issueやPull Requestと統合されたプロジェクト管理ツールです。スプレッドシート、カンバンボード、ガントチャートの機能を一つのプラットフォームで提供し、開発チームのワークフローを最適化します。

この記事では、GitHub Projectsの全機能を体系的に解説します。基本的な使い方から高度な自動化まで、実務で即活用できる情報をまとめました。

2. プロジェクトの作成と初期設定

2.1 組織プロジェクトの作成

組織レベルでプロジェクトを作成する手順です。

GitHubの右上にあるプロフィール画像をクリック
「Organizations」を選択
組織名をクリック
「Projects」タブを選択
「New project」をクリック

プロジェクトタイプを選択します：

空のプロジェクト: Table、Roadmap、Boardから選択
テンプレート: GitHub提供のテンプレートまたは組織のカスタムテンプレート

2.2 ユーザープロジェクトの作成

個人アカウントでプロジェクトを作成する場合：

右上のプロフィール画像から「Your profile」を選択
「Projects」タブをクリック
「New project」をクリック
プロジェクトタイプを選択

2.3 プロジェクトの説明とREADMEの設定

プロジェクトの目的と使い方を明確にします。

プロジェクト画面右上のメニューアイコンをクリック
「Settings」を選択
「Add a description」でプロジェクトの概要を入力
「README」セクションでMarkdown形式のドキュメントを作成

READMEには以下の情報を含めることを推奨します：

プロジェクトの目的
ビューの使い方
関連リンク
連絡先情報

3. 3つのレイアウトとその使い分け

GitHub Projectsは3つのレイアウトを提供し、それぞれ異なる用途に最適化されています。

3.1 Tableレイアウト - データ重視の管理

Tableレイアウトの特徴：

スプレッドシート形式: 全データを一覧表示
フィールドの表示/非表示: 必要な情報だけを表示
一括編集: セルの内容をドラッグでコピー
グループ化: フィールドごとにアイテムをグループ化
フィールド合計: 数値フィールドの合計を表示

適用シーン：

チームバックログの管理
詳細なタスク分析
データの一括更新

3.2 Boardレイアウト - カンバン方式の管理

Boardレイアウトの特徴：

カンバンボード: カードを列間で移動
列のカスタマイズ: 単一選択フィールドまたはイテレーションフィールドを列として使用
列の制限設定: WIP（Work In Progress）制限を設定可能
水平グループ化: フィールドで追加のグループ化

適用シーン：

スプリント管理
ワークフロー可視化
進捗トラッキング

3.3 Roadmapレイアウト - タイムライン管理

Roadmapレイアウトの特徴：

タイムライン表示: 期間にわたるアイテムを可視化
日付フィールド: 開始日と目標日を設定
イテレーションフィールド: スプリントベースの計画
マーカー: イテレーション、マイルストーン、重要日程を表示
ズーム機能: 月、四半期、年単位で表示

適用シーン：

プロダクトロードマップ
リリース計画
長期的なプロジェクト管理

4. カスタムフィールドの活用

GitHub Projectsは、標準のissue/PR情報に加えて、カスタムフィールドを追加できます。

4.1 フィールドタイプ一覧

フィールドタイプ	用途	フィルタリング
テキスト	自由記述のメモ	`field:"完全一致"`
数値	タスクの複雑度、ポイント	`field:>=5` または `field:1..10`
日付	出荷予定日、デッドライン	`date:2025-01-01..2025-12-31`
単一選択	優先度、タスクタイプ	`field:高優先度`
イテレーション	スプリント管理	`iteration:@current`

4.2 テキストフィールドの追加

1. Tableビューで右端のフィールドヘッダーの「+」をクリック
2. 「New field」を選択
3. フィールド名を入力
4. 「Text」を選択
5. 「Save」をクリック

用途例：

作業メモ
外部リンク
簡単な説明

4.3 数値フィールドの追加

数値フィールドは合計やソートに使用できます。

1. Tableビューで右端のフィールドヘッダーの「+」をクリック
2. 「New field」を選択
3. フィールド名を入力（例：「ストーリーポイント」）
4. 「Number」を選択
5. 「Save」をクリック

数値フィールドのフィルタリング例：

points:>10 - 10より大きい
points:5..15 - 5から15の範囲
points:<=20 - 20以下

4.4 日付フィールドの追加

1. Tableビューで右端のフィールドヘッダーの「+」をクリック
2. 「New field」を選択
3. フィールド名を入力（例：「出荷予定日」）
4. 「Date」を選択
5. 「Save」をクリック

日付フィールドのフィルタリング例：

date:@today - 本日
date:>=2025-01-01 - 2025年1月1日以降
date:@today..@today+7 - 今日から7日後まで

4.5 単一選択フィールドの追加

1. Tableビューで右端のフィールドヘッダーの「+」をクリック
2. 「New field」を選択
3. フィールド名を入力（例：「優先度」）
4. 「Single select」を選択
5. オプションを追加（例：高、中、低）
6. 各オプションに色と説明を設定
7. 「Save」をクリック

単一選択フィールドの編集：

プロジェクト設定からフィールドを選択
各オプションのラベル、色、説明を編集可能

4.6 イテレーションフィールドの追加

イテレーションフィールドはスプリント管理に最適です。

1. Tableビューで右端のフィールドヘッダーの「+」をクリック
2. 「New field」を選択
3. フィールド名を入力（例：「スプリント」）
4. 「Iteration」を選択
5. 開始日を設定
6. 期間を設定（日数または週数）
7. 「Save」をクリック

イテレーションの管理：

プロジェクト設定で追加のイテレーションを作成
各イテレーションの名前と期間を編集
休憩期間を挿入可能

イテレーションのフィルタリング：

iteration:@current - 現在のイテレーション
iteration:@next - 次のイテレーション
iteration:>"スプリント4" - スプリント4より後

5. アイテムの追加と管理

5.1 issueとPull Requestの追加

プロジェクトにアイテムを追加する方法は複数あります。

5.1.1 URLで直接追加

1. Tableビューの最下行にカーソルを置く
2. issueまたはPRのURLを貼り付け
3. Returnキーを押す

5.1.2 検索して追加

1. Tableビューの最下行の「+」をクリック
2. リポジトリを選択
3. issueまたはPR番号やタイトルの一部を入力
4. 表示されたリストから選択

5.1.3 一括追加

1. Tableビューの最下行の「+」をクリック
2. 「Add item from repository」を選択
3. リポジトリを選択
4. フィルタを使用して絞り込み（例：label:bug）
5. 追加したいアイテムを選択
6. 「Add selected items」をクリック

5.1.4 リポジトリから追加

1. リポジトリのIssuesまたはPull requestsタブに移動
2. 追加したいアイテムを選択（チェックボックス）
3. 上部の「Projects」をクリック
4. プロジェクトを選択

5.2 ドラフトissueの作成

ドラフトissueは、プロジェクト内でアイデアを素早く記録するための機能です。

1. Tableビューの最下行にタイトルを入力
2. Returnキーを押す
3. タイトルをクリックして本文を追加

ドラフトissueの特徴：

プロジェクト内でのみ存在
担当者とカスタムフィールドを設定可能
後からissueに変換可能（リポジトリを選択）

ドラフトissueからissueへの変換：

1. ドラフトissueの「...」メニューをクリック
2. 「Convert to issue」を選択
3. リポジトリを選択

5.3 issueの作成

プロジェクトから直接issueを作成できます。

1. Tableビュー、グループ、またはBoard列の下部の「+」をクリック
2. 「Create new issue」を選択
3. リポジトリを選択
4. タイトルを入力
5. 担当者、ラベル、マイルストーンを設定
6. 説明を入力（オプション）
7. 「Create」をクリック

グループ化されたビューでissueを作成すると、そのグループの値が自動的に設定されます。

5.4 アイテムの編集

5.4.1 セルのコピー&ペースト

1. Tableビューでコピーしたいセルを選択
2. Command+C（Mac）またはCtrl+C（Windows）
3. ペースト先のセルを選択（複数選択可能）
4. Command+V（Mac）またはCtrl+V（Windows）

複数セルの選択方法：

Command（Mac）またはCtrl（Windows）を押しながらクリック
Shiftを押しながら上下に移動
マウスをドラッグして範囲選択

5.4.2 セルの内容をドラッグでコピー

1. Tableビューでセルを選択
2. セル右下の青いハンドルをドラッグ
3. コピー先のセルまでドラッグ
4. ドロップすると内容がコピーされる

5.4.3 複数セルの一括クリア

1. Tableビューでクリアしたいセルを選択
2. DeleteまたはBackspaceキーを押す

5.4.4 変更の取り消し

一括変更後、右下に表示される「Undo」ボタンで取り消し可能です。

5.5 アイテムのアーカイブと削除

5.5.1 アーカイブ

アーカイブは、アイテムをビューから削除しつつ、後で復元可能な状態で保持します。

1. TableまたはBoardレイアウトでアイテムを選択
2. 「...」メニューをクリック
3. 「Archive」を選択

アーカイブされたアイテムの確認：

1. プロジェクト右上のメニューアイコンをクリック
2. 「Archived items」を選択
3. フィルタリングして検索可能

アーカイブからの復元：

1. 「Archived items」ページで復元したいアイテムを選択
2. 「Restore」をクリック

5.5.2 削除

削除はアイテムをプロジェクトから完全に削除します（issueやPR自体は削除されません）。

1. TableまたはBoardレイアウトでアイテムを選択
2. 「...」メニューをクリック
3. 「Delete from project」を選択
4. 確認ダイアログで「Delete」をクリック

注意：プロジェクトは最大50,000アイテム（アクティブ+アーカイブ）まで保持できます。

6. ビューのカスタマイズ

ビューは、プロジェクトを異なる視点で表示するための機能です。チームメンバーごとに最適なビューを作成できます。

6.1 ビューの作成

1. 既存のビュータブの右側にある「New view」をクリック
2. レイアウトを選択（Table、Board、Roadmap）
3. フィルタ、ソート、グループ化を設定
4. ビュー名を変更

6.2 フィルタリング

フィルタリングは、特定の条件に一致するアイテムのみを表示します。

6.2.1 基本的なフィルタ構文

# 担当者でフィルタ
assignee:田中太郎

# ラベルでフィルタ
label:バグ

# ステータスでフィルタ
status:進行中

# 優先度でフィルタ
priority:高

# 複数条件（AND）
assignee:田中太郎 status:進行中

# 複数値（OR）
label:バグ,機能

# 否定
-label:バグ

# 値がある
has:assignee

# 値がない
no:label

# 自分自身
assignee:@me

# 数値範囲
points:5..15

# 日付範囲
date:2025-01-01..2025-12-31

# 相対日付
updated:>@today-7d

6.2.2 高度なフィルタ例

# 最近更新されていない高優先度タスク
priority:高 updated:<@today-14d

# 担当者がいないバグ
label:バグ no:assignee

# 現在のイテレーションの進行中タスク
iteration:@current status:進行中

# 10ポイント以上の未着手タスク
points:>=10 status:未着手

# 今日から1週間以内の期日
date:@today..@today+7d

6.3 ソート

ソートは、アイテムを特定の順序で並べ替えます。

1. ビューメニューアイコンをクリック
2. 「Sort」を選択
3. ソートするフィールドを選択
4. 必要に応じて第2ソートを追加
5. フィールドを再度クリックして昇順/降順を切り替え

注意：Boardレイアウトでソートを設定すると、列内でアイテムを手動で並べ替えできなくなります。

6.4 グループ化

グループ化は、フィールドの値ごとにアイテムをまとめて表示します。

1. ビューメニューアイコンをクリック
2. 「Group by」を選択
3. グループ化するフィールドを選択

グループ化の利点：

アイテムを別のグループにドラッグすると、そのフィールドの値が自動更新
各グループの合計を表示可能

グループ化できないフィールド：

タイトル
ラベル
レビュアー
リンクされたPR

6.5 スライス

スライスは、フィールドの値をサイドパネルに表示し、クリックでフィルタリングします。

1. ビューメニューアイコンをクリック
2. 「Slice by」を選択
3. スライスするフィールドを選択

スライスは現在のフィルタと組み合わせて動作します。

6.6 フィールド合計の表示

数値フィールドの合計を表示できます。

1. ビューメニューアイコンをクリック
2. 「Field sum」を選択
3. 合計を表示したいフィールドを選択

合計は以下の場所に表示されます：

Boardレイアウト：各列の上部
TableとRoadmapレイアウト：各グループのヘッダー

6.7 ビューの保存と管理

6.7.1 変更の保存

ビューに変更を加えると、ビュー名の横にドットが表示されます。

1. ビューメニューアイコンをクリック
2. 「Save changes」をクリック

6.7.2 ビューの複製

1. 複製したいビューに切り替え
2. ビューメニューアイコンをクリック
3. 「Duplicate view」を選択

6.7.3 ビューの名前変更

1. ビューメニューアイコンをクリック
2. 「Rename view」を選択
3. 新しい名前を入力
4. Returnキーを押す

6.7.4 ビューの削除

1. 削除したいビューに切り替え
2. ビューメニューアイコンをクリック
3. 「Delete view」を選択

7. 自動化とワークフロー

GitHub Projectsは、手動作業を削減するための自動化機能を提供します。

7.1 ビルトインワークフロー

7.1.1 デフォルトで有効なワークフロー

issueまたはPRがクローズされたとき、ステータスを「完了」に設定
PRがマージされたとき、ステータスを「完了」に設定

7.1.2 ワークフローの有効化と編集

1. プロジェクト右上のメニューアイコンをクリック
2. 「Workflows」を選択
3. 「Default workflows」から編集したいワークフローをクリック
4. 右上の「Edit」をクリック
5. 設定を変更
6. 「Save and turn on workflow」をクリック

7.2 自動追加ワークフロー

特定の条件に一致するissueやPRを自動的にプロジェクトに追加します。

7.2.1 自動追加の設定

1. プロジェクト右上のメニューアイコンをクリック
2. 「Workflows」を選択
3. 「Auto-add to project」をクリック
4. 右上の「Edit」をクリック
5. リポジトリを選択
6. フィルタ条件を入力（例：label:バグ）
7. 「Save and turn on workflow」をクリック

7.2.2 サポートされているフィルタ

修飾子	可能な値
`is`	open, closed, merged, draft, issue, pr
`label`	"ラベル名"
`reason`	completed, reopened, "not planned"
`assignee`	GitHubユーザー名
`no`	label, assignee, reason

フィルタ例：

# バグラベルの付いたissue
is:issue label:バグ

# 担当者がいないPR
is:pr no:assignee

# 完了理由でクローズされていないissue
is:closed -reason:completed

7.2.3 自動追加ワークフローの制限

プラン	最大ワークフロー数
GitHub Free	1
GitHub Pro	5
GitHub Team	5
GitHub Enterprise	20

7.2.4 複数の自動追加ワークフローの作成

1. 「Workflows」ページで「Auto-add to project」の「...」をクリック
2. 「Duplicate workflow」を選択
3. ワークフロー名を入力
4. 各ワークフローで異なるリポジトリとフィルタを設定

7.3 自動アーカイブワークフロー

条件に一致するアイテムを自動的にアーカイブします。

7.3.1 自動アーカイブの設定

1. プロジェクト右上のメニューアイコンをクリック
2. 「Workflows」を選択
3. 「Auto-archive items」をクリック
4. 右上の「Edit」をクリック
5. フィルタ条件を入力
6. 「Save and turn on workflow」をクリック

7.3.2 サポートされているフィルタ

修飾子	可能な値
`is`	open, closed, merged, draft, issue, pr
`reason`	completed, reopened, "not planned"
`updated`	`<@today-14d`（過去14日）、`<@today-3w`（過去3週間）

フィルタ例：

# 14日以上更新されていない完了済みissue
is:closed reason:completed updated:<@today-14d

# 1ヶ月以上更新されていないドラフト
is:draft updated:<@today-1m

注意：GitHubがissueやPRを「更新済み」とマークする条件：

作成
再オープン
編集
コメント
ラベル付け
担当者の更新
マイルストーンの更新
リポジトリへの転送
プロジェクトのフィールド値の変更

7.4 GitHub Actionsとの統合

より高度な自動化には、GitHub Actionsを使用します。

7.4.1 ワークフロー例：PRをプロジェクトに追加

name: PRをプロジェクトに追加
on:
  pull_request:
    types:
      - ready_for_review
jobs:
  track_pr:
    runs-on: ubuntu-latest
    steps:
      # GitHub Appトークンを生成（組織プロジェクトの場合）
      - name: トークンの生成
        id: generate-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ vars.APP_ID }}
          private-key: ${{ secrets.APP_PEM }}
      
      # プロジェクトデータの取得
      - name: プロジェクトデータの取得
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
          ORGANIZATION: your-organization
          PROJECT_NUMBER: 5
        run: |
          gh api graphql -f query='
            query($org: String!, $number: Int!) {
              organization(login: $org){
                projectV2(number: $number) {
                  id
                  fields(first:20) {
                    nodes {
                      ... on ProjectV2Field {
                        id
                        name
                      }
                      ... on ProjectV2SingleSelectField {
                        id
                        name
                        options {
                          id
                          name
                        }
                      }
                    }
                  }
                }
              }
            }' -f org=$ORGANIZATION -F number=$PROJECT_NUMBER > project_data.json
          
          echo 'PROJECT_ID='$(jq '.data.organization.projectV2.id' project_data.json) >> $GITHUB_ENV
          echo 'STATUS_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "ステータス") | .id' project_data.json) >> $GITHUB_ENV
          echo 'TODO_OPTION_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "ステータス") | .options[] | select(.name=="未着手") |.id' project_data.json) >> $GITHUB_ENV
      
      # PRをプロジェクトに追加
      - name: PRをプロジェクトに追加
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
          PR_ID: ${{ github.event.pull_request.node_id }}
        run: |
          item_id="$( gh api graphql -f query='
            mutation($project:ID!, $pr:ID!) {
              addProjectV2ItemById(input: {projectId: $project, contentId: $pr}) {
                item {
                  id
                }
              }
            }' -f project=$PROJECT_ID -f pr=$PR_ID --jq '.data.addProjectV2ItemById.item.id')"
          
          echo 'ITEM_ID='$item_id >> $GITHUB_ENV
      
      # フィールドを設定
      - name: フィールドを設定
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
        run: |
          gh api graphql -f query='
            mutation (
              $project: ID!
              $item: ID!
              $status_field: ID!
              $status_value: String!
            ) {
              set_status: updateProjectV2ItemFieldValue(input: {
                projectId: $project
                itemId: $item
                fieldId: $status_field
                value: {
                  singleSelectOptionId: $status_value
                }
              }) {
                projectV2Item {
                  id
                }
              }
            }' -f project=$PROJECT_ID -f item=$ITEM_ID -f status_field=$STATUS_FIELD_ID -f status_value=${{ env.TODO_OPTION_ID }} --silent

7.4.2 認証方法

組織プロジェクト（推奨：GitHub App）:

GitHub Appを作成または選択
組織プロジェクトへの読み取り/書き込み権限を付与
組織にインストール
App IDを設定変数として保存
秘密鍵をシークレットとして保存

ユーザープロジェクト（推奨：Personal Access Token）:

projectとrepoスコープを持つPATを作成
シークレットとして保存

7.5 GraphQL APIの活用

7.5.1 プロジェクトIDの取得

gh api graphql -f query='
  query{
    organization(login: "your-organization"){
      projectV2(number: 5) {
        id
      }
    }
  }'

7.5.2 フィールド情報の取得

gh api graphql -f query='
  query{
    node(id: "PROJECT_ID") {
      ... on ProjectV2 {
        fields(first: 20) {
          nodes {
            ... on ProjectV2Field {
              id
              name
            }
            ... on ProjectV2SingleSelectField {
              id
              name
              options {
                id
                name
              }
            }
          }
        }
      }
    }
  }'

7.5.3 アイテムの追加

gh api graphql -f query='
  mutation {
    addProjectV2ItemById(input: {projectId: "PROJECT_ID" contentId: "ISSUE_ID"}) {
      item {
        id
      }
    }
  }'

7.5.4 フィールド値の更新

gh api graphql -f query='
  mutation {
    updateProjectV2ItemFieldValue(
      input: {
        projectId: "PROJECT_ID"
        itemId: "ITEM_ID"
        fieldId: "FIELD_ID"
        value: {
          text: "更新されたテキスト"
        }
      }
    ) {
      projectV2Item {
        id
      }
    }
  }'

8. インサイトとチャート

インサイト機能は、プロジェクトデータを視覚化します。

8.1 チャートの種類

8.1.1 現在のチャート

プロジェクトの現在の状態を視覚化します。

棒グラフ: カテゴリ別のアイテム数
列グラフ: 時系列データの比較
円グラフ: 割合の表示

8.1.2 履歴チャート

時間経過に伴う変化を追跡します。

バーンアップチャート: 完了した作業と残りの作業
累積フローダイアグラム: 各ステータスのアイテム数の推移

8.2 チャートの作成

1. プロジェクト右上のインサイトアイコンをクリック
2. 左メニューで「New chart」をクリック
3. フィルタを入力してデータを絞り込み
4. チャートタイプを選択
5. X軸とY軸を設定
6. 右側の「Save changes」をクリック

8.3 チャートの設定

1. インサイトページで設定したいチャートをクリック
2. 右側の「Configure」をクリック
3. 設定を変更：
   - Layout: チャートタイプ
   - X-axis: X軸のフィールド
   - Group by: グループ化するフィールド
   - Y-axis: Y軸の集計方法（合計、平均、最小、最大）
4. 「Save changes」をクリック

8.4 チャートの例

8.4.1 優先度別のアイテム数

Layout: 棒グラフ
X-axis: 優先度
Y-axis: アイテム数

8.4.2 担当者別のストーリーポイント合計

Layout: 棒グラフ
X-axis: 担当者
Y-axis: 合計
Y-axis field: ストーリーポイント

8.4.3 イテレーション別の進捗

Layout: 列グラフ
X-axis: イテレーション
Group by: ステータス

8.4.4 バーンアップチャート

Layout: 履歴チャート
X-axis: 時間
フィルタ: iteration:@current

9. アクセス管理と権限

9.1 組織プロジェクトのアクセス管理

9.1.1 ベース権限の設定

組織全体のデフォルト権限を設定します。

1. プロジェクト右上のメニューアイコンをクリック
2. 「Settings」を選択
3. 「Manage access」をクリック
4. 「Base role」ドロップダウンから選択：
   - No access: 組織オーナーと個別アクセス権を持つユーザーのみ
   - Read: 全員が閲覧可能
   - Write: 全員が編集可能
   - Admin: 全員が管理者

9.1.2 チームと個人の追加

1. 「Manage access」ページで「Invite collaborators」を検索
2. チーム名またはユーザー名を入力
3. ロールを選択（Read、Write、Admin）
4. 「Invite」をクリック

チームへの権限付与の利点：

チームのProjectsページにプロジェクトが表示される
チームメンバー全員に一括で権限付与

9.1.3 既存のコラボレーターの権限変更

1. 「Manage access」ページで対象のユーザーまたはチームを検索
2. ロールを変更
3. または「Remove」をクリックして削除

9.2 ユーザープロジェクトのアクセス管理

個人プロジェクトでもコラボレーターを追加できます。

1. プロジェクト右上のメニューアイコンをクリック
2. 「Settings」を選択
3. 「Manage access」をクリック
4. 「Invite collaborators」でユーザー名を検索
5. ロールを選択（Read、Write、Admin）
6. 「Invite」をクリック

注意：プロジェクトのアイテムを表示するには、元のリポジトリへのアクセス権も必要です。

9.3 プロジェクトの可視性

9.3.1 公開/非公開の設定

1. プロジェクト右上のメニューアイコンをクリック
2. 「Settings」を選択
3. 「Danger zone」セクションの「Visibility」で選択：
   - Private: 権限を持つユーザーのみ閲覧可能
   - Public: インターネット上の全員が閲覧可能

公開プロジェクトの注意点：

プロジェクト自体は公開されるが、アイテムの表示にはリポジトリのアクセス権が必要
プライベートリポジトリのアイテムは、リポジトリへのアクセス権がないユーザーには表示されない

10. プロジェクトテンプレート

テンプレートは、事前設定されたプロジェクトを組織内で共有する機能です。

10.1 テンプレートに含まれる内容

ビュー
カスタムフィールド
ドラフトissueとフィールド値
設定済みワークフロー（自動追加を除く）
インサイト

10.2 新しいテンプレートの作成

1. 組織の「Projects」ページに移動
2. 左サイドバーで「Templates」をクリック
3. 「New template」をクリック
4. テンプレートを設定
5. 保存

10.3 既存のプロジェクトをテンプレートに設定

1. テンプレートにしたいプロジェクトに移動
2. プロジェクト右上のメニューアイコンをクリック
3. 「Settings」を選択
4. 「Templates」セクションで「Make template」をオンに切り替え

10.4 プロジェクトをテンプレートとしてコピー

1. コピーしたいプロジェクトに移動
2. プロジェクト右上のメニューアイコンをクリック
3. 「Settings」を選択
4. 「Templates」セクションで「Copy as template」をクリック

10.5 推奨テンプレートの設定（組織オーナー）

最大6個のテンプレートを推奨として設定できます。

1. 組織の「Settings」に移動
2. 「Projects」セクションをクリック
3. 「Recommended templates」で「Customize recommended templates」をクリック
4. 推奨したいテンプレートを選択（最大6個）
5. 「Save」をクリック

推奨テンプレートの並び替え：

1. 「Recommended templates」セクションで移動したいテンプレートを選択
2. ドラッグハンドルをクリックして新しい位置にドラッグ

10.6 テンプレートからプロジェクトを作成

1. 組織またはユーザーの「Projects」ページに移動
2. 「New project」をクリック
3. テンプレートを選択
4. プロジェクト名を入力
5. 「Create project」をクリック

11. リポジトリとチームへのリンク

11.1 リポジトリへのプロジェクト追加

リポジトリにプロジェクトをリンクすると、そのリポジトリのProjectsタブから簡単にアクセスできます。

1. リポジトリのメインページに移動
2. 「Projects」タブをクリック
3. 「Link a project」をクリック
4. プロジェクトを検索して選択

11.1.1 デフォルトリポジトリの設定

プロジェクトにデフォルトリポジトリを設定すると、新しいissueが自動的にそのリポジトリに作成されます。

1. リポジトリの「Projects」タブでプロジェクトをクリック
2. プロジェクトページ右上のメニューから「Settings」を選択
3. 「Default repository」でリポジトリを選択
4. 「Save changes」をクリック

11.2 チームへのプロジェクト追加

1. 組織の「Teams」タブに移動
2. チーム名をクリック
3. 「Projects」タブをクリック
4. 「Link a project」をクリック
5. プロジェクトを検索して選択
6. 権限変更の確認ダイアログで確認

チームにプロジェクトを追加すると：

チーム全体にRead権限が付与される
チームのProjectsページに表示される
プロジェクトの発見性が向上

11.3 プロジェクトの検索

11.3.1 すべてのプロジェクトを参照

1. 左上のグローバルナビゲーションメニューをクリック
2. 「Projects」を選択
3. フィルタを入力して絞り込み

11.3.2 組織のプロジェクトを検索

1. 右上のプロフィール画像から「Organizations」を選択
2. 組織名をクリック
3. 「Projects」タブをクリック
4. フィルタを入力して絞り込み

11.3.3 個人のプロジェクトを検索

1. 右上のプロフィール画像から「Your profile」を選択
2. 「Projects」タブをクリック
3. フィルタを入力して絞り込み

11.3.4 リポジトリのプロジェクトを検索

1. リポジトリのメインページに移動
2. 「Projects」タブをクリック
3. フィルタを入力して絞り込み

11.3.5 チームのプロジェクトを検索

1. 組織の「Teams」タブに移動
2. チーム名をクリック
3. 「Projects」タブをクリック
4. フィルタを入力して絞り込み

11.4 プロジェクトリストのフィルタ構文

修飾子	説明
`is:open`	オープンなプロジェクト
`is:closed`	クローズしたプロジェクト
`is:template`	テンプレートとしてマークされたプロジェクト
`is:private`	非公開プロジェクト
`is:public`	公開プロジェクト
`creator:USERNAME`	ユーザーが作成したプロジェクト
`sort:title-asc`	タイトルで並び替え
`sort:updated-asc`	更新日で並び替え（昇順）
`sort:updated-desc`	更新日で並び替え（降順）
`sort:created-asc`	作成日で並び替え（昇順）
`sort:created-desc`	作成日で並び替え（降順）

12. ステータス更新の共有

プロジェクトのハイレベルな概要を共有する機能です。

12.1 ステータス更新の追加

1. プロジェクト右上のサイドパネルアイコンをクリック
2. 「Status updates」の横にある「Add update」をクリック
3. ステータスを選択（On track、At risk、Off trackなど）
4. 開始日と目標日を設定
5. コメントフィールドにメッセージを入力（Markdown対応）
6. 「Save update」をクリック

ステータス更新の表示場所：

プロジェクトのサイドパネル（説明とREADMEの下）
プロジェクトのヘッダー
プロジェクトリスト

ステータス更新は、プロジェクトへの読み取りアクセス権を持つ全員が閲覧でき、書き込みアクセス権を持つユーザーが投稿できます。

13. データのエクスポート

プロジェクトデータをTSV（タブ区切り）ファイルとしてエクスポートできます。

1. エクスポートしたいビューを開く
2. ビューメニューアイコンをクリック
3. 「Export view data」を選択

エクスポートされるデータ：

現在のビューで表示されているアイテム
適用されているフィルタに基づくデータ
表示されているフィールドのみ

14. プロジェクトのクローズと削除

14.1 プロジェクトのクローズ

クローズしたプロジェクトは、プロジェクトリストから削除されますが、後で再オープン可能です。

1. プロジェクト右上のメニューアイコンをクリック
2. 「Settings」を選択
3. 「Danger zone」セクションで「Close this project」をクリック

14.2 プロジェクトの再オープン

14.2.1 組織プロジェクトの再オープン

1. 組織の「Projects」ページに移動
2. 左サイドバーで「Projects」をクリック
3. 上部の「X Closed」をクリック
4. 再オープンしたいプロジェクトをクリック
5. プロジェクト右上のメニューから「Settings」を選択
6. 「Danger Zone」で「Re-open this project」をクリック

14.2.2 ユーザープロジェクトの再オープン

1. プロフィールの「Projects」タブに移動
2. 上部の「X Closed」をクリック
3. 再オープンしたいプロジェクトをクリック
4. プロジェクト右上のメニューから「Settings」を選択
5. 「Danger Zone」で「Re-open this project」をクリック

14.3 プロジェクトの削除

削除は永久的で、元に戻せません。

1. プロジェクト右上のメニューアイコンをクリック
2. 「Settings」を選択
3. 「Danger zone」セクションで「Delete this project」をクリック
4. 警告を読み、プロジェクト名を入力
5. 「I understand the consequences, delete this project」をクリック

15. ベストプラクティス

15.1 issueとPRでのコミュニケーション

@メンション: チームメンバーや特定の人に通知
担当者の設定: 責任の所在を明確化
関連issueのリンク: 依存関係を可視化

15.2 タスクの適切な分割

大きなissueは小さなissueに分割します。

サブissue機能を使用すると：

階層的なタスク管理が可能
親issueで進捗を追跡
複数レベルの階層を作成可能

15.3 issue依存関係の管理

ブロックしているissueやブロックされているissueを明確にします。

1. issueの説明またはコメントに記載
2. 「Blocked by #123」または「Blocks #456」と記述
3. カスタムフィールドで追跡

15.4 マイルストーンとラベルの活用

マイルストーン: 大きな目標やリリースを追跡
ラベル: issueのカテゴリ分類（バグ、機能、ドキュメントなど）

15.5 説明、README、ステータス更新の活用

15.6 カスタマイズされたビューの作成

チームの異なるニーズに対応するため、複数のビューを作成します。

例：

バックログビュー: 未着手のアイテムをすべて表示
スプリントビュー: 現在のイテレーションのアイテムのみ
レビュービュー: レビュー待ちのPRを表示
完了ビュー: 最近完了したアイテムを表示

15.7 フィールドタイプの効果的な使用

フィールドタイプ	用途例
日付	出荷予定日、デッドライン
数値	タスクの複雑度、ストーリーポイント
単一選択	優先度（高、中、低）、タスクタイプ
テキスト	クイックメモ、外部リンク
イテレーション	スプリント計画

15.8 イテレーションフィールドの活用

スプリントベースの開発に最適です。

1. イテレーションフィールドを作成（期間：1週間または2週間）
2. 各スプリントの開始日を設定
3. 休憩期間を挿入（例：年末年始）
4. イテレーションでグループ化してビューを作成
5. フィルタで現在のスプリントに絞り込み（iteration:@current）

イテレーションの利点：

ベロシティの計測
作業のバランス確認
過去の成果の振り返り

15.9 自動化の活用

手動作業を減らし、プロジェクトを最新状態に保ちます。

自動化の例：

自動追加: 新しいバグを自動的にプロジェクトに追加
ステータス更新: PRがマージされたら自動的に「完了」に設定
自動アーカイブ: 14日以上更新されていない完了済みissueをアーカイブ

15.10 インサイトの作成と共有

プロジェクトの進捗を可視化し、データに基づいた意思決定を行います。

作成すべきチャート：

優先度別のアイテム数: リソース配分の確認
担当者別の作業量: チーム負荷の可視化
バーンアップチャート: スプリントの進捗追跡
イテレーション別の完了率: ベロシティの測定

15.11 テンプレートの作成と標準化

組織全体で一貫したワークフローを維持します。

1. 成功したプロジェクトをテンプレートに設定
2. ビュー、フィールド、ワークフローを含める
3. 推奨テンプレートとして設定
4. チームメンバーに使用を促進

15.12 チームとリポジトリへのリンク

プロジェクトの発見性を向上させます。

1. 関連するチームにプロジェクトを追加
2. 関連するリポジトリにプロジェクトをリンク
3. デフォルトリポジトリを設定

15.13 単一の情報源の維持

情報の重複を避けます。

目標日は1つの日付フィールドで管理
プロジェクトのフィールドが変更されると、自動的にissue/PRに反映
GitHubデータ（担当者、マイルストーン、ラベル）は自動同期

16. 実践的なワークフロー例

16.1 スクラム開発のワークフロー

16.1.1 設定

イテレーションフィールドの作成
- フィールド名：「スプリント」
- 期間：2週間
- 開始日：月曜日
ステータスフィールドの作成
- バックログ
- 計画済み
- 進行中
- レビュー中
- 完了
ビューの作成
- バックログビュー（Table）
  - フィルタ：status:バックログ
  - ソート：優先度（降順）
- スプリントボード（Board）
  - フィルタ：iteration:@current
  - 列フィールド：ステータス
  - グループ化：担当者
- スプリントロードマップ（Roadmap）
  - フィルタ：iteration:@current..@current+2
  - マーカー：イテレーション
自動化の設定
- PRがレビュー準備完了になったらプロジェクトに追加
- PRがマージされたらステータスを「完了」に設定
- 14日以上更新されていない完了済みissueを自動アーカイブ

16.2 カンバン開発のワークフロー

16.2.1 設定

ステータスフィールドの作成
- バックログ
- 準備完了
- 進行中
- レビュー
- 完了
ビューの作成
- カンバンボード（Board）
  - 列フィールド：ステータス
  - 列制限：進行中=5、レビュー=3
- 優先度ビュー（Table）
  - グループ化：優先度
  - フィールド合計：ストーリーポイント
自動化の設定
- 新しいissueを自動的にバックログに追加
- issueがクローズされたらステータスを「完了」に設定

16.3 リリース管理のワークフロー

16.3.1 設定

カスタムフィールドの作成
- リリース日（日付）
- リリースバージョン（単一選択：v1.0、v1.1など）
- ステータス（単一選択：計画中、開発中、テスト中、リリース準備、リリース済み）
ビューの作成
- リリースロードマップ（Roadmap）
  - グループ化：リリースバージョン
  - マーカー：マイルストーン
  - 開始日/目標日：リリース日フィールド
- リリース進捗ボード（Board）
  - 列フィールド：ステータス
  - グループ化：リリースバージョン
- 次回リリース（Table）
  - フィルタ：milestone:"v1.1"
  - グループ化：ステータス
インサイトの作成
- リリースバージョン別の完了率
- 機能タイプ別の分布

16.4 バグトリアージのワークフロー

16.4.1 設定

カスタムフィールドの作成
- 重要度（単一選択：重大、高、中、低）
- 影響範囲（テキスト）
- 再現手順（テキスト）
ビューの作成
- トリアージビュー（Table）
  - フィルタ：label:バグ status:トリアージ待ち
  - ソート：作成日（昇順）
- バグボード（Board）
  - フィルタ：label:バグ
  - 列フィールド：ステータス
  - グループ化：重要度
自動化の設定
- label:バグのissueを自動的にプロジェクトに追加
- ステータスを「トリアージ待ち」に自動設定

17. 高度な活用テクニック

17.1 複雑なフィルタの組み合わせ

実務でよく使うフィルタパターンです。

17.1.1 担当者がいない高優先度タスク

priority:高 no:assignee -status:完了

用途：リソース配分が必要なタスクの特定

17.1.2 期限が迫っているタスク

date:@today..@today+7d -status:完了 -status:レビュー中

用途：今週中に対応が必要なタスク

17.1.3 長期間更新されていないオープンissue

is:open updated:<@today-30d

用途：放置されているissueの発見

17.1.4 特定のチームメンバーのレビュー待ちPR

is:pr status:レビュー中 assignee:yamada,suzuki

用途：レビュー担当者の作業量確認

17.1.5 サブissueの進捗確認

parent-issue:octocat/repo#123

用途：親issueに関連する全サブissueの表示

17.2 カスタムフィールドの応用

17.2.1 Tシャツサイズでの見積もり

1. 単一選択フィールド「サイズ」を作成
2. オプション：XS、S、M、L、XL
3. 各サイズに対応するストーリーポイントを説明に記載
   - XS: 1ポイント
   - S: 2ポイント
   - M: 3ポイント
   - L: 5ポイント
   - XL: 8ポイント

17.2.2 複数の日付フィールドの管理

- 要望受付日（日付）
- 設計開始日（日付）
- 実装開始日（日付）
- レビュー完了日（日付）
- リリース予定日（日付）

Roadmapレイアウトで開始日と目標日に異なる日付フィールドを設定し、プロジェクトのフェーズを可視化できます。

17.2.3 依存関係の追跡

1. テキストフィールド「ブロッカー」を作成
2. ブロックしているissue番号を記載（例：#123, #456）
3. フィルタでブロックされているタスクを表示：has:ブロッカー

17.3 ビューの階層構造

チームごとに異なるビューセットを作成します。

# 開発チーム用
- 開発バックログ（Table）
- 現在のスプリント（Board）
- 技術的負債（Table）

# QAチーム用
- テスト待ち（Table）
- バグトリアージ（Board）
- リグレッションテスト（Table）

# プロダクトマネージャー用
- ロードマップ（Roadmap）
- 機能リクエスト（Table）
- リリース計画（Table）

# マネジメント用
- プロジェクト全体（Roadmap）
- リソース配分（Table）
- 進捗サマリー（インサイト）

17.4 GitHub Actionsの高度な活用

17.4.1 issue作成時にラベルに基づいてフィールドを自動設定

name: ラベルに基づくフィールド設定
on:
  issues:
    types:
      - opened
      - labeled

jobs:
  set_fields:
    runs-on: ubuntu-latest
    steps:
      - name: トークンの生成
        id: generate-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ vars.APP_ID }}
          private-key: ${{ secrets.APP_PEM }}
      
      - name: プロジェクトに追加して優先度を設定
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
        run: |
          # バグラベルがあれば優先度を「高」に設定
          if [[ "${{ contains(github.event.issue.labels.*.name, 'bug') }}" == "true" ]]; then
            # プロジェクトに追加
            # 優先度フィールドを「高」に設定
            echo "バグとして高優先度を設定"
          fi

17.4.2 週次レポートの自動生成

name: 週次レポート
on:
  schedule:
    - cron: '0 9 * * 1'  # 毎週月曜日9時

jobs:
  weekly_report:
    runs-on: ubuntu-latest
    steps:
      - name: トークンの生成
        id: generate-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ vars.APP_ID }}
          private-key: ${{ secrets.APP_PEM }}
      
      - name: プロジェクトデータの取得
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
        run: |
          # 先週完了したissueの数を取得
          # 現在進行中のissueの数を取得
          # ステータス更新を投稿

17.4.3 カスタム通知

name: カスタム通知
on:
  project_card:
    types: [moved]

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: Slackに通知
        if: contains(github.event.project_card.column_name, '完了')
        uses: slackapi/slack-github-action@v1
        with:
          payload: |
            {
              "text": "タスクが完了しました: ${{ github.event.project_card.note }}"
            }
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

17.5 GraphQL APIの高度な使用例

17.5.1 複数フィールドの一括更新

mutation {
  updateItem1: updateProjectV2ItemFieldValue(
    input: {
      projectId: "PROJECT_ID"
      itemId: "ITEM_ID_1"
      fieldId: "STATUS_FIELD_ID"
      value: { singleSelectOptionId: "DONE_OPTION_ID" }
    }
  ) {
    projectV2Item { id }
  }
  
  updateItem2: updateProjectV2ItemFieldValue(
    input: {
      projectId: "PROJECT_ID"
      itemId: "ITEM_ID_2"
      fieldId: "STATUS_FIELD_ID"
      value: { singleSelectOptionId: "DONE_OPTION_ID" }
    }
  ) {
    projectV2Item { id }
  }
}

17.5.2 プロジェクト全体のデータ取得

query {
  node(id: "PROJECT_ID") {
    ... on ProjectV2 {
      items(first: 100) {
        nodes {
          id
          fieldValues(first: 20) {
            nodes {
              ... on ProjectV2ItemFieldTextValue {
                text
                field {
                  ... on ProjectV2FieldCommon {
                    name
                  }
                }
              }
              ... on ProjectV2ItemFieldNumberValue {
                number
                field {
                  ... on ProjectV2FieldCommon {
                    name
                  }
                }
              }
              ... on ProjectV2ItemFieldDateValue {
                date
                field {
                  ... on ProjectV2FieldCommon {
                    name
                  }
                }
              }
              ... on ProjectV2ItemFieldSingleSelectValue {
                name
                field {
                  ... on ProjectV2FieldCommon {
                    name
                  }
                }
              }
            }
          }
          content {
            ... on Issue {
              title
              number
              url
            }
            ... on PullRequest {
              title
              number
              url
            }
          }
        }
      }
    }
  }
}

18. トラブルシューティング

18.1 よくある問題と解決方法

18.1.1 プロジェクトにアイテムが追加されない

原因：

自動追加ワークフローのフィルタが正しくない
リポジトリが選択されていない
ワークフローが無効になっている

解決方法：

1. ワークフローの設定を確認
2. フィルタ構文をテスト
3. ワークフローが有効か確認
4. 手動でアイテムを追加してテスト

18.1.2 フィールドの値が更新されない

原因：

APIのアクセス権限が不足
フィールドIDが間違っている
オプションIDが存在しない

解決方法：

1. プロジェクトへの書き込み権限を確認
2. GraphQL APIでフィールドIDを再取得
3. 単一選択フィールドのオプションIDを確認

18.1.3 ビューが正しくフィルタされない

原因：

フィルタ構文のエラー
フィールド名のタイプミス
値の形式が間違っている

解決方法：

1. フィルタを部分的に適用してテスト
2. フィールド名が完全一致するか確認
3. 日付や数値の形式を確認
4. スペースや特殊文字に注意

18.1.4 アーカイブが機能しない

原因：

自動アーカイブワークフローのフィルタが条件を満たしていない
updatedフィールドが正しく更新されていない

解決方法：

1. フィルタ条件を確認（is、reason、updatedのみサポート）
2. テストissueで動作を確認
3. 手動でアーカイブして動作をテスト

18.1.5 50,000アイテムの制限に達した

原因：

アクティブアイテムとアーカイブアイテムの合計が50,000を超えた

解決方法：

1. アーカイブされたアイテムを確認
2. 不要なアイテムをプロジェクトから削除
3. 古いissueを別のプロジェクトに移動
4. 自動アーカイブの条件を見直す

19. パフォーマンス最適化

19.1 大規模プロジェクトの管理

19.1.1 フィルタの最適化

# 遅い
label:バグ,機能,改善 assignee:田中,山田,鈴木

# 速い
label:バグ assignee:田中

複雑なフィルタを避け、必要最小限の条件に絞ります。

19.1.2 ビューの数を制限

必要なビューのみを作成（推奨：10個以下）
使用していないビューは削除
類似のビューを統合

19.1.3 アーカイブの活用

# 30日以上更新されていない完了済みアイテムをアーカイブ
is:closed updated:<@today-30d

アクティブなアイテム数を減らし、パフォーマンスを向上させます。

19.2 APIリクエストの最適化

19.2.1 バッチ処理

mutation {
  item1: updateProjectV2ItemFieldValue(...) { ... }
  item2: updateProjectV2ItemFieldValue(...) { ... }
  item3: updateProjectV2ItemFieldValue(...) { ... }
}

1つのリクエストで複数の更新を実行します。

19.2.2 ページネーション

query {
  node(id: "PROJECT_ID") {
    ... on ProjectV2 {
      items(first: 100, after: "cursor") {
        nodes { ... }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  }
}

大量のデータを取得する際は、ページネーションを使用します。

20. まとめ

GitHub Projectsは、開発チームのプロジェクト管理を統合し、効率化する強力なツールです。

20.1 主な利点

GitHub統合: issueやPRと完全に統合され、コンテキストスイッチを削減
柔軟性: Table、Board、Roadmapの3つのレイアウトで多様なニーズに対応
カスタマイズ: カスタムフィールドで独自のワークフローを構築
自動化: ビルトインワークフローとGitHub Actionsで手動作業を削減
可視化: インサイトとチャートでプロジェクトの状態を把握
スケーラビリティ: 小規模チームから大規模組織まで対応

20.2 導入のステップ

20.3 成功のためのチェックリスト

プロジェクトの目的を明確にする
READMEと説明を記載する
チームに必要なカスタムフィールドを追加する
各ロール向けのビューを作成する
自動化ワークフローを設定する
チームメンバーに適切な権限を付与する
リポジトリとチームにプロジェクトをリンクする
インサイトで進捗を追跡する
定期的にアーカイブと整理を実施する
チームからフィードバックを収集して改善する

20.4 最後に

GitHub Projectsを活用することで、チームの生産性が向上し、プロジェクトの透明性が高まります。この記事の内容を参考に、チームに最適なプロジェクト管理を構築してください。

重要なのは、ツールを導入することではなく、チームのワークフローを改善することです。まずは小さく始めて、チームのフィードバックを聞きながら段階的に機能を追加していくことをお勧めします。

プロジェクト管理の成功は、継続的な改善と適応にあります。GitHub Projectsの柔軟性を活かして、チームに最適な形を見つけてください。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up