Skip to main content

orun github

orun github inspects GitHub Actions artifact shards and workflow runs — no actions/download-artifact step required.

Prerequisites​

Requires one of:

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

The repository is resolved from GITHUB_REPOSITORY or inferred from the origin git remote.

Commands​

CommandPurpose
orun github runsList workflow runs and their artifact shards
orun github pullDownload all shards and hydrate into the object model
orun github statusQuick remote status via artifact name parsing
orun github logsDownload specific job shard logs

orun github runs​

List workflow runs with artifact shard counts. Three levels of detail:

LevelWhat happensSpeed
1 (default)List runs + parse exec-id, role, status from artifact namesFast
2 (--details)Download plan shard manifests for exact statusMedium
3 (orun github pull)Full shard download + hydrateSlowest
orun github runs
orun github runs --branch main --failed
orun github runs --sha 0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b --details --limit 5

Flags:

FlagDefaultMeaning
--workfloworun.yamlWorkflow filename filter
--branchBranch filter
--shaCommit SHA filter
--failedfalseShow only failed runs
--limit10Max runs to show
--detailsfalseDownload manifests for accurate status

orun github pull​

Download all Orun artifact shards from a GitHub Actions workflow run, synthesize the execution, and import it into the local object model (it prints imported … into the object graph). Once hydrated, existing orun status, orun logs, and orun describe can inspect the execution offline.

# Pull the latest run for the current branch
orun github pull --latest

# Pull by execution ID
orun github pull --exec-id gh-26185145757-1-a1b2c3d4

# Pull the latest failed run
orun github pull --failed

# Include raw (unredacted) logs
orun github pull --failed --include-raw

# Pull to a custom .orun directory
orun github pull --latest --orun-dir /tmp/my-orun

Flags:

FlagDefaultMeaning
--run-id0Explicit GitHub run ID
--exec-idExecution ID (gh-<run>-<attempt>-<sha>)
--shaPull latest run for this SHA
--branchPull latest run for this branch
--latestfalsePull the latest run
--failedfalsePull the latest failed run
--include-rawfalseInclude unredacted logs
--orun-dir.Target working directory. A .orun/ subdirectory is created/used inside it (e.g. --orun-dir /tmp/foo writes to /tmp/foo/.orun/). For back-compat, a path that already ends in .orun is also accepted as-is.

SHA note: --sha is forwarded to the GitHub API, which expects the full 40-char commit SHA. Short SHAs (abc123) return "no runs found". Use git rev-parse HEAD to expand.

Resolution order (when no explicit --run-id is given):

  1. --exec-id: parse gh-{run_id}-{attempt}-{sha}, fetch that run
  2. --sha: list runs for the full SHA, pick the latest
  3. --branch: latest run on that branch
  4. --failed: latest run with conclusion=failure
  5. --latest / default: latest run for the current branch

orun github status​

Lightweight remote status: lists artifact shards grouped by execution ID without downloading full shard contents. Accepts the same resolution flags as pull / logs.

orun github status                                   # latest run on current branch
orun github status --latest --branch main
orun github status --exec-id gh-26606158847-1-896da6b09c29
orun github status --run-id 26606158847

Flags: --run-id, --exec-id, --sha (full SHA), --branch, --latest, --failed — same semantics as orun github pull.

orun github logs​

Download specific job artifact shard logs from a workflow run.

# Logs from the latest run
orun github logs --latest

# Logs for a specific execution and job
orun github logs --exec-id gh-26185145757-1-a1b2c3d4 --job my-job-id

# Logs from the latest failed run
orun github logs --failed

Flags:

FlagDefaultMeaning
--run-id0Explicit GitHub run ID
--exec-idExecution ID (gh-<run>-<attempt>-<sha>)
--shaLatest run for this SHA
--branchLatest run for this branch
--failedfalseLatest failed run
--latestfalseLatest run
--jobJob ID to fetch logs for

--job matching: Currently a substring match against the GitHub artifact name (e.g. --job job_896da6b or --job api-edge-worker), not a structured component/env/job lookup. Use orun github runs --details to discover available shard names.

Artifact naming​

All Orun artifacts use the naming convention:

orun.v1.<exec-id>.<role>.<suffix>.<status>

Examples:

orun.v1.gh-26185145757-1-a1b2c3d4.plan.a1b2c3d4.created
orun.v1.gh-26185145757-1-a1b2c3d4.job.7f6a9c21d4e8b012.failed

Components:

  • orun.v1 — fixed prefix and version
  • gh-{run_id}-{attempt}-{sha} — execution ID
  • plan or job — shard role
  • {suffix} — plan short SHA or job UID
  • {status} — created, completed, failed, cancelled, etc.

Partial hydration​

When some job shards are missing (cancelled run, in-progress execution), orun github pull produces status: "partial" rather than failing. Missing shards appear as "pending" in the synthesized state.

Security​

  • Default hydration includes only redacted logs. Use --include-raw for trusted users.
  • The GitHub token is never logged or persisted.
  • Artifact ZIP extraction includes path traversal defense.
  • Private repo pull requires Actions: read fine-grained token permission.

See also​