@taraxvoid/voidflow 0.8.1 → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +68 -27
- package/package.json +23 -1
package/README.md
CHANGED
|
@@ -1,10 +1,22 @@
|
|
|
1
1
|
# voidflow
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Shared CI and deploy pipeline for a small fleet of Astro sites on Cloudflare Workers. One set of reusable GitHub Actions workflows and composite actions keeps lint, type checks, license policy, Playwright and axe-core accessibility tests, Unlighthouse budgets, and deploys identical across every site.
|
|
4
|
+
|
|
5
|
+
- **SHA-pinned.** Every third-party action in this repo is pinned to a full commit SHA with a version comment.
|
|
6
|
+
- **Audited.** Workflows are checked with [zizmor](https://github.com/zizmorcore/zizmor), [actionlint](https://github.com/rhysd/actionlint), check-jsonschema and shellcheck on every change (see [Self-validation](#self-validation)).
|
|
7
|
+
- **In production.** It runs the pipelines for the sites listed under [Used by](#used-by), including the marketing site for [RavenFlight Industries, LLC](https://rvnflt.com/github).
|
|
8
|
+
|
|
9
|
+
It is semi-opinionated: the defaults match how my own sites are built (bun, Astro, Playwright).
|
|
10
|
+
|
|
11
|
+
## Used by
|
|
12
|
+
|
|
13
|
+
- [taraxvoid.net](https://taraxvoid.net), my portfolio
|
|
14
|
+
- [Queer Omaha](https://queeromaha.net), [Synth Omaha](https://synthomaha.net) and [Soundry](https://soundryomaha.net), free community sites for Omaha's queer and music scenes
|
|
15
|
+
- [ravenflight.io](https://ravenflight.io), RavenFlight's marketing site
|
|
4
16
|
|
|
5
17
|
## Usage
|
|
6
18
|
|
|
7
|
-
Point `uses`
|
|
19
|
+
Point `uses` in your configuration at a workflow, e.g. in your `.github/workflows/ci.yml`. Pin to a release commit SHA with the version in a comment, the same way you would any third-party action (see [Versioning](#versioning)).
|
|
8
20
|
|
|
9
21
|
```yaml
|
|
10
22
|
name: CI
|
|
@@ -16,7 +28,7 @@ on:
|
|
|
16
28
|
|
|
17
29
|
jobs:
|
|
18
30
|
validate:
|
|
19
|
-
uses: taraxvoid/voidflow/.github/workflows/site-ci.yml@
|
|
31
|
+
uses: taraxvoid/voidflow/.github/workflows/site-ci.yml@15caea203066d42cb7be021eedb6356fac6ffdec # v0.8.1
|
|
20
32
|
```
|
|
21
33
|
|
|
22
34
|
### Non-GitHub / self-hosted runners
|
|
@@ -26,16 +38,39 @@ Pass `runner` (defaults to GitHub runner `ubuntu-latest`)
|
|
|
26
38
|
```yaml
|
|
27
39
|
jobs:
|
|
28
40
|
validate:
|
|
29
|
-
uses: taraxvoid/voidflow/.github/workflows/site-ci.yml@
|
|
41
|
+
uses: taraxvoid/voidflow/.github/workflows/site-ci.yml@15caea203066d42cb7be021eedb6356fac6ffdec # v0.8.1
|
|
30
42
|
with:
|
|
31
43
|
runner: my-hosted-runner
|
|
32
44
|
```
|
|
33
45
|
|
|
46
|
+
### pnpm sites, build env, extra e2e paths
|
|
47
|
+
|
|
48
|
+
```yaml
|
|
49
|
+
jobs:
|
|
50
|
+
validate:
|
|
51
|
+
uses: taraxvoid/voidflow/.github/workflows/site-ci.yml@<sha> # <version>
|
|
52
|
+
with:
|
|
53
|
+
package-manager: pnpm # default: bun
|
|
54
|
+
e2e-extra-paths: '["wrangler.jsonc", "site.vars.json"]' # JSON array of globs
|
|
55
|
+
build-env: ${{ format('{{"PUBLIC_SITE_URL":"https://example.com","GIT_SHA":"{0}"}}', github.sha) }}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
With `pnpm`, the pnpm version comes from `packageManager` and Node from `volta`
|
|
59
|
+
or `engines` in `package.json`. The lockfile (`bun.lock` or `pnpm-lock.yaml`)
|
|
60
|
+
follows the package manager. `build-env` is a JSON object, visible in logs, so
|
|
61
|
+
no secrets.
|
|
62
|
+
|
|
34
63
|
## Workflow Types
|
|
35
64
|
|
|
36
65
|
### Validation / Checks
|
|
37
66
|
|
|
38
|
-
Runs lint, typecheck, check for GPL licenses, e2e with Playwright
|
|
67
|
+
Runs lint, typecheck, check for GPL licenses, e2e with Playwright.
|
|
68
|
+
|
|
69
|
+
`site-ci.yml` runs these `package.json` scripts: `lint`, `check`, `build`,
|
|
70
|
+
`test:unit`, `check:licenses`, `test:e2e:full` (PRs into `main`),
|
|
71
|
+
`test:e2e:all` (PRs into `next` and `live`), `test:e2e:a11y` (`next` and
|
|
72
|
+
`live`), and `test:e2e:lighthouse` (`live`). A script the site does not define
|
|
73
|
+
is skipped with a notice, so none of them is required.
|
|
39
74
|
|
|
40
75
|
### Unlighthouse (performance / SEO budgets)
|
|
41
76
|
|
|
@@ -48,7 +83,7 @@ Chromium. It exits non-zero if a category budget in the site's config fails.
|
|
|
48
83
|
In the site's `package.json` (pin the tag):
|
|
49
84
|
|
|
50
85
|
```json
|
|
51
|
-
"test:e2e:lighthouse": "bun run build && bunx --package @taraxvoid/voidflow@0.
|
|
86
|
+
"test:e2e:lighthouse": "bun run build && bunx --package @taraxvoid/voidflow@0.8.1 unlighthouse-runner --dir dist"
|
|
52
87
|
```
|
|
53
88
|
|
|
54
89
|
Options: `--dir` (default `dist`, use `dist/client` for Cloudflare adapter
|
|
@@ -76,8 +111,8 @@ import { definePreviewConfig } from '@taraxvoid/voidflow/playwright'
|
|
|
76
111
|
export default definePreviewConfig({ ciPort: 4141 })
|
|
77
112
|
```
|
|
78
113
|
|
|
79
|
-
The same release is also published unscoped as `voidflow` (identical
|
|
80
|
-
|
|
114
|
+
The same release is also published unscoped as `voidflow` (identical code and
|
|
115
|
+
version, with a short pointer README), so `bun add -d voidflow` and
|
|
81
116
|
`import ... from 'voidflow/playwright'` work too. `@taraxvoid/voidflow` is the
|
|
82
117
|
canonical name.
|
|
83
118
|
|
|
@@ -90,7 +125,7 @@ Options: `ciPort` (required in CI), `runner` (default `bun`, e.g. `pnpm`),
|
|
|
90
125
|
Example deployment job added to your workflow above. `resolve-env` maps the
|
|
91
126
|
branch to dev/staging/prod once, up front, so its output can be used both to
|
|
92
127
|
drive the deploy and to label the job (`Deploy [dev]`, `Deploy [staging]`,
|
|
93
|
-
`Deploy [prod]`)
|
|
128
|
+
`Deploy [prod]`). A job's `name:` can reference `needs.<job>.outputs.*` but
|
|
94
129
|
not a step output from within itself, hence the split:
|
|
95
130
|
|
|
96
131
|
```yaml
|
|
@@ -98,7 +133,7 @@ jobs:
|
|
|
98
133
|
resolve-env:
|
|
99
134
|
needs: validate
|
|
100
135
|
if: github.event_name == 'push'
|
|
101
|
-
uses: taraxvoid/voidflow/.github/workflows/resolve-env.yml@
|
|
136
|
+
uses: taraxvoid/voidflow/.github/workflows/resolve-env.yml@15caea203066d42cb7be021eedb6356fac6ffdec # v0.8.1
|
|
102
137
|
|
|
103
138
|
deploy:
|
|
104
139
|
name: Deploy [${{ needs.resolve-env.outputs.env }}]
|
|
@@ -106,53 +141,59 @@ jobs:
|
|
|
106
141
|
if: github.event_name == 'push'
|
|
107
142
|
environment: ${{ needs.resolve-env.outputs.env }}
|
|
108
143
|
steps:
|
|
109
|
-
- uses: actions/checkout@v7.0.1
|
|
110
|
-
- uses: taraxvoid/voidflow/actions/cloudflare-deploy@
|
|
144
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
145
|
+
- uses: taraxvoid/voidflow/actions/cloudflare-deploy@15caea203066d42cb7be021eedb6356fac6ffdec # v0.8.1
|
|
111
146
|
with:
|
|
112
147
|
env: ${{ needs.resolve-env.outputs.env }}
|
|
113
148
|
cloudflare-api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
|
|
114
149
|
```
|
|
115
150
|
|
|
151
|
+
Sites with a single production environment and per-PR previews (no `next` or
|
|
152
|
+
`live` branch) pass `with: { single-environment: true }` to `resolve-env.yml`
|
|
153
|
+
(or the same input on `actions/branch-env-map`). `main` then maps to `prod` and
|
|
154
|
+
`pull_request` events map to `preview`; any other ref fails.
|
|
155
|
+
|
|
116
156
|
### Versioning
|
|
117
157
|
|
|
118
158
|
This project uses semver, released with [release-please](https://github.com/googleapis/release-please)
|
|
119
159
|
([`release-please.yml`](.github/workflows/release-please.yml)). It keeps a standing
|
|
120
|
-
`chore(
|
|
160
|
+
`chore(main): release X.Y.Z` PR open against `main`, updated as commits land. Merging it bumps
|
|
121
161
|
`package.json` and [`CHANGELOG.md`](CHANGELOG.md), tags `vX.Y.Z`, creates the GitHub release,
|
|
122
162
|
and publishes to npm. The PR is opened with the org's release-bot GitHub App token
|
|
123
163
|
(`RELEASE_BOT_CLIENT_ID` / `RELEASE_BOT_APP_PRIVATE_KEY`) so CI runs on it.
|
|
124
164
|
|
|
125
|
-
Commit messages should follow [Conventional Commits](https://www.conventionalcommits.org)
|
|
165
|
+
Commit messages should follow [Conventional Commits](https://www.conventionalcommits.org),
|
|
126
166
|
enforced loosely, as an advisory `commit-msg` hint (see
|
|
127
167
|
[`scripts/check-commit-msg.sh`](scripts/check-commit-msg.sh)), not a blocking check. They
|
|
128
168
|
drive the version bump and generated changelog.
|
|
129
169
|
|
|
130
|
-
Treat `@main` as unstable. Consumers should pin to
|
|
131
|
-
|
|
170
|
+
Treat `@main` as unstable. Consumers should pin to the commit SHA of a release tag and
|
|
171
|
+
keep the version in a trailing comment, e.g. `@15caea2... # v0.8.1`, so a Renovate or
|
|
172
|
+
Dependabot config can bump it. There is no floating major-version tag (`@v1`) to track yet.
|
|
132
173
|
|
|
133
174
|
## Self-validation
|
|
134
175
|
|
|
135
176
|
This repo validates its own workflows and composite actions (`.github/workflows/ci.yml`):
|
|
136
177
|
|
|
137
|
-
- **actionlint
|
|
138
|
-
- **check-jsonschema
|
|
139
|
-
- **shellcheck** (`scripts/shellcheck-actions.
|
|
140
|
-
- **zizmor
|
|
178
|
+
- **actionlint**: workflow schema/logic; also shellchecks `run:` steps in `.github/workflows/*.yml` automatically (`shellcheck` ships on `ubuntu-latest`)
|
|
179
|
+
- **check-jsonschema**: schema-checks `actions/**/action.yml` and the workflow files against [SchemaStore](https://www.schemastore.org/)'s `github-action.json` / `github-workflow.json`
|
|
180
|
+
- **shellcheck** (`scripts/shellcheck-actions.ts`): checks `run:` steps inside `actions/**/action.yml`, which actionlint doesn't reach
|
|
181
|
+
- **zizmor**: security audit (unpinned refs, script injection via `${{ }}` in `run:`, excess permissions, etc.)
|
|
141
182
|
|
|
142
183
|
### Local dev setup
|
|
143
184
|
|
|
144
185
|
```sh
|
|
145
|
-
brew install just lefthook actionlint shellcheck
|
|
186
|
+
brew install just lefthook actionlint shellcheck bun act uv
|
|
146
187
|
lefthook install
|
|
147
188
|
```
|
|
148
189
|
|
|
149
|
-
- `just validate
|
|
150
|
-
- `just lint-workflows` / `lint-actions` / `lint-shell` / `security
|
|
151
|
-
- `just dry-run
|
|
190
|
+
- `just validate`: run everything CI runs, locally
|
|
191
|
+
- `just lint-workflows` / `lint-actions` / `lint-shell` / `security`: run one check at a time
|
|
192
|
+
- `just dry-run`: full local run of `ci.yml` via [`act`](https://github.com/nektos/act) (needs Docker running); pass extra args, e.g. `just dry-run -j validation`
|
|
152
193
|
- lefthook runs the fast checks (`lint-workflows`, `lint-actions`, `lint-shell`) on `pre-commit`, and `zizmor` on `pre-push`
|
|
153
194
|
|
|
154
|
-
**Colima users:** `.actrc` already disables the docker-socket mount (`--container-daemon-socket -`)
|
|
195
|
+
**Colima users:** `.actrc` already disables the docker-socket mount (`--container-daemon-socket -`). `act` binds `/var/run/docker.sock` by default, which doesn't exist under Colima and fails with `operation not supported`. None of these workflow steps need docker-in-docker, so this is safe.
|
|
155
196
|
|
|
156
|
-
**Run `just dry-run` from a normal checkout, not a linked git worktree.** `act` copies the working tree via `docker cp` rather than a real clone, so a worktree's `.git` pointer back to the parent repo doesn't resolve inside the container
|
|
197
|
+
**Run `just dry-run` from a normal checkout, not a linked git worktree.** `act` copies the working tree via `docker cp` rather than a real clone, so a worktree's `.git` pointer back to the parent repo doesn't resolve inside the container, so `git ls-files`-based steps (schema validation, `scripts/shellcheck-actions.ts`) silently see zero files instead of erroring. Verified clean end-to-end (`🏁 Job succeeded`) from a plain clone.
|
|
157
198
|
|
|
158
|
-
|
|
199
|
+
Provided as is under the [MIT license](LICENSE). Issues and pull requests are welcome.
|
package/package.json
CHANGED
|
@@ -1,8 +1,21 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@taraxvoid/voidflow",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.9.0",
|
|
4
4
|
"description": "Shared workflows, actions and tooling for @taraxvoid sites",
|
|
5
5
|
"license": "MIT",
|
|
6
|
+
"keywords": [
|
|
7
|
+
"github-actions",
|
|
8
|
+
"ci",
|
|
9
|
+
"reusable-workflows",
|
|
10
|
+
"playwright",
|
|
11
|
+
"unlighthouse",
|
|
12
|
+
"astro",
|
|
13
|
+
"cloudflare"
|
|
14
|
+
],
|
|
15
|
+
"homepage": "https://github.com/taraxvoid/voidflow#readme",
|
|
16
|
+
"bugs": {
|
|
17
|
+
"url": "https://github.com/taraxvoid/voidflow/issues"
|
|
18
|
+
},
|
|
6
19
|
"repository": {
|
|
7
20
|
"type": "git",
|
|
8
21
|
"url": "git+https://github.com/taraxvoid/voidflow.git"
|
|
@@ -25,7 +38,16 @@
|
|
|
25
38
|
"playwright",
|
|
26
39
|
"scripts/unlighthouse"
|
|
27
40
|
],
|
|
41
|
+
"engines": {
|
|
42
|
+
"bun": ">=1.4.0"
|
|
43
|
+
},
|
|
44
|
+
"scripts": {
|
|
45
|
+
"test": "bun test"
|
|
46
|
+
},
|
|
28
47
|
"peerDependencies": {
|
|
29
48
|
"@playwright/test": ">=1.40"
|
|
49
|
+
},
|
|
50
|
+
"devDependencies": {
|
|
51
|
+
"@playwright/test": "^1.40.0"
|
|
30
52
|
}
|
|
31
53
|
}
|