Skip to main content

API を使用して Projects を管理する

GraphQL API を使用して、プロジェクトを自動化できます。

Tool navigation

この記事では、GraphQL API を使用してプロジェクトを管理する方法を説明します。 GitHub Actions ワークフローでの API の使い方について詳しくは、「Actions を使用した Projects の自動化」をご覧ください。 使用可能なデータ型の完全な一覧については、「関連項目」をご覧ください。

認証

次のすべての curl コマンドの例では、TOKEN を、read:project スコープ (クエリの場合) または project スコープ (クエリとミューテーションの場合) を持つトークンに置き換えます。 このトークンは、ユーザーのpersonal access token (classic)でも、GitHub App のインストール アクセス トークンでもかまいません。 personal access tokenの作成について詳しくは、「個人用アクセス トークンを管理する」をご覧ください。 GitHub App のインストール アクセス トークンの作成について詳しくは、「GitHub アプリのインストール アクセス トークンの生成」をご覧ください。

GitHub App にインストール アクセス トークンを使用する場合、一部の GraphQL ミューテーションには追加のアクセス許可が必要になります。 たとえば、createProjectV2 ミューテーションを使用する際に repositoryId 入力パラメーターを指定する場合は、プロジェクトをターゲット リポジトリにリンクするために、そのリポジトリの Contents アクセス許可も必要です。

GitHub CLI の詳細については、「GitHub CLI について」を参照してください。

GitHub CLI コマンドを実行する前に、gh auth login --scopes "project" を実行して認証する必要があります。 プロジェクトの読み取りだけを行い、編集を行う必要がないのであれば、project の代わりに read:project スコープを指定できます。 コマンド ライン認証の詳細については、「gh auth login」を参照してください。

変数の使用

以下のすべての例で、変数を使ってスクリプトをシンプルにできます。 数値、ブール値、または null 値である変数を渡すには、-F を使用ます。 その他の変数の場合は、-f を使用します。 たとえば、次のように入力します。

my_org="octo-org"
my_num=5
gh api graphql -f query='
  query($organization: String! $number: Int!){
    organization(login: $organization){
      projectV2(number: $number) {
        id
      }
    }
  }' -f organization=$my_org -F number=$my_num

詳しくは、「GraphQLでの呼び出しの作成」を参照してください。

プロジェクトに関する情報を見つける

プロジェクトに関するデータを取得するには、クエリを使ってください。 詳しくは、「GraphQLでの呼び出しの作成」を参照してください。

OrganizationプロジェクトのノードIDを調べる

APIを通じてプロジェクトを更新するには、プロジェクトのノードIDを知る必要があります。

Organization名とプロジェクト番号が分かっていれば、OrganizationプロジェクトのノードIDを知ることができます。 ORGANIZATION を自身の組織の名前に置き換えます。 たとえば、「 octo-org 」のように入力します。 NUMBER をプロジェクト番号に置き換えます。 プロジェクト番号を見つけるには、プロジェクトのURLを見てください。 たとえば、https://github.com/orgs/octo-org/projects/5 のプロジェクト番号は 5 です。

curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: Bearer TOKEN' \
  --data '{"query":"query{organization(login: \"ORGANIZATION\") {projectV2(number: NUMBER){id}}}"}'
gh api graphql -f query='
  query{
    organization(login: "ORGANIZATION"){
      projectV2(number: NUMBER) {
        id
      }
    }
  }'

Organization中のすべてのプロジェクトのノードIDを見つけることもできます。 以下の例は、Orgazation中の最初の20個のプロジェクトのノードIDとタイトルを返します。 ORGANIZATION を自身の組織の名前に置き換えます。 たとえば、「 octo-org 」のように入力します。

curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: Bearer TOKEN' \
  --data '{"query":"{organization(login: \"ORGANIZATION\") {projectsV2(first: 20) {nodes {id title}}}}"}'
gh api graphql -f query='
  query{
    organization(login: "ORGANIZATION") {
      projectsV2(first: 20) {
        nodes {
          id
          title
        }
      }
    }
  }'

ユーザプロジェクトのノードIDを調べる

APIを通じてプロジェクトを更新するには、プロジェクトのノードIDを知る必要があります。

ユーザプロジェクトのノードIDは、プロジェクト番号を知っていれば見つけることができます。 USER は、実際のユーザー名に置き換えます。 たとえば、「 octocat 」のように入力します。 NUMBERをプロジェクト番号に置き換えます。 プロジェクト番号を見つけるには、プロジェクトのURLを見てください。 たとえば、https://github.com/users/octocat/projects/5 のプロジェクト番号は 5 です。

curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: Bearer TOKEN' \
  --data '{"query":"query{user(login: \"USER\") {projectV2(number: NUMBER){id}}}"}'
gh api graphql -f query='
  query{
    user(login: "USER"){
      projectV2(number: NUMBER) {
        id
      }
    }
  }'

自分のすべてのプロジェクトのノードIDを知ることもできます。 以下の例では、自分の最初の20個のプロジェクトのノードIDとタイトルが返されます。 USER をご自分のユーザー名に置き換えます。 たとえば、octocat のようにします。

curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: Bearer TOKEN' \
  --data '{"query":"{user(login: \"USER\") {projectsV2(first: 20) {nodes {id title}}}}"}'
gh api graphql -f query='
  query{
    user(login: "USER") {
      projectsV2(first: 20) {
        nodes {
          id
          title
        }
      }
    }
  }'

フィールドのノードIDを見つける

フィールドの値を更新するには、フィールドのノードIDを知る必要があります。 加えて、単一選択フィールドの選択肢のIDと、繰り返しフィールドの繰り返しのIDも知る必要があります。

以下の例では、プロジェクト内の最初の 20 個のフィールドの ID、名前、設定、構成が返されます。 PROJECT_ID はプロジェクトのノード ID に置き換えます。

curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: Bearer TOKEN' \
  --data '{"query":"query{ node(id: \"PROJECT_ID\") { ... on ProjectV2 { fields(first: 20) { nodes { ... on ProjectV2Field { id name } ... on ProjectV2IterationField { id name configuration { iterations { startDate id }}} ... on ProjectV2SingleSelectField { id name options { id name }}}}}}}"}'
gh api graphql -f query='
  query{
  node(id: "PROJECT_ID") {
    ... on ProjectV2 {
      fields(first: 20) {
        nodes {
          ... on ProjectV2Field {
            id
            name
          }
          ... on ProjectV2IterationField {
            id
            name
            configuration {
              iterations {
                startDate
                id
              }
            }
          }
          ... on ProjectV2SingleSelectField {
            id
            name
            options {
              id
              name
            }
          }
        }
      }
    }
  }
}'

応答は、次の例のようになります。

{
  "data": {
    "node": {
      "fields": {
        "nodes": [
          {
            "id": "PVTF_lADOANN5s84ACbL0zgBZrZY",
            "name": "Title"
          },
          {
            "id": "PVTF_lADOANN5s84ACbL0zgBZrZc",
            "name": "Assignees"
          },
          {
            "id": "PVTSSF_lADOANN5s84ACbL0zgBZrZg",
            "name": "Status",
            "options": [
              {
                "id": "f75ad846",
                "name": "Todo"
              },
              {
                "id": "47fc9ee4",
                "name": "In Progress"
              },
              {
                "id": "98236657",
                "name": "Done"
              }
            ]
          },
          {
            "id": "PVTIF_lADOANN5s84ACbL0zgBah28",
            "name": "Iteration",
            "configuration": {
              "iterations": [
                {
                  "startDate": "2022-05-29",
                  "id": "cfc16e4d"
                }
              ]
            }
          }
        ]
      }
    }
  }
}

各フィールドには ID と名前があります。 単一選択フィールドは ProjectV2SingleSelectField オブジェクトとして返され、単一選択の各オプションの ID を見つけることができる options フィールドがあります。 繰り返しフィールドは ProjectV2IterationField オブジェクトとして返され、ID と各繰り返しに関する情報が含まれている iterations フィールドを含む configuration フィールドがあります。

フィールドの名前と ID のみが必要で、繰り返しや単一選択フィールドのオプションに関する情報が必要ない場合は、ProjectV2FieldCommon オブジェクトを利用できます。

curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: Bearer TOKEN' \
  --data '{"query":"query{ node(id: \"PROJECT_ID\") { ... on ProjectV2 { fields(first: 20) { nodes { ... on ProjectV2FieldCommon { id name }}}}}}"}'
gh api graphql -f query='
  query{
  node(id: "PROJECT_ID") {
    ... on ProjectV2 {
      fields(first: 20) {
        nodes {
          ... on ProjectV2FieldCommon {
            id
            name
          }
        }
      }
    }
  }
}'

ProjectV2FieldCommon オブジェクトを使用する場合の応答は、次の例のようになります。

{
  "data": {
    "node": {
      "fields": {
        "nodes": [
          {
            "__typename": "ProjectV2Field",
            "id": "PVTF_lADOANN5s84ACbL0zgBZrZY",
            "name": "Title"
          },
          {
            "__typename": "ProjectV2Field",
            "id": "PVTF_lADOANN5s84ACbL0zgBZrZc",
            "name": "Assignees"
          },
          {
            "__typename": "ProjectV2SingleSelectField",
            "id": "PVTSSF_lADOANN5s84ACbL0zgBZrZg",
            "name": "Status"
          },
          {
            "__typename": "ProjectV2IterationField",
            "id": "PVTIF_lADOANN5s84ACbL0zgBah28",
            "name": "Iteration"
          }
        ]
      }
    }
  }
}

プロジェクト中のアイテムに関する情報を見つける

APIでクエリを行い、プロジェクト中のアイテムに関する情報を見つけることができます。

次の例では、プロジェクトの最初の 20 件の issue、pull request、ドラフト issue が返されます。 issue と pull request の場合は、タイトルと最初の 10 人の担当者も返されます。 ドラフト issue の場合は、タイトルと本文が返されます。 この例では、プロジェクトの最初の 8 つのフィールドのテキスト、日付、または単一選択フィールドのフィールド名と値も返されます。 PROJECT_ID はプロジェクトのノード ID に置き換えます。

curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: Bearer TOKEN' \
  --data '{"query":"query{ node(id: \"PROJECT_ID\") { ... on ProjectV2 { items(first: 20) { nodes{ id fieldValues(first: 8) { nodes{ ... on ProjectV2ItemFieldTextValue { text field { ... on ProjectV2FieldCommon {  name }}} ... on ProjectV2ItemFieldDateValue { date field { ... on ProjectV2FieldCommon { name } } } ... on ProjectV2ItemFieldSingleSelectValue { name field { ... on ProjectV2FieldCommon { name }}}}} content{ ... on DraftIssue { title body } ...on Issue { title assignees(first: 10) { nodes{ login }}} ...on PullRequest { title assignees(first: 10) { nodes{ login }}}}}}}}}"}'
gh api graphql -f query='
  query{
    node(id: "PROJECT_ID") {
        ... on ProjectV2 {
          items(first: 20) {
            nodes{
              id
              fieldValues(first: 8) {
                nodes{                
                  ... on ProjectV2ItemFieldTextValue {
                    text
                    field {
                      ... on ProjectV2FieldCommon {
                        name
                      }
                    }
                  }
                  ... on ProjectV2ItemFieldDateValue {
                    date
                    field {
                      ... on ProjectV2FieldCommon {
                        name
                      }
                    }
                  }
                  ... on ProjectV2ItemFieldSingleSelectValue {
                    name
                    field {
                      ... on ProjectV2FieldCommon {
                        name
                      }
                    }
                  }
                }              
              }
              content{              
                ... on DraftIssue {
                  title
                  body
                }
                ...on Issue {
                  title
                  assignees(first: 10) {
                    nodes{
                      login
                    }
                  }
                }
                ...on PullRequest {
                  title
                  assignees(first: 10) {
                    nodes{
                      login
                    }
                  }
                }
              }
            }
          }
        }
      }
    }'

プロジェクトは、ユーザが表示権限を持たないアイテムを含んでいることがあります。 この場合、アイテムの種類は REDACTED として返されます。

プロジェクトの更新

プロジェクトを更新するには、ミューテーションを使ってください。 詳しくは、「GraphQLでの呼び出しの作成」を参照してください。

注: 同じ呼び出しで項目を追加および更新することはできません。 addProjectV2ItemById を使用して項目を追加してから、updateProjectV2ItemFieldValue を使用して項目を更新する必要があります。

プロジェクトへのアイテムの追加

以下の例は、プロジェクトにIssueあるいはPull Requestを追加します。 PROJECT_ID はプロジェクトのノード ID に置き換えます。 CONTENT_ID は、追加する Issue または Pull Request のノード ID に置き換えます。

curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: Bearer TOKEN' \
  --data '{"query":"mutation {addProjectV2ItemById(input: {projectId: \"PROJECT_ID\" contentId: \"CONTENT_ID\"}) {item {id}}}"}'
gh api graphql -f query='
  mutation {
    addProjectV2ItemById(input: {projectId: "PROJECT_ID" contentId: "CONTENT_ID"}) {
      item {
        id
      }
    }
  }'

レスポンスには、新しく作成されたアイテムのノードIDが含まれます。

{
  "data": {
    "addProjectV2ItemById": {
      "item": {
        "id": "PVTI_lADOANN5s84ACbL0zgBVd94"
      }
    }
  }
}

既に存在しているアイテムを追加しようとすると、代わりに既存のアイテムのIDが返されます。

プロジェクトへのドラフト issue の追加

次の例では、プロジェクトにドラフト issue を追加します。 PROJECT_ID はプロジェクトのノード ID に置き換えます。 TITLEBODY は、新しいドラフト issue に必要なコンテンツに置き換えます。

curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: Bearer TOKEN' \
  --data '{"query":"mutation {addProjectV2DraftIssue(input: {projectId: \"PROJECT_ID\" title: \"TITLE\" body: \"BODY\"}) {projectItem {id}}}"}'
gh api graphql -f query='
  mutation {
    addProjectV2DraftIssue(input: {projectId: "PROJECT_ID" title: "TITLE" body: "BODY"}) {
      projectItem {
        id
      }
    }
  }'

応答には、新しく作成されたドラフト issue のノード ID が含まれます。

{
  "data": {
    "addProjectV2DraftIssue": {
      "projectItem": {
        "id": "PVTI_lADOANN5s84ACbL0zgBbxFc"
      }
    }
  }
}

プロジェクトの設定の更新

以下の例は、プロジェクトの設定を更新します。 PROJECT_ID はプロジェクトのノード ID に置き換えます。 publictrue に設定し、GitHub Enterprise Cloud でプロジェクトをパブリックにします。 readme を変更し、プロジェクトの README に変更を加えます。

curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: Bearer TOKEN' \
--data '{"query":"mutation { updateProjectV2(input: { projectId: \"PROJECT_ID\", title: \"Project title\", public: false, readme: \"# Project README\n\nA long description\", shortDescription: \"A short description\"}) { projectV2 { id, title, readme, shortDescription }}}"}'
gh api graphql -f query='
  mutation {
    updateProjectV2(
      input: {
        projectId: "PROJECT_ID", 
        title: "Project title",
        public: false,
        readme: "# Project README\n\nA long description",
        shortDescription: "A short description"
      }
    ) {
      projectV2 {
        id
        title
        readme
        shortDescription
      }
    }
  }'

カスタムのテキスト、数値、日付フィールドの更新

以下の例では、アイテムのテキスト フィールドの値を更新します。 PROJECT_ID はプロジェクトのノード ID に置き換えます。 ITEM_ID は、更新する項目のノード ID に置き換えます。 FIELD_ID は、更新するフィールドの ID に置き換えます。

curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: Bearer TOKEN' \
  --data '{"query":"mutation {updateProjectV2ItemFieldValue( input: { projectId: \"PROJECT_ID\" itemId: \"ITEM_ID\" fieldId: \"FIELD_ID\" value: { text: \"Updated text\" }}) { projectV2Item { id }}}"}'
gh api graphql -f query='
  mutation {
    updateProjectV2ItemFieldValue(
      input: {
        projectId: "PROJECT_ID"
        itemId: "ITEM_ID"
        fieldId: "FIELD_ID"
        value: { 
          text: "Updated text"        
        }
      }
    ) {
      projectV2Item {
        id
      }
    }
  }'

注: updateProjectV2ItemFieldValue を使用して AssigneesLabelsMilestoneRepository を変更することはできません。これらのフィールドは、プロジェクト項目ではなく、Pull Request と Issue のプロパティであるためです。 代わりに、次のミューテーションを使用できます。

単一選択フィールドの更新

以下の例は、アイテムの単一選択フィールドの値を更新します。

  • PROJECT_ID - これをプロジェクトのノード ID に置き換えます。
  • ITEM_ID - これを、更新する項目のノード ID に置き換えます。
  • FIELD_ID - これを、更新する単一選択フィールドの ID に置き換えます。
  • OPTION_ID - これを、目的の単一選択オプションの ID に置き換えます。
curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: Bearer TOKEN' \
  --data '{"query":"mutation {updateProjectV2ItemFieldValue( input: { projectId: \"PROJECT_ID\" itemId: \"ITEM_ID\" fieldId: \"FIELD_ID\" value: { singleSelectOptionId: \"OPTION_ID\" }}) { projectV2Item { id }}}"}'
gh api graphql -f query='
  mutation {
    updateProjectV2ItemFieldValue(
      input: {
        projectId: "PROJECT_ID"
        itemId: "ITEM_ID"
        fieldId: "FIELD_ID"
        value: { 
          singleSelectOptionId: "OPTION_ID"        
        }
      }
    ) {
      projectV2Item {
        id
      }
    }
  }'

繰り返しフィールドの更新

以下の例は、アイテムの繰り返しフィールドの値を更新します。

  • PROJECT_ID - これをプロジェクトのノード ID に置き換えます。
  • ITEM_ID - これを、更新する項目のノード ID に置き換えます。
  • FIELD_ID - これを、更新する繰り返しフィールドの ID に置き換えます。
  • ITERATION_ID - これを、目的の繰り返しの ID に置き換えます。 これは、アクティブなまたは完了した繰り返しにすることができます。
curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: Bearer TOKEN' \
  --data '{"query":"mutation {updateProjectV2ItemFieldValue( input: { projectId: \"PROJECT_ID\" itemId: \"ITEM_ID\" fieldId: \"FIELD_ID\" value: { iterationId: \"ITERATION_ID\" }}) { projectV2Item { id }}}"}'
gh api graphql -f query='
  mutation {
    updateProjectV2ItemFieldValue(
      input: {
        projectId: "PROJECT_ID"
        itemId: "ITEM_ID"
        fieldId: "FIELD_ID"
        value: { 
          iterationId: "ITERATION_ID"        
        }
      }
    ) {
      projectV2Item {
        id
      }
    }
  }'

プロジェクトからのアイテムの削除

以下の例は、プロジェクトからアイテムを削除します。 PROJECT_ID はプロジェクトのノード ID に置き換えます。 ITEM_ID は、削除する項目のノード ID に置き換えます。

curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: Bearer TOKEN' \
  --data '{"query":"mutation {deleteProjectV2Item(input: {projectId: \"PROJECT_ID\" itemId: \"ITEM_ID\"}) {deletedItemId}}"}'
gh api graphql -f query='
  mutation {
    deleteProjectV2Item(
      input: {
        projectId: "PROJECT_ID"
        itemId: "ITEM_ID"
      }
    ) {
      deletedItemId
    }
  }'

プロジェクトを管理する

プロジェクトの作成

ミューテーションを使って、新しいプロジェクトを作成できます。 詳しくは、「GraphQLでの呼び出しの作成」を参照してください。

API を使って新しいプロジェクトを作成するには、プロジェクトの名前と、プロジェクトの所有者になる GitHub Enterprise Cloud ユーザーまたは Organization のノード ID を指定する必要があります。

ユーザー名がわかっている場合は、GitHub Enterprise Cloud ユーザーまたは Organization のノード ID を確認できます。 GITHUB_OWNER を、新しいプロジェクト所有者の GitHub Enterprise Cloud ユーザー名に置き換えます。

curl --request GET \
  --url https://api.github.com/users/GITHUB_OWNER \
  --header 'Authorization: token TOKEN' \
  --header 'Accept: application/vnd.github+json'
gh api -H "Accept: application/vnd.github+json" /users/GITHUB_OWNER

プロジェクトを作成するには、OWNER_ID を新しいプロジェクト所有者のノード ID に置き換え、PROJECT_NAME をプロジェクトの名前に置き換えます。

curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: token TOKEN' \
  --data '{"query":"mutation {createProjectV2(input: {ownerId: \"OWNER_ID\" title: \"PROJECT_NAME\"}) {projectV2 {id}}}"}'
gh api graphql -f query='
  mutation{
    createProjectV2(
      input: {
        ownerId: "OWNER_ID",
        title: "PROJECT_NAME"
      }
    ){
      projectV2 {
        id
      }
     }
  }'

Webhook の使用

Webhook を使用して、プロジェクトで発生するイベントをサブスクライブできます。 たとえば、アイテムが編集されると、GitHub Enterprise Cloud では、サーバーでの自動化をトリガーできる Webhook の構成済み URL に HTTP POST ペイロードを送信できます。 Webhook について詳しくは、「webhook について」をご覧ください。 projects_v2_item Webhook イベントについて詳しくは、「Webhook のイベントとペイロード」をご覧ください。