Machine & CI access

On a laptop, envless login caches an API token at ~/.envless/config.json, and envless passphrase set caches the derived workspace key in that same file. CI runners, Docker builds, and production hosts have neither, so they configure Envless entirely through environment variables. This page is the complete keystone for that non-interactive path.

The two roles#

Every non-interactive setup needs to answer two separate questions, and they use two separate credentials:

Every variable at a glance#

Where each credential comes from#

Selecting project and environment#

The token identifies the workspace, but you still have to say which project and environment to pull. Envless resolves each field in this order:

1. The --product / --project / --env flag (CLI only).
2. The ENVLESS_PRODUCT / ENVLESS_PROJECT / ENVLESS_ENV environment variables.
3. The committed .envless file at the project root.

They all take a slug (e.g. billing-api, production). In CI, set them explicitly rather than relying on the file. That's unambiguous and survives a checkout that omits .envless.

export ENVLESS_PROJECT=billing-api
export ENVLESS_ENV=production

What actually happens on the runner#

GitHub Actions#

Store ENVLESS_TOKEN and ENVLESS_KEY as repository or environment secrets, then choose the consumption mode that fits the step.

sync and run are commands of the envless binary, which ships in @goenvless/cli. A runner starts with nothing installed, so every job that calls them needs an install step first. The /register mode calls no binary at all: it needs @goenvless/env in your package.json, which npm ci restores like any other dependency.

The examples install the CLI globally. To pin its version in your lockfile instead, add @goenvless/cli to devDependencies and call it as npx envless sync. npx resolves the binary from node_modules/.bin, which only holds it when the package is a dependency of the project.

name: deploy
jobs:
    deploy:
        runs-on: ubuntu-latest
        env:
            ENVLESS_TOKEN: ${{ secrets.ENVLESS_TOKEN }}
            ENVLESS_KEY: ${{ secrets.ENVLESS_KEY }}
            ENVLESS_PROJECT: billing-api
            ENVLESS_ENV: production
        steps:
            - uses: actions/checkout@v4
            - uses: actions/setup-node@v4
            - run: npm ci
            # puts the envless binary on PATH for the steps below
            - run: npm i -g @goenvless/cli@latest
            # writes .env.production, decrypted, mode 0600
            - run: envless sync
            - run: npm run deploy

name: test
jobs:
    test:
        runs-on: ubuntu-latest
        env:
            ENVLESS_TOKEN: ${{ secrets.ENVLESS_TOKEN }}
            ENVLESS_KEY: ${{ secrets.ENVLESS_KEY }}
            ENVLESS_PROJECT: billing-api
            ENVLESS_ENV: test
        steps:
            - uses: actions/checkout@v4
            - uses: actions/setup-node@v4
            - run: npm ci
            - run: npm i -g @goenvless/cli@latest
            # injects decrypted vars into the test process only, nothing on disk
            - run: envless run -- npm test

name: build
jobs:
    build:
        runs-on: ubuntu-latest
        env:
            ENVLESS_TOKEN: ${{ secrets.ENVLESS_TOKEN }}
            ENVLESS_KEY: ${{ secrets.ENVLESS_KEY }}
            ENVLESS_PROJECT: billing-api
            ENVLESS_ENV: production
        steps:
            - uses: actions/checkout@v4
            - uses: actions/setup-node@v4
            # @goenvless/env is a project dependency, so this installs it
            - run: npm ci
            # /register preloads + decrypts before your entrypoint runs
            - run: node --import @goenvless/env/register build.js

Docker#

Mount the token and key as build secrets so they never land in an image layer, then run the container with the @goenvless/env/register hook.

FROM node:20-slim AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
ENV ENVLESS_PROJECT=billing-api ENVLESS_ENV=production
# NODE_OPTIONS carries the preload into the build script, so it starts with the
# variables already loaded. Without it the secrets below are mounted for nothing.
RUN --mount=type=secret,id=envless_token \
    --mount=type=secret,id=envless_key \
    ENVLESS_TOKEN=$(cat /run/secrets/envless_token) \
    ENVLESS_KEY=$(cat /run/secrets/envless_key) \
    NODE_OPTIONS='--import @goenvless/env/register' \
    npm run build

FROM node:20-slim
WORKDIR /app
COPY --from=build /app .
# ENVLESS_TOKEN + ENVLESS_KEY provided at runtime by the platform
ENV ENVLESS_PROJECT=billing-api ENVLESS_ENV=production
CMD ["node", "--import", "@goenvless/env/register", "server.js"]

docker build \
    --secret id=envless_token,env=ENVLESS_TOKEN \
    --secret id=envless_key,env=ENVLESS_KEY \
    -t myapp .

For the running container (Fly.io, Railway, Render, ECS, Kubernetes), set ENVLESS_TOKEN and ENVLESS_KEY as platform secrets and ENVLESS_PROJECT / ENVLESS_ENV as plain env vars. The /register loader fetches and decrypts at boot.

Rotation#

Because the token and key are independent, rotate whichever leaked without disturbing the other:

• Token compromised → rotate it on the Keys page, which mints a fresh ev_sk_ and stops the old one authenticating, then update the CI secret. It only ever saw ciphertext, so no plaintext value leaked, but assume everything its scopes allowed it to write was reachable.
• Key/passphrase compromised → rotate the workspace passphrase from Settings → Encryption in the dashboard. That decrypts every variable in the workspace and re-encrypts it under the new passphrase, so the leaked key opens nothing afterwards. Re-export a fresh ENVLESS_KEY from the CI / Machine Access page and update every runner.