Skip to main content

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

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

この記事では、GraphQL API を使用してプロジェクトを管理する方法を説明します。 GitHub ActionsワークフローでのAPIの使用方法に関する詳しい情報については「プロジェクト(ベータ)の自動化」を参照してください。 利用可能なデータタイプの完全なリストについては「リファレンス」を参照してください。

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

認証

以下のすべてのcURLの例で、TOKENread:orgスコープ(クエリの場合)もしくはwrite:orgスコープ(クエリ及びミューテーションの場合)を持つトークンで置き換えてください。 このトークンは、ユーザの場合は個人アクセストークンに、GitHub Appの場合はインストールアクセストークンにできます。 個人アクセストークンの作成に関する詳しい情報については「個人アクセストークンの作成」を参照してください。 GitHub Appのためのインストールアクセストークンの作成に関する詳しい情報については「GitHub Appsでの認証」を参照してください。

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

GitHub CLIコマンドを実行する前に、gh auth login --scopes "write:org"を実行して認証を受けなければなりません。 プロジェクトの読み取りだけを行い、編集を行う必要がないのであれば、--scopes引数は省略できます。 コマンドラインの認証に関する詳しい情報については「 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での読み出しの形成」を参照してください。

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

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

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

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

Organization名とプロジェクト番号が分かっていれば、OrganizationプロジェクトのノードIDを知ることができます。 ORGANIZATIONを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: 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
        }
      }
    }
  }'

ユーザプロジェクトのノード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: 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
      }
    }
  }'

自分のすべてのプロジェクトのノードIDを知ることもできます。 以下の例では、自分の最初の20個のプロジェクトのノードIDとタイトルが返されます。 USERは自分のユーザ名で置き換えてください。 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を知る必要があります。 加えて、単一選択フィールドの選択肢のIDと、繰り返しフィールドの繰り返しのIDも知る必要があります。

以下の例は、プロジェクト内の最初の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を持ちます。 加えて、単一選択フィールドと繰り返しフィールドは、settings値を持ちます。 単一選択の設定では、単一選択の各選択肢のIDを知ることができます。 繰り返しの設定では、繰り返しの期間、繰り返しの開始日(月曜の1から日曜の7まで)、未完了の繰り返しのリスト、完了した繰り返しのリストを知ることができます。 繰り返しのリスト中の各繰り返しについて、繰り返しのID、タイトル、期間、開始日を知ることができます。

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

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

ノート: このAPIはドラフトIssueに関する情報は返しません。

以下の例は、プロジェクト中の最初の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",
  ...
  }
}

プロジェクトの更新

プロジェクトを更新するには、ミューテーションを使ってください。 詳しい情報については「ミューテーションについて」を参照してください。

ノート: 同じ呼び出し中で、アイテムを追加して更新することはできません。 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が返されます。

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

以下の例は、プロジェクトの設定を更新します。 PROJECT_IDをプロジェクトのノードIDで置き換えてください。 プロジェクトをGitHub Enterprise Cloud上でパブリックにするために、publictrueに設定してください。 descriptionを修正して、プロジェクトのREADMEを変更してください。

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

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

以下の例は、アイテムの日付フィールドの値を更新します。 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のプロパティだからです。 代わりに、addAssigneesToAssignableremoveAssigneesFromAssignableaddLabelsToLabelableremoveLabelsFromLabelableupdateIssueupdatePullRequesttransferIssueといったミューテーションを使ってください。

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

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

  • PROJECT_ID - プロジェクトのノードIDで置き換えてください。
  • ITEM_ID - 更新したいアイテムのノードIDで置き換えてください。
  • FIELD_ID - 更新したい単一選択フィールドのIDで置き換えてください。
  • OPTION_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: \"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
      }
    }
  }'

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

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

  • PROJECT_ID - プロジェクトのノードIDで置き換えてください。
  • ITEM_ID - 更新したいアイテムのノードIDで置き換えてください。
  • FIELD_ID - 更新したい繰り返しフィールドのIDで置き換えてください。
  • ITERATION_ID - 希望する繰り返しのIDで置き換えてください。 これはアクティブな繰り返し(iterations配列から)もしくは完了した繰り返し(completed_iterations配列から)にできます。
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
    }
  }'