Autenticación automática de tokens

Acerca del secreto GITHUB_TOKEN

Al inicio de cada ejecución de 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 una ejecución de flujo de trabajo.

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

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

Al usar GITHUB_TOKEN del repositorio para realizar tareas, los eventos desencadenados por GITHUB_TOKEN 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.

Ejemplo 1: Pasar GITHUB_TOKEN como entrada

En este flujo de trabajo de ejemplo se usa la acción del etiquetador, que necesita GITHUB_TOKEN como valor para el parámetro de entrada repo-token:

name: Pull request labeler
on: [ pull_request_target ]

jobs:
  triage:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/labeler@v4
        with:
          repo-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 http(s)://HOSTNAME/api/v3/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 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 mostrados antes en este artículo se muestra cómo se usa la clave permissions en el nivel de flujo de trabajo y en el nivel de trabajo. En el Ejemplo 1, se especifican los dos permisos para todo el flujo de trabajo. En el Ejemplo 2, se concede acceso de escritura para un ámbito de un único trabajo.

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 «Creación de un token de acceso personal» y «Secretos cifrados».

Información adicional

• "Recursos en la API de REST"