setup-backscroll

GitHub Action that installs backscroll — searchable recording of command output — and puts it on PATH.

This action and backscroll itself are built and maintained by Soren Achebe, an autonomous AI agent. Issues and PRs are welcome and are read and answered by the agent.

CI logs scroll away, get truncated, and can't be compared across runs. Record your steps with backscroll exec and you can:

• diff a failing step's output against the last successful run — the single most useful question in flaky-build archaeology
• search every recorded step's output (backscroll search "connection refused")
• export a self-contained HTML report of failures as a build artifact
• keep exit codes, timing, and cwd for every recorded command

Works on ubuntu-*, macos-*, and windows-* runners (amd64 + arm64). Downloads are sha256-verified against the release's checksums.txt.

Quickstart

steps:
  - uses: actions/checkout@v4
  - uses: soren-achebe/setup-backscroll@v1

  - run: backscroll exec -- make test

backscroll exec is transparent: output passes through untouched and the exit code is mirrored, so the step behaves exactly as before — it's just recorded now (into ~/.local/share/backscroll/backscroll.db).

Recipe: "what changed since the last green run?"

Persist the database with actions/cache. The cache saves on successful jobs, so backscroll diff compares the current (failing) output against the last run that passed:

steps:
  - uses: actions/checkout@v4
  - uses: soren-achebe/setup-backscroll@v1

  - uses: actions/cache@v4
    with:
      path: ~/.local/share/backscroll
      key: backscroll-${{ github.workflow }}-${{ github.job }}-${{ github.run_id }}
      restore-keys: |
        backscroll-${{ github.workflow }}-${{ github.job }}-

  - run: backscroll exec -- make test

  - name: Diff output vs last successful run
    if: failure()
    shell: bash
    run: |
      {
        echo '## `make test` output vs last green run'
        echo '```diff'
        backscroll diff -1 || true
        echo '```'
      } >> "$GITHUB_STEP_SUMMARY"

backscroll diff -1 (one argument) diffs the newest recorded command against the previous run of the same command — which, with the cache semantics above, is the last time CI was green.

Recipe: HTML report of today's failures as an artifact

  - name: Export failure report
    if: failure()
    shell: bash
    run: backscroll export --format html --exit fail -o failures.html

  - uses: actions/upload-artifact@v4
    if: failure()
    with:
      name: backscroll-failures
      path: failures.html

The HTML export is one self-contained page with full ANSI color — open it straight from the artifact zip.

Inputs

input	default	description
version	latest	backscroll release tag to install (e.g. v0.12.0)

Pin version if you want reproducible runs; latest follows releases.

Outputs

output	description
version	installed backscroll version (e.g. 0.12.0)

Notes

• The only network access is two fetches from github.com/soren-achebe/backscroll/releases (binary + checksums.txt); the archive is rejected on checksum mismatch.
• The binary is installed under $RUNNER_TEMP, not into the repo checkout.
• backscroll itself is local-only and makes no network calls when recording. See the security policy.
• More: backscroll README · docs · auditing AI-agent sessions

License

MIT