Usando a API para gerenciar Projects

Você pode usar a API do GraphQL para automatizar seus projetos.

Tool navigation

Neste artigo

Este artigo demonstra como usar a API do GraphQL para gerenciar um projeto. Para obter mais informações sobre como usar a API em um fluxo de trabalho do GitHub Actions, confira AUTOTITLE. Para ver a lista completa dos tipos de dados disponíveis, confira AUTOTITLE.

Autenticação

Em todos os exemplos de comando a seguir, substitua por um token que tenha o escopo (para consultas) ou escopo (para consultas e mutações). O token pode ser um personal access token (classic) para um usuário ou um token de acesso de instalação para um GitHub App. Para obter mais informações sobre como criar um personal access token, confira AUTOTITLE. Para obter mais informações sobre como criar um token de acesso de instalação para um GitHub App, confira AUTOTITLE.

Quando um token de acesso de instalação é usado para um GitHub App, algumas mutações do GraphQL exigem permissões adicionais. Por exemplo, ao usar a mutação , se você especificar um parâmetro de entrada , a permissão para esse repositório também será necessária para vincular o projeto ao repositório de destino.

Observação

Para saber mais sobre GitHub CLI, confira Sobre o a CLI do GitHub.

Antes de executar os comandos da GitHub CLI, você precisa se autenticar executando . Se você só precisar ler projetos, mas não editá-los, forneça o escopo em vez do . Para obter mais informações sobre a autenticação de linha de comando, confira gh auth login.

Usando variáveis

Em todos os exemplos a seguir, você pode usar variáveis para simplificar seus scripts. Use para passar uma variável que seja um número, booleano ou nulo. Use-o para outras variáveis. Por exemplo:

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

Para saber mais, confira AUTOTITLE.

Encontrando informações sobre os projetos

Use consultas para obter dados sobre projetos. Para saber mais, confira AUTOTITLE.

Encontrando o ID do nó de um projeto da organização

Para atualizar seu projeto por meio da API, você precisará conhecer o nó de ID do projeto.

Você pode encontrar o ID do nó de um projeto de uma organização desde que você saiba o nome da organização e o número do projeto. Substitua pelo nome da sua organização. Por exemplo, . Substitua pelo número do projeto. Para encontrar o número do projeto, consulte a URL do projeto. Por exemplo, tem o número de projeto 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
      }
    }
  }'

Você também pode encontrar o ID do nó de todos os projetos na sua organização. O exemplo a seguir retornará o ID do nó e o título dos primeiros 20 projetos em uma organização. Substitua pelo nome da sua organização. Por exemplo, .

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
        }
      }
    }
  }'

Encontrar o ID do nó do projeto de um usuário

Para atualizar seu projeto por meio da API, você precisará conhecer o nó de ID do projeto.

Você pode encontrar o ID do nó do projeto se você souber o número do projeto. Substitua por seu nome de usuário. Por exemplo, . Substitua pelo número do projeto. Para encontrar o número do projeto, consulte a URL do projeto. Por exemplo, tem o número de projeto 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
      }
    }
  }'

Também é possível encontrar o ID do nó para todos os seus projetos. O exemplo a seguir retornará o node ID e o título dos seus primeiros 20 projetos. Substitua pelo seu nome de usuário. Por exemplo, .

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
        }
      }
    }
  }'

Encontrando o ID do nó de um campo

Para atualizar o valor de um campo, você precisará saber o ID do nó do campo. Além disso, você precisará saber o ID das opções para um único campo selecionado e o ID das iterações para os campos de iteração.

O exemplo a seguir retornará a ID, o nome, as definições e as configurações dos primeiros 20 campos de um projeto. Substitua pela ID de nó do projeto.

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
            }
          }
        }
      }
    }
  }
}'

A resposta será semelhante ao seguinte exemplo:

{
  "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"
                }
              ]
            }
          }
        ]
      }
    }
  }
}

Cada campo tem uma ID e um nome. Os campos de seleção única são retornados como um objeto e têm um campo contendo a ID de cada opção da seleção única. Os campos de iteração são retornados como um objeto e têm um campo que inclui um campo contendo a ID e informações de cada iteração.

Se você precisar apenas do nome e da ID de um campo e não precisar de informações sobre iterações ou opções de um campo de seleção única, use o objeto .

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
          }
        }
      }
    }
  }
}'

A resposta ao usar o objeto será semelhante ao seguinte exemplo:

{
  "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"
          }
        ]
      }
    }
  }
}

Encontrando informações sobre os itens de um projeto

Você pode consultar a API para encontrar informações sobre itens no seu projeto.

O exemplo a seguir retornará os primeiros 20 problemas, solicitações de pull e problemas de rascunho em um projeto. Para os problemas e as solicitações de pull, ele também retornará o título e os dez primeiros destinatários. Para os problemas de rascunho, ele retornará o título e o corpo. O exemplo também retornará o nome e o valor de campos de texto, data ou seleção única nos primeiros oito campos do projeto. Substitua pela ID de nó do projeto.

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
                    }
                  }
                }
              }
            }
          }
        }
      }
    }'

Um projeto pode conter itens que um usuário não tem permissão para visualizar. Nesse caso, o tipo de item será retornado como .

Atualizando projetos

Use mutações para atualizar projetos. Para saber mais, confira AUTOTITLE.

Observação

Não é possível adicionar nem atualizar um item na mesma chamada. Você precisa usar para adicionar o item e usar para atualizar o item.

Adicionando um item a um projeto

O exemplo a seguir adicionará um problema ou pull request ao seu projeto. Substitua pela ID de nó do projeto. Substitua pela ID de nó do problema ou da solicitação de pull que deseja adicionar.

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
      }
    }
  }'

A resposta conterá o ID do nó do item recém-criado.

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

Se você tentar adicionar um item que já existe, o ID do item existente será retornado.

Como adicionar um problema de rascunho a um projeto

O exemplo a seguir adicionará um problema de rascunho ao projeto. Substitua pela ID de nó do projeto. Substitua e pelo conteúdo desejado para o novo problema de rascunho.

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
      }
    }
  }'

A resposta conterá a ID do nó do item do problema de rascunho recém-criado.

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

Atualizando configurações de um projeto

O exemplo a seguir irá atualizar as configurações do seu projeto. Substitua pela ID de nó do projeto. Defina como para tornar seu projeto público no GitHub. Modifique para fazer alterações no README do projeto.

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
      }
    }
  }'

Atualizando um campo de texto, número ou data personalizado

O exemplo a seguir atualizará o valor de um campo de texto de um item. Substitua pela ID de nó do projeto. Substitua pela ID de nó do item que deseja atualizar. Substitua pela ID do campo que deseja atualizar.

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
      }
    }
  }'

Observação

Não é possível usar para alterar , , ou , porque esses campos são propriedades de pull requests e problemas, não de itens de projeto. Nesse caso, você pode usar as seguintes mutações:

  • addAssigneesToAssignable
  • removeAssigneesFromAssignable
  • addLabelsToLabelable
  • removeLabelsFromLabelable
  • updateIssue
  • updatePullRequest
  • transferIssue

Atualizando um único campo de seleção

O exemplo a seguir atualizará o valor de um campo de seleção única para um item.

  • – Substitua-a pela ID de nó do projeto.
  • – Substitua-a pela ID de nó do item que deseja atualizar.
  • – Substitua-a pela ID do campo de seleção única que deseja atualizar.
  • – Substitua-a pela ID da opção de seleção única desejada.
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
      }
    }
  }'

Atualizando um campo de iteração

O exemplo a seguir atualizará o valor de um campo de iteração para um item.

  • – Substitua-a pela ID de nó do projeto.
  • – Substitua-a pela ID de nó do item que deseja atualizar.
  • – Substitua-a pela ID do campo de iteração que deseja atualizar.
  • – Substitua-a pela ID da iteração desejada. Essa iteração pode ser ativa ou concluída.
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
      }
    }
  }'

Excluir um item de um projeto

O exemplo a seguir excluirá um item de um projeto. Substitua pela ID de nó do projeto. Substitua pelo identificador do nó do item que você deseja excluir.

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
    }
  }'

Como gerenciar projetos

Criando projetos

Você pode usar uma mutação para criar um projeto. Para saber mais, confira AUTOTITLE.

Para criar um projeto usando a API, você precisará fornecer um nome para o projeto e a ID do nó de um usuário ou de uma organização do GitHub que passará a ser o proprietário do projeto.

Você pode encontrar o ID do node de um usuário ou de uma organização do GitHub conhecendo o nome de usuário. Substitua pelo nome de usuário do GitHub do novo proprietário do projeto.

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

Para criar o projeto, substitua pela ID do nó do novo proprietário do projeto e substitua por um nome do projeto.

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
      }
     }
  }'

Usando webhooks

Você pode usar webhooks para assinar eventos que ocorrem em seu projeto. Por exemplo, quando um item é editado, o GitHub pode enviar um conteúdo HTTP POST para a URL configurada do webhook que pode disparar a automação em seu servidor. Para obter mais informações sobre webhooks, confira AUTOTITLE. Para saber mais sobre o evento de webhook, confira AUTOTITLE.