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