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 .orun/executions/
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 hydrate into the local .orun/executions/ layout. 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. See improvements doc.

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​