GitHub - Projects

提供: MochiuWiki : SUSE, EC, PCB

📢 Webサイト閉鎖と移転のお知らせ
このWebサイトは2026年9月に閉鎖いたします。
新しい記事は移転先で追加しております。（旧サイトでは記事を追加しておりません）

概要

GitHub Projectsは、Issue、Pull Request、ドラフトアイテムをテーブル・ボード・ロードマップの複数ビューで一元管理する統合プロジェクト管理ツールである。

スプレッドシート形式のテーブルビュー、カンバン形式のボードビュー、タイムライン形式のロードマップビューを切り替えながら、チームの作業状況を多角的に把握できる。

GitHub Projectsが提供する主な機能は以下の通りである。

  • テーブル / ボード / ロードマップビュー
    1つのプロジェクトに対して複数のビューを作成して、目的に応じた形式で作業状況を確認できる。
  • カスタムフィールド
    テキスト、数値、日付、単一選択、イテレーションの最大50個のフィールドを追加して、プロジェクト固有の情報を管理できる。
  • 自動化
    組み込みワークフローやGitHub Actions、GraphQL APIを利用して、アイテムの追加やステータス変更を自動化できる。


プロジェクトには最大50,000アイテムを登録でき、アーカイブ機能によってカスタムフィールドのデータを保持したまま表示から除外できる。


プロジェクトの作成

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

ユーザ個人のプロジェクトを作成する手順を以下に示す。

  1. GitHubの右上にあるプロフィールアイコンを選択する。
  2. メニューから[Your projects]を選択する。
  3. Projectsページで[New project]ボタンを押下する。
  4. プロジェクトのタイプ (Table / Roadmap / Board) を選択する。
  5. プロジェクト名を入力して、[Create project]ボタンを押下する。


組織プロジェクトの作成

組織 (Organization) 配下にプロジェクトを作成する手順を以下に示す。

  1. GitHubで対象の組織ページを開く。
  2. [Projects]タブを選択する。
  3. [New project]ボタンを押下する。
  4. プロジェクトのタイプとプロジェクト名を入力して、[Create project]ボタンを押下する。


組織プロジェクトは、組織内の複数リポジトリをまたいで、Issue や Pull Requestを管理できる。

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

新規プロジェクト作成時にテンプレートを選択することにより、ビュー構成やカスタムフィールドをすぐに利用できる。

テンプレートの種類は以下の通りである。

  • プリセットテンプレート
    GitHubが公式に提供するテンプレートで、スプリント計画、バグ管理、フィーチャーリクエスト等のユースケースに対応している。
  • 組織テンプレート
    組織内で作成・登録されたカスタムテンプレートを選択できる。


下表に、テンプレートからプロジェクトを作成した場合にコピーされる要素とコピーされない要素を示す。

テンプレートコピーの対象
コピーされる要素 コピーされない要素
ビュー構成 アイテム (Issue / PR)
カスタムフィールドの定義 コラボレータの設定
ドラフト問題 リポジトリリンク
ワークフローの設定 -
インサイト (チャート設定) -


プロジェクトの設定

作成後のプロジェクトは、[Settings]から各種設定を変更できる。

プロジェクトの基本設定
項目 説明
タイトル プロジェクトの表示名を変更する。
説明(README) プロジェクトの概要や使い方をMarkdownで記述できる。
可視性 Public(公開)または Private(非公開)を選択する。
組織プロジェクトの場合は組織のメンバーのみに公開することもできる。
アクセス権 コラボレータをロール (Read / Write / Admin) 付きで招待できる。
組織プロジェクトはベースロールを設定して組織メンバー全体に権限を付与できる。



アイテムの管理

アイテムの追加

プロジェクトへのアイテム追加方法は複数用意されている。

プロジェクトへのアイテム追加方法
方法 説明
URLの貼り付け テーブルまたはボードビューの下部にある[Add item]フィールドに、Issue または Pull RequestのURLを貼り付けて追加する。
# 入力によるリポジトリ選択 [Add item]フィールドで # を入力するとリポジトリ一覧が表示される。
リポジトリを選択後、Issue または Pull Requestを検索して追加する。
Issue / PR サイドバーからの追加 Issue または Pull Requestの詳細ページにある右サイドバーの[Projects]セクションから直接プロジェクトへ追加できる。
一括追加 [Add item] - [Add items from repository]を選択して、フィルタ条件を指定することで複数のIssue / PRを1度に追加できる。


ドラフトアイテム

ドラフトアイテムは、プロジェクト限定の仮Issueとして作成できるアイテムである。

リポジトリにIssueを作成する前の段階でアイデアやタスクを記録しておく用途に適している。

ドラフトアイテムは後から通常のIssueに変換できる。
変換するには、ドラフトアイテムの詳細パネルを開き、[Convert to issue]ボタンを押下して対象リポジトリを指定する。

編集・削除・アーカイブ

テーブルビューでのセル編集手順を以下に示す。

  1. テーブルビューで対象のセルを選択する。
  2. 値を直接入力または選択する。
  3. [Enter]キー または セル外を選択して確定する。


一括編集の操作方法を以下に示す。

  • コピー & ペースト
    複数のセルを選択して [Cmd] + [C]キー (macOS) または [Ctrl] + [C]キー (Windows / Linux) でコピーして、[Cmd] + [V]キー または [Ctrl] + [V]キーで貼り付ける。
  • ドラッグによる複製
    セルの右下に表示される青いハンドルをドラッグすることで、値を隣接するセルに複製できる。
  • 複数セルの削除
    複数のセルを選択して、[Delete]キーで値を削除する。


操作を誤った場合は、ページ上部の[Undo]ボタンで直前の変更を取り消すことができる。

アーカイブはアイテムをプロジェクトの表示から除外する機能である。
アーカイブされたアイテムはカスタムフィールドのデータを保持したまま、[Settings] - [Archived items]ページから確認・復元できる。

一括操作

テーブルビューでは複数アイテムを選択して一括操作を実行できる。

  1. 行の左端にあるチェックボックスを選択して、複数アイテムを選択する。
  2. 画面上部に表示される操作バーから、ステータス変更・フィールド更新・アーカイブ・削除等の操作を実行する。



ビュー

テーブルビュー

テーブルビューはスプレッドシート形式でアイテムを管理するビューである。

各行がアイテム (Issue / PR / ドラフト) を表し、各列がフィールドに対応する。
セルを選択して値を直接編集でき、列の追加・非表示・並べ替えを自由にカスタマイズできる。

大量のアイテムを一覧で把握しながら効率的に編集する用途に最適である。

ボードビュー (Kanban)

ボードビューはカンバン形式でアイテムをカード表示するビューである。

アイテムをドラッグ&ドロップで別のカラムに移動することでステータスを更新できる。
カラムは単一選択フィールドの各オプションに対応しており、デフォルトでは[Status]フィールドを基準に表示される。

ステータスの変遷を視覚的に追跡するスクラム・カンバン管理に最適である。

ロードマップビュー

ロードマップビューはタイムライン形式でアイテムをガントチャート的に表示するビューである。

日付フィールド (開始日・終了日) を軸にしてアイテムの期間をバー表示する。
イテレーションフィールドと連携することで、スプリントの進行をタイムライン上で可視化できる。

マイルストーン管理やリリース計画の把握に最適である。

ビューのカスタマイズ

各ビューはそれぞれ独立して設定を保存できる。

ビューのカスタマイズ機能
機能 説明
フィルタ 特定の条件に合致するアイテムのみを表示する。
ソート 指定したフィールドの値で昇順・降順に並べ替える。
グループ化 指定したフィールドの値でアイテムをグループに分けて表示する。
表示フィールドの選択 表示する列を選択して不要なフィールドを非表示にする。


ビューの設定は、[Save changes]ボタンを押下することで保存される。

保存前は変更内容がビュー名の右側に表示される。


カスタムフィールド

フィールドの種類

下表に、GitHub Projectsで作成できるカスタムフィールドの種類を示す。

カスタムフィールドの種類
フィールド種類 説明 主な用途
テキスト 任意のテキストを入力するフィールド メモ、補足説明
数値 数値を入力するフィールド ストーリーポイント、見積工数
日付 カレンダーから日付を選択するフィールド 期日、リリース予定日
単一選択 ドロップダウンから1つの値を選択するフィールド
色や説明を設定できる。		 優先度、カテゴリ
イテレーション 時間枠 (スプリント) に関連付けるフィールド スプリント管理


組み込みフィールド

GitHub Projectsには、デフォルトで用意されている組み込みフィールドがある。

プロジェクトの主な組み込みフィールド
フィールド 説明
Status アイテムの進捗状態を管理するフィールド
デフォルトで Todo / In Progress / Done の3つのオプションが用意されている。
Assignees アイテムに割り当てられた担当者を表示するフィールド
Labels Issue / PRに設定されたラベルを表示するフィールド
親課題 (Parent issue) Sub-issues機能を使用している場合に親Issueを表示するフィールド
Sub-issues progress 親課題の配下にあるSub-issuesの完了率を表示するフィールド
リンク済みPR (Linked pull requests) Issueに紐付けられたPull Requestを表示するフィールド
レビュアー (Reviewers) Pull Requestのレビュアーを表示するフィールド
課題タイプ (Issue type) Issueの種類 (Bug / Feature / Task等) を表示するフィールド


フィールドの作成

新しいカスタムフィールドを作成する手順を以下に示す。

  1. テーブルビューの列ヘッダ右端にある[+]ボタンを押下する。
  2. [New field]を選択する。
  3. フィールド名を入力する。
  4. フィールドの種類 (テキスト / 数値 / 日付 / 単一選択 / イテレーション) を選択する。
  5. 単一選択の場合は選択肢を追加して、必要に応じて色と説明を設定する。
  6. [Create]ボタンを押下して、フィールドを作成する。


1つのプロジェクトに作成できるカスタムフィールドの上限は50個である。


フィルタリング・ソート・グループ化

フィルタ構文

ビューのフィルタフィールドに構文を入力することにより、表示するアイテムを絞り込める。

下表に、主なフィルタ構文を示す。

フィルタ構文一覧
構文 説明 例
is:open / is:closed Issue の状態でフィルタリングする is:open
is:merged / is:draft PR の状態でフィルタリングする is:merged
is:issue / is:pr アイテムの種類でフィルタリングする is:issue
label: 指定したラベルを持つアイテムを絞り込む label:bug
assignee: 指定したユーザが担当するアイテムを絞り込む assignee:@me
no: 指定フィールドが未設定のアイテムを絞り込む no:assignee
reason: クローズの理由でフィルタリングする reason:completed
updated: 更新日でフィルタリングする updated:>2024-01-01


フィルタ構文の先頭に - を付加することにより、否定条件として使用できる。
例: -label:bug は、bugラベルが付加されていないアイテムを表示する。

複数の条件をスペースで区切って組み合わせることができる。
例: is:open assignee:@me label:bug

ソートとグループ化

ビューの表示順序や分類をカスタマイズできる。

  • ソート
    列ヘッダをクリックする、または、ビューメニューの[Sort]オプションから対象フィールドと昇順・降順を指定する。
    複数フィールドによる複合ソートも設定できる。
  • グループ化
    ビューメニューの[Group by]オプションから対象フィールドを指定する。
    単一選択フィールドやイテレーションフィールドでグループ化すると、カテゴリ別にアイテムをまとめて表示できる。



ワークフロー自動化

組み込みワークフロー

GitHub Projectsには設定するだけで利用できる組み込みワークフローが用意されている。

  • Auto-add to project
    指定したリポジトリでIssue または Pull Requestが作成・更新された時に、フィルタ条件に合致する場合に自動的にプロジェクトへ追加するワークフローである。
    ワークフローの設定上限はプランによって異なる。
  • Auto-archive items
    条件 (クローズから一定期間経過等) に合致したアイテムを自動的にアーカイブするワークフローである。
    アーカイブ後もカスタムフィールドのデータは保持される。


下表に、Auto-add to projectワークフローの設定上限を示す。

Auto-add to project の設定上限 (プラン別)
プラン 設定上限数
Free 1
Pro / Team 5
Enterprise 20


既存のアイテムはワークフロー有効化後に自動追加されない。
新規に作成・更新されたアイテムのみが追加対象となる。

GitHub Actionsとの連携

GitHub Actionsワークフローを使用して、より柔軟なプロジェクト自動化を実現できる。

GitHubが公式に提供するアクション actions/add-to-project を利用することにより、イベントをトリガーにしてアイテムの追加やフィールドの更新を自動化できる。

以下の例では、Issueが作成された際に指定したプロジェクトへ自動追加する設定を示している。
github-token には repo および project スコープを持つPersonal Access Token (PAT) を設定する。

 name: Add issue to project
 on:
    issues:
       types:
          - opened
 jobs:
    add-to-project:
       runs-on: ubuntu-latest
       steps:
          - uses: actions/add-to-project@v1.0.2
            with:
               project-url: https://github.com/orgs/YOUR_ORG/projects/1
               github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}


GraphQL APIによる自動化

GitHub GraphQL APIを使用して、プロジェクトをプログラムから操作できる。

APIを使用するために必要なスコープは以下の通りである。

プロジェクトAPIに必要なスコープ
スコープ 説明
read:project プロジェクト情報の読み取り(クエリ)に使用する。
project プロジェクト情報の書き込み (ミューテーション) に使用する。


認証方法は、PAT (Personal Access Token) または GitHub Appsトークンを使用する。

プロジェクトのアイテム一覧を取得するクエリの例を以下に示す。

query {
   node(id: "PROJECT_ID") {
      ... on ProjectV2 {
         items(first: 20) {
            nodes {
               id
               fieldValues(first: 8) {
                  nodes {
                     ... on ProjectV2ItemFieldTextValue {
                        text
                        field { ... on ProjectV2FieldCommon { name } }
                     }
                     ... on ProjectV2ItemFieldSingleSelectValue {
                        name
                        field { ... on ProjectV2FieldCommon { name } }
                     }
                  }
               }
            }
         }
      }
   }
}



イテレーション

イテレーションフィールドの設定

イテレーションフィールドを使用することにより、スプリントやタイムボックスを定義してアイテムを関連付けられる。

イテレーションフィールドの作成手順を以下に示す。

  1. テーブルビューの列ヘッダ右端にある[+]ボタンを押下する。
  2. [New field]を選択し、フィールド種類で[Iteration]を選択する。
  3. 以下の項目を設定する。
    1. 開始日 (Start date)
      イテレーションの開始日を指定する。
    2. 期間 (Duration)
      イテレーションの長さを日数または週数で指定する。
  4. [Save]ボタンを押下すると、開始日と期間をもとに自動的に3つのイテレーションが作成される。


イテレーション設定では休憩期間 (Break) を挿入することもできる。

休憩期間は祝日や連休等、スプリントを行わない期間を表現する時に使用する。

スプリント計画への活用

イテレーションフィールドを作成すると、以下の特殊な検索キーワードで現在・次回のスプリントを参照できる。

  • @current
    現在進行中のイテレーションに属するアイテムを絞り込む。
    例: フィルタに iteration:@current を入力する。
  • @next
    次のイテレーションに属するアイテムを絞り込む。
    例: フィルタに iteration:@next を入力する。


ロードマップビューでイテレーションフィールドを日付の基準に設定すると、スプリントの期間をタイムライン上に視覚的に表示できる。


インサイト

カスタムチャートの作成

インサイト機能を使用することにより、プロジェクトのデータを集計したグラフを作成・共有できる。

チャートを作成する手順を以下に示す。

  1. プロジェクトページの上部にある[Insights]タブを選択する。
  2. [New chart]ボタンを押下する。
  3. チャートの種類 (棒グラフ、円グラフ等) を選択する。
  4. X軸、Y軸、グループ化に使用するフィールドを選択する。
  5. 必要に応じてフィルタ条件を設定する。
  6. [Save changes]ボタンを押下してチャートを保存する。


インサイトで作成できるチャートの活用例を以下に示す。

  • 優先度別アイテム数
    単一選択フィールド (優先度) をX軸に設定して、各優先度に属するアイテム数を棒グラフで確認する。
  • ステータス別進捗
    [Status]フィールドをX軸に設定して、各ステータスのアイテム数を円グラフで確認する。
  • 担当者別ワークロード
    [Assignees]フィールドをX軸に設定して、各担当者が抱えるアイテム数を棒グラフで確認する。
  • イテレーション別消化量
    イテレーションフィールドをX軸、数値フィールド (ポイント) をY軸に設定して、スプリントごとの消化ポイントを確認する。



「http://mochiuwiki.e2.valueserver.jp/index.php?title=GitHub_-_Projects&oldid=14574」から取得