Skip to main content

v2.6 integration guide for downstream orun users

This guide describes how downstream repositories that consume orun (as a CLI in CI/CD or as a library dependency) should adopt the v2.6 release.

Who this is for​

Teams that:

  • Run orun as part of a GitHub Actions workflow or other CI/CD pipeline.
  • Vendor orun as a library dependency from another Go project.
  • Ship orun as part of a developer toolchain (dev containers, internal CLIs, docs sites).

What changed in v2.6​

  • New orun tui interactive cockpit.
  • New GitHub Actions artifact integration for plan and job shards.
  • New orun github runs / pull / status / logs commands for inspecting remote runs without actions/download-artifact.
  • No breaking CLI flags or library surface changes.

Pick up orun tui​

Install the new CLI on developer machines:

go install github.com/sourceplane/orun/cmd/orun@v2.6.0
orun tui

The cockpit is read-only against .orun/ — it generates plans, dry-runs, and inspects state, but it doesn't write anything CI cares about. You can safely:

  • Add orun tui to a dev container image.
  • Document it in onboarding without changing CI.
  • Run it against a hydrated .orun/ produced by orun github pull.

No workflow changes are required.

Pick up GitHub Artifacts​

For teams running orun inside GitHub Actions, opt in via environment variables in the workflow:

env:
  ORUN_ARTIFACT_BACKEND: github
  ORUN_ARTIFACT_UPLOAD: "true"

With those set, orun plan and orun run upload immutable plan / job shards using the embedded @actions/artifact helper. No additional actions/upload-artifact step is needed.

To inspect or hydrate from a local machine:

orun github pull --latest
orun github status --branch main
orun github logs --failed

Token requirements​

Local commands need one of:

  • GITHUB_TOKEN env var
  • GH_TOKEN env var
  • gh auth token (authenticated gh CLI)

Private repositories require the Actions: read fine-grained permission. The token is never logged or persisted.

See GitHub Artifacts architecture for the full pipeline.

Updated commands​

CommandOne-line
orun github runsList workflow runs and their artifact shards.
orun github pullDownload all shards and hydrate into .orun/executions/.
orun github statusQuick remote status via artifact name parsing.
orun github logsDownload specific job shard logs.

API / library changes​

Orun's public surface is anything outside internal/. v2.6 added:

  • internal/artifactstore/github/ — not public.
  • internal/tui/* — not public.

Library consumers see no surface change in v2.6. Vendoring upgrades are safe.

Migration checklist​

  1. Bump orun to v2.6.0 in CI installer scripts.
  2. (Optional) Enable artifact upload by setting ORUN_ARTIFACT_BACKEND=github and ORUN_ARTIFACT_UPLOAD=true.
  3. (Optional) Wire orun tui into your dev container or contributor docs.
  4. Re-run baseline CI to confirm no regressions.
  5. Consult the release notes for any pin updates and review downstream consumers.

Troubleshooting​

  • Artifact upload silently skipped. Verify ACTIONS_RUNTIME_TOKEN is present in the job environment — uploads gate on it and no-op when absent.
  • TUI rendering glitches. The inspector auto-opens at ≥100 columns; below that, toggle it manually with i. Resize the terminal or collapse the inspector if the main pane looks cramped.
  • Plan Studio shows (no plan). Press g to generate a plan first — Plan Studio doesn't auto-generate on entry.

References​