Skip to content
Back to skills

Record

DSecurity

Record deploys your OWN CI does — one `forge release record` step after the existing deploy job, in any repo and any language, no deploy/kcl, forge builds and applies nothing. Monitoring then gets deploy markers (`forge obs changes`), per-release verdicts (`forge obs check --wait`) and a Releases page labelled "recorded by CI". Copy-paste recipes for GitHub Actions (step and vendored composite action), GitLab CI and Buildkite. Use when a team keeps its pipeline and wants forge's release track...

  • 10 stars
  • 0 votes
  • 0 copies
  • 1 view
  • Added November 13, 2026
devopsgoshellbashgitapici/cd

Works with

  • cli
  • api

Security analysis

D59/100
  • criticalPipes output to a shell interpreter
  • mediumUses curl or wget to download content
  • criticalExfiltrates credentials via HTTP — exact pattern from Snyk ToxicSkills study
  • criticalDownloads and executes remote scripts — classic supply chain attack

Pro shows the line behind each finding and how to fix it

Scanned November 18, 2026

npx -y skills add reliant-labs/forge --skill record --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Record?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Record
[![Security: D — Skills Directory](https://www.skillsdirectory.com/api/skills/reliant-labs-record/badge)](https://www.skillsdirectory.com/skills/reliant-labs-record)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: deploy/record
description: Record deploys your OWN CI does — one `forge release record` step after the existing deploy job, in any repo and any language, no deploy/kcl, forge builds and applies nothing. Monitoring then gets deploy markers (`forge obs changes`), per-release verdicts (`forge obs check --wait`) and a Releases page labelled "recorded by CI". Copy-paste recipes for GitHub Actions (step and vendored composite action), GitLab CI and Buildkite. Use when a team keeps its pipeline and wants forge's release tracking or monitoring, or asks "can forge see my deploys?".
applies: any
---

# Record deploys from your existing CI

Your pipeline keeps deploying exactly as it does today. After its deploy step
succeeds, one more step tells forge what went out:

```bash
forge release record --env prod --version "$VERSION" \
  --workload api --image "ghcr.io/acme/api@$DIGEST"
forge obs check prod --release "$VERSION" --wait
```

That is the whole integration. forge builds nothing and applies nothing.

**What you get.**

- A **deploy marker** per deploy: `forge obs changes prod` lists it ("promoted
  v1.4.0 (recorded by CI)"), and dashboards and issues line up against it.
- A **verdict per release**: `forge obs check prod --release v1.4.0 --wait`
  compares the window after the deploy with the one before (exit 0 good, 1
  regressed, 2 not proven, 8 not enough data yet). Recorded releases are judged
  like forge-built ones: from telemetry, by `service.version`.
- A **Releases page** in the console —
  `https://forge.reliantlabs.io/forge/p/<project>/releases/<version>` — showing
  the commit, the run and each workload's digest, labelled "recorded by CI".
  The command prints the link.

**How easy.** Easy: ~15 minutes the first time, then nothing per deploy.

| Step | Time |
|---|---|
| Name the project and the workloads your pipeline deploys in the env's document, `deploy/envs/prod.yaml` (below; `forge obs init prod` writes its first lines). No forge.yaml needed; one with `name:` works too | 2 min |
| A token with `deploy:write`, minted by a person in the web app (Settings → API tokens, https://forge.reliantlabs.io/settings/tokens; no deploy/kcl needed), stored as the CI secret `FORGE_CONTROL_PLANE_TOKEN` | 5 min |
| Paste the recipe below after the deploy job | 5 min |
| Run the pipeline once; `forge obs changes prod` shows the marker | 4 min |

## Which project it is filed under

The project comes from the repo's forge files, by the same precedence `forge
obs init` uses:

1. `forge.yaml`'s `name:`, when there is one. An env document that names
   another project is refused: the env's telemetry carries the document's
   project, so a marker filed elsewhere would line up with no dashboard.
2. Else the `project:` of the env's own document, `deploy/envs/<env>.yaml`.
3. Else the one project every env document names.

A repo with none of these is refused with what to add. The command finds the
files by walking up from where it runs, as it finds forge.yaml, so a CI step
in a subdirectory works.

An env document that records deploys is the monitoring one plus the workloads
your pipeline deploys, each bound to the external runtime:

```yaml
# deploy/envs/prod.yaml
apiVersion: forge.dev/env/v1
project: shop
env: prod
control_plane: {}            # Reliant cloud; or {endpoint: "https://cp.example.com"}
observability:
  enabled: true
  destination: {token_from_control_plane: true}
workloads:
  - name: api
    runtime: {type: external}
  - name: worker
    kind: worker
    runtime: {type: external}
```

`forge obs init` writes everything above `workloads:`. Without the workloads,
the document says where telemetry goes but not who deploys the env, so a
record into it is refused (`record_only_release`) with a message naming the
file and the lines to add.

## What a record is

- **A record-only release.** `--version` labels it; `--commit` (default: the
  CI commit — `GITHUB_SHA`, `CI_COMMIT_SHA`, `BUILDKITE_COMMIT` — or git HEAD)
  says what it was built from. `--workload <name> --image <ref>@sha256:<hex>`
  pairs, in order, record the digest each workload runs; with none it is
  **version-only**, which is valid only because it is record-only. Images must
  be pinned by digest: a tag names whatever was pushed last, not what was
  deployed.
- **A promotion into the env**, with actor `ci` inside CI, and the CI run (id
  and URL detected for GitHub Actions, GitLab CI and Buildkite; `--url` for
  anything else). It records no plan, because nothing forge planned was
  applied.
- **Idempotent.** A retried step records once (`release_created` and
  `promoted` are false in `--json`). The same version with other digests — or,
  version-only, at another commit — is refused as a conflict, never an
  overwrite: a version names one release.
- **Never posing as forge's own deploy.** The control plane refuses to bind a record-only
  release to an env forge itself deploys (a hosted env, or one bound to a
  cluster forge reconciles): reason `record_only_release`. The command refuses
  an env that `deploy/kcl/<env>/main.k` or an env document declares the same
  way, before it cuts anything, on every ledger — unless every workload in it
  is bound to `forge.OnExternal` (in a document, `runtime: {type: external}`;
  `deploy/external`): your own tooling deploys that env, so recording what it
  shipped is the point. When forge takes
  over deploying an env, its own `forge env deploy` releases follow the
  recorded ones in the same history.

## Where it records

| Situation | Ledger |
|---|---|
| `deploy/kcl/<env>/main.k` or `deploy/envs/<env>.yaml` declares the env, and it has no workloads or some workload is not external (or it does not render) | none: refused (`record_only_release`), forge deploys that env or nothing shows who does |
| `deploy/kcl/<env>/main.k` or `deploy/envs/<env>.yaml` binds every workload to the external runtime | the control plane the env declares (`forge.ControlPlane`, a document's `control_plane:`), where it is **self-managed**; Reliant cloud when it declares none. Not signed in, or `FORGE_LEDGER=machine`: this machine, as below |
| signed in (`FORGE_CONTROL_PLANE_TOKEN`, `forge login`, a credential helper; or `--token`) | Reliant cloud. The env is created there as **self-managed** on first use |
| `FORGE_LEDGER=machine`, or not signed in | this machine's ledger. It works, but monitoring cannot see it; a note says so. `forge ledger import --from-file-ledger` moves it later |

Monitoring needs sign-in: a record on this machine is history, not a marker.

A control plane that predates record-only releases refuses a **version-only**
record with an upgrade hint, and accepts one with image digests as an ordinary
release, without the "recorded by CI" label. The machine ledger takes both.
Record digests whenever you have them: they are what ran.

## Recipes

Each one installs forge with the release installer (no Go toolchain), records,
then judges. Put them AFTER the step that deploys, so a failed deploy records
nothing.

### GitHub Actions — a step

```yaml
  record:
    needs: deploy                     # your existing deploy job
    runs-on: ubuntu-latest
    env:
      FORGE_CONTROL_PLANE_TOKEN: ${{ secrets.FORGE_CONTROL_PLANE_TOKEN }}
    steps:
      - uses: actions/checkout@v4     # for deploy/envs/prod.yaml (or forge.yaml's name)
      - name: Install forge
        run: |
          curl -fsSL https://raw.githubusercontent.com/reliant-labs/forge/main/install.sh | sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - name: Record the deploy
        run: |
          forge release record --env prod --version "${{ github.ref_name }}" \
            --workload api --image "ghcr.io/${{ github.repository }}/api@${{ needs.deploy.outputs.digest }}"
      - name: Judge it
        run: forge obs check prod --release "${{ github.ref_name }}" --wait
```

### GitHub Actions — a vendored composite action

forge's convention is a composite action VENDORED into your repository
(versioned with your repo, so a forge flag change cannot break a pipeline
pinned to a separately published action). Save as
`.github/actions/forge-record/action.yml`:

```yaml
name: forge release record + check
description: Record a deploy this pipeline did, then judge it with forge obs check.
inputs:
  env:       {description: Environment deployed to., required: true}
  version:   {description: Version label deployed., required: true}
  workloads: {description: "Space-separated name=ref@sha256:… pairs; empty for version-only.", required: false, default: ""}
  check:     {description: Run forge obs check --wait after recording., required: false, default: "true"}
  forge-version: {description: "Version of the forge CLI to install (default: latest).", required: false, default: ""}
runs:
  using: composite
  steps:
    - shell: bash
      env: {FORGE_VERSION: "${{ inputs.forge-version }}"}
      run: |
        curl -fsSL https://raw.githubusercontent.com/reliant-labs/forge/main/install.sh | sh
        echo "$HOME/.local/bin" >> "$GITHUB_PATH"
    - shell: bash
      env: {ENV: "${{ inputs.env }}", VERSION: "${{ inputs.version }}", WORKLOADS: "${{ inputs.workloads }}"}
      run: |
        set -euo pipefail
        args=()
        for pair in $WORKLOADS; do args+=(--workload "${pair%%=*}" --image "${pair#*=}"); done
        forge release record --env "$ENV" --version "$VERSION" "${args[@]}" --json > forge-record.json
        jq -r '"recorded \(.version) to \(.env): \(.console_url // .location)"' forge-record.json >> "$GITHUB_STEP_SUMMARY"
    - if: inputs.check == 'true'
      shell: bash
      run: forge obs check "${{ inputs.env }}" --release "${{ inputs.version }}" --wait
```

and use it:

```yaml
      - uses: ./.github/actions/forge-record
        env: {FORGE_CONTROL_PLANE_TOKEN: "${{ secrets.FORGE_CONTROL_PLANE_TOKEN }}"}
        with:
          env: prod
          version: ${{ github.ref_name }}
          workloads: api=ghcr.io/acme/api@${{ needs.deploy.outputs.digest }}
```

### GitLab CI

```yaml
record:
  stage: .post                        # after your deploy stage
  needs: [deploy]
  image: debian:stable-slim
  variables:
    FORGE_CONTROL_PLANE_TOKEN: $FORGE_CONTROL_PLANE_TOKEN   # masked CI/CD variable
  script:
    - apt-get update -qq && apt-get install -y -qq curl ca-certificates git >/dev/null
    - curl -fsSL https://raw.githubusercontent.com/reliant-labs/forge/main/install.sh | sh
    - export PATH="$HOME/.local/bin:$PATH"
    - forge release record --env prod --version "$CI_COMMIT_TAG" --workload api --image "$CI_REGISTRY_IMAGE/api@$API_DIGEST"
    - forge obs check prod --release "$CI_COMMIT_TAG" --wait
  rules:
    - if: $CI_COMMIT_TAG
```

The commit (`CI_COMMIT_SHA`) and the pipeline (`CI_PIPELINE_ID`,
`CI_PIPELINE_URL`) are detected.

### Buildkite

```yaml
steps:
  - label: ":rocket: deploy"
    key: deploy
    command: ./scripts/deploy.sh
  - label: ":memo: record"
    depends_on: deploy
    command: |
      curl -fsSL https://raw.githubusercontent.com/reliant-labs/forge/main/install.sh | sh
      export PATH="$$HOME/.local/bin:$$PATH"
      forge release record --env prod --version "$$BUILDKITE_TAG" \
        --workload api --image "$$(buildkite-agent meta-data get api-image)"
      forge obs check prod --release "$$BUILDKITE_TAG" --wait
```

Store the token as a pipeline secret named `FORGE_CONTROL_PLANE_TOKEN`. The
commit (`BUILDKITE_COMMIT`) and the build (`BUILDKITE_PIPELINE_SLUG`,
`BUILDKITE_BUILD_NUMBER`, `BUILDKITE_BUILD_URL`) are detected.

### Anything else

Run the two commands after the deploy. Pass `--commit` and `--url` when the CI
is not one of the three above; the `--url` then also identifies the run, so a
retry of the same run records once.

## Reading `obs check` in CI

Branch on its exit code, never on its text: **0** done; **1** the release
regressed — run the document's `suggested[]` commands and fix forward; **2** it
could not be proved good — report "not proven good", never "passed"; **8** not
enough data yet, or the control plane's query quota was spent
(`reason_code: quota_exhausted`) — check again later, after `retry_at` when the
document has one. Load `observability/query` for the document.

Make the judgement meaningful: set `service.version` in your telemetry to the
same value you pass as `--version` (the tag or the git SHA). Without it, the
verdict cannot tell the new release's traffic from the old.

## JSON

`--json` prints one object: `project`, `env`, `version`, `commit`, `workloads`
(name → ref@digest), `ledger` (`hosted` | `machine`), `location`,
`release_created`, `promoted`, `promotion_id`, `run_url`, `console_url`.

## Next

- Monitoring first, if it is not set up yet: `observability`.
- Hand the deploy to forge when you are ready: `deploy` (`forge env deploy`); the
  recorded history stays in the same ledger, and forge's own releases follow it.

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in devops →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.