Utilizar la API para administrar proyectos (beta)

Puedes utilizar la API de GraphQL para encontrar información acerca de los proyectos y para actualizarlos.

El artículo muestra cómo utilizar la API de GraphQL para administrar un proyecto. 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.

Autenticación

En el resto de los ejemplos de cURL, reemplaza a TOKEN con un token que tenga el alcance read:org (para las consultas) o write:org (para las consultas y mutaciones). 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."

Para aprender más sobre el CLI de GitHub, consulta la sección "Acerca del CLI de GitHub".

Before running CLI de GitHub 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 obtener más información sobre la autenticación por la línea de comandos, consulta la sección "gh auth login".

Utilizar variables

Puedes utilizar variables para simplificar tus scripts en todos los ejemplos siguientes. Utiliza -F para pasar una variable que sea un número, un booleano o nula. Utiliza -f para otras variables. Por ejemplo,

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 obtener más información, consulta la sección "Formatear llamados con GraphQL".

Encontrar información sobre los proyectos

Utiliza consultas para obtener datos sobre los proyectos. Paraobtener más información, consulta la sección "Acerca de las consultas".

Finding the node ID of an organization project

Para actualizar tu proyecto a través de la API, necesitarás conocer la ID de nodo del proyecto.

You can find the node ID of an organization project if you know the organization name and project number. Reemplaza ORGANIZATION con el nombre de tu organización. Por ejemplo, octo-org. Replace NUMBER with the project number. Para encontrar un número de proyecto, revisa su URL. Por ejemplo, la dirección https://github.com/orgs/octo-org/projects/5 tiene "5" como número de proyecto.

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

También puedes encontrar la ID de nodo de todos los proyectos en tu organización. El siguiente ejemplo devolverá la ID de nodo y el título de los primeros 20 proyectos en una organización. Reemplaza ORGANIZATION con el nombre de tu organización. Por ejemplo, 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 actualizar tu proyecto a través de la API, necesitarás conocer la ID de nodo del proyecto.

You can find the node ID of a user project if you know the project number. Replace USER with your user name. Por ejemplo, octocat. Reemplaza NUMBER con tu número de proyecto. Para encontrar un número de proyecto, revisa su URL. Por ejemplo, la dirección https://github.com/users/octocat/projects/5 tiene "5" como número de proyecto.

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

Encontrar la ID de nodo de un campo

Para actualizar el valor de un campo, necesitarás conocer la ID de nodo del mismo. Additionally, you will need to know the ID of the options for single select fields and the ID of the iterations for iteration fields.

El siguiente ejemplo devolverá la ID, nombre y configuración de los primeros 20 campos de un proyecto. Reemplaza a PROJECT_ID con la ID de nodo de tu proyecto.

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

La respuesta se verá de forma similar al siguiente ejemplo:

{
  "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 tiene una 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.

Encontrar información sobre los elementos en un proyecto

Puedes consultar mediante la API para encontrar información sobre los elementos de tu proyecto.

El siguiente ejemplo devolverá el título y la ID de los primeros 20 elementos en un proyecto. Para cada elemento, también devolverá el valor y nombre de los primeros 8 campos en el proyecto. Si el elemento es una propuesta o solicitud de cambios, este devolverá al inicio de sesión de los primeros 10 asignados. Reemplaza a PROJECT_ID con la ID de nodo de tu proyecto.

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

Un proyecto podría contener elementos que los usuarios no tengan permiso para ver. En este caso, la respuesta incluirá el elemento redactado.

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

Actualizar los proyectos

Utiliza las mutaciones para actualizar los proyectos. For more information, see "About mutations."

Nota: No puedes agregar y actualizar un elemento en el mismo llamado. Debes utilizar addProjectNextItem para agregar el elemento y luego updateProjectNextItemField para actualizarlo.

Agregar un elemento a un proyecto

El siguiente ejemplo agregará una propuesta o solicitud de cambios a tu proyecto. Reemplaza a PROJECT_ID con la ID de nodo de tu proyecto. Reemplaza a CONTENT_ID con la ID de nodo de la propuesta o solicitud de cambios que quieras agregar.

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

La respuesta contendrá la ID de nodo del elemento recién creado.

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

Si intentas agregar un elemento que ya existe, se devolverá la ID de este.

Updating a custom text, number, or date field

The following example will update the value of a date field for an item. Reemplaza a PROJECT_ID con la ID de nodo de tu proyecto. Reemplaza a ITEM_ID con la ID de nodo del elemento que quieras actualizar. Reemplaza a FIELD_ID con la ID del campo que quieras actualizar.

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

Nota: No puedes utilizar updateProjectNextItemField para cambiar Assignees, Labels, Milestone, o Repository ya que estos campos son propiedades de las solicitudes de cambio y propuestas y no de los elementos del proyecto. 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 - Reemplázalo con la ID de nodo de tu proyecto.
  • ITEM_ID - Reemplázalo con la ID de nodo del elemento que quieras actualizar.
  • 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 - Reemplázalo con la ID de nodo de tu proyecto.
  • ITEM_ID - Reemplázalo con la ID de nodo del elemento que quieras actualizar.
  • 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
      }
    }
  }'

Borrar un elemento de un proyecto

El siguiente ejemplo borrará un elemento de un proyecto. Reemplaza a PROJECT_ID con la ID de nodo de tu proyecto. Reemplaza ITEM_ID con la ID de nodo del elemento que quieras borrar.

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

¿Te ayudó este documento?

Política de privacidad

¡Ayúdanos a hacer geniales estos documentos!

Todos los documentos de GitHub son de código abierto. ¿Notas algo que esté mal o que no sea claro? Emite una solicitud de cambios.

Haz una contribución

O, aprende cómo contribuir.