Skip to main content
Publicamos actualizaciones para la documentación con frecuencia y es posible que aún se esté traduciendo esta página. Para obtener la información más reciente, consulta la documentación en inglés.
All products
Problemas de GitHub

Uso de la API para administrar instancias de Projects

En este artículo

Puedes usar GraphQL API para automatizar los proyectos.

El artículo muestra cómo utilizar la API de GraphQL para administrar un proyecto. Para obtener más información sobre cómo usar la API en un flujo de trabajo de GitHub Actions, consulta "Automatización de Projects mediante acciones". Para ver una lista completa de los tipos de datos disponibles, consulta "Referencia".

Authentication

En todos los ejemplos del comando curl siguientes, reemplaza TOKEN por un token que tenga el ámbito read:project (para consultas) o el ámbito project (para consultas y mutaciones). El token puede ser un personal access token (classic) para un usuario o un token de acceso a la instalación para una GitHub App. Para obtener más información sobre la creación de un personal access token, consulte "Creación de un token de acceso personal". Para obtener más información sobre cómo crear un token de acceso de instalación para una GitHub App, consulta "Generación de un token de acceso de instalación para una aplicación de GitHub".

Para más información sobre GitHub CLI, consulta "Acerca del CLI de GitHub".

Antes de ejecutar los comandos de GitHub CLI, debes autenticarte mediante la ejecución de gh auth login --scopes "project". Si solo necesitas leer los proyectos, pero no editarlos, puedes proporcionar el ámbito read:project en lugar de project. Para obtener más información sobre la autenticación de la línea de comandos, consulta "gh auth login".

Utilizar variables

Puedes utilizar variables para simplificar tus scripts en todos los ejemplos siguientes. Usa -F para pasar una variable que sea un número, un operador booleano o un valor NULL. Usa -f para las demás variables. Por ejemplo,

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 obtener más información, vea «Formar llamados con GraphQl».

Encontrar información sobre los proyectos

Utiliza consultas para obtener datos sobre los proyectos. Para obtener más información, vea «Formar llamados con GraphQl».

Encontrar la ID de nodo de un proyecto organizacional

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

Puedes encontrar la ID de nodo de un proyecto organizacional si conoces el nombre de la organización y el número de proyecto. Reemplaza ORGANIZATION por el nombre de la organización. Por ejemplo, octo-org. Reemplaza NUMBER por el número del proyecto. Para encontrar un número de proyecto, revisa su URL. Por ejemplo, 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: 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
      }
    }
  }'

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 por el nombre de la organización. Por ejemplo, octo-org.

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 la ID de nodo de un proyecto de usuario

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

Puedes encontrar la ID de nodo de un proyecto de usuario si conoces el número del mismo. Reemplace USER por el nombre de usuario. Por ejemplo, octocat. Reemplace NUMBER por el número del proyecto. Para encontrar un número de proyecto, revisa su URL. Por ejemplo, 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: 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
      }
    }
  }'

También puedes encontrar la ID de nodo de todos tus proyectos. El siguiente ejemplo devolverá la ID de nodo y el título de tus primeros 20 proyectos. Reemplaza USER por el nombre de usuario. Por ejemplo, octocat.

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

Encontrar la ID de nodo de un campo

Para actualizar el valor de un campo, necesitarás conocer la ID de nodo del mismo. Adicionalmente, necesitarás saber la ID de las opciones para los campos de selección única y la ID de las iteraciones de los campos de iteración.

En el ejemplo siguiente se devolverá el id., nombre, valores y configuración de los primeros 20 campos de un proyecto. Reemplaza PROJECT_ID por el identificador de nodo del proyecto.

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

La respuesta será similar al ejemplo siguiente:

{
  "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 tiene un id. y un nombre. Los campos de selección única se devuelven como un objeto ProjectV2SingleSelectField y tienen un campo options donde puedes encontrar el id. de cada opción para la selección única. Los campos de iteración se devuelven como un objeto ProjectV2IterationField y tienen un campo configuration que incluye un campo iterations que contiene el id. y la información sobre cada iteración.

Si solo necesitas el nombre y el id. de un campo y no necesitas información sobre las iteraciones o las opciones de un campo de selección única, puedes usar el objeto ProjectV2FieldCommon. 

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

La respuesta al usar el objeto ProjectV2FieldCommon será similar al ejemplo siguiente:

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

Encontrar información sobre los elementos en un proyecto

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

En el ejemplo siguiente se devolverán los 20 primeros problemas, solicitudes de incorporación de cambios y problemas de borrador de un proyecto. En el caso de los problemas y las solicitudes de incorporación de cambios, también devolverá el título y los primeros 10 usuarios asignados. En el caso del problema de borrador, devolverá el título y el cuerpo. En el ejemplo también se devolverá el nombre del campo y el valor de los campos de texto, fecha o selección única en los primeros 8 campos del proyecto. Reemplaza PROJECT_ID por el identificador de nodo del proyecto.

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

Un proyecto podría contener elementos que los usuarios no tengan permiso para ver. En este caso, el tipo de elemento se devolverá como REDACTED.

Actualizar los proyectos

Utiliza las mutaciones para actualizar los proyectos. Para obtener más información, vea «Formar llamados con GraphQl».

Nota: No se puede agregar y actualizar un elemento en la misma llamada. Debes usar addProjectV2ItemById para agregar el elemento y, a continuación, usar updateProjectV2ItemFieldValue para actualizarlo.

Agregar un elemento a un proyecto

El siguiente ejemplo agregará una propuesta o solicitud de cambios a tu proyecto. Reemplaza PROJECT_ID por el identificador de nodo del proyecto. Reemplaza CONTENT_ID por el identificador de nodo de la propuesta o solicitud de incorporación de cambios que quieras agregar.

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

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

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

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

Incorporación de un problema de borrador a un proyecto

En el ejemplo siguiente se agregará un problema de borrador al proyecto. Reemplaza PROJECT_ID por el identificador de nodo del proyecto. Reemplaza TITLE y BODY por el contenido que quieras para el nuevo problema de borrador.

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

La respuesta contendrá el id. de nodo del problema de borrador recién creado.

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

Actualizar los ajustes de un proyecto

El siguiente ejemplo actualizará los ajustes de tu proyecto. Reemplaza PROJECT_ID por el identificador de nodo del proyecto. Establece public en true para que el proyecto sea público en GitHub. Modifica readme para realizar cambios en el archivo README del proyecto.

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

Actualizar un campo personalizado de texto, número o fecha

En el ejemplo siguiente se actualizará el valor de un campo de texto para un elemento. Reemplaza PROJECT_ID por el identificador de nodo del proyecto. Reemplaza ITEM_ID por el identificador de nodo del elemento que quieras actualizar. Reemplaza FIELD_ID por el identificador del campo que quieras actualizar.

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

Nota: No se puede usar updateProjectV2ItemFieldValue para cambiar Assignees, Labels, Milestone o Repository porque estos campos son propiedades de solicitudes de incorporación de cambios y propuestas, no de elementos del proyecto. En su lugar, puedes usar las mutaciones siguientes:

Actualizar un campo de selección simple

El siguiente ejemplo actualizará el valor de un campo de selección simple para un elemento.

  • PROJECT_ID: reemplázalo por el identificador de nodo del proyecto.
  • ITEM_ID: reemplázalo por el identificador de nodo del elemento que quieras actualizar.
  • FIELD_ID : reemplázalo por el identificador del campo de selección única que quieras actualizar.
  • OPTION_ID : reemplázalo por el identificador de la opción de selección única deseada.
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
      }
    }
  }'

Actualizar un campo de iteración

El siguiente ejemplo actualizará el valor de un campo de iteración para un elemento.

  • PROJECT_ID: reemplázalo por el identificador de nodo del proyecto.
  • ITEM_ID: reemplázalo por el identificador de nodo del elemento que quieras actualizar.
  • FIELD_ID : reemplázalo por el identificador del campo de iteración que quieras actualizar.
  • ITERATION_ID : reemplázalo por el identificador de la iteración deseada. Esto puede ser una iteración activa o completada.
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
      }
    }
  }'

Borrar un elemento de un proyecto

El siguiente ejemplo borrará un elemento de un proyecto. Reemplaza PROJECT_ID por el identificador de nodo del proyecto. Reemplaza ITEM_ID por el identificador de nodo del elemento que quieras eliminar.

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

Administración de proyectos

Creación de proyectos

Puedes usar una mutación para crear un proyecto. Para obtener más información, vea «Formar llamados con GraphQl».

A fin de crear un proyecto con la API, deberás proporcionar un nombre para el proyecto y el id. de nodo de un usuario u organización de GitHub, que se convertirá en el propietario del proyecto.

Si conoces el nombre de usuario, podrás encontrar el id. de nodo de un usuario u organización de GitHub. Reemplaza GITHUB_OWNER por el nombre de usuario de GitHub del nuevo propietario del proyecto.

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

A fin de crear el proyecto, reemplaza OWNER_ID por el id. de nodo del nuevo propietario del proyecto y PROJECT_NAME por un nombre para el proyecto.

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

Uso de webhooks

Puedes usar webhooks para suscribirte a los eventos que tienen lugar en el proyecto. Por ejemplo, cuando se edita un elemento, GitHub puede enviar una carga HTTP POST a la dirección URL configurada del webhook que puede desencadenar la automatización en el servidor. Para obtener más información sobre los webhooks, consulta "Acerca de webhooks". Para obtener más información sobre el evento de webhook projects_v2_item, consulta "Eventos y cargas de webhook".