Note: Projects (beta) is currently in public beta and subject to change.
はじめに
プロジェクトの管理に役立つ自動化を追加できます。 プロジェクト(ベータ)には、UIを通じて設定できる組み込みのワークフローが含まれています。 加えて、GraphQL APIとGitHub Actionsでカスタムのワークフローを書くことができます。
組み込みのワークフロー
Projects (beta) includes built-in workflows that you can use to update the Status of items based on certain events. For example, you can automatically set the status to Todo when an item is added to your project or set the status to Done when an issue is closed.
When your project initializes, two workflows are enabled by default: When issues or pull requests in your project are closed, their status is set to Done, and when pull requests in your project are merged, their status is set to Done.
プロジェクトでは、組み込みのワークフローを有効化あるいは無効化できます。
- プロジェクトにアクセスします。
- In the top-right, click to open the menu.
- In the menu, click Workflows.
- Under Default workflows, click on the workflow that you want to edit.
- If the workflow can apply to both issues and pull requests, next to When, check the item type(s) that you want to act on.
- Next to Set, choose the value that you want to set the status to.
- If the workflow is disabled, click the toggle next to Disabled to enable the workflow.
GitHub Actionsのワークフロー
このセクションでは、GraphQL APIとGitHub Actionsを使ってOrganizationのプロジェクトにPull Requestを追加する方法を紹介します。 このワークフローの例では、Pull Requestが"ready for review"としてマークされると、プロジェクトに新しいタスクが追加され、"Status"フィールドが"Todo"に設定され、現在の日付がカスタムの"Date posted"フィールドに追加されます。
必要に応じて、以下のワークフローの1つをコピーして、以下の表にあるように変更できます。
プロジェクトは複数のリポジトリにまたがることができますが、ワークフローは1つのリポジトリに固有です。 ワークフローを、プロジェクトに追跡させたいそれぞれのリポジトリに追加してください。 ワークフローファイルの作成に関する詳しい情報については「GitHub Actionsのクイックスタート」を参照してください。
この記事は、GitHub Actionsを基本的に理解していることを前提としています。 GitHub Actionsに関する詳しい情報については「GitHub Actions 」を参照してください。
APIを通じてプロジェクトに対して行える他の変更に関する情報については「APIを使ったプロジェクトの管理」を参照してください。
ノート: GITHUB_TOKEN
はリポジトリレベルをスコープとしており、プロジェクト(ベータ)にはアクセスできません。 プロジェクト(ベータ)にアクセスするには、GitHub App(Organizationプロジェクトの場合に推奨)もしくは個人アクセストークン(ユーザプロジェクトの場合に推奨)を作成できます。 以下には、どちらの方法のワークフローの例も示します。
GitHub Appで認証を行うワークフローの例
-
GitHub Appを作成するか、自分のOrganizationが所有する既存のGitHub Appを選択してください。 詳しい情報については「GitHub Appの作成」を参照してください。
-
GitHub Appに、Organizationプロジェクトに対する読み込み及び書き込み権限を与えてください。 詳しい除法については「GitHub Appの権限の編集」を参照してください。
ノート: アプリケーションのOrganizationプロジェクトに対する権限と、リポジトリプロジェクトに対する権限を制御できます。 Organizationプロジェクトに対する読み書き権限を与えなければなりません。リポジトリプロジェクトに対する読み書き権限だけでは不十分です。
-
OrganizationにGitHub Appをインストールしてください。 プロジェクトがアクセスする必要があるすべてのリポジトリにインストールしてください。 詳しい情報については「GitHub Appsのインストール」を参照してください。
-
GitHub AppのIDを、リポジトリもしくはOrganizationのシークレットとして保存してください。 以下のワークフローでは、
APP_ID
をシークレット名に置き換えてください。 アプリケーションIDは、アプリケーションの設定ページで、あるいはアプリケーションのAPIを通じて確認できます。 詳しい情報については「アプリケーション」を参照してください。 -
アプリケーションの秘密鍵を生成してください。 作成されたファイルの内容を、シークレットとしてリポジトリもしくはOrganizationに保存してください。 (ファイルの内容は、
-----BEGIN RSA PRIVATE KEY-----
and-----END RSA PRIVATE KEY-----
という部分も含めて全体をほぞんしてください。) 以下のワークフローでは、APP_PEM
をシークレットの名前に置き換えてください。 詳しい情報については「GitHub Appsでの認証」を参照してください。 -
以下のワークフローでは、
YOUR_ORGANIZATION
をOrganizationの名前で置き換えてください。 たとえばocto-org
というようにします。YOUR_PROJECT_NUMBER
は、プロジェクトの番号で置き換えてください。 プロジェクト番号を知るには、プロジェクトのURLを見てください。 たとえばhttps://github.com/orgs/octo-org/projects/5
ではプロジェクト番号は5です。
# このワークフローはGitHubによって認定されていないアクションを使用します。
# それらはサードパーティによって提供され、
# 別個の利用規約、プライバシーポリシー、
# サポートドキュメンテーションが適用されます。
name: Add PR to project
on:
pull_request:
types:
- ready_for_review
jobs:
track_pr:
runs-on: ubuntu-latest
steps:
- name: Generate token
id: generate_token
uses: tibdex/github-app-token@36464acb844fc53b9b8b2401da68844f6b05ebb0
with:
app_id: ${{ secrets.APP_ID }}
private_key: ${{ secrets.APP_PEM }}
- name: Get project data
env:
GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
ORGANIZATION: YOUR_ORGANIZATION
PROJECT_NUMBER: YOUR_PROJECT_NUMBER
run: |
gh api graphql -f query='
query($org: String!, $number: Int!) {
organization(login: $org){
projectNext(number: $number) {
id
fields(first:20) {
nodes {
id
name
settings
}
}
}
}
}' -f org=$ORGANIZATION -F number=$PROJECT_NUMBER > project_data.json
echo 'PROJECT_ID='$(jq '.data.organization.projectNext.id' project_data.json) >> $GITHUB_ENV
echo 'DATE_FIELD_ID='$(jq '.data.organization.projectNext.fields.nodes[] | select(.name== "Date posted") | .id' project_data.json) >> $GITHUB_ENV
echo 'STATUS_FIELD_ID='$(jq '.data.organization.projectNext.fields.nodes[] | select(.name== "Status") | .id' project_data.json) >> $GITHUB_ENV
echo 'TODO_OPTION_ID='$(jq '.data.organization.projectNext.fields.nodes[] | select(.name== "Status") |.settings | fromjson.options[] | select(.name=="Todo") |.id' project_data.json) >> $GITHUB_ENV
- name: Add PR to project
env:
GITHUB_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!) {
addProjectNextItem(input: {projectId: $project, contentId: $pr}) {
projectNextItem {
id
}
}
}' -f project=$PROJECT_ID -f pr=$PR_ID --jq '.data.addProjectNextItem.projectNextItem.id')"
echo 'ITEM_ID='$item_id >> $GITHUB_ENV
- name: Get date
run: echo "DATE=$(date +"%Y-%m-%d")" >> $GITHUB_ENV
- name: Set fields
env:
GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
run: |
gh api graphql -f query='
mutation (
$project: ID!
$item: ID!
$status_field: ID!
$status_value: String!
$date_field: ID!
$date_value: String!
) {
set_status: updateProjectNextItemField(input: {
projectId: $project
itemId: $item
fieldId: $status_field
value: $status_value
}) {
projectNextItem {
id
}
}
set_date_posted: updateProjectNextItemField(input: {
projectId: $project
itemId: $item
fieldId: $date_field
value: $date_value
}) {
projectNextItem {
id
}
}
}' -f project=$PROJECT_ID -f item=$ITEM_ID -f status_field=$STATUS_FIELD_ID -f status_value=${{ env.TODO_OPTION_ID }} -f date_field=$DATE_FIELD_ID -f date_value=$DATE --silent
個人アクセストークンで認証するワークフローの例
org:write
スコープを使用して個人アクセストークンを作成します。 詳しい情報については、「個人アクセストークンを作成する」を参照してください。- この個人アクセストークンをシークレットとしてリポジトリもしくはOrganizationに保存します。
- 以下のワークフローでは、
YOUR_TOKEN
をそのシークレットの名前で置き換えてください。YOUR_ORGANIZATION
をOrganizationの名前で置き換えてください。 たとえばocto-org
というようにします。YOUR_PROJECT_NUMBER
は、プロジェクトの番号で置き換えてください。 プロジェクト番号を知るには、プロジェクトのURLを見てください。 たとえばhttps://github.com/orgs/octo-org/projects/5
ではプロジェクト番号は5です。
name: Add PR to project
on:
pull_request:
types:
- ready_for_review
jobs:
track_pr:
runs-on: ubuntu-latest
steps:
- name: Get project data
env:
GITHUB_TOKEN: ${{ secrets.YOUR_TOKEN }}
ORGANIZATION: YOUR_ORGANIZATION
PROJECT_NUMBER: YOUR_PROJECT_NUMBER
run: |
gh api graphql -f query='
query($org: String!, $number: Int!) {
organization(login: $org){
projectNext(number: $number) {
id
fields(first:20) {
nodes {
id
name
settings
}
}
}
}
}' -f org=$ORGANIZATION -F number=$PROJECT_NUMBER > project_data.json
echo 'PROJECT_ID='$(jq '.data.organization.projectNext.id' project_data.json) >> $GITHUB_ENV
echo 'DATE_FIELD_ID='$(jq '.data.organization.projectNext.fields.nodes[] | select(.name== "Date posted") | .id' project_data.json) >> $GITHUB_ENV
echo 'STATUS_FIELD_ID='$(jq '.data.organization.projectNext.fields.nodes[] | select(.name== "Status") | .id' project_data.json) >> $GITHUB_ENV
echo 'TODO_OPTION_ID='$(jq '.data.organization.projectNext.fields.nodes[] | select(.name== "Status") |.settings | fromjson.options[] | select(.name=="Todo") |.id' project_data.json) >> $GITHUB_ENV
- name: Add PR to project
env:
GITHUB_TOKEN: ${{ secrets.YOUR_TOKEN }}
PR_ID: ${{ github.event.pull_request.node_id }}
run: |
item_id="$( gh api graphql -f query='
mutation($project:ID!, $pr:ID!) {
addProjectNextItem(input: {projectId: $project, contentId: $pr}) {
projectNextItem {
id
}
}
}' -f project=$PROJECT_ID -f pr=$PR_ID --jq '.data.addProjectNextItem.projectNextItem.id')"
echo 'ITEM_ID='$item_id >> $GITHUB_ENV
- name: Get date
run: echo "DATE=$(date +"%Y-%m-%d")" >> $GITHUB_ENV
- name: Set fields
env:
GITHUB_TOKEN: ${{ secrets.YOUR_TOKEN }}
run: |
gh api graphql -f query='
mutation (
$project: ID!
$item: ID!
$status_field: ID!
$status_value: String!
$date_field: ID!
$date_value: String!
) {
set_status: updateProjectNextItemField(input: {
projectId: $project
itemId: $item
fieldId: $status_field
value: $status_value
}) {
projectNextItem {
id
}
}
set_date_posted: updateProjectNextItemField(input: {
projectId: $project
itemId: $item
fieldId: $date_field
value: $date_value
}) {
projectNextItem {
id
}
}
}' -f project=$PROJECT_ID -f item=$ITEM_ID -f status_field=$STATUS_FIELD_ID -f status_value=${{ env.TODO_OPTION_ID }} -f date_field=$DATE_FIELD_ID -f date_value=$DATE --silent
ワークフローの説明
以下の表は、ワークフローの例のセクションについて説明しており、自分の利用方法にそれらのワークフローを適応させる方法を示します。
|
このワークフローは、リポジトリ内のPull Requestが"ready for review"としてマークされたときに実行されます。 |
GitHub App only:
|
tibdex/github-app-token actionを使い、アプリケーションIDと秘密鍵からアプリケーション用のインストールアクセストークンを生成します。 このインストールアクセストークンは、後にワークフロー内で${{ steps.generate_token.outputs.token }} としてアクセスされます。
APP_ID はアプリケーションIDを含むシークレットの名前で置き換えてください。
APP_PEM は、アプリケーションの秘密鍵を含むシークレットの名前で置き換えてください。
|
GitHub App:
Personal access token:
|
このステップのための環境変数を設定します。
個人アクセストークンを使っているなら、 YOUR_TOKEN を個人アクセストークンを含むシークレットの名前で置き換えてください。
YOUR_ORGANIZATION をOrganization名で置き換えてください。 たとえばocto-org というようにします。
YOUR_PROJECT_NUMBER をプロジェクト番号で置き換えてください。 プロジェクト番号を知るには、プロジェクトのURLを見てください。 たとえばhttps://github.com/orgs/octo-org/projects/5 ではプロジェクト番号は5です。
|
|
GitHub CLIを使って、プロジェクトのIDと、プロジェクトの最初の20個のフィールドのID、名前、設定を、APIに問い合わせます。 レスポンスはproject_data.json というファイルに保存されます。
|
|
APIクエリからのレスポンスをパースし、関連するIDを環境変数として保存します。 これを変更して、様々なフィールドやオプションのIDを取得してください。 例:
|
GitHub App:
Personal access token:
|
このステップのための環境変数を設定します。 GITHUB_TOKEN は上で説明されています。 PR_ID は、このワークフローをトリガーしたPull RequestのIDです。
|
|
GitHub CLIとAPIを使って、このワークフローをトリガーしたPull Requestをプロジェクトに追加します。 jq フラグは、レスポンスをパースして作成されたアイテムのIDを取得します。
|
|
作成されたアイテムのIDを環境変数として保存します。 |
|
現在の日付をyyyy-mm-dd というフォーマットで環境変数に保存します。
|
GitHub App:
Personal access token:
|
このステップのための環境変数を設定します。 GITHUB_TOKEN は上で説明されています。
|
|
Status フィールドの値をTodo に設定します。 Date posted フィールドの値を設定します。
|