プロジェクト（ベータ）の自動化

Note: Projects (beta) is currently in public beta and subject to change.

はじめに

You can add automation to help manage your project. Projects (beta) includes built-in workflows that you can configure through the UI. Additionally, you can write custom workflows with the GraphQL API and GitHub Actions.

Built-in workflows

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.

You can enable or disable the built-in workflows for your project.

In your project, click .
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 workflows

This section demonstrates how to use the GraphQL API and GitHub Actions to add a pull request to an organization project. In the example workflows, when the pull request is marked as "ready for review", a new task is added to the project with a "Status" field set to "Todo", and the current date is added to a custom "Date posted" field.

You can copy one of the workflows below and modify it as described in the table below to meet your needs.

プロジェクトは複数のリポジトリにまたがることができますが、ワークフローは1つのリポジトリに固有です。 Add the workflow to each repository that you want your project to track. ワークフローファイルの作成に関する詳しい情報については「GitHub Actionsのクイックスタート」を参照してください。

この記事は、GitHub Actionsを基本的に理解していることを前提としています。 GitHub Actionsに関する詳しい情報については「GitHub Actions 」を参照してください。

APIを通じてプロジェクトに対して行える他の変更に関する情報については「APIを使ったプロジェクトの管理」を参照してください。

Note: GITHUB_TOKEN is scoped to the repository level and cannot access projects (beta). To access projects (beta) you can either create a GitHub App (recommended for organization projects) or a personal access token (recommended for user projects). Workflow examples for both approaches are shown below.

Example workflow authenticating with a GitHub App

Create a GitHub App or choose an existing GitHub App owned by your organization. For more information, see "Creating a GitHub App."
Give your GitHub App read and write permissions to organization projects. For more information, see "Editing a GitHub App's permissions."

Note: You can control your app's permission to organization projects and to repository projects. You must give permission to read and write organization projects; permission to read and write repository projects will not be sufficient.
Install the GitHub App in your organization. Install it for all repositories that your project needs to access. For more information, see "Installing GitHub Apps."
Store your GitHub App's ID as a secret in your repository or organization. In the following workflow, replace APP_ID with the name of the secret. You can find your app ID on the settings page for your app or through the App API. For more information, see "Apps."
Generate a private key for your app. Store the contents of the resulting file as a secret in your repository or organization. (Store the entire contents of the file, including -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY-----.) In the following workflow, replace APP_PEM with the name of the secret. For more information, see "Authenticating with GitHub Apps."
In the following workflow, replace YOUR_ORGANIZATION with the name of your organization. たとえばocto-orgというようにします。 Replace YOUR_PROJECT_NUMBER with your project number. プロジェクト番号を知るには、プロジェクトのURLを見てください。たとえばhttps://github.com/orgs/octo-org/projects/5ではプロジェクト番号は5です。

YAML

# このワークフローは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

Example workflow authenticating with a personal access token

Create a personal access token with org:write scope. 詳しい情報については、「個人アクセストークンを作成する」を参照してください。
Save the personal access token as a secret in your repository or organization.
以下のワークフローでは、YOUR_TOKENをそのシークレットの名前で置き換えてください。 Replace YOUR_ORGANIZATION with the name of your organization. たとえばocto-orgというようにします。 Replace YOUR_PROJECT_NUMBER with your project number. プロジェクト番号を知るには、プロジェクトのURLを見てください。たとえばhttps://github.com/orgs/octo-org/projects/5ではプロジェクト番号は5です。

YAML

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

Workflow explanation

The following table explains sections of the example workflows and shows you how to adapt the workflows for your own use.

`on: pull_request: types: - ready_for_review`	このワークフローは、リポジトリ内のPull Requestが"ready for review"としてマークされたときに実行されます。
GitHub App only: `- name: Generate token id: generate_token uses: tibdex/github-app-token@36464acb844fc53b9b8b2401da68844f6b05ebb0 with: app_id: ${{ secrets.APP_ID }} private_key: ${{ secrets.APP_PEM }}`	Uses the tibdex/github-app-token action to generate an installation access token for your app from the app ID and private key. The installation access token is accessed later in the workflow as `${{ steps.generate_token.outputs.token }}`. Replace `APP_ID` with the name of the secret that contains your app ID. Replace `APP_PEM` with the name of the secret that contains your app private key.
GitHub App: `env: GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }} ORGANIZATION: YOUR_ORGANIZATION PROJECT_NUMBER: YOUR_PROJECT_NUMBER` Personal access token: `env: GITHUB_TOKEN: ${{ secrets.YOUR_TOKEN }} ORGANIZATION: YOUR_ORGANIZATION PROJECT_NUMBER: YOUR_PROJECT_NUMBER`	このステップのための環境変数を設定します。 If you are using a personal access token, replace `YOUR_TOKEN` with the name of the secret that contains your personal access token. `YOUR_ORGANIZATION`をOrganization名で置き換えてください。たとえば`octo-org`というようにします。 `YOUR_PROJECT_NUMBER`をプロジェクト番号で置き換えてください。プロジェクト番号を知るには、プロジェクトのURLを見てください。たとえば`https://github.com/orgs/octo-org/projects/5`ではプロジェクト番号は5です。
`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`	GitHub CLIを使って、プロジェクトのIDと、プロジェクトの最初の20個のフィールドのID、名前、設定を、APIに問い合わせます。レスポンスは`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	APIクエリからのレスポンスをパースし、関連するIDを環境変数として保存します。これを変更して、様々なフィールドやオプションのIDを取得してください。例: `Team`というフィールドのIDを取得するには、`echo 'TEAM_FIELD_ID='$(jq '.data.organization.projectNext.fields.nodes[] \| select(.name== "Team") \| .id' project_data.json) >> $GITHUB_ENV`を追加してください。 `Team`フィールドの`Octoteam`というオプションのIDを取得するには、`echo 'OCTOTEAM_OPTION_ID='$(jq '.data.organization.projectNext.fields.nodes[] \| select(.name== "Team") \|.settings \| fromjson.options[] \| select(.name=="Octoteam") \|.id' project_data.json) >> $GITHUB_ENV`を追加してください。ノート: このワークフローは、プロジェクトが"Todo"というオプションを含む"Status"という単一選択フィールドと"Date posted"という日付フィールドを持つことを前提としています。テーブル中にあるフィールドにマッチするよう、このセクションは変更しなければなりません。
GitHub App: `env: GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }} PR_ID: ${{ github.event.pull_request.node_id }}` Personal access token: `env: GITHUB_TOKEN: ${{ secrets.YOUR_TOKEN }} PR_ID: ${{ github.event.pull_request.node_id }}`	このステップのための環境変数を設定します。 `GITHUB_TOKEN`は上で説明されています。 `PR_ID`は、このワークフローをトリガーしたPull RequestのIDです。
`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')"`	GitHub CLIとAPIを使って、このワークフローをトリガーしたPull Requestをプロジェクトに追加します。 `jq`フラグは、レスポンスをパースして作成されたアイテムのIDを取得します。
`echo 'ITEM_ID='$item_id >> $GITHUB_ENV`	作成されたアイテムのIDを環境変数として保存します。
`echo "DATE=$(date +"%Y-%m-%d")" >> $GITHUB_ENV`	現在の日付を`yyyy-mm-dd`というフォーマットで環境変数に保存します。
GitHub App: `env: GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}` Personal access token: `env: GITHUB_TOKEN: ${{ secrets.YOUR_TOKEN }}`	このステップのための環境変数を設定します。 `GITHUB_TOKEN`は上で説明されています。
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	`Status`フィールドの値を`Todo`に設定します。 `Date posted`フィールドの値を設定します。

プロジェクト（ベータ）の自動化

ここには以下の内容があります:

はじめに

Built-in workflows

GitHub Actions workflows

Example workflow authenticating with a GitHub App

Example workflow authenticating with a personal access token

Workflow explanation

このドキュメントは役立ちましたか？

これらのドキュメントを素晴らしいものにするのを手伝ってください！

問題がまだ解決していませんか？