Skip to main content

Uso de secretos en Acciones de GitHub

Los secretos te permiten almacenar información confidencial en tu organización, repositorio o entornos de repositorio.

Tool navigation

Acerca de los secretos

Los secretos son variables que se crean en una organización, repositorio o entorno de repositorio. Los secretos que creas están disponibles para utilizarse en los flujos de trabajo de GitHub Actions. GitHub Actions solo puede leer un secreto si incluye explícitamente el secreto en un flujo de trabajo.

Para los secretos almacenados a nivel organizacional, peudes utilizar las políticas de acceso para controlar qué repositorios pueden utilizar secretos organizacionales. Los secretos a nivel organizacional te permiten compartir secretos entre repositorios múltiples, lo cual reduce la necesidad de crear secretos duplicados. El actualizar un secreto de organización en una ubicación también garantiza que el cambio tome efecto en todos los flujos de trabajo del repositorio que lo utilicen.

Para que los secretos se almacenen a nivel de ambiente, puedes habilitar los revisores requeridos para controlar el acceso a los secretos. Un job de flujo de trabajo no puede acceder a los secretos del ambiente hasta que los revisores requeridos le otorguen aprobación.

Nota: Si tus flujos de trabajo de GitHub Actions necesitan acceder a los recursos de un proveedor de servicios en la red que sea compatible con OpenID Connect (OIDC), puedes configurarlos para que se autentiquen directamente con dicho proveedor. Esto te permitirá dejar de almacenar estas credenciales como secretos de duración larga y te proporcionará otros beneficios de seguridad. Para más información, consulta "Acerca del fortalecimiento de seguridad con OpenID Connect".

Nombrar tus secretos

Las siguientes reglas aplican a los nombres secretos:

  • Los nombres solo pueden contener caracteres alfanuméricos ([a-z], [A-Z], [0-9]) o caracteres de subrayado (_). No se permiten espacios.

  • Los nombres no deben comenzar con el prefijo GITHUB_.

  • Los nombres no deben comenzar con un número.

  • Los nombres no distinguen mayúsculas de minúsculas.

  • Los nombres deben ser únicos en el nivel en el que se hayan creado.

    Por ejemplo, un secreto que se creó a nivel de ambiente debe tener un nombre único en éste, un secreto que se creó a nivel de repositorio debe tener un nombre único en éste, y un secreto que se creó a nivel de organización debe tener un nombre único en este nivel.

    Si existe un secreto con el mismo nombre en varios niveles, tiene preferencia el del nivel más bajo. Por ejemplo, si un secreto a nivel de organización tiene el mismo nombre que un secreto a nivel de repositorio, entonces el secreto a nivel de repositorio tomará precedencia. De forma similar, si una organización, repositorio y ambiente tienen u secreto con el mismo nombre, el que esté a nivel de ambiente tomará precedencia.

Para ayudarte a garantizar que GitHub redacta tus secretos en bitácoras, evita utilizar datos estructurados como los valores de los secretos. Por ejemplo, evita crear secretos que contengan JSON o blobs de Git codificados.

Acceder a tus secretos

Para hacer que un secreto esté disponible para una acción, debes configurar el secreto como variable de entrada o de entorno en tu archivo de flujo de trabajo. Revisa el archivo README de la acción para saber qué variables de entrada y de entorno espera la acción. Para obtener más información, vea «Sintaxis del flujo de trabajo para Acciones de GitHub».

Puede usar y leer secretos en un archivo de flujo de trabajo si tiene acceso para editar el archivo. Para obtener más información, vea «Permisos de acceso en GitHub».

Advertencia: si se usó un secreto en el trabajo, GitHub redacta automáticamente los secretos impresos en el registro. Debe evitar imprimir secretos en el registro intencionadamente.

Los secretos de organización y de repositorio se leen cuando una ejecución de flujo de trabajo está en cola y los secretos de ambiente se leen cuando un job que referencia el ambiente comienza.

También puedes administrar secretos utilizando la API de REST. Para obtener más información, vea «Puntos de conexión de API de REST para secretos de Acciones de GitHub».

Limitar permisos de credenciales

Cuando generes credenciales, te recomendamos que otorgues los mínimos permisos posibles. Por ejemplo, en lugar de usar credenciales personales, use claves de implementación o una cuenta de servicio. Considera otorgar permisos de solo lectura si eso es todo lo que se necesita, y limita el acceso lo máximo posible.

Al generar un personal access token (classic), selecciona el menor número de ámbitos necesarios. Al generar un fine-grained personal access token, selecciona el acceso y los permisos mínimos del repositorio necesarios.

En lugar de usar un personal access token, considera la posibilidad de usar una GitHub App, que usa permisos específicos y tokens de corta duración, similar a un fine-grained personal access token. A diferencia de un personal access token, una GitHub App no está vinculada a un usuario, por lo que el flujo de trabajo seguirá funcionando incluso si el usuario que instaló la aplicación deja la organización. 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».

Nota: Los usuarios con acceso de colaborador a un repositorio pueden usar la API REST para administrar los secretos de ese repositorio, mientras que los usuarios con acceso de administrador a una organización pueden usar la API REST para administrar los secretos de esa organización. Para obtener más información, vea «Puntos de conexión de API de REST para secretos de Acciones de GitHub».

Creación de secretos para un repositorio

Para crear secretos o variables en GitHub para un repositorio de una cuenta personal, debes ser propietario del repositorio. Para crear secretos o variables en GitHub para un repositorio de una organización, debes tener acceso de admin. Por último, para crear secretos o variables para un repositorio de cuentas personales o un repositorio de una organización a través de la API REST, es preciso tener acceso de colaborador.

  1. En GitHub.com, navega a la página principal del repositorio.

  2. En el nombre del repositorio, haz clic en Configuración. Si no puedes ver la pestaña "Configuración", selecciona el menú desplegable y, a continuación, haz clic en Configuración.

    Captura de pantalla de un encabezado de repositorio en el que se muestran las pestañas. La pestaña "Configuración" está resaltada con un contorno naranja oscuro.

  3. En la sección "Seguridad" de la barra lateral, selecciona Secretos y variables, después, haz clic en Acciones.

  4. Haz clic en la pestaña Secretos. Captura de pantalla de la página de "Secretos y variables de las acciones".

  5. Haga clic en New repository secret.

  6. En el campo Nombre, escribe un nombre para el secreto.

  7. En el campo Secreto, escribe el valor del secreto.

  8. Haga clic en Add Secret.

So tu repositorio tiene secretos de ambiente o puede acceder a los secretos de la organización padre, entonces estos también se listarán en esta página.

Para más información sobre GitHub CLI, consulta "Acerca del CLI de GitHub".

Para agregar un secreto del repositorio, use el subcomando gh secret set. Reemplace secret-name por el nombre del secreto.

gh secret set SECRET_NAME

El CLI te pedirá ingresar un valor secreto. Como alternativa, puedes leer el valor del secreto desde un archivo.

gh secret set SECRET_NAME < secret.txt

Para mostrar todos los secretos del repositorio, use el subcomando gh secret list.

Crear secretos para un ambiente

Para crear secretos o variables para un entorno en un repositorio de una cuenta personal, el repositorio debe ser de tu propiedad. Para crear secretos o variables para un entorno en un repositorio de una organización, debes tener acceso a admin. Para obtener más información sobre los entornos, consulta "Utilizar ambientes para el despliegue".

  1. En GitHub.com, navega a la página principal del repositorio.

  2. En el nombre del repositorio, haz clic en Configuración. Si no puedes ver la pestaña "Configuración", selecciona el menú desplegable y, a continuación, haz clic en Configuración.

    Captura de pantalla de un encabezado de repositorio en el que se muestran las pestañas. La pestaña "Configuración" está resaltada con un contorno naranja oscuro.

  3. En la barra lateral de la izquierda, haz clic en Entornos.

  4. Da clic en el ambiente al cual quieras agregar un secreto.

  5. En Environment secrets, haga clic en Add secret.

  6. Escriba un nombre para su secreto en el cuadro de entrada Name.

  7. Ingresa el valor de tu secreto.

  8. Haga clic en Add Secret.

Para agregar un secreto de un entorno, use el subcomando gh secret set con la --env marca o -e seguida del nombre del entorno.

gh secret set --env ENV_NAME SECRET_NAME

Para mostrar todos los secretos de un entorno, use el subcomando gh secret list con la --env marca o -e seguida del nombre del entorno.

gh secret list --env ENV_NAME

Crear secretos para una organización

Cuando creas un secreto o una variable en una organización, puedes usar una política para limitar el acceso por repositorio. Por ejemplo, puedes otorgar acceso a todos los repositorios, o limitarlo a solo los repositorios privados o a una lista específica de estos.

Los propietarios de la organización y los usuarios con los permisos "Administrar variables de acciones de la organización" o "Administrar secretos de acciones de la organización" pueden crear secretos o variables en el nivel de organización.

Para más información, consulta "Acerca de los roles personalizados de organización".

  1. En GitHub.com, ve a la página principal de la organización.

  2. En el nombre de la organización, haz clic en Configuración. Si no puedes ver la pestaña "Configuración", selecciona el menú desplegable y, a continuación, haz clic en Configuración.

    Captura de pantalla de las pestañas en el perfil de una organización. La pestaña "Configuración" se destaca en naranja oscuro.

  3. En la sección "Seguridad" de la barra lateral, selecciona Secretos y variables, después, haz clic en Acciones.

  4. Haz clic en la pestaña Secretos.

    Captura de pantalla de la página "Secretos y variables de acciones". Una pestaña, con la etiqueta "Secretos", se resalta en color naranja oscuro.

    Nota: Es posible que la página "Secretos y variables de acciones" no muestre pestañas distintas para secretos y variables en función de los permisos. Los propietarios y usuarios de la organización con los permisos "Administrar variables de acciones de la organización" y "Administrar secretos de acciones de la organización" verán las pestañas Variables y Secretos. Para obtener más información, vea «Acerca de los roles personalizados de organización».

  5. Haga clic en New organization secret.

  6. Escriba un nombre para su secreto en el cuadro de entrada Name.

  7. Introduzca el valor del secreto en Value.

  8. En la lista desplegable Repository access (Acceso al repositorio), elija una directiva de acceso.

  9. Haga clic en Add Secret.

Nota: De manera predeterminada, GitHub CLI se autentica con los alcances repo y read:org. Para administrar secretos de la organización, debe autorizar además el alcance admin:org.

gh auth login --scopes "admin:org"

Para agregar un secreto de una organización, use el subcomando gh secret set con la marca --org o -o seguida del nombre de la organización.

gh secret set --org ORG_NAME SECRET_NAME

Predeterminadamente, el secreto solo se encuentra disponible para los repositorios privados. Para especificar que el secreto debe estar disponible para todos los repositorios de la organización, use la marca --visibility o -v.

gh secret set --org ORG_NAME SECRET_NAME --visibility all

Para especificar que el secreto debe estar disponible para los repositorios seleccionados de la organización, use la marca --repos o -r.

gh secret set --org ORG_NAME SECRET_NAME --repos REPO-NAME-1, REPO-NAME-2"

Para mostrar todos los secretos de una organización, use el subcomando gh secret list con la marca --org o -o seguida del nombre de la organización.

gh secret list --org ORG_NAME

Revisar el acceso a los secretos de nivel organizacional

Puedes revisar qué políticas de acceso se están aplicando a un secreto en tu organización.

  1. En GitHub.com, ve a la página principal de la organización.

  2. En el nombre de la organización, haz clic en Configuración. Si no puedes ver la pestaña "Configuración", selecciona el menú desplegable y, a continuación, haz clic en Configuración.

    Captura de pantalla de las pestañas en el perfil de una organización. La pestaña "Configuración" se destaca en naranja oscuro.

  3. En la sección "Seguridad" de la barra lateral, selecciona Secretos y variables, después, haz clic en Acciones.

  4. La lista de secretos incluye cualquier política y permiso configurado. Para obtener más información sobre los permisos configurados para cada secreto, haz clic en Actualizar.

Uso de secretos en un flujo de trabajo

Notas:

  • Con la excepción de GITHUB_TOKEN, los secretos no se pasan al ejecutor cuando se desencadena un flujo de trabajo desde un repositorio bifurcado.

  • Los secretos no se pasan automáticamente a flujos de trabajo reutilizables. Para obtener más información, vea «Reutilización de flujos de trabajo».

Para proporcionar una acción con un secreto como variable de entrada o de entorno, puede usar el contexto secrets para acceder a los secretos que haya creado en el repositorio. Para obtener más información, vea «Contextos» y «Sintaxis del flujo de trabajo para Acciones de GitHub».

steps:
  - name: Hello world action
    with: # Set the secret as an input
      super_secret: ${{ secrets.SuperSecret }}
    env: # Or as an environment variable
      super_secret: ${{ secrets.SuperSecret }}

No se puede hacer referencia a los secretos directamente en las condicionales if:. En vez de esto, considera configurar secretos como variables de ambiente a nivel de jobs y luego referencia dichas variables para ejecutar pasos de forma condicional en el job. Para obtener más información, consulta: "Contextos" y jobs.<job_id>.steps[*].if.

Si no se ha establecido ningún secreto, el valor devuelto de una expresión que hace referencia al secreto (como ${{ secrets.SuperSecret }} en el ejemplo) será una cadena vacía.

Evita pasar secretos entre procesos desde la línea de comando, siempre que sea posible. Los procesos de la línea de comandos pueden ser visibles para otros usuarios (mediante el comando ps) o capturados mediante eventos de auditoría de seguridad. Para proteger los secretos, considere la opción de usar variables de entorno, STDIN u otros mecanismos admitidos por el proceso de destino.

Si debes pasar secretos dentro de una línea de comando, enciérralos usando las normas de uso de comillas adecuadas. Los secretos suelen contener caracteres especiales que pueden afectar involuntariamente a tu shell. Para evitar estos caracteres especiales, usa comillas en tus variables de entorno. Por ejemplo:

Ejemplo usando Bash

steps:
  - shell: bash
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "$SUPER_SECRET"

Ejemplo usando PowerShell

steps:
  - shell: pwsh
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "$env:SUPER_SECRET"

Ejemplo usando Cmd.exe

steps:
  - shell: cmd
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "%SUPER_SECRET%"

Límites para los secretos

Puedes almacenar hasta 1,000 secretos de organización, 100 secretos de repositorio y 100 secretos de ambiente.

Un flujo de trabajo que se haya creado en un repositorio puede acceder a la siguiente cantidad de secretos:

  • Todos los 100 secretos de repositorio.
  • Si se asigna acceso a más de 100 secretos de la organización para este repositorio, el flujo de trabajo solo puede utilizar los primeros 100 secretos de organización (que se almacenan por orden alfabético por nombre de secreto).
  • Todos los 100 secretos de ambiente.

Los secretos tienen un tamaño máximo de 48 KB. Para almacenar secretos más grandes, consulta la solución alternativa "Almacenamiento de secretos grandes" que se muestra a continuación.

Almacenamiento de secretos grandes

Para usar secretos de un tamaño superior a 48 KB, puede usar una solución alternativa consistente en almacenar los secretos en su repositorio y guardar la frase de contraseña de descifrado como un secreto en GitHub. Por ejemplo, puedes usar gpg para cifrar un archivo que contiene el secreto de manera local antes de comprobar el archivo cifrado en el repositorio en GitHub. Para obtener más información, consulte la "página man de gpg".

Advertencia: Intenta evitar que los secretos se impriman cuando se ejecute el flujo de trabajo. Cuando usas esta solución, GitHub no redacta los secretos que están impresos en los registros.

  1. Ejecuta el comando siguiente desde el terminal para cifrar el archivo que contiene el secreto mediante gpg y el algoritmo de cifrado AES256. En este ejemplo, my_secret.json es el archivo que contiene el secreto.

    gpg --symmetric --cipher-algo AES256 my_secret.json
    
  2. Se te pedirá que ingreses una contraseña. Recuerda la contraseña, porque deberás crear un nuevo secreto en GitHub que use esa contraseña como valor.

  3. Crear un nuevo secreto que contiene la frase de acceso. Por ejemplo, crea un secreto con el nombre LARGE_SECRET_PASSPHRASE y establece el valor del secreto en la frase de contraseña que usaste en el paso anterior.

  4. Copia el archivo cifrado en una ruta de acceso de tu repositorio y confírmalo. En este ejemplo, el archivo cifrado es my_secret.json.gpg.

    Advertencia: Asegúrate de copiar el archivo cifrado my_secret.json.gpg que termina con la extensión de archivo .gpg y no el archivo sin cifrar my_secret.json.

    git add my_secret.json.gpg
    git commit -m "Add new secret JSON file"
    
  5. Crea un script de shell en el repositorio para descifrar el archivo secreto. En este ejemplo, el script se denomina decrypt_secret.sh.

    Shell
    #!/bin/sh
    
    # Decrypt the file
    mkdir $HOME/secrets
    # --batch to prevent interactive command
    # --yes to assume "yes" for questions
    gpg --quiet --batch --yes --decrypt --passphrase="$LARGE_SECRET_PASSPHRASE" \
    --output $HOME/secrets/my_secret.json my_secret.json.gpg
    
  6. Asegúrate de que tu script de shell sea ejecutable antes de verificarlo en tu repositorio.

    chmod +x decrypt_secret.sh
    git add decrypt_secret.sh
    git commit -m "Add new decryption script"
    git push
    
  7. En el flujo de trabajo de GitHub Actions, usa step para llamar al script de shell y descifrar el secreto. Para tener una copia del repositorio en el entorno en el que se ejecuta el flujo de trabajo, deberá usar la acción actions/checkout. Haga referencia a su script de shell mediante el comando run que corresponde con la raíz de su repositorio.

    name: Workflows with large secrets
    
    on: push
    
    jobs:
      my-job:
        name: My Job
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - name: Decrypt large secret
            run: ./decrypt_secret.sh
            env:
              LARGE_SECRET_PASSPHRASE: ${{ secrets.LARGE_SECRET_PASSPHRASE }}
          # This command is just an example to show your secret being printed
          # Ensure you remove any print statements of your secrets. GitHub does
          # not hide secrets that use this workaround.
          - name: Test printing your secret (Remove this step in production)
            run: cat $HOME/secrets/my_secret.json
    

Almacenar blobs binarios en Base64 como secretos

Puedes utilizar el cifrado en Base64 para almacenar blobs binarios pequeños como secretos. Puedes referenciar el secreto en tu flujo de trabajo y decodificarlo para utilizarlo en el ejecutor. Para conocer los límites de tamaño, consulta: "Uso de secretos en Acciones de GitHub".

Nota: Tenga en cuenta que Base64 solo convierte elementos binarios en texto y no es un sustituto del cifrado real.

  1. Use base64 para codificar el archivo en una cadena Base64. Por ejemplo:

    En macOS, puede ejecutar:

    base64 -i cert.der -o cert.base64
    

    En Linux, puede ejecutar:

    base64 -w 0 cert.der > cert.base64
    
  2. Crea un secreto que contenga la secuencia de Base64. Por ejemplo:

    $ gh secret set CERTIFICATE_BASE64 < cert.base64
    ✓ Set secret CERTIFICATE_BASE64 for octocat/octorepo
    
  3. Para acceder a la cadena Base64 desde el ejecutor, canalice el secreto a base64 --decode. Por ejemplo:

    name: Retrieve Base64 secret
    on:
      push:
        branches: [ octo-branch ]
    jobs:
      decode-secret:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - name: Retrieve the secret and decode it to a file
            env:
              CERTIFICATE_BASE64: ${{ secrets.CERTIFICATE_BASE64 }}
            run: |
              echo $CERTIFICATE_BASE64 | base64 --decode > cert.der
          - name: Show certificate information
            run: |
              openssl x509 -in cert.der -inform DER -text -noout
    

Nota: El uso de otro shell podría requerir comandos diferentes para descodificar el secreto en un archivo. En los ejecutores de Windows, se recomienda usar un shell de Bash con shell: bash para usar los comandos del paso run anterior.

Censura de secretos de registros de ejecución de flujo de trabajo

Aunque GitHub redacta automáticamente los secretos impresos en los registros de flujo de trabajo, los ejecutores solo pueden eliminar secretos a los que tienen acceso. Esto significa que un secreto solo se censurará si se usó dentro de un trabajo. Como medida de seguridad, puede eliminar los registros de ejecución de flujo de trabajo para evitar que se filtren valores confidenciales. Para obtener más información, vea «Uso de registros de ejecución de flujo de trabajo».