Uso de secretos en Acciones de GitHub

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.

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 más información, consulta 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 más información, consulta Permisos de acceso en GitHub.

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 más información, consulta 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), seleccione los ámbitos más mínimos necesarios. Al generar un fine-grained personal access token, seleccione los permisos mínimos y el acceso al repositorio necesarios.

En lugar de usar un personal access token, considere la posibilidad de usar un 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 más información, consulta Realización de solicitudes de API autenticadas con una aplicación de GitHub en un flujo de trabajo de Acciones de GitHub.

Creación de secretos para un repositorio

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

gh secret set SECRET_NAME

gh secret set SECRET_NAME < secret.txt

Crear secretos para un ambiente

Para crear secretos o variables para un entorno en el repositorio de una cuenta personal, debe ser el propietario del repositorio. A fin de crear secretos o variables para un entorno en el repositorio de una organización, debe tener acceso de admin. Para obtener más información sobre los entornos, consulta "Administrar entornos para la implementación".

gh secret set --env ENV_NAME SECRET_NAME

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 a nivel de organización.

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

gh auth login --scopes "admin:org"

gh secret set --org ORG_NAME SECRET_NAME

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

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

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, navega a la página principal de tu 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.

   

3. En la sección "Seguridad" de la barra lateral, seleccione Secretos y variables y haga 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

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 más información, consulta Acceso a información contextual sobre ejecuciones de flujo de trabajo 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 Acceso a información contextual sobre ejecuciones de flujo de trabajo 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, consulta la página man de gpg.

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.

   Warning

   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.

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
   

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

GitHub Actions redacta automáticamente el contenido de todos los secretos de GitHub que se imprimen en los registros de flujo de trabajo.

GitHub Actions también censura la información que se reconoce como confidencial, pero no se almacena como secreto. Actualmente GitHub admite lo siguiente:

• Claves de Azure de 32 bytes y 64 bytes
• Contraseñas de aplicación cliente de Azure AD
• Claves de Azure Cache
• Claves de Azure Container Registry
• Claves de host de Azure Functions
• Claves de Azure Search
• Cadenas de conexión de base de datos
• Encabezados de token de portador HTTP
• JWT
• Tokens de creación de NPM
• Claves de API de NuGet
• Tokens de instalación de GitHub v1
• Tokens de instalación de GitHub v2 (ghp, gho, ghu, ghs, ghr)
• PAT de GitHub v2

Como hábito del procedimiento recomendado, debe enmascarar toda la información confidencial que no sea un secreto de GitHub mediante ::add-mask::VALUE. Esto hace que el valor se trate como un secreto y se redacte de los registros. Para más información sobre el enmascaramiento de datos, consulta Comandos de flujo de trabajo para Acciones de GitHub.

Los ejecutores de flujo de trabajo realizan la redacción de secretos. Esto significa que un secreto solo se censurará si se usó dentro de un trabajo y es accesible para el ejecutor. Si se envía un secreto no aprobado a un registro de ejecución de flujo de trabajo, debe eliminar el registro y rotar el secreto. Para obtener información sobre cómo eliminar registros, consulta Uso de registros de ejecución de flujo de trabajo.