canopy - Moses Yebei

The Problem

Developers who need to test or validate GitHub Actions workflows locally often must spin up a full runner environment or rely on remote execution, adding latency and operational overhead. The repository provides a self‑contained Rust implementation that can parse, lint, plan, and execute actions on a developer machine, eliminating the need for a hosted runner for basic workflows.

What This Does

Canopy is split into a SDK of crates and a binary that composes them. The SDK crates live under crates/:

Crate	Responsibility
`gh-actions-spec`	Types for workflow and `action.yml` formats
`gh-actions-expr`	Lexer, parser, evaluator for `${{ }}` expressions
`gh-actions-context`	Contexts a run exposes (e.g., `github`, `runner`)
`gh-actions-plan`	Converts a workflow into a valid job graph
`gh-actions-lint`	Linting rules for workflows (`crates/gh-actions-lint/src/rules/`)
`gh-actions-runner`	Executes a planned job (`crates/gh-actions-runner/src/executor.rs`)
`gh-actions-services`	Artifact and cache services a job talks to
`gh-actions-listener`	Protocol a self‑hosted runner speaks: register, poll, acquire, report (`crates/gh-actions-listener/src/lib.rs`)

The binary canopy is built from crates/canopy/src/main.rs and wires these crates together. The examples/ directory shows two compositions: gh-runner-local pulls jobs from GitHub and runs them locally, while gh-runner-fargate-ondemand provisions an AWS Fargate task per job.

How It Is Wired

Execution starts at crates/canopy/src/main.rs, which parses the CLI and dispatches to the appropriate crate. A typical run flow:

Parse workflow – gh-actions-spec reads the YAML file.
Plan job graph – gh-actions-plan (crates/gh-actions-plan/src/lib.rs) topologically sorts jobs, resolves needs, and produces a validated job list.
Linter – gh-actions-lint checks for common problems (crates/gh-actions-lint/src/rules/) before execution.
Runner – gh-actions-runner (crates/gh-actions-runner/src/executor.rs) iterates the planned jobs, invoking the executor for each step. The executor (crates/gh-actions-runner/src/executor.rs) triggers actions, handles run commands, and manages I/O.
Services – gh-actions-services (crates/gh-actions-services/src/lib.rs) provides artifact upload and caching during job execution.
Listener – If the workflow is run via the self‑hosted runner protocol, gh-actions-listener (crates/gh-actions-listener/src/listener.rs) handles registration, polling, and report payloads.

The call graph is shallow: main → plan → runner → executor, with services and listener as side‑effects. The widest blast radius is in crates/gh-actions-runner/src/executor.rs, which touches the filesystem, spawns subprocesses, and interacts with the cache/artifact store.

How To Use It

Setup – The repo uses Cargo. To build the binary:

cargo build --release -p canopy

or install via cargo install --path crates/canopy if a published crate is available.

Configuration – No external keys are required for local runs. Environment variables that affect runner behavior are documented in crates/gh-actions-runner/src/ but are optional for basic workflow execution.

Running it – The README provides the exact commands (quoted verbatim):

canopy run .github/workflows/ci.yml          # run it here
canopy run ci.yml --job build -n            # plan what would run, and in what order
canopy lint ci.yml                           # lint the workflow
canopy lsp                                   # language server over stdio

These invoke crates/canopy/src/main.rs with the appropriate subcommand.

Real‑World Use

A team can drop canopy lint ci.yml into their pre‑commit hook to catch malformed expressions or missing needs dependencies before pushing. For CI‑free development, canopy run ci.yml --job test -n shows the planned job order without executing anything, letting developers reason about matrix expansions and job ordering locally.

Code Health & Issues

Static analysis of the repository reveals:

60 test files across tests/ and per‑crate test modules.
6 documentation files (README, LICENSE, etc.).
No structural red flags: CI workflows (.github/workflows/test.yml, release.yml, publish-extension.yml) are present, a Cargo.lock is committed, and a LICENSE file exists.
The test suite exercises the expression evaluator, planner validation, and runner execution paths.

Beyond the measured findings, the repo’s modular crate layout makes it straightforward to add new lint rules or extend the runner, but the listener crate’s protocol handling is tightly coupled to GitHub’s self‑hosted runner API, which may require upstream changes if the protocol evolves.

The Bottom Line

Canopy delivers a lightweight, Rust‑based runtime for GitHub Actions that can parse, lint, and locally execute workflows without a remote runner. The crate separation is clean, the test coverage is solid, and the binary commands are well‑documented. It is well‑suited for teams that need fast local feedback on workflow changes or want to prototype self‑hosted runner behavior. Organizations already invested in the GitHub Actions protocol will find the SDK useful for building custom tooling, while the binary provides an immediate “run here” experience.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

190 files

Rust94
YAML37
TOML21
TypeScript7
JSON6
Markdown5

ReactExpressDockerTerraform

Module dependencies

The 10 most depended-upon modules of 11, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_editors_vscode_src_run["run"] n1_editors_vscode_src_runs["runs"] n2_editors_vscode_src_extension["extension"] n3_code_src_test_suite_run_test["run.test"] n4_editors_vscode_esbuild["esbuild"] n5_tors_vscode_src_test_runTest["runTest"] n6_rc_test_suite_extension_test["extension.test"] n7__vscode_src_test_suite_index["index"] n8_sts_actions_greet_node_index["index"] n9_ests_actions_greet_node_post["post"] n2_editors_vscode_src_extension --> n1_editors_vscode_src_runs n1_editors_vscode_src_runs --> n0_editors_vscode_src_run n3_code_src_test_suite_run_test --> n0_editors_vscode_src_run

Dependencies

29 declared dependencies, none a major version behind. Resolved 0 of 29 against the registry.

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high1

medium7

low2

Pin third-party GitHub Actions to a commit SHAhigh4 occurrences

.github/workflows

dtolnay/rust-toolchain@stable, Swatinem/rust-cache@v2, softprops/action-gh-release@v2, taiki-e/install-action@just

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Declare least-privilege permissions for GITHUB_TOKENmedium2 occurrences

.github/workflows/publish-extension.yml

2 workflow(s) declare no permissions, 1 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

15 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Install from the lockfile in CImedium

.github/workflows

npm install with a committed package-lock.json

A fresh resolution in CI means the tested dependency set is not the locked one, so the failure only appears after merge.

Fix: Use npm ci, yarn install --immutable, or pnpm install --frozen-lockfile.

Pin the container base image by digestmedium2 occurrences

examples/job-runner/Dockerfile

rust:1-bookworm, catthehacker/ubuntu:act-latest

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/release.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

examples/job-runner/Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Set timeout-minutes on the workflow jobslow3 occurrences

.github/workflows/publish-extension.yml

3 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.