From f0bfb4f46f71919af6f6854b84f6423794a101fb Mon Sep 17 00:00:00 2001 From: jcotillo Date: Tue, 17 Nov 2026 14:09:41 -0500 Subject: [PATCH 1/2] docs: MIT license and a README an outside developer can start from [FACT-2004] Follows the public-releases-follow-the-crm-defaults decision: LICENSE copied from PracticalWorks/crm (MIT, Practical Works), a quick start at the top of the README, and License and Used by sections at the bottom. The job.workflow_sha example now names v1.3.0. No workflow changes, so no tag bump. Refs: FACT-2004 Co-Authored-By: Claude Opus 5.5 --- LICENSE | 21 +++++++++++++++++++++ README.md | 28 +++++++++++++++++++++++++--- 2 files changed, 46 insertions(+), 3 deletions(-) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..a0e1141 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Practical Works + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index b5c00bd..d21f1d8 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,29 @@ # Shared workflows -Reusable workflows for Practical Works repositories. A job that calls one runs in the caller, so its minutes and logs stay on the caller. Private source is not checked out into a run of this repository. +**Reusable GitHub Actions workflows for pnpm repositories: test, build a GHCR image, deploy to Coolify and wait until it is live, and guard a pull request body.** Call one with a single `uses:` line and pin a tag; a fix reaches every caller through a pin bump instead of one copied YAML file per repository. -Consumers pin a tag: +[![ci](https://github.com/PracticalWorks/.github/actions/workflows/ci.yml/badge.svg)](https://github.com/PracticalWorks/.github/actions/workflows/ci.yml) +[![MIT licence](https://img.shields.io/badge/licence-MIT-blue)](LICENSE) + +This repository also holds the Practical Works organization profile (`profile/README.md`). The workflows are what you can reuse. A job that calls one runs in the caller, so its minutes and logs stay on the caller. Private source is not checked out into a run of this repository. + +## Quick start + +In a pnpm repository with `lint` and `test` scripts, add `.github/workflows/ci.yml`: ```yaml +name: ci +on: [push, pull_request] + jobs: test: uses: PracticalWorks/.github/.github/workflows/test.yml@v1.3.0 ``` +That checks out the repository, installs pnpm and Node 22, runs `pnpm install --frozen-lockfile`, then `pnpm lint` and `pnpm test`. Override any of them with `with:` (for example `test: pnpm vitest run`, or `runner: '["self-hosted"]'`). The sections below cover the other workflows and their inputs. + +Always pin a tag, never `@main`. The tags so far: + ## Tags | Tag | Commit | What it adds | @@ -21,7 +35,7 @@ jobs: A release is a new tag on a commit of `main`. Existing tags are never moved or deleted, so a caller sees a change only when it bumps its pin. Do not pin `@main`. -`pr-guard.yml` and `coolify-deploy.yml` check out this repository's scripts at `job.workflow_sha`, the commit of the workflow file the caller invoked, so a caller pinned to `v1.2.0` runs `v1.2.0`'s scripts. If a runner leaves `job.workflow_sha` empty, they fall back to a tag written into the workflow file and say so with a warning. A release bumps that fallback to its own tag. +`pr-guard.yml` and `coolify-deploy.yml` check out this repository's scripts at `job.workflow_sha`, the commit of the workflow file the caller invoked, so a caller pinned to `v1.3.0` runs `v1.3.0`'s scripts. If a runner leaves `job.workflow_sha` empty, they fall back to a tag written into the workflow file and say so with a warning. A release bumps that fallback to its own tag. ## Workflows @@ -107,3 +121,11 @@ The webhook URL and the token are masked with `::add-mask::` before anything run `pr-guard.yml` fails a pull request whose body lacks `## Verification`, or a line `Refs: KEY-123` with an uppercase key, unless the caller turns that check off. `scan-secrets: true` fails the job when an added diff line matches a high-confidence credential shape. The log names the pattern, not the line. Every failure is printed to the log and also emitted as an `::error::` workflow command, so the reason shows as an annotation on the check even when a self-hosted runner loses the job log. The workflow sets up Node 22 itself, so it runs on self-hosted runners that ship without Node. + +## Used by + +[PracticalWorks/frontdesk](https://github.com/PracticalWorks/frontdesk), [PracticalWorks/crm](https://github.com/PracticalWorks/crm), [PracticalWorks/guardrails](https://github.com/PracticalWorks/guardrails), [PracticalWorks/rc-bridge](https://github.com/PracticalWorks/rc-bridge), [practical-works-acropolis/practical-works-factory](https://github.com/practical-works-acropolis/practical-works-factory). + +## License + +MIT, see [LICENSE](LICENSE). Made by [Practical Works](https://practical.works), a small software shop in Tampa Bay; questions and bug reports are welcome in [issues](https://github.com/PracticalWorks/.github/issues). From d07b7bbfcd763f229c08c1590e966a6b7b6e87a0 Mon Sep 17 00:00:00 2001 From: jcotillo Date: Tue, 17 Nov 2026 14:13:37 -0500 Subject: [PATCH 2/2] docs(readme): name only public repos; no internal runner label [FACT-2004] This repository is public. "Used by" linked PracticalWorks/frontdesk and practical-works-acropolis/practical-works-factory, both private, and the runner example used our internal `mini` label. "Used by" now names only the public packages that call these workflows (crm, guardrails, rc-bridge), and the example uses `["self-hosted","linux"]`. Refs: FACT-2004 Co-Authored-By: Claude Opus 5.5 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d21f1d8..b7abfc5 100644 --- a/README.md +++ b/README.md @@ -65,7 +65,7 @@ The setup action caches the pnpm store through `actions/setup-node` unless the c On macOS the setup action selects arm64 Node, so an Apple Silicon runner does not install an x64 build under Rosetta. Pass `node-architecture` to override it. -`runner` is a JSON array of labels, for example `'["ubuntu-latest"]'` or `'["self-hosted","mini"]'`. +`runner` is a JSON array of labels, for example `'["ubuntu-latest"]'` or `'["self-hosted","linux"]'`. ## Secrets @@ -124,7 +124,7 @@ Every failure is printed to the log and also emitted as an `::error::` workflow ## Used by -[PracticalWorks/frontdesk](https://github.com/PracticalWorks/frontdesk), [PracticalWorks/crm](https://github.com/PracticalWorks/crm), [PracticalWorks/guardrails](https://github.com/PracticalWorks/guardrails), [PracticalWorks/rc-bridge](https://github.com/PracticalWorks/rc-bridge), [practical-works-acropolis/practical-works-factory](https://github.com/practical-works-acropolis/practical-works-factory). +Our public packages build and release with these workflows: [PracticalWorks/crm](https://github.com/PracticalWorks/crm), [PracticalWorks/guardrails](https://github.com/PracticalWorks/guardrails) and [PracticalWorks/rc-bridge](https://github.com/PracticalWorks/rc-bridge). ## License