Usando a API para gerenciar projetos (beta)

Este artigo demonstra como usar a API do GraphQL para gerenciar um projeto. 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.

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). The token can be a personal access token for a user or an installation access token for a aplicativo GitHub. 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 aplicativo GitHub, see "Authenticating with Aplicativos do GitHub."

Para saber mais sobre GitHub CLI, consulte "Sobre 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. 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".

Finding the node ID of an organization project

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

You can find the node ID of an organization project if you know the organization name and project number. Substitua ORGANIZATION pelo nome da sua organização. Por exemplo, octo-org. Replace NUMBER with the project number. 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
        }
      }
    }
  }'

Finding the node ID of a user project

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

You can find the node ID of a user project if you know the project number. Replace USER with your user name. 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
      }
    }
  }'

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. 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. Additionally, you will need to know the ID of the options for single select fields and the ID of the iterations for iteration fields.

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. 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.

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á 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. For more information, see "About mutations."

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.

Updating a custom text, number, or date field

The following example will update the value of a date field for an 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. 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.

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 - 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.

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

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