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.

Secretos cifrados

Los secretos cifrados te permiten almacenar información sensible en tu organización, repositorio o ambientes de repositorio.

Acerca de los secretos cifrados

Los secretos son variables cifradas que creas 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 usa una sealed box de libsodium para garantizar que los secretos se cifren antes de llegar a GitHub y permanezcan cifrados hasta que los use 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, vea "Acerca del fortalecimiento de la 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, consulte "Sintaxis de flujo de trabajo para GitHub Actions".

Puedes usar y leer secretos cifrados en un archivo de flujo de trabajo si tienes acceso para editar el archivo. Para más información, vea "Permisos de acceso en GitHub".

Advertencia: GitHub censura automáticamente los secretos impresos en el registro, pero debe evitar imprimirlos en el registro de manera intencionada.

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, consulte Secretos.

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 mínimo al repositorio necesario.

Nota: Puede usar la API de REST para administrar secretos. Para más información, vea "API de secretos de GitHub Actions".

Crear secretos cifrados para un repositorio

Para crear secretos o variables para un repositorio de una cuenta personal, el repositorio debe ser de tu propiedad. Para crear secretos o variables para un repositorio de una organización, debes tener acceso a admin.

  1. En GitHub.com, navega a la página principal del repositorio. 1. Debajo del nombre del repositorio, haz clic en Configuración. Botón de configuración del repositorio 1. En la sección "Seguridad" de la barra lateral, selecciona Secretos y variables, then click Acciones. 1. Haz clic en la pestaña Secretos. Pestaña Secretos de repositorio
  2. Haga clic en New repository secret.
  3. Escriba un nombre para su secreto en el cuadro de entrada Name.
  4. Ingresa el valor de tu secreto.
  5. 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 obtener más información sobre GitHub CLI, vea "Acerca de GitHub CLI".

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

  1. En GitHub.com, navega a la página principal del repositorio. 1. Debajo del nombre del repositorio, haz clic en Configuración. Botón de configuración del repositorio 1. En la barra lateral de la izquierda, haz clic en Entornos.
  2. Da clic en el ambiente al cual quieras agregar un secreto.
  3. En Environment secrets, haga clic en Add secret.
  4. Escriba un nombre para su secreto en el cuadro de entrada Name.
  5. Ingresa el valor de tu secreto.
  6. 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 cifrados 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.

Para crear secretos o variables en el nivel de organización, debes tener acceso de admin.

  1. En GitHub.com, ve a la página principal de la organización. 1. Debajo del nombre de la organización, haga clic en Settings. Botón de configuración de la organización 1. En la sección "Seguridad" de la barra lateral, selecciona Secretos y variables, then click Acciones. 1. Haz clic en la pestaña Secretos. Pestaña secretos de organización
  2. Haga clic en New organization secret.
  3. Escriba un nombre para su secreto en el cuadro de entrada Name.
  4. Introduzca el valor del secreto en Value.
  5. En la lista desplegable Repository access (Acceso al repositorio), elija una directiva de acceso.
  6. 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. 1. Debajo del nombre de la organización, haga clic en Settings. Botón de configuración de la organización 1. En la sección "Seguridad" de la barra lateral, selecciona Secretos y variables, then click Acciones.
  2. La lista de secretos incluye cualquier política y permiso configurado. Por ejemplo: Lista de secretos
  3. Para obtener más información sobre los permisos configurados para cada secreto, haga clic en Update.

Uso de secretos cifrados 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.

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, consulte "Contextos" y "Sintaxis de flujo de trabajo para GitHub Actions".

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, consulte "Disponibilidad de 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, puedes usar una solución alternativa consistente en almacenar los secretos cifrados en tu 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 encrypted 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.

    #!/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@v3
          - 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, consulte "Límites para los secretos".

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:

    $ base64 -i cert.der -o 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@v3
          - 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