Automatizar proyectos (beta)

Note: Projects (beta) is currently in public beta and subject to change.

Introducción

You can add automation to help manage your project. Projects (beta) includes built-in workflows that you can configure through the UI. Additionally, you can write custom workflows with the GraphQL API and GitHub Actions.

Built-in workflows

Projects (beta) includes built-in workflows that you can use to update the Status of items based on certain events. For example, you can automatically set the status to Todo when an item is added to your project or set the status to Done when an issue is closed.

When your project initializes, two workflows are enabled by default: When issues or pull requests in your project are closed, their status is set to Done, and when pull requests in your project are merged, their status is set to Done.

You can enable or disable the built-in workflows for your project.

In your project, click .
Under Default workflows, click on the workflow that you want to edit.
If the workflow can apply to both issues and pull requests, next to When, check the item type(s) that you want to act on.
Next to Set, choose the value that you want to set the status to.
If the workflow is disabled, click the toggle next to Disabled to enable the workflow.

GitHub Actions workflows

This section demonstrates how to use the GraphQL API and GitHub Actions to add a pull request to an organization project. In the example workflows, when the pull request is marked as "ready for review", a new task is added to the project with a "Status" field set to "Todo", and the current date is added to a custom "Date posted" field.

You can copy one of the workflows below and modify it as described in the table below to meet your needs.

Un proyecto puede abarcar repositorios múltiples, pero un flujo de trabajo es específico par aun repositorio. Add the workflow to each repository that you want your project to track. Para obtener más información sobre cómo crear archivos de flujo de trabajo, consulta la sección "Inicio rápido para las GitHub Actions".

Este artículo asume que tienes un entendimiento básico de las GitHub Actions. Para obtener más información acerca de GitHub Actions, consulta la sección "GitHub Actions".

Para obtener más información sobre otros cambios que puedes hacer a tu proyecto a través de la API, consulta la sección "Utilizar la API para administrar proyectos".

Note: GITHUB_TOKEN is scoped to the repository level and cannot access projects (beta). To access projects (beta) you can either create a GitHub App (recommended for organization projects) or a personal access token (recommended for user projects). Workflow examples for both approaches are shown below.

Example workflow authenticating with a GitHub App

Create a GitHub App or choose an existing GitHub App owned by your organization. For more information, see "Creating a GitHub App."
Give your GitHub App read and write permissions to organization projects. For more information, see "Editing a GitHub App's permissions."

Note: You can control your app's permission to organization projects and to repository projects. You must give permission to read and write organization projects; permission to read and write repository projects will not be sufficient.
Install the GitHub App in your organization. Install it for all repositories that your project needs to access. For more information, see "Installing GitHub Apps."
Store your GitHub App's ID as a secret in your repository or organization. In the following workflow, replace APP_ID with the name of the secret. You can find your app ID on the settings page for your app or through the App API. For more information, see "Apps."
Generate a private key for your app. Store the contents of the resulting file as a secret in your repository or organization. (Store the entire contents of the file, including -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY-----.) In the following workflow, replace APP_PEM with the name of the secret. For more information, see "Authenticating with GitHub Apps."
In the following workflow, replace YOUR_ORGANIZATION with the name of your organization. Por ejemplo, octo-org. Replace YOUR_PROJECT_NUMBER with your project number. Para encontrar un número de proyecto, revisa su URL. Por ejemplo, la dirección https://github.com/orgs/octo-org/projects/5 tiene "5" como número de proyecto.

YAML

# This workflow uses actions that are not certified by GitHub.
# Estas las proporcionan entidades terceras y las gobiernan
# condiciones de servicio, políticas de privacidad y documentación de soporte
# documentación.

name: Add PR to project
on:
  pull_request:
    types:
      - ready_for_review
jobs:
  track_pr:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate_token
        uses: tibdex/github-app-token@36464acb844fc53b9b8b2401da68844f6b05ebb0
        with:
          app_id: ${{ secrets.APP_ID }}
          private_key: ${{ secrets.APP_PEM }}

      - name: Get project data
        env:
          GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
          ORGANIZATION: YOUR_ORGANIZATION
          PROJECT_NUMBER: YOUR_PROJECT_NUMBER
        run: |
          gh api graphql -f query='
            query($org: String!, $number: Int!) {
              organization(login: $org){
                projectNext(number: $number) {
                  id
                  fields(first:20) {
                    nodes {
                      id
                      name
                      settings
                    }
                  }
                }
              }
            }' -f org=$ORGANIZATION -F number=$PROJECT_NUMBER > project_data.json

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

      - name: Add PR to project
        env:
          GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
          PR_ID: ${{ github.event.pull_request.node_id }}
        run: |
          item_id="$( gh api graphql -f query='
            mutation($project:ID!, $pr:ID!) {
              addProjectNextItem(input: {projectId: $project, contentId: $pr}) {
                projectNextItem {
                  id
                }
              }
            }' -f project=$PROJECT_ID -f pr=$PR_ID --jq '.data.addProjectNextItem.projectNextItem.id')"

          echo 'ITEM_ID='$item_id >> $GITHUB_ENV

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

      - name: Set fields
        env:
          GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
        run: |
          gh api graphql -f query='
            mutation (
              $project: ID!
              $item: ID!
              $status_field: ID!
              $status_value: String!
              $date_field: ID!
              $date_value: String!
            ) {
              set_status: updateProjectNextItemField(input: {
                projectId: $project
                itemId: $item
                fieldId: $status_field
                value: $status_value
              }) {
                projectNextItem {
                  id
                  }
              }
              set_date_posted: updateProjectNextItemField(input: {
                projectId: $project
                itemId: $item
                fieldId: $date_field
                value: $date_value
              }) {
                projectNextItem {
                  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

Example workflow authenticating with a personal access token

Create a personal access token with org:write scope. Para obtener más información, consulta la sección "Crear un token de acceso personal".
Save the personal access token as a secret in your repository or organization.
En el siguiente flujo de trabajo, reemplaza a YOUR_TOKEN con el nombre del secreto. Replace YOUR_ORGANIZATION with the name of your organization. Por ejemplo, octo-org. Replace YOUR_PROJECT_NUMBER with your project number. Para encontrar un número de proyecto, revisa su URL. Por ejemplo, la dirección https://github.com/orgs/octo-org/projects/5 tiene "5" como número de proyecto.

YAML

name: Add PR to project
on:
  pull_request:
    types:
      - ready_for_review
jobs:
  track_pr:
    runs-on: ubuntu-latest
    steps:
      - name: Get project data
        env:
          GITHUB_TOKEN: ${{ secrets.YOUR_TOKEN }}
          ORGANIZATION: YOUR_ORGANIZATION
          PROJECT_NUMBER: YOUR_PROJECT_NUMBER
        run: |
          gh api graphql -f query='
            query($org: String!, $number: Int!) {
              organization(login: $org){
                projectNext(number: $number) {
                  id
                  fields(first:20) {
                    nodes {
                      id
                      name
                      settings
                    }
                  }
                }
              }
            }' -f org=$ORGANIZATION -F number=$PROJECT_NUMBER > project_data.json

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

      - name: Add PR to project
        env:
          GITHUB_TOKEN: ${{ secrets.YOUR_TOKEN }}
          PR_ID: ${{ github.event.pull_request.node_id }}
        run: |
          item_id="$( gh api graphql -f query='
            mutation($project:ID!, $pr:ID!) {
              addProjectNextItem(input: {projectId: $project, contentId: $pr}) {
                projectNextItem {
                  id
                }
              }
            }' -f project=$PROJECT_ID -f pr=$PR_ID --jq '.data.addProjectNextItem.projectNextItem.id')"

          echo 'ITEM_ID='$item_id >> $GITHUB_ENV

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

      - name: Set fields
        env:
          GITHUB_TOKEN: ${{ secrets.YOUR_TOKEN }}
        run: |
          gh api graphql -f query='
            mutation (
              $project: ID!
              $item: ID!
              $status_field: ID!
              $status_value: String!
              $date_field: ID!
              $date_value: String!
            ) {
              set_status: updateProjectNextItemField(input: {
                projectId: $project
                itemId: $item
                fieldId: $status_field
                value: $status_value
              }) {
                projectNextItem {
                  id
                  }
              }
              set_date_posted: updateProjectNextItemField(input: {
                projectId: $project
                itemId: $item
                fieldId: $date_field
                value: $date_value
              }) {
                projectNextItem {
                  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

Workflow explanation

The following table explains sections of the example workflows and shows you how to adapt the workflows for your own use.

`on: pull_request: types: - ready_for_review`	Este flujo de trabajo se ejecuta cada que una solicitud de cambios en el repositorio se marca como "ready for review".
GitHub App only: `- name: Generate token id: generate_token uses: tibdex/github-app-token@36464acb844fc53b9b8b2401da68844f6b05ebb0 with: app_id: ${{ secrets.APP_ID }} private_key: ${{ secrets.APP_PEM }}`	Uses the tibdex/github-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 secret that contains your app ID. Replace `APP_PEM` with the name of the secret that contains your app private key.
GitHub App: `env: GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }} ORGANIZATION: YOUR_ORGANIZATION PROJECT_NUMBER: YOUR_PROJECT_NUMBER` Personal access token: `env: GITHUB_TOKEN: ${{ secrets.YOUR_TOKEN }} ORGANIZATION: YOUR_ORGANIZATION PROJECT_NUMBER: YOUR_PROJECT_NUMBER`	Configura las variables para este paso. If you are using a personal access token, replace `YOUR_TOKEN` with the name of the secret that contains your personal access token. Reemplaza `YOUR_ORGANIZATION` con el nombre de tu organización. Por ejemplo, `octo-org`. reemplaza `YOUR_PROJECT_NUMBER` con el número de tu proeycto. Para encontrar un número de proyecto, revisa su URL. Por ejemplo, la dirección `https://github.com/orgs/octo-org/projects/5` tiene "5" como número de proyecto.
`gh api graphql -f query=' query($org: String!, $number: Int!) { organization(login: $org){ projectNext(number: $number) { id fields(first:20) { nodes { id name settings } } } } }' -f org=$ORGANIZATION -F number=$PROJECT_NUMBER > project_data.json`	Utiliza el CLI de GitHub para consultar la API para la ID del proyecto y para la ID, nombre y configuración de los primeros 20 campos en este. La respuesta se almacena en un archivo que se llama `project_data.json`.
echo 'PROJECT_ID='$(jq '.data.organization.projectNext.id' project_data.json) >> $GITHUB_ENV echo 'DATE_FIELD_ID='$(jq '.data.organization.projectNext.fields.nodes[] \| select(.name== "Date posted") \| .id' project_data.json) >> $GITHUB_ENV echo 'STATUS_FIELD_ID='$(jq '.data.organization.projectNext.fields.nodes[] \| select(.name== "Status") \| .id' project_data.json) >> $GITHUB_ENV echo 'TODO_OPTION_ID='$(jq '.data.organization.projectNext.fields.nodes[] \| select(.name== "Status") \|.settings \| fromjson.options[] \| select(.name=="Todo") \|.id' project_data.json) >> $GITHUB_ENV	Analiza la respuesta desde la consulta de la API y almacena las ID relevantes como variables de ambiente. Modifica esto para obtener la ID para los campos u opciones diferentes. Por ejemplo: Para obtener la ID de un campo llamado `Team`, agrega `echo 'TEAM_FIELD_ID='$(jq '.data.organization.projectNext.fields.nodes[] \| select(.name== "Team") \| .id' project_data.json) >> $GITHUB_ENV`. Para obtener la ID de una opción llamada `Octoteam` para el campo `Team`, agrega `echo 'OCTOTEAM_OPTION_ID='$(jq '.data.organization.projectNext.fields.nodes[] \| select(.name== "Team") \|.settings \| fromjson.options[] \| select(.name=="Octoteam") \|.id' project_data.json) >> $GITHUB_ENV` Nota: Este flujo de trabajo asume que tienes un proyecto con un campo de selección simple llamado "Status" que incluye una opción llamada "Todo" y un campo de fecha llamado "Date Posted". Debes modificar esta sección para empatar con los campos que están presentes en tu tabla.
GitHub App: `env: GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }} PR_ID: ${{ github.event.pull_request.node_id }}` Personal access token: `env: GITHUB_TOKEN: ${{ secrets.YOUR_TOKEN }} PR_ID: ${{ github.event.pull_request.node_id }}`	Configura las variables para este paso. `GITHUB_TOKEN` se describe anteriormente. `PR_ID` es la ID de la solicitud de cambios que activó este flujo de trabajo.
`item_id="$( gh api graphql -f query=' mutation($project:ID!, $pr:ID!) { addProjectNextItem(input: {projectId: $project, contentId: $pr}) { projectNextItem { id } } }' -f project=$PROJECT_ID -f pr=$PR_ID --jq '.data.addProjectNextItem.projectNextItem.id')"`	Utiliza el CLI de GitHub y la API para agrega la solicitud de cambios que activó este flujo de trabajo hacia el proyecto. La bandera `jq` analiza la respuesta para obtener la ID del elemento creado.
`echo 'ITEM_ID='$item_id >> $GITHUB_ENV`	Almacena la ID del elemento creado como variable de ambiente.
`echo "DATE=$(date +"%Y-%m-%d")" >> $GITHUB_ENV`	Guarda la fecha actual como variable de ambiente en el formato `yyyy-mm-dd`.
GitHub App: `env: GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}` Personal access token: `env: GITHUB_TOKEN: ${{ secrets.YOUR_TOKEN }}`	Configura las variables para este paso. `GITHUB_TOKEN` se describe anteriormente.
gh api graphql -f query=' mutation ( $project: ID! $item: ID! $status_field: ID! $status_value: String! $date_field: ID! $date_value: String! ) { set_status: updateProjectNextItemField(input: { projectId: $project itemId: $item fieldId: $status_field value: $status_value }) { projectNextItem { id } } set_date_posted: updateProjectNextItemField(input: { projectId: $project itemId: $item fieldId: $date_field value: $date_value }) { projectNextItem { 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	Configura el valor del campo `Status` como `Todo`. Configura el valor del campo `Date posted`.

Automatizar proyectos (beta)

En este artículo

Introducción

Built-in workflows

GitHub Actions workflows

Example workflow authenticating with a GitHub App

Example workflow authenticating with a personal access token

Workflow explanation

¿Te ayudó este documento?

¡Ayúdanos a hacer geniales estos documentos!

¿Aún necesitas ayuda?