Forem: Darius Hermes

GitLab CI deploy failed because one token was never documented

Darius Hermes — Sun, 24 May 2026 16:32:43 +0000

A common GitLab CI failure is not that the deploy script is wrong.

It is that the pipeline expects a variable nobody documented.

Example:

stages:
  - deploy

deploy_production:
  stage: deploy
  image: alpine:3.20
  script:
    - test -n "$DEPLOY_TOKEN"
    - echo "Deploying $NEXT_PUBLIC_APP_URL"
    - ./scripts/deploy.sh --token "$DEPLOY_TOKEN"

And the repo contract says only this:

NEXT_PUBLIC_APP_URL=

DEPLOY_TOKEN exists as an assumption in the pipeline, but not in .env.example or .env.dist.

That means a reviewer can approve the pipeline change without realizing that someone still needs to configure a GitLab CI/CD Variable before deploy.

Why this is deployment drift

The actual secret value belongs in GitLab CI/CD Variables.

The variable name belongs in the repo's environment contract.

When those drift apart, the failure usually appears late:

a merge request updates .gitlab-ci.yml;
the deploy job references $DEPLOY_TOKEN;
the env template does not mention it;
the pipeline reaches deploy time and fails with missing configuration.

This is especially easy to miss when an AI coding agent or quick cleanup PR changes CI YAML and the review focuses on application code.

A small review habit that catches it

When a merge request changes .gitlab-ci.yml, deploy scripts, or Docker commands, scan for new env references:

$VARIABLE
${VARIABLE}
process.env.VARIABLE
deploy CLI flags such as --token "$DEPLOY_TOKEN"

Then check whether the variable name is present in the env contract:

NEXT_PUBLIC_APP_URL=
DEPLOY_TOKEN=

The template should not contain the real value. It only documents that the variable is required.

Automated check

With Secret Coverage, the local check looks like this:

pnpm dlx @leviro-ai/secret-coverage scan --path . --ci

For a pnpm script wrapper inside the repo:

pnpm scan -- --path . --ci

The useful finding is the variable name and location, not the secret value:

DEPLOY_TOKEN is referenced in .gitlab-ci.yml but missing from the env template.

That is the point: metadata-only deployment readiness, before CI or production discovers the missing contract.

Safe fix

Add DEPLOY_TOKEN= to .env.example or .env.dist.
Configure the real value in GitLab CI/CD Variables.
Re-run the scan.
Keep the check in the merge request or CI path so future pipeline edits do not silently add new assumptions.

PR checklist

For any GitLab pipeline change, ask:

Did this MR add a new $VARIABLE reference?
Is the variable name documented in .env.example or .env.dist?
Is the real value configured in GitLab CI/CD Variables before merge?
Should the check fail the MR with --ci if a required deployment variable is missing?

It is a small habit, but it prevents the frustrating class of deploys that fail because the repo and CI environment stopped agreeing.

Secret Coverage is a local-first, metadata-only environment/deployment readiness scanner: it checks variable names and config references, not raw secret values.

Repo/package: @leviro-ai/secret-coverage

How I review AI-generated PRs for missing environment variables

Darius Hermes — Sat, 23 May 2026 10:32:00 +0000

AI-assisted PRs often change application code, deployment config, and CI at the same time.

That is useful, but it creates a boring failure mode that is easy to miss in review:

the PR starts using a new environment variable, but .env.example or .env.dist is not updated.

No raw secret values need to be leaked for this to break a deploy. The problem is metadata drift: the repo now depends on a variable that the declared environment contract does not mention.

Here is the review flow I use for that kind of PR.

Scenario

An AI agent opens a PR that looks reasonable:

adds a Stripe-backed checkout deploy step to GitHub Actions;
adds a Redis-backed worker in Docker Compose;
updates runtime code paths;
forgets to update .env.example.

The diff might pass normal code review because each individual change looks small.

1. Start with the env contract

The template file is the contract future contributors and reviewers see:

NEXT_PUBLIC_APP_URL=https://example.com
DATABASE_URL=

This says the project expects NEXT_PUBLIC_APP_URL and DATABASE_URL.

It does not say anything about Stripe or Redis.

2. Check CI and deployment config, not only source code

The workflow now references a new secret:

env:
  DATABASE_URL: ${{ secrets.DATABASE_URL }}
  STRIPE_SECRET_KEY: ${{ secrets.STRIPE_SECRET_KEY }}

Docker Compose also expects Redis:

services:
  web:
    environment:
      DATABASE_URL: ${DATABASE_URL}
      REDIS_URL: ${REDIS_URL}

  worker:
    environment:
      REDIS_URL: ${REDIS_URL}

Both changes are normal. The bug is that STRIPE_SECRET_KEY and REDIS_URL became required deployment inputs without being added to the env template.

3. Run a metadata-only drift check

In the Secret Coverage repo, these fixtures model the two review findings:

pnpm scan -- --path examples/demos/github-actions-missing-secret --ci
pnpm scan -- --path examples/demos/docker-compose-missing-redis-url --ci

For a consumer repo using the published package:

pnpm dlx @leviro-ai/secret-coverage scan --path . --ci

The check compares variable names referenced by CI/CD, Docker, and config files with variable names declared in env templates. It does not need production secret values.

4. Read the findings like review comments

GitHub Actions drift:

## Critical

- **STRIPE_SECRET_KEY** — STRIPE_SECRET_KEY is used in .github/workflows/deploy.yml but missing from an env template.
  - Context: `.github/workflows/deploy.yml` · `missing-from-template`
  - Fix: Add STRIPE_SECRET_KEY= to an env template and configure the value in your deployment environment.

Docker Compose drift:

## Critical

- **REDIS_URL** — REDIS_URL is used in docker-compose.yml but missing from an env template.
  - Context: `docker-compose.yml` · `missing-from-template`
  - Fix: Add REDIS_URL= to an env template and configure the value in your deployment environment.

That is a useful PR-review signal because it points to the missing contract update, not to a vague deployment risk.

5. Ask for the smallest safe fix

The fix is usually a tiny template update:

NEXT_PUBLIC_APP_URL=https://example.com
DATABASE_URL=
STRIPE_SECRET_KEY=
REDIS_URL=

The real values still belong in the deployment platform:

GitHub Actions secrets for CI/CD secrets;
Docker or Compose runtime environment for service variables;
Vercel, CircleCI, or another platform's environment settings where relevant.

Do not put raw secret values into .env.example, docs, screenshots, or review comments.

6. Add the check before merge

A small CI check can fail the PR before the deploy job discovers the mismatch:

name: secret-coverage

on:
  pull_request:
  push:
    branches: [main]

jobs:
  env-contract:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 20
      - run: pnpm dlx @leviro-ai/secret-coverage scan --path . --ci

PR review checklist

Use this when an AI-assisted PR touches deployment config, CI, Docker, workers, or framework runtime config:

Did the PR add a new process.env.NAME, ${NAME}, ${{ secrets.NAME }}, or CI env reference?
Is every new required variable declared in .env.example, .env.dist, or the chosen template file?
Are demo/docs outputs metadata-only, without raw secret values?
Does the CI check run before deploy?
Does the finding tell the contributor which template entry to add?

Secret Coverage is the local-first tool I am using for this check. It is deterministic, metadata-only, and does not need a cloud account.

Links:

GitHub: https://github.com/leviro-ai/secret-coverage
npm: https://www.npmjs.com/package/@leviro-ai/secret-coverage
AI-agent PR walkthrough: https://github.com/leviro-ai/secret-coverage/blob/main/docs/articles/ai-agent-pr-env-review-walkthrough.md
GitHub Actions demo: https://github.com/leviro-ai/secret-coverage/tree/main/examples/demos/github-actions-missing-secret
Docker Compose demo: https://github.com/leviro-ai/secret-coverage/tree/main/examples/demos/docker-compose-missing-redis-url

Two tiny deployment drift bugs: env vars added, templates forgotten

Darius Hermes — Sat, 23 May 2026 02:49:42 +0000

A small deployment failure pattern I keep seeing:

A config file starts using a new environment variable or secret.
The repo's .env.example or .env.dist is not updated.
The mismatch is discovered later, usually during a deploy job, local preview, worker boot, or production config check.

The bug is rarely dramatic in code review. It can be as small as one extra variable in CI/CD or Docker config.

Example 1: GitHub Actions secret drift

A workflow starts using a new secret:

env:
  DATABASE_URL: ${{ secrets.DATABASE_URL }}
  STRIPE_SECRET_KEY: ${{ secrets.STRIPE_SECRET_KEY }}

But the env template only documents this:

NEXT_PUBLIC_APP_URL=https://example.com
DATABASE_URL=

Now STRIPE_SECRET_KEY has become an undocumented deployment requirement.

Run the demo fixture with Secret Coverage:

pnpm dlx @leviro-ai/secret-coverage scan --path examples/demos/github-actions-missing-secret --ci

In the repo itself, the equivalent dev command is:

pnpm scan -- --path examples/demos/github-actions-missing-secret --ci

Expected output:

# Secret Coverage Report

Readiness score: **73/100**

Critical: 1 · Warning: 0 · Info: 1

## Critical

- **STRIPE_SECRET_KEY** — STRIPE_SECRET_KEY is used in .github/workflows/deploy.yml but missing from an env template.
  - Context: `.github/workflows/deploy.yml` · `missing-from-template`
  - Fix: Add STRIPE_SECRET_KEY= to an env template and configure the value in your deployment environment.

Example 2: Docker Compose runtime drift

The same thing can happen outside CI. A Compose file starts expecting Redis:

services:
  web:
    environment:
      APP_ENV: ${APP_ENV}
      DATABASE_URL: ${DATABASE_URL}
      REDIS_URL: ${REDIS_URL}

  worker:
    environment:
      REDIS_URL: ${REDIS_URL}

But .env.example only documents:

APP_ENV=production
DATABASE_URL=

Now both the web service and worker depend on REDIS_URL, but the repository contract does not say so.

Run the demo fixture:

pnpm dlx @leviro-ai/secret-coverage scan --path examples/demos/docker-compose-missing-redis-url --ci

Expected output:

# Secret Coverage Report

Readiness score: **71/100**

Critical: 1 · Warning: 0 · Info: 2

## Critical

- **REDIS_URL** — REDIS_URL is used in docker-compose.yml but missing from an env template.
  - Context: `docker-compose.yml` · `missing-from-template`
  - Fix: Add REDIS_URL= to an env template and configure the value in your deployment environment.

That is deployment drift: deployment/runtime config expects something the repository's declared env contract does not describe.

The point is not to read or expose secret values. The check only compares metadata:

variables documented by env templates;
variables referenced by CI/CD, Docker, and config files;
mismatches that should be fixed before deployment.

A minimal fix is to update the env template:

# GitHub Actions example
NEXT_PUBLIC_APP_URL=https://example.com
DATABASE_URL=
STRIPE_SECRET_KEY=

# Docker Compose example
APP_ENV=production
DATABASE_URL=
REDIS_URL=

Then configure the real values in GitHub Actions secrets, Docker/Compose runtime environment, or the deployment platform.

This is especially useful when AI-assisted PRs update application code and config quickly, because env contracts are easy to forget during review.

Secret Coverage is local-first and deterministic. It is not a vault and it does not need a cloud account for this check.

Links:

npm: https://www.npmjs.com/package/@leviro-ai/secret-coverage
GitHub: https://github.com/leviro-ai/secret-coverage
GitHub Actions demo: https://github.com/leviro-ai/secret-coverage/tree/main/examples/demos/github-actions-missing-secret
Docker Compose demo: https://github.com/leviro-ai/secret-coverage/tree/main/examples/demos/docker-compose-missing-redis-url