Skip to content

Docs: guidance on composite actions vs reusable workflows (+ env-test harness proposal) #29

Open

Description

@mmcky

Summary

Add contributor-facing guidance on when to use a composite action vs a reusable workflow, so new CI lands at the right altitude across the lecture repos — prompted by a discussion about automated testing of the lecture anaconda environment.

Nothing covers this today: no reusable workflow exists here (workflow_call appears in no file), and neither docs/, CONTRIBUTING.md nor README.md mentions the choice. PLAN.md:81 (backlog item 11) tracks it; CONTRIBUTING.md:98 ("Action Development Guidelines") is the cheapest home — a section there, not a new file, per the docs-trim direction in PLAN.md:80.

Comparison

  • Unit of reuse — a sequence of steps called at step level (steps: - uses:) vs a whole job (or jobs) called at job level (jobs.x.uses:).
  • Runtime — the caller's job/runner, sharing its filesystem & env, vs its own job on its own runner.
  • Job-level config — a composite inherits the caller's runs-on and owns no strategy.matrix/services/permissions/environment, taking secrets as plain inputs; a workflow owns all of those, has first-class secrets: (inherit), and the caller can matrix over it.
  • Shape — a composite slots freely between your steps, can call other actions, and many independently versioned ones live per repo in subfolders (a monorepo of actions); a workflow is all-or-nothing (no step mid-job), one per file under .github/workflows/, nesting up to 4 levels.

Default rule: composite action for a reusable piece of a job — a step sequence the caller composes with its own steps (setup-environment, build-lectures); reusable workflow for a reusable whole job/pipeline each repo calls in a few lines via workflow_call. Layer them: workflow for the job shape + matrix/secrets/schedule, composite(s) for the steps it runs.

Worked example — environment test harness

The motivating harness is already built, so it's an example, not a deliverable: .github/workflows/test-actions.yml:432 and :462 run the cold→warm conda-cache chain plus a build-lectures on the restored env on every relevant PR — the first automated tests of the action logic, shipped in v0.10.0 (#114), and why backlog item 9 is struck done at PLAN.md:79. The canary repo QuantEcon/test-actions-lecture-intro exercises the real @v0 chain weekly.

Layering point: the composite (setup-environment) is the unit under test and gives parity with production builds; the rest is inexpressible in a composite — runs-on, the needs: chain handing the cold run's saved cache to the warm run, the relevance gate that lets a skipped job still report success to a required check (:75), and the canary's weekly schedule:.

Unbuilt from the sketch: the python/CUDA matrix and upstream-breakage schedule — test-actions.yml has neither a matrix nor a cron. That belongs as a scheduled matrix on the existing canary, so it goes with #100's coverage gaps rather than staying open here. (#135 covers gating a release on a green canary.)

A python-version matrix over setup-environment would not test two pythons: it only seeds setup-miniconda (setup-environment/action.yml:119) and salts the cache key (:134); the env comes from conda env update -n <environment-name> -f <environment> --prune (:145), so the environment file's python pin wins — fixture .github/fixtures/mini-lectures/environment.yml:5 is python=3.13, and the lecture repos pin the same way. A real env matrix must generate the environment file per leg.

Next steps


Context: the consuming side — the manual documenting quantecon/actions as the target deploy architecture — is QuantEcon/QuantEcon.manual#88.

🤖 Issue drafted with Claude Code

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationRepo docs and contributor meta

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions