Automatisation des Projects avec Actions

Cet article montre comment utiliser l’API GraphQL et Actions pour ajouter une demande de tirage (pull request) à un projet d’organisation. Dans l’exemple de workflows, lorsque la demande de tirage est marquée comme « prête pour évaluation », une nouvelle tâche est ajoutée au projet avec un champ « État » défini sur « À faire » et la date actuelle est ajoutée à un champ « Date publié » personnalisé.

Vous pouvez copier l’un des workflows ci-dessous et le modifier comme décrit dans le tableau ci-dessous pour répondre à vos besoins.

Un projet peut s’étendre sur plusieurs référentiels, mais un workflow est spécifique à un référentiel. Ajoutez le flux de travail à chaque référentiel que vous souhaitez suivre pour votre projet. Pour plus d’informations sur la création de fichiers de flux de travail, consultez Démarrage rapide pour Actions.

Cet article part du principe que vous avez une compréhension de base de Actions. Pour plus d’informations sur Actions, consultez Documentation Actions.

Pour plus d’informations sur les autres modifications que vous pouvez apporter à votre projet via l’API, consultez Utilisation de l’API pour gérer des Projects.

Vous pouvez aussi vouloir utiliser le workflow actions/add-to-project, qui est géré par et qui ajoute le problème ou la demande de tirage en cours dans le projet spécifié. Pour plus d’informations, consultez le dépôt actions/add-to-project et le fichier README.

Remarque

_TOKEN est délimité au niveau du référentiel et ne peut pas accéder aux projects. Pour accéder aux projects, vous pouvez créer une App (recommandé pour les projets d’organisation) ou un personal access token (recommandé pour les projets d’utilisateur). Les exemples de workflow pour les deux approches sont présentés ci-dessous.

Pour plus d’informations sur l’authentification dans un flux de travail Actions avec une App, consultez Effectuer des requêtes d’API authentifiées avec une application dans un workflow Actions.

Créez un App ou choisissez un App existant appartenant à votre organisation. Pour plus d’informations, consultez « Inscription d’une application ».
Accordez à App des autorisations de lecture et d’écriture pour les projets de l’organisation. Pour cet exemple spécifique, votre App a également besoin d’autorisations de lecture pour les demandes de tirage du référentiel et les problèmes du référentiel. Pour plus d’informations, consultez « Modification d’une inscription d’application ».
Remarque
Vous pouvez contrôler l’autorisation de votre application pour les projets d’organisation et pour les projets de référentiel. Vous devez accorder l’autorisation de lecture et d’écriture des projets d’organisation ; l’autorisation de lecture et d’écriture des projets de référentiel ne suffit pas.
Installation le App dans votre organisation. Installez-le pour tous les référentiels auxquels votre projet doit accéder. Pour plus d’informations, consultez « Installation de votre propre application ».
Stockez l’ID de votre App en tant que variable de configuration dans votre référentiel ou organisation. Dans le workflow suivant, remplacez APP_ID par le nom de la variable de configuration. Vous pouvez trouver votre ID d’application dans la page Paramètres de votre application ou via l’API d’application. Pour plus d’informations, consultez « Points de terminaison d’API REST pour les applications ». Pour plus d’informations concernant les variables de configuration, consultez Stocker des informations dans des variables.
Générez une clé privée pour votre application. Stockez le contenu du fichier résultant sous la forme d’un secret dans votre référentiel ou organisation. (Stockez l’intégralité du contenu du fichier, y compris -----BEGIN RSA PRIVATE KEY----- et -----END RSA PRIVATE KEY-----.) Dans le workflow suivant, remplacez APP_PEM par le nom du secret. Pour plus d’informations, consultez « Gestion des clés privées pour les applications ». Pour plus d’informations sur le stockage de secrets, consultez Utilisation de secrets dans Actions.
Dans le workflow suivant, remplacez YOUR_ORGANIZATION par le nom de votre organisation. Par exemple : octo-org. Remplacez YOUR_PROJECT_NUMBER par votre 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. Pour que cet exemple spécifique fonctionne, votre projet doit également disposer d’un champ de date « Date de publication ».

name: Add PR to project

on:
  pull_request:
    types:
      - ready_for_review
jobs:
  track_pr:
    runs-on: ubuntu-latest
    steps:

This workflow runs whenever a pull request in the repository is marked as "ready for review".

      - name: Generate token
        id: generate-token
        uses: actions/create--app-token@v1
        with:
          app-id: ${{ vars.APP_ID }}
          private-key: ${{ secrets.APP_PEM }}

Uses the actions/create--app-token action to generate an installation access token for your app from the app ID and private key. The installation access token is accessed later in the workflow as ${{ steps.generate-token.outputs.token }}.

Replace APP_ID with the name of the configuration variable that contains your app ID.

Replace APP_PEM with the name of the secret that contains your app private key.

      - name: Get project data
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
          ORGANIZATION: YOUR_ORGANIZATION
          PROJECT_NUMBER: YOUR_PROJECT_NUMBER

Sets environment variables for this step.

Replace YOUR_ORGANIZATION with the name of your organization. For example, octo-org.

Replace YOUR_PROJECT_NUMBER with your project number. To find the project number, look at the project URL. For example, https://.com/orgs/octo-org/projects/5 has a project number of 5.

        run: |
          gh api graphql -f query='
            query($org: String!, $number: Int!) {
              organization(login: $org){
                projectV2(number: $number) {
                  id
                  fields(first:20) {
                    nodes {
                      ... on ProjectV2Field {
                        id
                        name
                      }
                      ... on ProjectV2SingleSelectField {
                        id
                        name
                        options {
                          id
                          name
                        }
                      }
                    }
                  }
                }
              }
            }' -f org=$ORGANIZATION -F number=$PROJECT_NUMBER > project_data.json

Uses CLI to query the API for the ID of the project and return the name and ID of the first 20 fields in the project. fields returns a union and the query uses inline fragments (... on) to return information about any ProjectV2Field and ProjectV2SingleSelectField fields. The response is stored in a file called project_data.json.

          echo 'PROJECT_ID='$(jq '.data.organization.projectV2.id' project_data.json) >> $_ENV
          echo 'DATE_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Date posted") | .id' project_data.json) >> $_ENV
          echo 'STATUS_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Status") | .id' project_data.json) >> $_ENV
          echo 'TODO_OPTION_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Status") | .options[] | select(.name=="Todo") |.id' project_data.json) >> $_ENV

Parses the response from the API query and stores the relevant IDs as environment variables. Modify this to get the ID for different fields or options. For example:

To get the ID of a field called Team, add echo 'TEAM_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Team") | .id' project_data.json) >> $_ENV.
To get the ID of an option called Octoteam for the Team single select field, add echo 'OCTOTEAM_OPTION_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Team") |.options[] | select(.name=="Octoteam") |.id' project_data.json) >> $_ENV.

Note: This workflow assumes that you have a project with a single select field called "Status" that includes an option called "Todo" and a date field called "Date posted". You must modify this section to match the fields that are present in your table.

      - name: Add PR to project
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
          PR_ID: ${{ .event.pull_request.node_id }}

Sets environment variables for this step. GH_TOKEN is the token generated in the first step. PR_ID is the ID of the pull request that triggered this workflow.

        run: |
          item_id="$( gh api graphql -f query='
            mutation($project:ID!, $pr:ID!) {
              addProjectV2ItemById(input: {projectId: $project, contentId: $pr}) {
                item {
                  id
                }
              }
            }' -f project=$PROJECT_ID -f pr=$PR_ID --jq '.data.addProjectV2ItemById.item.id')"

Uses CLI and the API to add the pull request that triggered this workflow to the project. The jq flag parses the response to get the ID of the created item.

          echo 'ITEM_ID='$item_id >> $_ENV

Stores the ID of the created item as an environment variable.

      - name: Get date
        run: echo "DATE=$(date +"%Y-%m-%d")" >> $_ENV

Saves the current date as an environment variable in yyyy-mm-dd format.

      - name: Set fields
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}

Sets environment variables for this step. GH_TOKEN is the token generated in the first step.

        run: |
          gh api graphql -f query='
            mutation (
              $project: ID!
              $item: ID!
              $status_field: ID!
              $status_value: String!
              $date_field: ID!
              $date_value: Date!
            ) {
              set_status: updateProjectV2ItemFieldValue(input: {
                projectId: $project
                itemId: $item
                fieldId: $status_field
                value: {
                  singleSelectOptionId: $status_value
                  }
              }) {
                projectV2Item {
                  id
                  }
              }
              set_date_posted: updateProjectV2ItemFieldValue(input: {
                projectId: $project
                itemId: $item
                fieldId: $date_field
                value: {
                  date: $date_value
                }
              }) {
                projectV2Item {
                  id
                }
              }
            }' -f project=$PROJECT_ID -f item=$ITEM_ID -f status_field=$STATUS_FIELD_ID -f status_value=${{ env.TODO_OPTION_ID }} -f date_field=$DATE_FIELD_ID -f date_value=$DATE --silent

Sets the value of the Status field to Todo. Sets the value of the Date posted field.

#
name: Add PR to project
# This workflow runs whenever a pull request in the repository is marked as "ready for review".
on:
  pull_request:
    types:
      - ready_for_review
jobs:
  track_pr:
    runs-on: ubuntu-latest
    steps:
    # Uses the [actions/create--app-token](https://.com/marketplace/actions/create--app-token) action to generate an installation access token for your app from the app ID and private key. The installation access token is accessed later in the workflow as `${{ steps.generate-token.outputs.token }}`.
    #
    # Replace `APP_ID` with the name of the configuration variable that contains your app ID.
    #
    # Replace `APP_PEM` with the name of the secret that contains your app private key.
      - name: Generate token
        id: generate-token
        uses: actions/create--app-token@v1
        with:
          app-id: ${{ vars.APP_ID }}
          private-key: ${{ secrets.APP_PEM }}
      # Sets environment variables for this step.
      #
      # Replace `YOUR_ORGANIZATION` with the name of your organization. For example, `octo-org`.
      #
      # Replace `YOUR_PROJECT_NUMBER` with your project number. To find the project number, look at the project URL. For example, `https://.com/orgs/octo-org/projects/5` has a project number of 5.
      - name: Get project data
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
          ORGANIZATION: YOUR_ORGANIZATION
          PROJECT_NUMBER: YOUR_PROJECT_NUMBER
        # Uses [ CLI](https://cli..com/manual/) to query the API for the ID of the project and return the name and ID of the first 20 fields in the project. `fields` returns a union and the query uses inline fragments (`... on`) to return information about any `ProjectV2Field` and `ProjectV2SingleSelectField` fields. The response is stored in a file called `project_data.json`.
        run: |
          gh api graphql -f query='
            query($org: String!, $number: Int!) {
              organization(login: $org){
                projectV2(number: $number) {
                  id
                  fields(first:20) {
                    nodes {
                      ... on ProjectV2Field {
                        id
                        name
                      }
                      ... on ProjectV2SingleSelectField {
                        id
                        name
                        options {
                          id
                          name
                        }
                      }
                    }
                  }
                }
              }
            }' -f org=$ORGANIZATION -F number=$PROJECT_NUMBER > project_data.json

          # Parses the response from the API query and stores the relevant IDs as environment variables. Modify this to get the ID for different fields or options. For example:
          #
          # - To get the ID of a field called `Team`, add `echo 'TEAM_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Team") | .id' project_data.json) >> $_ENV`.
          # - To get the ID of an option called `Octoteam` for the `Team` single select field, add `echo 'OCTOTEAM_OPTION_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Team") |.options[] | select(.name=="Octoteam") |.id' project_data.json) >> $_ENV`.
          #
          # **Note:** This workflow assumes that you have a project with a single select field called "Status" that includes an option called "Todo" and a date field called "Date posted". You must modify this section to match the fields that are present in your table.

          echo 'PROJECT_ID='$(jq '.data.organization.projectV2.id' project_data.json) >> $_ENV
          echo 'DATE_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Date posted") | .id' project_data.json) >> $_ENV
          echo 'STATUS_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Status") | .id' project_data.json) >> $_ENV
          echo 'TODO_OPTION_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Status") | .options[] | select(.name=="Todo") |.id' project_data.json) >> $_ENV

# Sets environment variables for this step. `GH_TOKEN` is the token generated in the first step. `PR_ID` is the ID of the pull request that triggered this workflow.
      - name: Add PR to project
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
          PR_ID: ${{ .event.pull_request.node_id }}
        # Uses [ CLI](https://cli..com/manual/) and the API to add the pull request that triggered this workflow to the project. The `jq` flag parses the response to get the ID of the created item.
        run: |
          item_id="$( gh api graphql -f query='
            mutation($project:ID!, $pr:ID!) {
              addProjectV2ItemById(input: {projectId: $project, contentId: $pr}) {
                item {
                  id
                }
              }
            }' -f project=$PROJECT_ID -f pr=$PR_ID --jq '.data.addProjectV2ItemById.item.id')"

          # Stores the ID of the created item as an environment variable.
          echo 'ITEM_ID='$item_id >> $_ENV

# Saves the current date as an environment variable in `yyyy-mm-dd` format.
      - name: Get date
        run: echo "DATE=$(date +"%Y-%m-%d")" >> $_ENV

# Sets environment variables for this step. `GH_TOKEN` is the token generated in the first step.
      - name: Set fields
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
        # Sets the value of the `Status` field to `Todo`. Sets the value of the `Date posted` field.
        run: |
          gh api graphql -f query='
            mutation (
              $project: ID!
              $item: ID!
              $status_field: ID!
              $status_value: String!
              $date_field: ID!
              $date_value: Date!
            ) {
              set_status: updateProjectV2ItemFieldValue(input: {
                projectId: $project
                itemId: $item
                fieldId: $status_field
                value: {
                  singleSelectOptionId: $status_value
                  }
              }) {
                projectV2Item {
                  id
                  }
              }
              set_date_posted: updateProjectV2ItemFieldValue(input: {
                projectId: $project
                itemId: $item
                fieldId: $date_field
                value: {
                  date: $date_value
                }
              }) {
                projectV2Item {
                  id
                }
              }
            }' -f project=$PROJECT_ID -f item=$ITEM_ID -f status_field=$STATUS_FIELD_ID -f status_value=${{ env.TODO_OPTION_ID }} -f date_field=$DATE_FIELD_ID -f date_value=$DATE --silent

Créez un personal access token (classic) avec les étendues project et repo. Pour plus d’informations, consultez « Gestion de vos jetons d'accès personnels ».
Enregistrez le personal access token en tant que secret dans votre dépôt ou votre organisation.
Dans le workflow suivant, remplacez YOUR_TOKEN par le nom du secret. Remplacez YOUR_ORGANIZATION par le nom de votre organisation. Par exemple : octo-org. Remplacez YOUR_PROJECT_NUMBER par votre 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.

name: Add PR to project
on:
  pull_request:
    types:
      - ready_for_review
jobs:
  track_pr:
    runs-on: ubuntu-latest
    steps: