From f1b9d0ed77a3dbe1f34576118fd49e655876a8ae Mon Sep 17 00:00:00 2001 From: Kevin Deng Date: Thu, 21 May 2026 03:18:36 +0900 Subject: [PATCH] docs: explain actionspack workflow --- README.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/README.md b/README.md index 5f00697..77461ed 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,23 @@ It currently supports inlining composite actions and safely transformable reusable workflows. JavaScript and Docker actions are pinned as external dependencies instead of being bundled. +## Why actionspack? + +GitHub Actions workflows often depend on reusable workflows and actions from +other repositories. You may want to author those dependencies with convenient +floating refs like `@main` in `.github/workflows/src/`, but generated workflows +should be reproducible and reviewable. + +`actionspack` gives workflows a lockfile mechanism similar to `pnpm`. It locks +remote workflows and actions in `.github/workflow.lock.yml`, inlines everything +that can be transformed safely into the local repository, and pins anything that +cannot be inlined to a fixed SHA. + +To update workflow and action dependencies, run `actionspack update` +periodically. The updated lockfile and generated workflows are normal repository +files, so `git diff` shows exactly which dependencies changed and what generated +workflow output changed. + ## Install ```bash @@ -49,6 +66,16 @@ npx actionspack Generated workflows are safe to commit. Existing lockfile SHAs are reused until you explicitly run `actionspack update`. +When you want to refresh workflow/action dependencies: + +```bash +npx actionspack update +git diff +``` + +Review the dependency SHA changes in `.github/workflow.lock.yml` and the +resulting generated workflow changes before committing. + ## Commands ```bash -- 2.51.2