Cet article explique comment utiliser l’API GraphQL pour gérer un projet. Pour plus d’informations sur l’utilisation de l’API dans un flux de travail Actions, consultez Automatisation des Projects avec Actions. Pour obtenir la liste complète des types de données disponibles, consultez Référence.
Dans tous les exemples de commandes curl
suivants, remplacez TOKEN
par un jeton avec l’étendue read:project
(pour les requêtes) ou project
(pour les requêtes et les mutations). Le jeton peut être un personal access token (classic) pour un utilisateur ou un jeton d’accès d’installation pour une App. Pour plus d’informations sur la création de personal access token, consultez Gestion de vos jetons d'accès personnels. Pour plus d’informations sur la création d’un jeton d’accès d’installation pour une App, consultez Génération d’un jeton d’accès d’installation pour une application .
Lorsque vous utilisez un jeton d’accès d’installation pour un App, certaines mutations GraphQL nécessitent des autorisations supplémentaires. Par exemple, lorsque vous utilisez la createProjectV2
mutation, si vous spécifiez un repositoryId
paramètre d’entrée, Contents
l’autorisation de ce référentiel est également requise pour lier le projet au référentiel cible.
Remarque
Pour plus d’informations sur CLI, consultez À propos de CLI.
Avant d’exécuter les commandes CLI, vous devez vous authentifier en exécutant gh auth login --scopes "project"
. Si vous avez seulement besoin de lire, mais pas de modifier des projets, vous pouvez fournir l’étendue read:project
au lieu de project
. Pour plus d’informations sur l’authentification à la ligne de commande, consultez gh auth login.
Dans tous les exemples suivants, vous pouvez utiliser des variables pour simplifier vos scripts. Utilisez -F
pour passer une variable qui est un nombre, un booléen ou une valeur null. Utilisez -f
pour les autres variables. Par exemple,
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
Pour plus d’informations, consultez « Formation d’appels avec GraphQL ».
Utilisez des requêtes pour obtenir des données sur les projets. Pour plus d’informations, consultez « Formation d’appels avec GraphQL ».
Pour mettre à jour votre projet par le biais de l’API, vous devez connaître l’ID de nœud du projet.
Vous pouvez trouver l’ID de nœud d’un projet d’organisation si vous connaissez le nom de l’organisation et le numéro de projet. Remplacez ORGANIZATION
par le nom de votre organisation. Par exemple : octo-org
. Remplacez NUMBER
par le numéro de projet. Pour trouver le numéro de projet, consultez l’URL du projet. Par exemple, https://.com/orgs/octo-org/projects/5
a pour numéro de projet 5.
curl --request POST \
--url https://api..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
}
}
}'
Vous pouvez également trouver l’ID de nœud de tous les projets de votre organisation. L’exemple suivant retourne l’ID de nœud et le titre des 20 premiers projets d’une organisation. Remplacez ORGANIZATION
par le nom de votre organisation. Par exemple : octo-org
.
curl --request POST \
--url https://api..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
}
}
}
}'
Pour mettre à jour votre projet par le biais de l’API, vous devez connaître l’ID de nœud du projet.
Vous pouvez obtenir l’ID de nœud d’un projet d’utilisateur si vous connaissez le numéro de projet. Remplacez USER
par votre ID d’utilisateur. Par exemple : octocat
. Remplacez NUMBER
par votre numéro de projet. Pour trouver le numéro de projet, consultez l’URL du projet. Par exemple, https://.com/users/octocat/projects/5
a pour numéro de projet 5.
curl --request POST \
--url https://api..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
}
}
}'
Vous pouvez également trouver l’ID de nœud pour tous vos projets. L’exemple suivant retourne l’ID de nœud et le titre de vos 20 premiers projets. Remplacez USER
par votre nom d’utilisateur. Par exemple : octocat
.
curl --request POST \
--url https://api..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
}
}
}
}'
Pour mettre à jour la valeur d’un champ, vous devez connaître l’ID de nœud du champ. De plus, vous devez connaître l’ID des options pour les champs de sélection unique et l’ID des itérations pour les champs d’itération.
L’exemple suivant retourne l’ID, le nom, les paramètres et la configuration des 20 premiers champs d’un projet. Remplacez PROJECT_ID
par l’ID de nœud de votre projet.
curl --request POST \
--url https://api..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 réponse ressemblera à l’exemple suivant :
{
"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"
}
]
}
}
]
}
}
}
}
Chaque champ a un nom et un ID. Les champs de sélection unique sont renvoyés sous la forme d’un objet ProjectV2SingleSelectField
et comportent un champ options
dans lequel vous pouvez trouver l’ID de chaque option pour sélection unique. Les champs d’itération sont renvoyés sous forme d’objet ProjectV2IterationField
et comportent un champ configuration
qui comprend un champ iterations
contenant l’ID et des informations sur chaque itération.
Si vous avez simplement besoin du nom et de l’ID d’un champ, et que vous n’avez pas besoin d’informations sur les itérations ou les options d’un champ de sélection unique, vous pouvez utiliser l’objet ProjectV2FieldCommon
.
curl --request POST \
--url https://api..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 réponse lors de l’utilisation de l’objet ProjectV2FieldCommon
ressemblera à l’exemple suivant :
{
"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"
}
]
}
}
}
}
Vous pouvez interroger l’API pour trouver des informations sur les éléments de votre projet.
L’exemple suivant renvoie les 20 premiers problèmes, demandes de tirage et brouillons de problèmes d’un projet. Pour les questions et les demandes de tirage, il renverra également le titre et les 10 premiers responsables. Pour un projet de numéro, il renverra le titre et le corps. L’exemple renvoie également le nom et la valeur des champs de texte, de date ou de sélection unique dans les huit premiers champs du projet. Remplacez PROJECT_ID
par l’ID de nœud de votre projet.
curl --request POST \
--url https://api..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 projet peut contenir des éléments qu’un utilisateur n’est pas autorisé à afficher. Dans ce cas, le type d’article sera renvoyé sous la forme REDACTED
.
Utilisez des mutations pour mettre à jour des projets. Pour plus d’informations, consultez « Formation d’appels avec GraphQL ».
Remarque
Vous ne pouvez pas ajouter et mettre à jour un élément dans le même appel. Vous devez utiliser addProjectV2ItemById
pour ajouter l’élément, puis updateProjectV2ItemFieldValue
pour le mettre à jour.
L’exemple suivant ajoute un problème ou une demande de tirage à votre projet. Remplacez PROJECT_ID
par l’ID de nœud de votre projet. Remplacez CONTENT_ID
par l’ID de nœud du problème ou de la demande de tirage à ajouter.
curl --request POST \
--url https://api..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 réponse contient l’ID de nœud de l’élément récemment créé.
{
"data": {
"addProjectV2ItemById": {
"item": {
"id": "PVTI_lADOANN5s84ACbL0zgBVd94"
}
}
}
}
Si vous essayez d’ajouter un élément qui existe déjà, l’ID de l’élément existant est retourné à la place.
L’exemple suivant ajoutera un brouillon de problème à votre projet. Remplacez PROJECT_ID
par l’ID de nœud de votre projet. Remplacez TITLE
et BODY
par le contenu que vous souhaitez pour le nouveau problème provisoire.
curl --request POST \
--url https://api..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 réponse contient l’ID de nœud de brouillon de problème récemment créé.
{
"data": {
"addProjectV2DraftIssue": {
"projectItem": {
"id": "PVTI_lADOANN5s84ACbL0zgBbxFc"
}
}
}
}
L’exemple suivant met à jour les paramètres de votre projet. Remplacez PROJECT_ID
par l’ID de nœud de votre projet. Définissez public
sur true
pour rendre votre projet public sur . Modifiez readme
pour apporter des modifications au fichier README de votre projet.
curl --request POST \
--url https://api..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
}
}
}'
L’exemple suivant met à jour la valeur d’un champ texte pour un élément. Remplacez PROJECT_ID
par l’ID de nœud de votre projet. Remplacez ITEM_ID
par l’ID de nœud de l’élément que vous souhaitez mettre à jour. Remplacez FIELD_ID
par l’ID du champ que vous souhaitez mettre à jour.
curl --request POST \
--url https://api..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
}
}
}'
Remarque
Vous ne pouvez pas utiliser updateProjectV2ItemFieldValue
pour modifier Assignees
, Labels
, Milestone
, ou Repository
parce que ces champs sont des propriétés de demandes de tirage et de problèmes, et non des éléments de projet. Au lieu de cela, vous pouvez utiliser les mutations suivantes :
L’exemple suivant met à jour la valeur d’un champ de sélection unique pour un élément.
- Remplacez
PROJECT_ID
par l’ID de nœud de votre projet. - Remplacez
ITEM_ID
par l’ID de nœud de l’élément que vous souhaitez mettre à jour. - Remplacez
FIELD_ID
par l’ID du champ de sélection unique que vous souhaitez mettre à jour. - Remplacez
OPTION_ID
par l’ID de l’option de sélection unique désirée.
curl --request POST \
--url https://api..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
}
}
}'
L’exemple suivant met à jour la valeur d’un champ d’itération pour un élément.
- Remplacez
PROJECT_ID
par l’ID de nœud de votre projet. - Remplacez
ITEM_ID
par l’ID de nœud de l’élément que vous souhaitez mettre à jour. - Remplacez
FIELD_ID
par l’ID du champ d’itération que vous souhaitez mettre à jour. - Remplacez
ITERATION_ID
par l’ID de l’itération désirée. Il peut s’agir d’une itération active ou terminée.
curl --request POST \
--url https://api..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
}
}
}'
L’exemple suivant supprime un élément d’un projet. Remplacez PROJECT_ID
par l’ID de nœud de votre projet. Remplacez ITEM_ID
par l’ID de nœud de l’élément que vous souhaitez supprimer.
curl --request POST \
--url https://api..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
}
}'
Vous pouvez utiliser une mutation pour créer un projet. Pour plus d’informations, consultez « Formation d’appels avec GraphQL ».
Pour créer un projet en utilisant l’API, vous devez fournir un nom pour le projet et l’ID de nœud d’un utilisateur ou d’une organisation qui deviendra propriétaire du projet.
Vous pouvez trouver l’ID de nœud d’un utilisateur ou d’une organisation si vous connaissez le nom d’utilisateur. Remplacez _OWNER
par le nom d’utilisateur du propriétaire du nouveau projet.
curl --request GET \
--url https://api..com/users/_OWNER \
--header 'Authorization: token TOKEN' \
--header 'Accept: application/vnd.+json'
gh api -H "Accept: application/vnd.+json" /users/_OWNER
Pour créer le projet, remplacez OWNER_ID
par l’ID de nœud du propriétaire du nouveau projet et remplacez PROJECT_NAME
par un nom pour le projet.
curl --request POST \
--url https://api..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
}
}
}'
Vous pouvez utiliser des webhooks pour vous abonner à des événements qui se passent dans votre projet. Par exemple, lorsqu’un élément est modifié, peut envoyer une charge utile HTTP POST à l’URL configurée du Webhook qui peut déclencher une automatisation sur votre serveur. Pour plus d’informations sur les webhooks, consultez À propos des webhooks. Pour en savoir plus sur l’événement de webhook projects_v2_item
, consultez Événements et charges utiles du webhook.