Utilisation de l’API pour gérer des Projects

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 workflow GitHub Actions, consultez « Automatisation des Projects avec Actions ». Pour obtenir la liste complète des types de données disponibles, consultez « Référence ».

Authentification

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 GitHub App. Pour plus d’informations sur la création d’un 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 GitHub App, consultez « Génération d’un jeton d’accès d’installation pour une application GitHub ».

Lorsque vous utilisez un jeton d’accès d’installation pour un GitHub 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.

Pour plus d’informations sur GitHub CLI, consultez « À propos de GitHub CLI ».

Avant d’exécuter les commandes GitHub 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 ».

Utilisation de variables

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

Recherche d’informations sur les projets

Utilisez des requêtes pour obtenir des données sur les projets. Pour plus d’informations, consultez « Formation d’appels avec GraphQL ».

Recherche de l’ID de nœud d’un projet d’organisation

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://github.com/orgs/octo-org/projects/5 a pour numéro de projet 5.

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

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

Recherche de l’ID de nœud d’un projet d’utilisateur

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://github.com/users/octocat/projects/5 a pour numéro de projet 5.

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

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

Recherche de l’ID de nœud d’un champ

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

Recherche d’informations sur les éléments d’un projet

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

Mise à jour des projets

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.

Ajout d’un élément à un projet

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

Ajouter un brouillon de problème à un projet

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.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 réponse contient l’ID de nœud de brouillon de problème récemment créé.

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

Mise à jour des paramètres d’un projet

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 GitHub. Modifiez readme pour apporter des modifications au fichier README de votre projet.

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

Mise à jour d’un champ de texte, de nombre ou de date personnalisé

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

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 :

Mise à jour d’un champ de sélection unique

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

Mise à jour d’un champ d’itération

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

Suppression d’un élément d’un projet

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

Gestion de projets

Création de projets

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 GitHub qui deviendra propriétaire du projet.

Vous pouvez trouver l’ID de nœud d’un utilisateur ou d’une organisation GitHub si vous connaissez le nom d’utilisateur. Remplacez GITHUB_OWNER par le nom d’utilisateur GitHub du propriétaire du nouveau projet.

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

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

Utilisation de webhooks

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é, GitHub 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 ».