Uso de secretos con GitHub Actions

Tabla de contenidos

Un secreto de compilación es información confidencial, como una contraseña o un token de API, que se consume como parte del proceso de compilación. Docker Build admite dos formas de secretos:

Los montajes de secretos añaden secretos como archivos en el contenedor de compilación (bajo /run/secrets por defecto).
Los montajes SSH añaden sockets del agente SSH o claves en el contenedor de compilación.

Esta página muestra cómo usar secretos con GitHub Actions. Para una introducción a los secretos en general, consulta Secretos de compilación.

Montajes de secretos

El siguiente ejemplo utiliza y expone el secreto GITHUB_TOKEN proporcionado por GitHub en tu flujo de trabajo.

Primero, crea un Dockerfile que utilice el secreto:

# syntax=docker/dockerfile:1
FROM alpine
RUN --mount=type=secret,id=github_token,env=GITHUB_TOKEN ...

En este ejemplo, el nombre del secreto es github_token. El siguiente flujo de trabajo expone este secreto utilizando la entrada secrets:

name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Configurar QEMU
        uses: docker/setup-qemu-action@v4

      - name: Configurar Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Compilar
        uses: docker/build-push-action@v7
        with:
          platforms: linux/amd64,linux/arm64
          tags: user/app:latest
          secrets: |
            "github_token=${{ secrets.GITHUB_TOKEN }}"

Note
Los secretos se montan como archivos en el contenedor de compilación. Por defecto, están disponibles en /run/secrets/<id>. También puedes usar la opción env para cargar un secreto en una variable de entorno, o la opción target para personalizar la ruta de montaje. Para obtener más detalles sobre los montajes de secretos, consulta Secretos de compilación.

La entrada secret-files te permite montar archivos existentes como secretos en tu compilación. Esto es útil cuando necesitas usar archivos de credenciales generados durante tu flujo de trabajo, o cuando necesitas montar archivos de configuración como .npmrc o .pypirc que ya están en el formato esperado.

La diferencia clave entre secrets y secret-files:

secrets: Pasa valores de secreto como cadenas de texto (desde variables de entorno o secretos de GitHub)
secret-files: Monta archivos existentes desde el sistema de archivos del runner

Ejemplo: Uso de .npmrc para paquetes npm privados

Si tu compilación necesita instalar paquetes desde un registro npm privado, puedes crear un archivo .npmrc y montarlo como un secreto:

name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Clonar repositorio
        uses: actions/checkout@v6

      - name: Configurar Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Crear archivo .npmrc
        run: |
          echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > .npmrc

      - name: Compilar
        uses: docker/build-push-action@v7
        with:
          context: .
          secret-files: |
            npmrc=./.npmrc
          tags: user/app:latest

En tu Dockerfile, monta el archivo de secreto en la ubicación esperada:

# syntax=docker/dockerfile:1
FROM node:20-alpine

WORKDIR /app

COPY package*.json ./

RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
    npm ci

COPY . .

RUN npm run build

Ejemplo: Uso de credenciales generadas dinámicamente

Puedes generar archivos de credenciales a partir de múltiples secretos y montarlos:

name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Clonar repositorio
        uses: actions/checkout@v6

      - name: Configurar Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Crear archivo de credenciales
        run: |
          cat <<EOF > aws-credentials
          [default]
          aws_access_key_id = ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws_secret_access_key = ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          EOF

      - name: Compilar
        uses: docker/build-push-action@v7
        with:
          context: .
          secret-files: |
            aws=./aws-credentials
          tags: user/app:latest

En tu Dockerfile:

# syntax=docker/dockerfile:1
FROM alpine

RUN apk add --no-cache aws-cli

RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
    aws s3 cp s3://my-private-bucket/data.tar.gz /tmp/

Secretos multilínea

Si estás utilizando secretos de GitHub y necesitas manejar un valor multilínea, tendrás que colocar el par clave-valor entre comillas:

secrets: |
  "MYSECRET=${{ secrets.GPG_KEY }}"
  GIT_AUTH_TOKEN=abcdefghi,jklmno=0123456789
  "MYSECRET=aaaaaaaa
  bbbbbbb
  ccccccccc"
  FOO=bar
  "EMPTYLINE=aaaa

  bbbb
  ccc"
  "JSON_SECRET={""key1"":""value1"",""key2"":""value2""}"

Clave	Valor
`MYSECRET`	`***********************`
`GIT_AUTH_TOKEN`	`abcdefghi,jklmno=0123456789`
`MYSECRET`	`aaaaaaaa\nbbbbbbb\nccccccccc`
`FOO`	`bar`
`EMPTYLINE`	`aaaa\n\nbbbb\nccc`
`JSON_SECRET`	`{"key1":"value1","key2":"value2"}`

Note
Se necesitan dobles escapes para las comillas.

Montajes SSH

Los montajes SSH te permiten autenticarte con servidores SSH. Por ejemplo, para realizar un git clone, o para obtener paquetes de aplicaciones desde un repositorio privado.

El siguiente ejemplo de Dockerfile utiliza un montaje SSH para obtener módulos de Go desde un repositorio privado de GitHub.

# syntax=docker/dockerfile:1

ARG GO_VERSION="1.25"

FROM golang:${GO_VERSION}-alpine AS base
ENV CGO_ENABLED=0
ENV GOPRIVATE="github.com/foo/*"
RUN apk add --no-cache file git rsync openssh-client
RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan github.com >> ~/.ssh/known_hosts
WORKDIR /src

FROM base AS vendor
# este paso configura git y verifica que la clave ssh esté cargada
RUN --mount=type=ssh <<EOT
  set -e
  echo "Configurando el protocolo SSH de Git"
  git config --global url."[email protected]:".insteadOf "https://github.com/"
  (
    set +e
    ssh -T [email protected]
    if [ ! "$?" = "1" ]; then
      echo "No se ha cargado ninguna clave SSH de GitHub, saliendo..."
      exit 1
    fi
  )
EOT
# este descarga los módulos de go
RUN --mount=type=bind,target=. \
    --mount=type=cache,target=/go/pkg/mod \
    --mount=type=ssh \
    go mod download -x

FROM vendor AS build
RUN --mount=type=bind,target=. \
    --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache \
    go build ...

Para compilar este Dockerfile, debes especificar un montaje SSH que el constructor pueda usar en los pasos con --mount=type=ssh.

El siguiente flujo de trabajo de GitHub Action utiliza la acción de terceros MrSquaare/ssh-setup-action para inicializar la configuración de SSH en el runner de GitHub. La acción crea una clave privada definida por el secreto de GitHub Action SSH_GITHUB_PPK y la añade al archivo socket del agente SSH en SSH_AUTH_SOCK. El montaje SSH en el paso de compilación asume SSH_AUTH_SOCK por defecto, por lo que no es necesario especificar el ID o la ruta para el socket del agente SSH explícitamente.

name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Configurar SSH
        uses: MrSquaare/ssh-setup-action@2d028b70b5e397cf8314c6eaea229a6c3e34977a # v3.1.0
        with:
          host: github.com
          private-key: ${{ secrets.SSH_GITHUB_PPK }}
          private-key-name: github-ppk

      - name: Compilar y enviar
        uses: docker/build-push-action@v7
        with:
          ssh: default
          push: true
          tags: user/app:latest

name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Configurar SSH
        uses: MrSquaare/ssh-setup-action@2d028b70b5e397cf8314c6eaea229a6c3e34977a # v3.1.0
        with:
          host: github.com
          private-key: ${{ secrets.SSH_GITHUB_PPK }}
          private-key-name: github-ppk

      - name: Compilar
        uses: docker/bake-action@v7
        with:
          set: |
            *.ssh=default

¿En qué te puedo ayudar?

Uso de secretos con GitHub Actions

Montajes de secretos

Uso de archivos de secretos

Ejemplo: Uso de .npmrc para paquetes npm privados

Ejemplo: Uso de credenciales generadas dinámicamente

Secretos multilínea

Montajes SSH