Frecuentemente publicamos actualizaciones de nuestra documentación. Es posible que la traducción de esta página esté en curso. Para conocer la información más actual, visita la documentación en inglés. Si existe un problema con las traducciones en esta página, por favor infórmanos.

Crear y almacenar secretos cifrados

Los secretos cifrados te permiten almacenar información sensible en tu repositorio u organización.

GitHub Actions se encuentra disponible con GitHub Free, GitHub Pro, GitHub Free para organizaciones, GitHub Team, GitHub Enterprise Cloud, y GitHub One. GitHub Actions no está disponible para repositorios privados que pertenezcan a cuentas que utilicen planes tradicionales por repositorio. Para obtener más información, consulta la sección "Productos de GitHub".

En este artículo

Acerca de los secretos cifrados

Los secretos son variables de ambiente cifradas que creas en un repositorio u organización. Los secretos que crees se encuentran disponibles para su uso en los flujos de trabajo de GitHub Actions. GitHub utiliza una caja sellada de libsodium para ayudar a garantizar que los secretos se cifren antes de que lleguen a GitHub y que permanezcan cifrados hasta que los uses 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.

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 secretos deben ser únicos en el nivel en el que se hayan creado. Por ejemplo, un secreto que se crea a nivel de la organización debe tener un nombre único en ese nivel, y un secreto que se crea a nivel de un repositorio debe tener un nombre único en ese repositorio. Si un secreto a nivel de organización tiene el mismo nombre que uno a nivel de repositorio, entonces el que está a nivel del repositorio 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 la sección "Permisos de acceso en GitHub".

Advertencia: GitHub redacta automáticamente secretos impresos en el registro, pero debes evitar imprimir secretos en el registro intencionalmente.

También puedes administrar secretos utilizando la API de REST. Para obtener más información, consulta la sección "Secretos" en la documentación del programador 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, usa implementar claves 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.

Crear secretos cifrados para un repositorio

Para crear secretos para un repositorio de una cuenta de usuario, deberás ser el propietario de éste. Para crear secretos para un repositorio de una organización, deberás tener acceso de administrador.

  1. En GitHub, visita la página principal del repositorio.
  2. Debajo de tu nombre de repositorio, da clic en Configuración.
    Botón de configuración del repositorio
  3. En la barra lateral izquierda, haz clic en Secrets (Secretos).
  4. Haz clic en Agregar secreto nuevo.
  5. Teclea un nombre para tu secreto en el cuadro de entrada Name.
  6. Ingresa el valor de tu secreto.
  7. Haz clic en Add secret (Agregar secreto).

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

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.

  1. En GitHub, navega hasta la página principal de la organización.
  2. Debajo de tu nombre de organización, da clic en Configuración.
    Botón de configuración de organización
  3. En la barra lateral izquierda, haz clic en Secrets (Secretos).
  4. Da clic en Secreto nuevo.
  5. Teclea un nombre para tu secreto en el cuadro de entrada Name.
  6. Ingresa el Valor para tu secreto.
  7. Desde la lista desplegable Acceso de los repositorios, elige una política de acceso.
  8. Haz clic en Agregar secreto (Agregar secreto).

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 hasta la página principal de la organización.
  2. Debajo de tu nombre de organización, da clic en Configuración.
    Botón de configuración de organización
  3. En la barra lateral izquierda, haz clic en Secrets (Secretos).
  4. La lista de secretos incluye cualquier política y permiso configurado. Por ejemplo:
    Lista de secretos
  5. Para encontrar más detalles sobre los permisos configurados para cada secreto, da clic en Actualizar.

Usar secretos cifrados en un flujo de trabajo

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 variable de entrada o de entorno, puedes usar el contexto de secrets para acceder a los secretos que has creado en tu repositorio. Para obtener más información, consulta "Sintaxis de contexto y de expresiones para GitHub Actions 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 }}

Evita pasar secretos entre procesos desde la línea de comando, siempre que sea posible. Los procesos de la línea de comando pueden ser visibles para otros usuarios (utilizando el comando ps) o ser capturados por 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

Tu flujo de trabajo puede tener hasta 100 secretos. Los nombres de las variables de entorno secretas deben ser únicos en un repositorio.

Los secretos tienen un tamaño máximo de 64 KB. Para usar secretos de un tamaño mayor a 64 KB, puedes almacenar los secretos cifrados en tu repositorio y guardar la contraseña de descifrado como un secreto en GitHub. Por ejemplo, puedes usar gpg para cifrar tus credenciales de manera local antes de verificar el archivo en tu repositorio en GitHub. Para obtener más información, consulta la página del manual "gpg".

Advertencia: Ten la precaución de evitar que tus secretos se impriman cuando se ejecuta tu acción. Cuando usas esta solución, GitHub no redacta los secretos que están impresos en los registros.

  1. Ejecuta el siguiente comando en tu terminal para cifrar el archivo my_secret.json usando gpg y el algoritmo de cifras AES256.

    $ 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 nuevo secreto con el nombre LARGE_SECRET_PASSPHRASE y establece el valor del secreto para la contraseña que seleccionaste en el paso anterior.

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

  5. Crea un script shell para descifrar la contraseña. Guarda este archivo como 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 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
  7. En tu flujo de trabajo, usa un step para llamar al shell script y descifrar el secreto. Para tener una copia de tu repositorio en el entorno en el que se ejecuta tu flujo de trabajo, deberás usar la acción code>actions/checkout. Haz referencia a tu shell script usando el comando run 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: ./.github/scripts/decrypt_secret.sh
            env:
              LARGE_SECRET_PASSPHRASE: ${{ secrets.LARGE_SECRET_PASSPHRASE }}
          # Este comando es solo un ejemplo para mostrar cómo se imprime tu secreto.
          # Asegúrate de eliminar las declaraciones impresas de tus secretos. GitHub 
          # no oculta los secretos que usan esta solución.
          - name: Test printing your secret (Elimina este paso en la producción)
            run: cat $HOME/secrets/my_secret.json
    

Pregunta a una persona

¿No puedes encontrar lo que estás buscando?

Contáctanos