GitHub Actions: runs, workflows, cache, secrets, variables

Active contributors: Mislav, Andy Feller, Kynan, Sam Coe

Purpose

A cluster of commands targets GitHub Actions infrastructure:

• gh run - workflow run lifecycle (list, view, watch, rerun, cancel, delete, download artifacts).
• gh workflow - workflow definitions (list, view, run, enable, disable).
• gh cache - GitHub Actions cache entries.
• gh secret - Actions, Codespaces, and Dependabot secrets.
• gh variable - Actions and Dependabot variables.
• gh actions - top-level help index for the Actions group.

Directory layout

pkg/cmd/run/
  run.go               # NewCmdRun: subcommand registration
  list/  view/  watch/  rerun/  cancel/  delete/
  download/  shared/   # presenters, log streaming, artifact handling

pkg/cmd/workflow/
  workflow.go
  list/  view/  run/  enable/  disable/  shared/

pkg/cmd/cache/
  cache.go
  list/  delete/

pkg/cmd/secret/
  secret.go
  list/  set/  delete/  shared/   # entity (repo/org/env), encryption helpers

pkg/cmd/variable/
  variable.go
  list/  set/  delete/  get/  shared/

pkg/cmd/actions/  # gh actions: hidden help-only command

Key abstractions

Symbol	File	Role
NewCmdRun	pkg/cmd/run/run.go	Wires the run subcommands.
viewRun	pkg/cmd/run/view/view.go	Streams logs, renders job summary, paints status. The largest test file in the repo (view_test.go ~ 100 KB).
watchRun	pkg/cmd/run/watch/watch.go	Polls the API and re-renders until the run finishes.
presenter	pkg/cmd/run/shared/presenter.go	Status and timing rendering shared across subcommands.
download	pkg/cmd/run/download/download.go	Artifact discovery and zip extraction with safe-path checks.
secretEncrypt	pkg/cmd/secret/shared/	Resolves the public key for an org/repo/env and encrypts the secret value.
variableSet	pkg/cmd/variable/set/set.go	Variable upsert with entity-aware endpoints.

How it works

gh run watch <id>:

sequenceDiagram
    participant CLI
    participant API as GitHub REST API
    participant TTY

    loop until conclusion
        CLI->>API: GET /repos/.../actions/runs/{id}
        API-->>CLI: run + jobs
        CLI->>API: GET /repos/.../actions/runs/{id}/jobs
        API-->>CLI: jobs[]
        CLI->>TTY: clear & re-render presenter
        CLI->>CLI: sleep --interval (default 3s)
    end

The "live" rendering is implemented with terminal cursor control via pkg/iostreams (it does not pull in Bubble Tea here). For gh run view --log, the command uses internal/zip to walk the artifact archive that GitHub Actions returns.

gh secret set FOO --body=bar resolves the entity (--repo, --org, --env), fetches the corresponding NaCl public key, encrypts the value with golang.org/x/crypto/nacl/box, and PUTs the result. The same shape is reused for Codespaces and Dependabot secrets via the --app flag.

Integration points

• The smart repo resolver applies to run, workflow, and cache (registered against repoResolvingCmdFactory in root.go).
• Artifact download uses internal/safepaths/ to refuse zip-slip-style entries.
• Log rendering uses pkg/iostreams for color and pager handling.
• Many list commands speak to the REST API rather than GraphQL because Actions endpoints are REST-only.

Entry points for modification

• New gh run subcommand: add pkg/cmd/run/<name>/<name>.go and register in run.go.
• New artifact filter: edit download.go's matcher and update the table-driven test.
• New secret entity scope: extend the entity enum in secret/shared and add a route in the set/delete/list handlers.

Key source files

File	Purpose
pkg/cmd/run/view/view.go	Run view with logs and jobs.
pkg/cmd/run/watch/watch.go	Live-tailing watcher.
pkg/cmd/run/download/download.go	Artifact downloader.
pkg/cmd/workflow/run/run.go	Dispatch a workflow.
pkg/cmd/workflow/view/view.go	Workflow YAML view.
pkg/cmd/cache/list/list.go	Cache enumeration.
pkg/cmd/secret/set/set.go	Encrypt + upload a secret.
pkg/cmd/secret/shared/encrypt.go	NaCl box encryption helper.
pkg/cmd/variable/set/set.go	Variable upsert.
internal/safepaths/safepaths.go	Path-traversal-safe joining.
internal/zip/zip.go	Safe zip extraction.

Related pages

• API client for how REST endpoints are reached.
• Patterns and conventions for the Options + Factory shape these commands all use.