Docker Build Secrets

Some Docker builds need private credentials — NPM tokens for private registries, API keys for fetching assets, SSH keys for private dependencies. Ryvn’s build action makes these available to your Dockerfile through BUILD_SECRETS. This guide walks through configuring build secrets end-to-end: declaring them in your service YAML, passing them through your GitHub workflow, and consuming them in your Dockerfile.

How it works

Your service YAML declares which build args it needs using ${VAR} references. The build action resolves these from environment variables set by BUILD_SECRETS, then passes them to Docker.

Step 1: reference secrets in your service YAML

Declare the secrets your build needs as build.args with ${VAR} syntax. The build action uses envsubst to resolve these from environment variables at build time:

kind: Service
metadata:
  name: api
spec:
  type: server
  repo: acme/api
  build:
    context: .
    dockerfile: Dockerfile
    args:
      NPM_TOKEN: ${NPM_TOKEN}
      SOME_ACCESS_TOKEN: ${SOME_ACCESS_TOKEN}

You can mix literal values and variable references:

    args:
      NODE_ENV: production           # literal — always this value
      NPM_TOKEN: ${NPM_TOKEN}       # resolved from BUILD_SECRETS at build time

Step 2: add secrets to GitHub and pass them in your workflow

The BUILD_SECRETS workflow secret accepts KEY=VALUE pairs, one per line. There are two ways to set this up:

Individual secrets (recommended)
Single combined secret

Add each secret individually to your GitHub repository’s Actions secrets (e.g. NPM_TOKEN, SOME_ACCESS_TOKEN), then compose them into BUILD_SECRETS in your workflow:

jobs:
  release:
    uses: ryvn-technologies/ryvn-build-action/.github/workflows/release.yml@v2
    with:
      service_name: api
    secrets:
      RYVN_CLIENT_ID: ${{ secrets.RYVN_CLIENT_ID }}
      RYVN_CLIENT_SECRET: ${{ secrets.RYVN_CLIENT_SECRET }}
      BUILD_SECRETS: |
        NPM_TOKEN=${{ secrets.NPM_TOKEN }}
        SOME_ACCESS_TOKEN=${{ secrets.SOME_ACCESS_TOKEN }}

This gives you granular control — you can rotate or revoke each secret independently.

Create a single GitHub Actions secret called BUILD_SECRETS containing all your build credentials as KEY=VALUE pairs:

NPM_TOKEN=npm_abc123
SOME_ACCESS_TOKEN=ghp_xyz789

Then pass it directly:

jobs:
  release:
    uses: ryvn-technologies/ryvn-build-action/.github/workflows/release.yml@v2
    with:
      service_name: api
    secrets:
      RYVN_CLIENT_ID: ${{ secrets.RYVN_CLIENT_ID }}
      RYVN_CLIENT_SECRET: ${{ secrets.RYVN_CLIENT_SECRET }}
      BUILD_SECRETS: ${{ secrets.BUILD_SECRETS }}

This is simpler to set up but means updating the entire secret when any single value changes.

The build action sets each KEY=VALUE pair as an environment variable, then envsubst resolves the ${VAR} references in your service’s build.args.

Step 3: use secrets in your Dockerfile

Secret mounts (recommended)
ARG

BuildKit secret mounts make credentials available as files during a RUN step without writing them to image layers. This is the recommended approach for any sensitive value.

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

WORKDIR /app
COPY package.json yarn.lock ./

RUN --mount=type=secret,id=NPM_TOKEN \
    NPM_TOKEN=$(cat /run/secrets/NPM_TOKEN) \
    yarn install --frozen-lockfile

COPY . .
RUN yarn build

CMD ["yarn", "start"]

The # syntax=docker/dockerfile:1 directive on the first line is required for BuildKit secret mounts to work.

Mount multiple secrets by chaining --mount flags:

RUN --mount=type=secret,id=NPM_TOKEN \
    --mount=type=secret,id=SOME_ACCESS_TOKEN \
    NPM_TOKEN=$(cat /run/secrets/NPM_TOKEN) \
    SOME_ACCESS_TOKEN=$(cat /run/secrets/SOME_ACCESS_TOKEN) \
    yarn install --frozen-lockfile

Docker ARG is the simplest way to consume build secrets, but values are stored in image layer metadata and can be extracted with docker history --no-trunc.

FROM node:20-alpine

ARG NPM_TOKEN
ARG SOME_ACCESS_TOKEN

WORKDIR /app
COPY package.json yarn.lock ./
RUN yarn install --frozen-lockfile
COPY . .
RUN yarn build

CMD ["yarn", "start"]

Anyone with access to the image can extract ARG values from the layer metadata. Use secret mounts instead for credentials you wouldn’t want exposed.

Common issues

Secret file is empty or missing during build

Make sure the secret name in --mount=type=secret,id=NPM_TOKEN matches the key name in your BUILD_SECRETS exactly (case-sensitive). Also verify that your service YAML’s build.args has a matching ${NPM_TOKEN} reference.

RUN --mount=type=secret is not supported

Your Dockerfile is missing the # syntax=docker/dockerfile:1 directive on the first line. This directive must be the very first line — before any comments or FROM instructions.

Secret works locally but not in CI

Verify your GitHub Actions secrets are set correctly and that the key names in BUILD_SECRETS match the ${VAR} references in your service YAML’s build.args. Check for typos, extra whitespace, or quotes around values.

Build.args values showing up in docker history

Any value passed as --build-arg is baked into image layers. To prevent this, switch your Dockerfile to use --mount=type=secret instead of ARG. See the Secret mounts tab for an example.

Workflows

Constraints

Compute

Reference

Docker Build Secrets

How it works

Step 1: reference secrets in your service YAML

Step 2: add secrets to GitHub and pass them in your workflow

Step 3: use secrets in your Dockerfile

Common issues

Workflows

Constraints

Compute

Reference

Documentation Index

​How it works

​Step 1: reference secrets in your service YAML

​Step 2: add secrets to GitHub and pass them in your workflow

​Step 3: use secrets in your Dockerfile

​Common issues

How it works

Step 1: reference secrets in your service YAML

Step 2: add secrets to GitHub and pass them in your workflow

Step 3: use secrets in your Dockerfile

Common issues