Nota: Los ejecutores hospedados en GitHub no son compatibles con GitHub Enterprise Server actualmente. Puedes encontrar más información sobre el soporte que se tiene planeado en el futuro en el Itinerario público de GitHub.
Acerca de los secretos cifrados
Los secretos son variables de ambiente cifradas que creas en una organización, repositorio o ambiente de repositorio. Los secretos que creas están disponibles para utilizarse en los flujos de trabajo de GitHub Actions. GitHub utiliza una caja sellada de libsodium para ayudarte a garantizar que los secretos se cifran antes de llegar a GitHub y que permanezcan cifrados hasta que los utilices 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 secretos solo contienen caracteres alfanuméricos (
[a-z]
,[A-Z]
,[0-9]
) o guiones bajos (_
). No se permiten espacios. -
Los nombres secretos no deben comenzar con el prefijo
GITHUB_
. -
Los nombres secretos no deben comenzar con un número.
-
Los nombres de secreto no distinguen entre mayúsculas y minúsculas.
-
Los nombres secretos 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, el que esté en el nivel más bajo tomará precedencia. 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 una 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, consulta "Sintaxis del flujo de trabajo paraGitHub Actions".
Puedes usar y leer secretos cifrados en un archivo de flujo de trabajo si tienes acceso para editar el archivo. Para obtener más información, consulta "Permisos de acceso en GitHub."
Advertencia: GitHub redacta automáticamente secretos impresos en el registro, pero debes evitar imprimir secretos en el registro intencionalmente.
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, consulta la sección "Secretos".
Limitar permisos de credenciales
Cuando generes credenciales, te recomendamos que otorgues los mínimos permisos posibles. Por ejemplo, en lugar de utilizar credenciales personales, utiliza llaves de despliegue 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. Cuando generes un token de acceso personal (PAT), selecciona el menor número de ámbitos necesarios.
Nota: Puedes utilizar la API de REST para administrar los secretos. Para obtener más información, consulta la sección " API de secretos de GitHub Actions".
Crear secretos cifrados para un repositorio
Para crear secretos para un repositorio de una cuenta personal, debes ser el propietario de dicho repositorio. Para crear secretos para un repositorio de una organización, deberás tener acceso de administrador
.
-
En tu instancia de GitHub Enterprise Server, visita la página principal del repositorio.
-
Debajo de tu nombre de repositorio, da clic en Configuración.
-
En la barra lateral izquierda, haz clic en Secrets (Secretos).
-
Da clic en Secreto de repositorio nuevo.
-
Teclea un nombre para tu secreto en el cuadro de entrada Name.
-
Ingresa el valor de tu secreto.
-
Haz clic en Agregar secreto (Agregar secreto).
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 aprender más sobre el CLI de GitHub, consulta la sección "Acerca del CLI de GitHub".
Para agregar un secreto de repositorio, utiliza el subcomando gh secret set
. Reemplaza a secret-name
con el nombre de tu 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 listar todos los secretos del repositorio, utiliza el subcomando gh secret list
.
Crear secretos cifrados para un ambiente
Para crear secretos para un ambiente en un repositorio de una cuenta personal, debes ser el propietario de dicho repositorio. Para crear secretos para un ambiente en el repositorio de una organización, deberás tener acceso de administrador
.
- En tu instancia de GitHub Enterprise Server, visita la página principal del repositorio.
- Debajo de tu nombre de repositorio, da clic en Configuración.
- En la barra lateral izquierda, da clic en Ambientes.
- Da clic en el ambiente al cual quieras agregar un secreto.
- Debajo de Secretos de ambiente, da clic en Agregar secreto.
- Teclea un nombre para tu secreto en el cuadro de entrada Name.
- Ingresa el valor de tu secreto.
- Haz clic en Agregar secreto (Agregar secreto).
Para agregar un secreto para un ambiente, utiliza el subcomando gh secret set
con el marcador --env
o -e
seguido del nombre del ambiente.
gh secret set --env environment-name secret-name
Para listar todos los secretos de un ambiente, utiliza el subcomando gh secret list
con el marcador --env
o -e
seguido del nombre de ambiente.
gh secret list --env environment-name
Crear secretos cifrados para una organización
Cuando creas un secreto en una organización, puedes utilizar una política para limitar el acceso de los repositorios a este. 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 a nivel organizacional, deberás tener acceso de administrador
.
- En tu instancia de GitHub Enterprise Server, navega hasta la página principal de la organización.
- Debajo del nombre de tu organización, da clic en Ajustes.
-
En la barra lateral izquierda, haz clic en Secrets (Secretos).
-
Da clic en Secreto de organización nuevo.
-
Teclea un nombre para tu secreto en el cuadro de entrada Name.
-
Ingresa el Valor para tu secreto.
-
Desde la lista desplegable Acceso de los repositorios, elige una política de acceso.
-
Haz clic en Agregar secreto (Agregar secreto).
Nota: Predeterminadamente, el CLI de GitHub se autentica con los alcances repo
y read:org
. Para administrar los secretos de la organización, debes autorizar el alcance admin:org
adicionalmente.
gh auth login --scopes "admin:org"
Para agregar un secreto para una organización, utiliza el subcomando gh secret set
con el marcador --org
o -o
seguido del nombre de la organización.
gh secret set --org organization-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 dentro de la organización, utiliza el marcador --visibility
o -v
.
gh secret set --org organization-name secret-name --visibility all
Para especificar que el secreto debe estar disponible para los repositorios seleccionados dentro de la organización, utiliza el marcador --repos
o -r
.
gh secret set --org organization-name secret-name --repos repo-name-1,repo-name-2"
Para listar todos los secretos para una organización, utiliza el subcomando gh secret list
con el marcador --org
o -o
seguido del nombre de la organización.
gh secret list --org organization-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.
- En tu instancia de GitHub Enterprise Server, navega hasta la página principal de la organización.
- Debajo del nombre de tu organización, da clic en Ajustes.
-
En la barra lateral izquierda, haz clic en Secrets (Secretos).
-
La lista de secretos incluye cualquier política y permiso configurado. Por ejemplo:
-
Para encontrar más detalles sobre los permisos configurados para cada secreto, da clic en Actualizar.
Usar secretos cifrados en un flujo de trabajo
Nota: Con la excepción de GITHUB_TOKEN
, los secretos no se pasan al ejecutador cuando un flujo de trabajo se dispara desde un repositorio bifurcado.
Para proporcionar una acción con un secreto como una variable de entrada o de entorno, puedes usar el contexto de secretos
para acceder a los secretos que has creado en tu repositorio. Para obtener más información, consulta las secciones de "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 }}
Los secretos no se pueden referenciar 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 la sección "Disponibilidad de contexto" y "jobs.<job_id>.steps[*].if
.
Si aún no se configura un secreto, el valor de retorno de una expresión que lo referencia (tal como ${{ secrets.SuperSecret }}
en el ejemplo) será una secuencia vacía.
Evita pasar secretos entre procesos desde la línea de comando, siempre que sea posible. Los procesos de línea de comandos podrían estar visibles para otros usuarios (utilizando el comando ps
) o ser capturados por los eventos de auditoría de seguridad. Para ayudar a proteger los secretos, considera 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 64 KB. Para almacenar los secretos más grandes, consulta la solución alternativa "Almacenar secretos grandes" debajo.
Storing large secrets
To use secrets that are larger than 64 KB, you can use a workaround to store encrypted secrets in your repository and save the decryption passphrase as a secret on GitHub. For example, you can use gpg
to encrypt a file containing your secret locally before checking the encrypted file in to your repository on GitHub. Para obtener más información, consulta la página del manual "gpg".
Warning: Be careful that your secrets do not get printed when your workflow runs. Cuando usas esta solución, GitHub no redacta los secretos que están impresos en los registros.
-
Run the following command from your terminal to encrypt the file containing your secret using
gpg
and the AES256 cipher algorithm. In this example,my_secret.json
is the file containing the secret.gpg --symmetric --cipher-algo AES256 my_secret.json
-
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.
-
Crear un nuevo secreto que contiene la frase de acceso. For example, create a new secret with the name
LARGE_SECRET_PASSPHRASE
and set the value of the secret to the passphrase you used in the step above. -
Copy your encrypted file to a path in your repository and commit it. En este ejemplo, el archivo cifrado es
my_secret.json.gpg
.Warning: Make sure to copy the encrypted
my_secret.json.gpg
file ending with the.gpg
file extension, and not the unencryptedmy_secret.json
file.git add my_secret.json.gpg git commit -m "Add new encrypted secret JSON file"
-
Create a shell script in your repository to decrypt the secret file. In this example, the script is named
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
-
Asegúrate de que tu shell script 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
-
In your GitHub Actions workflow, use a
step
to call the shell script and decrypt the secret. Para tener una copia de tu repositorio en el entorno en el que se ejecuta tu flujo de trabajo, deberás usar la accióncode>actions/checkout
. Haz referencia a tu shell script usando el comandorun
relacionado con la raíz de tu repositorio.name: Workflows with large secrets on: push jobs: my-job: name: My Job runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - 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 los límites de tamaño, consulta la sección de Límites para los secretos".
Nota: Toma en cuenta que Base64 solo convierte los binarios a texto y no es un sustituto de un cifrado real.
-
Utiliza
base64
para cifrar tu archivo en una secuencia Base64. Por ejemplo:$ base64 -i cert.der -o cert.base64
-
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
-
Para acceder a la secuencia de Base64 desde tu ejecutor, lleva 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@v2 - 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