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 を使用して Projects を管理する」をご覧ください。
また、GitHub によって管理され、指定されたプロジェクトに現在の issue または pull request を追加する actions/add-to-project ワークフローを使用することもできます。 詳しくは、actions/add-to-project リポジトリと README を参照してください。
注: GITHUB_TOKEN
はリポジトリ レベルをスコープとしており、projects にはアクセスできません。 projects にアクセスするために、GitHub App (Organization プロジェクトの場合に推奨) または personal access token (ユーザー プロジェクトの場合に推奨) を作成できます。 以下には、どちらの方法のワークフローの例も示します。
GitHub Appで認証を行うワークフローの例
GitHub Actions ワークフローの認証と GitHub App について詳しくは、「Making authenticated API requests with a GitHub App in a GitHub Actions workflow」をご覧ください。
-
GitHub Appを作成するか、自分のOrganizationが所有する既存のGitHub Appを選択してください。 詳しくは、「Registering a GitHub App」を参照してください。
-
GitHub Appに、Organizationプロジェクトに対する読み込み及び書き込み権限を与えてください。 この特定の例では、GitHub App にはリポジトリの pull request とリポジトリのイシューに対する読み取りアクセス許可も必要です。 詳しくは、「Modifying a GitHub App registration」を参照してください。
注: Organization プロジェクトおよびリポジトリ プロジェクトに対するアプリのアクセス許可を制御できます。 Organizationプロジェクトに対する読み書き権限を与えなければなりません。リポジトリプロジェクトに対する読み書き権限だけでは不十分です。
-
OrganizationにGitHub Appをインストールしてください。 プロジェクトがアクセスする必要があるすべてのリポジトリにインストールしてください。 詳しくは、「独自の GitHub App のインストール」を参照してください。
-
GitHub AppのIDを、リポジトリもしくはOrganizationのシークレットとして保存してください。 以下のワークフローでは、
APP_ID
をシークレットの名前に置き換えます。 アプリケーションIDは、アプリケーションの設定ページで、あるいはアプリケーションのAPIを通じて確認できます。 詳しくは、「アプリ」を参照してください。 -
アプリケーションの秘密鍵を生成してください。 作成されたファイルの内容を、シークレットとしてリポジトリもしくはOrganizationに保存してください。 (
-----BEGIN RSA PRIVATE KEY-----
および-----END RSA PRIVATE KEY-----
を含め、ファイルの内容全体を保存してください)。以下のワークフローでは、APP_PEM
をシークレットの名前に置き換えます。 詳しくは、「GitHub Apps の秘密キーの管理」を参照してください。 -
以下のワークフローでは、
YOUR_ORGANIZATION
を自身の組織の名前に置き換えます。 たとえば、「octo-org
」のように入力します。YOUR_PROJECT_NUMBER
をプロジェクト番号に置き換えます。 プロジェクト番号を見つけるには、プロジェクトのURLを見てください。 たとえば、https://github.com/orgs/octo-org/projects/5
のプロジェクト番号は 5 です。 この特定の例を機能させるには、プロジェクトに "Date posted" 日付フィールドも必要です。
# このワークフローはGitHubによって認定されていないアクションを使用します。
# それらはサードパーティによって提供され、
# 別個の利用規約、プライバシーポリシー、
# ドキュメントを参照してください。
# GitHub では、コミット SHA にアクションをピン留めすることが推奨されます。
# 新しいバージョンを取得するには、SHA を更新する必要があります。
# タグまたはブランチを参照することもできますが、アクションは警告なしに変更される可能性があります。
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@b62528385c34dbc9f38e5f4225ac829252d1ea92
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){
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 'DATE_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Date posted") | .id' project_data.json) >> $GITHUB_ENV
echo 'STATUS_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Status") | .id' project_data.json) >> $GITHUB_ENV
echo 'TODO_OPTION_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Status") | .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!) {
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: 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: Date!
) {
set_status: updateProjectV2ItemFieldValue(input: {
projectId: $project
itemId: $item
fieldId: $status_field
value: {
singleSelectOptionId: $status_value
}
}) {
projectV2Item {
id
}
}
set_date_posted: updateProjectV2ItemFieldValue(input: {
projectId: $project
itemId: $item
fieldId: $date_field
value: {
date: $date_value
}
}) {
projectV2Item {
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
personal access token を使って認証を行うワークフローの例
project
スコープとrepo
スコープを使って personal access token (classic) を作成します。 詳しくは、「個人用アクセス トークンを管理する」を参照してください。- personal access token をリポジトリまたは Organization のシークレットとして保存してください。
- 以下のワークフローでは、
YOUR_TOKEN
をシークレットの名前に置き換えます。YOUR_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){
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 'DATE_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Date posted") | .id' project_data.json) >> $GITHUB_ENV
echo 'STATUS_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Status") | .id' project_data.json) >> $GITHUB_ENV
echo 'TODO_OPTION_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Status") | .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!) {
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: 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: Date!
) {
set_status: updateProjectV2ItemFieldValue(input: {
projectId: $project
itemId: $item
fieldId: $status_field
value: {
singleSelectOptionId: $status_value
}
}) {
projectV2Item {
id
}
}
set_date_posted: updateProjectV2ItemFieldValue(input: {
projectId: $project
itemId: $item
fieldId: $date_field
value: {
date: $date_value
}
}) {
projectV2Item {
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 のみ:
|
tibdex/github-app-token action を使用して、アプリ ID と秘密キーからアプリのインストール アクセス トークンを生成します。 このインストール アクセス トークンは、後で、ワークフロー内で ${{ steps.generate_token.outputs.token }} としてアクセスされます。
APP_ID を、アプリ ID を含むシークレットの名前に置き換えます。
APP_PEM を、アプリの秘密キーを含むシークレットの名前に置き換えます。
|
GitHub App:
Personal access token:
|
このステップのための環境変数を設定します。
personal access token を使っている場合は、 YOUR_TOKEN personal access token を含んでいるシークレットの名前で置き換えてください。
YOUR_ORGANIZATION を自身の組織の名前に置き換えます。 たとえば、「 octo-org 」のように入力します。
YOUR_PROJECT_NUMBER をプロジェクト番号に置き換えます。 プロジェクト番号を見つけるには、プロジェクトのURLを見てください。 たとえば、https://github.com/orgs/octo-org/projects/5 のプロジェクト番号は 5 です。
|
|
GitHub CLI を使用して、プロジェクトの ID に対するクエリを API に実行し、プロジェクト内の最初の 20 個のフィールドの名前と ID を返します。 応答は、 |
|
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 フィールドの値を設定します。
|