APIを使ったプロジェクト(ベータ)の管理

GraphQL APIを使って、プロジェクトに関する情報を見つけたり、プロジェクトを更新したりできます。

この記事では、GraphQL API を使用してプロジェクトを管理する方法を説明します。 For more information about how to use the API in a GitHub Actions workflow, see "Automating projects (beta)." For a full list of the available data types, see "Reference."

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

認証

以下のすべてのcURLの例で、TOKENread:orgスコープ(クエリの場合)もしくはwrite:orgスコープ(クエリ及びミューテーションの場合)を持つトークンで置き換えてください。 The token can be a personal access token for a user or an installation access token for a GitHub App. For more information about creating a personal access token, see "Creating a personal access token." For more information about creating an installation access token for a GitHub App, see "Authenticating with GitHub Apps."

To learn more about GitHub CLI, see "About GitHub CLI."

Before running GitHub CLI commands, you must authenticate by running gh auth login --scopes "write:org". If you only need to read, but not edit, projects, you can omit the --scopes argument. コマンドラインの認証に関する詳しい情報については「 gh authログイン」を参照してください。

変数の利用

以下のすべての例で、変数を使ってスクリプトをシンプルにできます。 数値、論理値あるいはヌルである変数を渡すには、-Fを使ってください。 その他の変数には-fを使ってください。 例,

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

詳しい情報については「GraphQLでの呼び出しの形成」を参照してください。

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

プロジェクトに関するデータを取得するには、クエリを使ってください。 詳しい情報については「クエリについて」を参照してください。

Finding the node ID of an organization project

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

You can find the node ID of an organization project if you know the organization name and project number. ORGANIZATIONをOrganization名で置き換えてください。 たとえばocto-orgというようにします。 Replace NUMBER with the project number. プロジェクト番号を知るには、プロジェクトのURLを見てください。 たとえばhttps://github.com/orgs/octo-org/projects/5ではプロジェクト番号は5です。

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

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

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

Finding the node ID of a user project

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

You can find the node ID of a user project if you know the project number. Replace USER with your user name. octocatなどです。 NUMBERはプロジェクト番号で置き換えてください。 プロジェクト番号を知るには、プロジェクトのURLを見てください。 たとえばhttps://github.com/users/octocat/projects/5ではプロジェクト番号は5です。

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

You can also find the node ID for all of your projects. The following example will return the node ID and title of your first 20 projects. Replace USER with your username. octocatなどです。

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

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

フィールドの値を更新するには、フィールドのノードIDを知る必要があります。 Additionally, you will need to know the ID of the options for single select fields and the ID of the iterations for iteration fields.

以下の例は、プロジェクト内の最初の20個のフィールドのID、名前、設定を返します。 PROJECT_IDをプロジェクトのノードIDで置き換えてください。

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

レスポンスは以下の例のようになります。

{
  "data": {
    "node": {
      "fields": {
        "nodes": [
          {
            "id": "MDE2OlByb2plY3ROZXh0RmllbGQxMzE1OQ==",
            "name": "Title",
            "settings": "null"
          },
          {
            "id": "MDE2OlByb2plY3ROZXh0RmllbGQxMzE2MA==",
            "name": "Assignees",
            "settings": "null"
          },
          {
            "id": "MDE2OlByb2plY3ROZXh0RmllbGQxMzE2MQ==",
            "name": "Status",
            "settings": "{\"options\":[{\"id\":\"f75ad846\",\"name\":\"Todo\",\"name_html\":\"Todo\"},{\"id\":\"47fc9ee4\",\"name\":\"In Progress\",\"name_html\":\"In Progress\"},{\"id\":\"98236657\",\"name\":\"Done\",\"name_html\":\"Done\"}]}"
          },
          {
            "id": "MDE2OlByb2plY3ROZXh0RmllbGQ3NTEwNw==",
            "name": "Iteration",
            "settings": "{\"configuration\":{\"duration\":7,\"start_day\":5,\"iterations\":[{\"id\":\"c4d8e84d\",\"title\":\"Iteration 2\",\"duration\":7,\"start_date\":\"2021-10-08\",\"title_html\":\"Iteration 2\"},{\"id\":\"fafa9c9f\",\"title\":\"Iteration 3\",\"duration\":7,\"start_date\":\"2021-10-15\",\"title_html\":\"Iteration 3\"}],\"completed_iterations\":[{\"id\":\"fa62c118\",\"title\":\"Iteration 1\",\"duration\":7,\"start_date\":\"2021-10-01\",\"title_html\":\"Iteration 1\"}]}}"
          }
        ]
      }
    }
  }
}

各フィールドはIDを持ちます。 Additionally, single select fields and iteration fields have a settings value. In the single select settings, you can find the ID of each option for the single select. In the iteration settings, you can find the duration of the iteration, the start day of the iteration (from 1 for Monday to 7 for Sunday), the list of incomplete iterations, and the list of completed iterations. For each iteration in the lists of iterations, you can find the ID, title, duration, and start date of the iteration.

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

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

以下の例は、プロジェクト中の最初の20個のアイテムのタイトルとIDを返します。 それぞれのアイテムについては、プロジェクト中の最初の8個のフィールドの値と名前も返します。 アイテムがIssueあるいはPull Requestの場合、アサインされた最初の10人のログインも返します。 PROJECT_IDをプロジェクトのノードIDで置き換えてください。

curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: token TOKEN' \
  --data '{"query":"query{node(id: \"PROJECT_ID\") {... on ProjectNext {items(first: 20) {nodes{title id fieldValues(first: 8) {nodes{value projectField{name}}} content{...on Issue {assignees(first: 10) {nodes{login}}} ...on PullRequest {assignees(first: 10) {nodes{login}}}}}}}}}"}'
gh api graphql -f query='
  query{
    node(id: "PROJECT_ID") {
      ... on ProjectNext {
        items(first: 20) {
          nodes{
            title
            id
            fieldValues(first: 8) {
              nodes{
                value
                projectField{
                  name
                }
              }
            }
            content{
              ...on Issue {
                assignees(first: 10) {
                  nodes{
                    login
                  }
                }
              }
              ...on PullRequest {
                assignees(first: 10) {
                  nodes{
                    login
                  }
                }
              }
            }
          }
        }
      }
    }
  }'

プロジェクトは、ユーザが表示権限を持たないアイテムを含んでいることがあります。 この場合、レスポンスには削減済みのアイテムが含まれます。

{
  "node": {
  "title": "You can't see this item",
  ...
  }
}

プロジェクトの更新

プロジェクトを更新するには、ミューテーションを使ってください。 For more information, see "About mutations."

ノート: 同じ呼び出し中で、アイテムを追加して更新することはできません。 addProjectNextItemを使ってアイテムを追加し、それからupdateProjectNextItemFieldを使ってそのアイテムを更新しなければなりません。

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

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

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

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

{
  "data": {
    "addProjectNextItem": {
      "projectNextItem": {
        "id": "MDE1OlByb2plY3ROZXh0SXRlbTM0MjEz"
      }
    }
  }
}

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

Updating a custom text, number, or date field

The following example will update the value of a date field for an item. PROJECT_IDをプロジェクトのノードIDで置き換えてください。 ITEM_IDを、更新したいアイテムのノードIDで置き換えてください。 FIELD_IDを、更新したいフィールドのIDで置き換えてください。

curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: token TOKEN' \
  --data '{"query":"mutation {updateProjectNextItemField(input: {projectId: \"PROJECT_ID\" itemId: \"ITEM_ID\" fieldId: \"FIELD_ID\" value: \"2021-5-11\"}) {projectNextItem {id}}}"}'
gh api graphql -f query='
  mutation {
    updateProjectNextItemField(
      input: {
        projectId: "PROJECT_ID"
        itemId: "ITEM_ID"
        fieldId: "FIELD_ID"
        value: "2021-5-11"
      }
    ) {
      projectNextItem {
        id
      }
    }
  }'

ノート: updateProjectNextItemFieldを使ってAssigneesLabelsMilestoneRepositoryを変更することはできません。これは、これらのフィールドがプロジェクトのアイテムのプロパティではなく、Pull RequestやIssueのプロパティだからです。 Instead, you must use the addAssigneesToAssignable, removeAssigneesFromAssignable, addLabelsToLabelable, removeLabelsFromLabelable, updateIssue, updatePullRequest, or transferIssue mutations.

Updating a single select field

The following example will update the value of a single select field for an item.

  • PROJECT_ID - プロジェクトのノードIDで置き換えてください。
  • ITEM_ID - 更新したいアイテムのノードIDで置き換えてください。
  • FIELD_ID - Replace this with the ID of the single select field that you want to update.
  • OPTION_ID - Replace this with the ID of the desired single select option.

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

Updating an iteration field

The following example will update the value of an iteration field for an item.

  • PROJECT_ID - プロジェクトのノードIDで置き換えてください。
  • ITEM_ID - 更新したいアイテムのノードIDで置き換えてください。
  • FIELD_ID - Replace this with the ID of the iteration field that you want to update.
  • ITERATION_ID - Replace this with the ID of the desired iteration. This can be either an active iteration (from the iterations array) or a completed iteration (from the completed_iterations array).

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

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

以下の例は、プロジェクトからアイテムを削除します。 PROJECT_IDをプロジェクトのノードIDで置き換えてください。 ITEM_IDを、削除したいアイテムのノードIDで置き換えてください。

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

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

プライバシーポリシー

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

GitHubのすべてのドキュメントはオープンソースです。間違っていたり、はっきりしないところがありましたか?Pull Requestをお送りください。

コントリビューションを行う

OR, コントリビューションの方法を学んでください。

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