CI/CD Integration

The public OSS CLI is useful in CI when you want generated files to become deterministic, portable evidence instead of a loose job workspace.

Basic CI pattern

Run a job that generates output files
Package that directory with npx filepacks pack
Verify the artifact with npx filepacks verify
Compare it against a known baseline artifact with npx filepacks compare
Upload the .fpk file as a job artifact for human review if needed

npx filepacks pack ./build-output --output ./candidate.fpk
npx filepacks verify ./candidate.fpk
npx filepacks compare ./baseline.fpk ./candidate.fpk

Why this works well in CI

the artifact is one file you can upload
verify confirms integrity before downstream use
compare gives deterministic exit codes for “same”, “changed”, and “failed”
reviewers can inspect the exact same artifact later

Exit handling

For the current public CLI:

verify exits 0 when the artifact is valid
verify exits 1 when the artifact is invalid
compare exits 0 when the artifacts are identical
compare exits 20 when files differ

That makes it easy to separate “artifact changed” from “command failed”.

Example: strict GitHub Actions gate

- name: Install filepacks
  run: npm install -g filepacks

- name: Package output
  run: filepacks pack ./build-output --output ./candidate.fpk

- name: Verify artifact
  run: filepacks verify ./candidate.fpk

- name: Compare against baseline
  run: filepacks compare ./baseline.fpk ./candidate.fpk

- name: Upload artifact for review
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: candidate
    path: candidate.fpk

If you want any structural difference to fail the job, this is enough.

Example: preserve artifact and fail only after capture

If you want to keep the candidate artifact even when the output changed, capture the exit code explicitly:

- name: Compare against baseline
  id: compare
  shell: bash
  run: |
    set +e
    npx filepacks compare ./baseline.fpk ./candidate.fpk
    status=$?
    set -e

    if [ "$status" -eq 1 ]; then
      exit 1
    fi

    echo "status=$status" >> "$GITHUB_OUTPUT"

- name: Upload candidate artifact
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: candidate
    path: candidate.fpk

- name: Fail when output changed
  if: steps.compare.outputs.status == '20'
  run: exit 1

This treats 20 as “review needed” instead of “tool failure”.

Agent and eval runner workflows

When an AI coding agent or eval runner produces output files, pack the output directory as an artifact immediately after the run:

# Pack agent output after the run completes
npx filepacks pack ./agent-output --output ./run-$(date +%s).fpk

# Or in an eval harness, pack each run by ID
npx filepacks pack ./eval-output --output ./eval-$RUN_ID.fpk

# Compare the new run against the last accepted run
npx filepacks compare ./eval-baseline.fpk ./eval-$RUN_ID.fpk

compare exits 0 if the output is structurally identical to the baseline and 20 if anything changed. Either exit code is usable in a script or CI job to decide whether to accept the run. Use @filepacks/core directly to build this into an eval harness:

import {pack, compare} from '@filepacks/core'

const run = await pack({input: outputDir, output: `eval-${runId}.fpk`})
const diff = await compare({baseline: 'eval-baseline.fpk', candidate: `eval-${runId}.fpk`})

if (!diff.ok) {
  console.log(`${diff.summary.changed} file(s) changed`)
  // diff.changed[] has per-file details
}

What to preserve

For the current OSS workflow, keep at least:

candidate.fpk
the baseline artifact used for comparison, if it is not already versioned elsewhere
the job log that captured the compare summary

Baseline management

The public OSS surface does not define a baseline registry or tag workflow. In CI, store the baseline artifact explicitly and compare against that file path. Common approaches:

commit a known-good .fpk to the repository and compare against it on each run
upload the accepted run’s .fpk as a named CI artifact and retrieve it in subsequent jobs

Good fit for CI

filepacks works well when you want:

reproducible build evidence
a reviewable snapshot of generated files
a stable baseline-versus-candidate comparison primitive
one artifact file that humans and automation can both inspect later

Getting started

CLI

Artifacts

Guides

Basic CI pattern

Why this works well in CI

Exit handling

Example: strict GitHub Actions gate

Example: preserve artifact and fail only after capture

Agent and eval runner workflows

What to preserve

Baseline management

Good fit for CI

​Basic CI pattern

​Why this works well in CI

​Exit handling

​Example: strict GitHub Actions gate

​Example: preserve artifact and fail only after capture

​Agent and eval runner workflows

​What to preserve

​Baseline management

​Good fit for CI

Basic CI pattern

Why this works well in CI

Exit handling

Example: strict GitHub Actions gate

Example: preserve artifact and fail only after capture

Agent and eval runner workflows

What to preserve

Baseline management

Good fit for CI