Skip to main content
Publicamos actualizaciones para la documentación con frecuencia y es posible que aún se esté traduciendo esta página. Para obtener la información más reciente, consulta la documentación en inglés.

Autenticación automática de tokens

GitHub proporciona un token que puedes usar para autenticar en nombre de GitHub Actions.

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

Importante: Una acción puede acceder a GITHUB_TOKEN mediante el contexto github.token incluso si el flujo de trabajo no pasa explícitamente GITHUB_TOKEN a la acción. Como procedimiento de seguridad correcto, siempre debe asegurarse de que las acciones solo tengan el acceso mínimo necesario para limitar los permisos que se conceden a GITHUB_TOKEN. Para más información, vea "Permisos para GITHUB_TOKEN".

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.

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:

YAML
name: Pull request labeler
on: [ pull_request_target ]

permissions:
  contents: read
  pull-requests: write

jobs:
  triage:
    runs-on: ubuntu-latest
    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 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, vea "Permisos de GitHub App".

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 en la empresa, la organización o el repositorio, vea "Aplicación de directivas para GitHub Actions en la empresa", "Deshabilitación o limitación de GitHub Actions para la organización" o "Administración de la configuración de GitHub Actions para un repositorio".

ÁmbitoAcceso predeterminado
(permisivo)
Acceso predeterminado
(restringido)
Acceso máximo para
solicitudes de incorporación de
repositorios bifurcados públicos[†]
actionslectura/escrituraningunoleer
checkslectura/escrituraningunoleer
contenidolectura/escrituraleerleer
deploymentslectura/escrituraningunoleer
id-tokenningunoningunoleer
issueslectura/escrituraningunoleer
metadataleerleerleer
packageslectura/escrituraningunoleer
páginaslectura/escrituraningunoleer
pull-requestslectura/escrituraningunoleer
repository-projectslectura/escrituraningunoleer
security-eventslectura/escrituraningunoleer
statuseslectura/escrituraningunoleer

[†] Los repositorios privados pueden controlar si las solicitudes de incorporación de cambios de bifurcaciones pueden ejecutar flujos de trabajo y configurar los permisos asignados a GITHUB_TOKEN. Para obtener más información, consulta "Administración de la configuración de Acciones de GitHub para un repositorio".

Nota: Las ejecuciones de flujos de trabajo que las solicitudes de incorporación de cambios de Dependabot desencadenan se ejecutan como si fueran de un repositorio bifurcado y, por lo tanto, usan un GITHUB_TOKEN de solo lectura. Estas ejecuciones de flujo de trabajo no pueden acceder a ningún secreto. Consulta "Mantenimiento de la seguridad de los flujos de trabajo y Acciones de GitHub: prevención de solicitudes pwn" para obtener estrategias destinadas a proteger estos flujos de trabajo.

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 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 más información, vea "Administración de la configuración de GitHub Actions para 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 los detalles completos de la clave permissions, vea "Sintaxis de flujo de trabajo para GitHub Actions".

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 requiere permisos que no están disponibles en GITHUB_TOKEN, puedes crear un personal access token y configurarlo como un secreto en el repositorio:

  1. Usa o crea un token con los permisos adecuados para ese repositorio. Para obtener más información, consulta "Creación de un personal access token".
  2. Agregue el token como un secreto en el repositorio del flujo de trabajo y use la sintaxis ${{ secrets.SECRET_NAME }} para hacerle referencia. Para más información, vea "Creación y uso de secretos cifrados".

Información adicional