Autenticación automática de tokens

Acerca del secreto GITHUB_TOKEN

Al inicio de cada trabajo del flujo de trabajo, GitHub crea automáticamente un secreto GITHUB_TOKEN único para usarlo en el flujo de trabajo. Puede usar GITHUB_TOKEN para autenticarse en el trabajo del flujo.

Cuando habilitas GitHub Actions, GitHub instala una GitHub App en tu repositorio. El secreto GITHUB_TOKEN es un token de acceso de instalación de GitHub App. Puedes usar el token de acceso de instalación para autenticarte en nombre de la GitHub App instalado en tu repositorio. Los permisos del token están limitados al repositorio que contiene tu flujo de trabajo. Para más información, vea "Permisos para GITHUB_TOKEN".

Antes de que comience cada job, GitHub extrae un token de acceso de instalación para éste. GITHUB_TOKEN expira cuando finaliza un trabajo o después de un máximo de 24 horas.

El token también está disponible en el contexto github.token. Para obtener más información, vea «Acceso a información contextual sobre ejecuciones de flujo de trabajo».

Uso de GITHUB_TOKEN en un flujo de trabajo

Puede usar GITHUB_TOKEN mediante la sintaxis estándar para hacer referencia a secretos: ${{ secrets.GITHUB_TOKEN }}. Los ejemplos de uso de GITHUB_TOKEN incluyen pasar el token como entrada a una acción, o bien usarlo para realizar una solicitud autenticada a la API de GitHub.

Al usar GITHUB_TOKEN del repositorio para realizar tareas, los eventos desencadenados por GITHUB_TOKEN, con la excepción de workflow_dispatch y repository_dispatch, no crearán una nueva ejecución de flujo de trabajo. Esto impide que crees ejecuciones de flujo de trabajo recursivas por accidente. Por ejemplo, si una ejecución de flujo de trabajo inserta código mediante GITHUB_TOKEN del repositorio, un nuevo flujo de trabajo no se ejecutará incluso cuando el repositorio contenga un flujo de trabajo configurado para ejecutarse cuando se produzcan eventos push.

Las confirmaciones insertadas por un flujo de trabajo de GitHub Actions que usa GITHUB_TOKEN no desencadenan una compilación de GitHub Pages.

Ejemplo 1: Pasar GITHUB_TOKEN como entrada

En este flujo de trabajo de ejemplo se usa la CLI de GitHub, que necesita GITHUB_TOKEN como valor para el parámetro de entrada GH_TOKEN:

name: Open new issue
on: workflow_dispatch

jobs:
  open-issue:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - run: |
          gh issue --repo ${{ github.repository }} \
            create --title "Issue title" --body "Issue body"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

name: Open new issue
on: workflow_dispatch

jobs:
  open-issue:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - run: |
          gh issue --repo ${{ github.repository }} \
            create --title "Issue title" --body "Issue body"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Ejemplo 2: llamar a la API de REST

Puede usar GITHUB_TOKEN para realizar llamadas API autenticadas. Este flujo de trabajo de ejemplo crea una propuesta mediante la API REST del GitHub:

name: Create issue on commit

on: [ push ]

jobs:
  create_issue:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    steps:
      - name: Create issue using REST API
        run: |
          curl --request POST \
          --url https://api.github.com/repos/${{ github.repository }}/issues \
          --header 'authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' \
          --header 'content-type: application/json' \
          --data '{
            "title": "Automated issue for commit: ${{ github.sha }}",
            "body": "This issue was automatically created by the GitHub Action workflow **${{ github.workflow }}**. \n\n The commit hash was: _${{ github.sha }}_."
            }' \
          --fail

Permisos para GITHUB_TOKEN

Para obtener información sobre los puntos de conexión de la API a los que GitHub Apps puede acceder con cada permiso, consulta "Permisos que requieren las Github Apps".

En la tabla siguiente, se muestran los permisos concedidos al GITHUB_TOKEN de manera predeterminada. Las personas con permisos administrativos en una empresa, organización o repositorio pueden configurar los permisos predeterminados para que sean permisivos o restringidos. Para obtener información sobre cómo establecer los permisos predeterminados para GITHUB_TOKEN para tu empresa, organización o repositorio, consulta "Requerir políticas para las GitHub Actions en tu empresa", "Inhabilitar o limitar GitHub Actions para tu organización" o "Administrar los ajustes de las GitHub Actions de un repositorio".

Modificación de los permisos para GITHUB_TOKEN

Puede modificar los permisos de GITHUB_TOKEN en archivos de flujo de trabajo individuales. Si los permisos predeterminados para GITHUB_TOKEN son restrictivos, es posible que tenga que elevarlos para permitir que algunas acciones y comandos se ejecuten correctamente. Si los permisos predeterminados son permisivos, puede editar el archivo de flujo de trabajo para quitar algunos permisos de GITHUB_TOKEN. Como práctica de seguridad recomendada, debe conceder el permiso de acceso menos necesario a GITHUB_TOKEN.

Puede ver los permisos que ha tenido GITHUB_TOKEN para un trabajo específico en la sección "Configuración del trabajo" del registro de ejecución de flujo de trabajo. Para obtener más información, vea «Uso de registros de ejecución de flujo de trabajo».

También puede usar la clave permissions en el archivo de flujo de trabajo a fin de modificar los permisos para GITHUB_TOKEN en un flujo de trabajo completo o en trabajos individuales. Esto te permite configurar los permisos mínimos requeridos para un flujo de trabajo o job. Cuando se usa la clave permissions, todos los permisos no especificados se establecen en Sin acceso, a excepción del ámbito metadata, que siempre obtiene acceso de lectura.

Puede usar la clave permissions a fin de agregar y quitar permisos de lectura para repositorios bifurcados, pero normalmente no se puede conceder acceso de escritura. La excepción a este comportamiento es cuando un usuario administrador ha seleccionado la opción Enviar tokens a flujos de trabajo desde solicitudes de incorporación de cambios en la configuración de GitHub Actions. Para obtener más información, vea «Administrar los ajustes de las GitHub Actions de un repositorio».

En los dos ejemplos de flujo de trabajo anteriores de este artículo se muestra la clave permissions que se usa en el nivel de trabajo, ya el procedimiento recomendado es limitar el ámbito de los permisos.

Para obtener detalles completos de la clave permissions, consulta "Sintaxis del flujo de trabajo para Acciones de GitHub".

Cómo se calculan los permisos para un job de un flujo de trabajo

Los permisos para GITHUB_TOKEN se establecen inicialmente con los valores predeterminados para la empresa, organización o repositorio. Si lo predeterminado se configura para los permisos restringidos en cualquiera de estos niveles, esto aplicará a los repositorios relevantes. Por ejemplo, si eliges las restricciones predeterminadas a nivel organizacional, entonces todos los repositorios de la organización utilizarán estos permisos restringidos como los predeterminados. Entonces, los permisos se ajustarán con base en cualquier configuración dentro del archivo de flujo de trabajo, primero a nivel del flujo de trabajo y luego al nivel de los jobs. Por último, si una solicitud de incorporación de cambios ha desencadenado el flujo de trabajo desde un repositorio bifurcado y no se selecciona el valor Enviar tokens de escritura a los flujos de trabajo desde las solicitudes de incorporación de cambios, los permisos se ajustarán para cambiar los de escritura a solo lectura.

Otorgar permisos adicionales

Si necesitas un token que requiera permisos que no estén disponibles en GITHUB_TOKEN, puedes crear una GitHub App y generar un token de acceso de instalación dentro del flujo de trabajo. Para obtener más información, vea «Realización de solicitudes de API autenticadas con una aplicación de GitHub en un flujo de trabajo de Acciones de GitHub». Como alternativa, puedes crear un personal access token, almacenarlo como secreto en el repositorio y usar el token en el flujo de trabajo con la sintaxis ${{ secrets.SECRET_NAME }}. Para obtener más información, vea «Administración de tokens de acceso personal» y «Uso de secretos en Acciones de GitHub».

Información adicional

• "Límites de volumen de la API de REST"