Usando a API para gerenciar projetos (beta)

Este artigo demonstra como usar a API do GraphQL para gerenciar um projeto. Para obter mais informações sobre como utilizar a API em um fluxo de trabalho GitHub Actions, consulte "Automatizando projetos (beta)". Para uma lista completa dos tipos de dados disponíveis, consulte "Referência".

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

Autenticação

Em todos os exemplos cURL a seguir, substitua TOKEN por um token que tem o escopo read:org (para consultas) ou write:org (para consultas e mutações). O token pode ser um token de acesso pessoal para um usuário ou um token de acesso de instalação para um aplicativo GitHub. Para obter mais informações sobre a criação de um token de acesso pessoal, consulteCriando um token de acesso pessoal." Para obter mais informações sobre a criação de um token de acesso de instalação para um aplicativo GitHub, consulte "Efetuando a autenticação com Aplicativos do GitHub".

Para saber mais sobre GitHub CLI, consulte "Sobre GitHub CLI."

Antes de executar os comandos de GitHub CLI, você deverá efetuar a autenticação executando gh login --scopes "write:org". Se você só tiver de ler, mas não editar, projetos, você poderá omitir o argumento --escopes. Para obter mais informações sobre a autenticação de linha de comando, consulte "gh auth login".

Usando variáveis

Em todos os exemplos a seguir, você pode usar variáveis para simplificar seus scripts. Use -F para passar uma variável que é um número, booleano ou nulo. Use -f 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){
      projectNext(number: $number) {
        id
      }
    }
  }' -f organization=$my_org -F number=$my_num

Para obter mais informações, consulte "Formando chamadas com o GraphQL".

Encontrando informações sobre os projetos

Use consultas para obter dados sobre projetos. Para obter mais informações, consulte "Sobre consultas".

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 nó do projeto de uma organização se você souber o nome da organização e o número do projeto. Substitua ORGANIZATION pelo nome da sua organização. Por exemplo, octo-org. Substituir NÚMERO pelo número do projeto. Para encontrar o número do projeto, consulte a URL do projeto. Por exemplo, https://github.com/orgs/octo-org/projects/5 tem um número de projeto de 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
      }
    }
  }'

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 ORGANIZATION pelo nome da sua organização. Por exemplo, 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
        }
      }
    }
  }'

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 USUÁRIO pelo seu nome de usuário. Por exemplo, octocat. Substitua NUMBER pelo número do seu projeto. Para encontrar o número do projeto, consulte a URL do projeto. Por exemplo, https://github.com/users/octocat/projects/5 tem um número de projeto de 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
      }
    }
  }'

Também é possível encontrar o ID do nó para todos os seus projetos. O exemplo a seguir retornará o ID do nó e o título de seus primeiros 20 projetos. Substitua USUÁRIO pelo seu nome de usuário. Por exemplo, 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
        }
      }
    }
  }'

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á o ID, o nome e as configurações para os primeiros 20 campos de um projeto. Substitua PROJECT_ID pelo ID do nó do seu projeto.

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

A resposta ficará semelhante ao seguinte exemplo:

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

Cada campo tem um ID. Além disso, campos únicos selecionados e iteração têm um valor de configurações. Nas configurações de seleção única, você pode encontrar o ID de cada opção para a seleção única. Nas configurações de iteração, você pode encontrar a duração da iteração, o dia de início da iteração (1 para segunda-feira e 7 para domingo), a lista de iterações incompletas e a lista de iterações concluídas. Para cada iteração nas listas de iterações, você pode encontrar o ID, título, duração e data de início da iteração.

Encontrando informações sobre os itens de um projeto

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

Observação: A API não retornará informações sobre os rascunhos dos problemas.

O exemplo a seguir retornará o título e ID dos primeiros 20 itens em um projeto. Para cada item, ela também retornará o valor e nome para os primeiros 8 campos do projeto. Se o item for um problema ou um pull request, ele retornará o login dos primeiros 10 responsáveis. Substitua PROJECT_ID pelo ID do nó do seu projeto.

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

Um projeto pode conter itens que um usuário não tem permissão para visualizar. Neste caso, a resposta incluirá o item redatado.

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

Atualizando projetos

Use mutações para atualizar projetos. Para obter mais informações, consulte "Sobre mutações".

Observação: Você não pode adicionar e atualizar um item na mesma chamada. Você deve usar addProjectNextItem para adicionar o item e, em seguida, usar updateProjectNextItemField para atualizar o item.

Adicionando um item a um projeto

O exemplo a seguir adicionará um problema ou pull request ao seu projeto. Substitua PROJECT_ID pelo ID do nó do seu projeto. Substitua CONTENT_ID pelo ID do n[o do problema ou pull request que você deseja adicionar.

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

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

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

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

Atualizando configurações de um projeto

O exemplo a seguir irá atualizar as configurações do seu projeto. Substitua PROJECT_ID pelo ID do nó do seu projeto. Defina público como verdadeiro para tornar o seu projeto público em GitHub. Modifique a descrição para fazer alterações no README do seu projeto.

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

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

O exemplo a seguir atualizará o valor de um campo de data para um item. Substitua PROJECT_ID pelo ID do nó do seu projeto. Substitua ITEM_ID pelo ID do nó do item que você deseja atualizar. Substitua FIELD_ID pelo ID do campo que você deseja atualizar.

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

Observação: Você não pode usar updateProjectNextItemField para alterar Assignees, Labels, Milestone ou Repository porque esses campos são propriedades de pull requests e problemas, não de itens do projeto. Em vez disso, você deverá usar a mutação addAssigneesToAssignable, removeAssigneesFromAssignable, addLabelsToLabelable, removeLabelsFromLabelable, updateIssue, updatePullRequest ou 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.

PROJET_ID - Substituir isso pelo ID do nó do seu projeto.
ITEM_ID - Substituir isso pelo ID do nó do item que você deseja atualizar.
FIELD_ID - Substitua-o pelo ID do campo de seleção única que você deseja atualizar.
OPTION_ID - Substitui esse ID da opção de seleção única desejada.

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

Atualizando um campo de iteração

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

PROJET_ID - Substituir isso pelo ID do nó do seu projeto.
ITEM_ID - Substituir isso pelo ID do nó do item que você deseja atualizar.
FIELD_ID - Substitua este ID do campo de iteração que você deseja atualizar.
ITERATION_ID - Substitua o ID da iteração desejada. Isso pode ser uma iteração ativa (da matriz de iterações) ou uma iteração concluída (da matriz 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
      }
    }
  }'

Excluir um item de um projeto

O exemplo a seguir excluirá um item de um projeto. Substitua PROJECT_ID pelo ID do nó do seu projeto. Substitua ITEM_ID pelo Id do nó do item que você deseja excluir.

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