Autenticación automática de token

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

Acerca del secreto del GITHUB_TOKEN

Al inicio de cada ejecución de flujo de trabajo, GitHub crea automáticamente un secreto único de GITHUB_TOKEN para utilizar en tu flujo de trabajo. Puedes usar el GITHUB_TOKEN para autenticarte en una ejecución de flujo de trabajo.

Cuando habilitas GitHub Actions, GitHub instala una GitHub App en tu repositorio. El secreto del 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 obtener más información, consulta "Permisos para el GITHUB_TOKEN."

Antes de que comience cada job, GitHub extrae un token de acceso de instalación para éste. El token expira cuando el trabajo termina.

El token también está disponible en el contexto github.token. Para obtener más información, consulta "Contextos".

Usar el GITHUB_TOKEN en un flujo de trabajo

Puedes utilizar el GITHUB_TOKEN si utilizas la sintaxis estándar para referenciar secretos: ${{ secrets.GITHUB_TOKEN }}. Los ejemplos de uso del GITHUB_TOKEN incluyen pasar el token como entrada a una acción o utilizarlo para hacer una solicitud autenticada a la API de GitHub.

Importante: Las acciones pueden acceder al GITHUB_TOKEN mediante el contexto github.token aún si el flujo de trabajo no pasa el GITHUB_TOKEN específicamente a la acción. Como buena práctica de seguridad. siempre deberías asegurarte de que las acciones solo tengan el acceso mínimo que necesitan para limitar los permisos que se le otorgan al GITHUB_TOKEN. Para obtener más información, consulta "Permisos para el GITHUB_TOKEN."

Cuando utilizas el GITHUB_TOKEN del repositorio para realizar tareas por parte de la app de GitHub Actions, los eventos que GITHUB_TOKEN desencadena no crearán una ejecución de flujo de trabajo. Esto impide que crees ejecuciones de flujo de trabajo recursivas por accidente. Por ejemplo, si un flujo de trabajo sube código utilizando el GITHUB_TOKEN del repositorio, no se ejecutará un nuevo flujo de trabajo aún si el repositorio contiene alguno configurado para ejecutarse cuando ocurran eventos de subida de información.

Ejemplo 1: pasar el GITHUB_TOKEN como entrada

Este flujo de trabajo de ejemplo usa la acción de etiquetadora, que necesita el GITHUB_TOKEN como el valor para el parámetro de entrada repo-token:

name: Pull request labeler

on: [ pull_request_target ]

permissions:
  contents: read
  pull-requests: write

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/labeler@v2
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}

Ejemplo 2: llamar a la API de REST

Puedes usar el 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_commit:
    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 el GITHUB_TOKEN

Para obtener mpas información sobre las terminales de la API a los que pueden acceder las GitHub Apps con cada permiso, consulta la sección " Permisos de las GitHub App".

La siguiente tabla muestra los permisos que se otorgan al GITHUB_TOKEN predeterminadamente. 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 más información sobre cómo configurar los permisos predeterminados del GITHUB_TOKEN para tu empresa, organización o repositorio, consulta las secciones "Requerir políticas de GitHub Actions en tu cuenta empresarial", "Inhabilitar o limitar las GitHub Actions para tu organización" o "Administrar los ajustes de las GitHub Actions para un repositorio".

ÁmbitoAcceso predeterminado
(permisivo)
Acceso predeterminado
(restringido)
Acceso máximo
de los repos bifurcados
accioneslectura/escrituraningunolectura
verificacioneslectura/escrituraningunolectura
contenidoslectura/escrituralecturalectura
implementacioneslectura/escrituraningunolectura
propuestaslectura/escrituraningunolectura
metadatoslecturalecturalectura
paqueteslectura/escrituraningunolectura
solicitudes de extracciónlectura/escrituraningunolectura
proyectos de repositoriolectura/escrituraningunolectura
eventos de seguridadlectura/escrituraningunolectura
estadoslectura/escrituraningunolectura

Nota: Las ejecuciones de flujo de trabajo que activan las solicitudes de cambios del Dependabot se ejecutan como si fueran de un repositorio bifurcado y, por lo tanto, utilizan un GITHUB_TOKEN de solo lectura. Estas ejecuciones de flujo de trabajo no pueden acceder a ningún secreto. Consulta la sección "Mantener seguras tus GitHub Actions y flujos de trabajo: Prevenir solicitudes de tipo pwn" para conocer estrategias para mantener la seguridad de estos flujos de trabajo.

Modificar los permisos del GITHUB_TOKEN

Puedes modificar los permisos del GITHUB_TOKEN en archivos de flujo de trabajo individuales. Si los permisos predeterminados del GITHUB_TOKEN son restrictivos, podría que necesites elevar los permisos para permitir que las acciones y comandos se ejecuten con éxito. Si los permisos predeterminados son permisivos, puedes editar el archivo de flujo de trabajo para eliminar algunos de ellos del GITHUB_TOKEN. Como buena práctica de seguridad, debes otorgar al GITHUB_TOKEN el menor acceso requerido.

Puedes ver los permisos que tuvo el GITHUB_TOKEN para un job específico en la sección "Configurar job" de la bitácora de la ejecución de flujo de trabajo. Para obtener más información, consulta la sección "Utilizar bitácoras de ejecución de flujos de trabajo".

Puedes utilizar la clave permissions en tu archivo de flujo de trabajo para modificar los permisos del GITHUB_TOKEN para un flujo de trabajo entero o para jobs individuales. Esto te permite configurar los permisos mínimos requeridos para un flujo de trabajo o job. Cuando se utiliza la clave permissions, todos los permisos no especificados se configuran como "sin acceso", con la excepción del alcance metadata, el cual siempre obtiene acceso de lectura.

Puedes utilizar la clave permissions para agregar y eliminar los permisos de lectura para los repositorios bifurcados pero, habitualmente, no puedes otorgar acceso de escritura. La excepción a este comportamiento es donde un usuario administrador seleccionó la opción de Enviar tokens a los flujos de trabajo desde las solicitudes de cambios en la configuración de GitHub Actions. Para obtener más información, consulta la sección "Administrar la configuración de GitHub Actions en un repositorio".

Los dos ejemplos de flujo de trabajo que se mostraron anteriormente en este artículo muestran como se utiliza la clave permissions a nivel de flujo de trabajo y de job. En el Ejemplo 1 se especifican los dos permisos para todo el flujo de trabajo. En el Ejemplo 2 se otorga acceso de escritura para un alcance para un solo job.

Para conocer todos los detalles de la clave permissions, consulta la sección "Sintaxis de flujo de trabajo para las GitHub Actions".

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

Los permisos para el GITHUB_TOKEN se configuran inicialmente con los ajustes 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 solilcitud de cambios activó el flujo de trabajo desde un repositorio bifurcado y no se selecciona el ajuste de Enviar tokens de escritura a los flujos de trabajo desde las solicitudes de cambios, los permisos se ajustarán para cambiar cualquier permiso de escritura a solo lectura.

Otorgar permisos adicionales

Si necesitas un token que requiere permisos que no están disponibles en el GITHUB_TOKEN, puedes crear un token de acceso personal y establecerlo como un secreto en tu repositorio:

  1. Usa o crea un token con los permisos adecuados para ese repositorio. Para obtener más información, consulta la sección "Crear un token de acceso personal".
  2. Añade el token como un secreto en el repositorio de tu flujo de trabajo y haz referencia a él mediante la sintaxis ${{ secrets.SECRET_NAME }}. Para obtener más información, consulta "Crear y usar secretos cifrados."

¿Te ayudó este documento?

Política de privacidad

¡Ayúdanos a hacer geniales estos documentos!

Todos los documentos de GitHub son de código abierto. ¿Notas algo que esté mal o que no sea claro? Emite una solicitud de cambios.

Haz una contribución

O, aprende cómo contribuir.