@taraxvoid/voidflow 0.0.0 → 0.8.3
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 +47 -32
- package/package.json +24 -2
- package/playwright/index.mjs +1 -0
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,7 +38,7 @@ 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
|
```
|
|
@@ -48,7 +60,7 @@ Chromium. It exits non-zero if a category budget in the site's config fails.
|
|
|
48
60
|
In the site's `package.json` (pin the tag):
|
|
49
61
|
|
|
50
62
|
```json
|
|
51
|
-
"test:e2e:lighthouse": "bun run build && bunx --package @taraxvoid/voidflow@0.
|
|
63
|
+
"test:e2e:lighthouse": "bun run build && bunx --package @taraxvoid/voidflow@0.8.1 unlighthouse-runner --dir dist"
|
|
52
64
|
```
|
|
53
65
|
|
|
54
66
|
Options: `--dir` (default `dist`, use `dist/client` for Cloudflare adapter
|
|
@@ -76,6 +88,11 @@ import { definePreviewConfig } from '@taraxvoid/voidflow/playwright'
|
|
|
76
88
|
export default definePreviewConfig({ ciPort: 4141 })
|
|
77
89
|
```
|
|
78
90
|
|
|
91
|
+
The same release is also published unscoped as `voidflow` (identical code and
|
|
92
|
+
version, with a short pointer README), so `bun add -d voidflow` and
|
|
93
|
+
`import ... from 'voidflow/playwright'` work too. `@taraxvoid/voidflow` is the
|
|
94
|
+
canonical name.
|
|
95
|
+
|
|
79
96
|
Options: `ciPort` (required in CI), `runner` (default `bun`, e.g. `pnpm`),
|
|
80
97
|
`timeout` (default 30000), `projects` (default Pixel 7 and Desktop Chrome),
|
|
81
98
|
`testDir` (default `./test/e2e`). Requires `@playwright/test` in the site.
|
|
@@ -85,7 +102,7 @@ Options: `ciPort` (required in CI), `runner` (default `bun`, e.g. `pnpm`),
|
|
|
85
102
|
Example deployment job added to your workflow above. `resolve-env` maps the
|
|
86
103
|
branch to dev/staging/prod once, up front, so its output can be used both to
|
|
87
104
|
drive the deploy and to label the job (`Deploy [dev]`, `Deploy [staging]`,
|
|
88
|
-
`Deploy [prod]`)
|
|
105
|
+
`Deploy [prod]`). A job's `name:` can reference `needs.<job>.outputs.*` but
|
|
89
106
|
not a step output from within itself, hence the split:
|
|
90
107
|
|
|
91
108
|
```yaml
|
|
@@ -93,7 +110,7 @@ jobs:
|
|
|
93
110
|
resolve-env:
|
|
94
111
|
needs: validate
|
|
95
112
|
if: github.event_name == 'push'
|
|
96
|
-
uses: taraxvoid/voidflow/.github/workflows/resolve-env.yml@
|
|
113
|
+
uses: taraxvoid/voidflow/.github/workflows/resolve-env.yml@15caea203066d42cb7be021eedb6356fac6ffdec # v0.8.1
|
|
97
114
|
|
|
98
115
|
deploy:
|
|
99
116
|
name: Deploy [${{ needs.resolve-env.outputs.env }}]
|
|
@@ -101,8 +118,8 @@ jobs:
|
|
|
101
118
|
if: github.event_name == 'push'
|
|
102
119
|
environment: ${{ needs.resolve-env.outputs.env }}
|
|
103
120
|
steps:
|
|
104
|
-
- uses: actions/checkout@v7.0.1
|
|
105
|
-
- uses: taraxvoid/voidflow/actions/cloudflare-deploy@
|
|
121
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
122
|
+
- uses: taraxvoid/voidflow/actions/cloudflare-deploy@15caea203066d42cb7be021eedb6356fac6ffdec # v0.8.1
|
|
106
123
|
with:
|
|
107
124
|
env: ${{ needs.resolve-env.outputs.env }}
|
|
108
125
|
cloudflare-api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
|
|
@@ -110,32 +127,30 @@ jobs:
|
|
|
110
127
|
|
|
111
128
|
### Versioning
|
|
112
129
|
|
|
113
|
-
This project uses semver, released
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
2. Merging that PR triggers [`tag-release.yml`](.github/workflows/tag-release.yml), which
|
|
120
|
-
tags the merge commit and publishes the GitHub release. (Tag pushes aren't covered by
|
|
121
|
-
`main`'s branch protection, only branch pushes are.)
|
|
130
|
+
This project uses semver, released with [release-please](https://github.com/googleapis/release-please)
|
|
131
|
+
([`release-please.yml`](.github/workflows/release-please.yml)). It keeps a standing
|
|
132
|
+
`chore(main): release X.Y.Z` PR open against `main`, updated as commits land. Merging it bumps
|
|
133
|
+
`package.json` and [`CHANGELOG.md`](CHANGELOG.md), tags `vX.Y.Z`, creates the GitHub release,
|
|
134
|
+
and publishes to npm. The PR is opened with the org's release-bot GitHub App token
|
|
135
|
+
(`RELEASE_BOT_CLIENT_ID` / `RELEASE_BOT_APP_PRIVATE_KEY`) so CI runs on it.
|
|
122
136
|
|
|
123
|
-
Commit messages should follow [Conventional Commits](https://www.conventionalcommits.org)
|
|
137
|
+
Commit messages should follow [Conventional Commits](https://www.conventionalcommits.org),
|
|
124
138
|
enforced loosely, as an advisory `commit-msg` hint (see
|
|
125
139
|
[`scripts/check-commit-msg.sh`](scripts/check-commit-msg.sh)), not a blocking check. They
|
|
126
|
-
drive the generated changelog.
|
|
140
|
+
drive the version bump and generated changelog.
|
|
127
141
|
|
|
128
|
-
Treat `@main` as unstable. Consumers should pin to
|
|
129
|
-
|
|
142
|
+
Treat `@main` as unstable. Consumers should pin to the commit SHA of a release tag and
|
|
143
|
+
keep the version in a trailing comment, e.g. `@15caea2... # v0.8.1`, so a Renovate or
|
|
144
|
+
Dependabot config can bump it. There is no floating major-version tag (`@v1`) to track yet.
|
|
130
145
|
|
|
131
146
|
## Self-validation
|
|
132
147
|
|
|
133
148
|
This repo validates its own workflows and composite actions (`.github/workflows/ci.yml`):
|
|
134
149
|
|
|
135
|
-
- **actionlint
|
|
136
|
-
- **check-jsonschema
|
|
137
|
-
- **shellcheck** (`scripts/shellcheck-actions.sh`)
|
|
138
|
-
- **zizmor
|
|
150
|
+
- **actionlint**: workflow schema/logic; also shellchecks `run:` steps in `.github/workflows/*.yml` automatically (`shellcheck` ships on `ubuntu-latest`)
|
|
151
|
+
- **check-jsonschema**: schema-checks `actions/**/action.yml` and the workflow files against [SchemaStore](https://www.schemastore.org/)'s `github-action.json` / `github-workflow.json`
|
|
152
|
+
- **shellcheck** (`scripts/shellcheck-actions.sh`): checks `run:` steps inside `actions/**/action.yml`, which actionlint doesn't reach
|
|
153
|
+
- **zizmor**: security audit (unpinned refs, script injection via `${{ }}` in `run:`, excess permissions, etc.)
|
|
139
154
|
|
|
140
155
|
### Local dev setup
|
|
141
156
|
|
|
@@ -144,13 +159,13 @@ brew install just lefthook actionlint shellcheck yq act uv
|
|
|
144
159
|
lefthook install
|
|
145
160
|
```
|
|
146
161
|
|
|
147
|
-
- `just validate
|
|
148
|
-
- `just lint-workflows` / `lint-actions` / `lint-shell` / `security
|
|
149
|
-
- `just dry-run
|
|
162
|
+
- `just validate`: run everything CI runs, locally
|
|
163
|
+
- `just lint-workflows` / `lint-actions` / `lint-shell` / `security`: run one check at a time
|
|
164
|
+
- `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`
|
|
150
165
|
- lefthook runs the fast checks (`lint-workflows`, `lint-actions`, `lint-shell`) on `pre-commit`, and `zizmor` on `pre-push`
|
|
151
166
|
|
|
152
|
-
**Colima users:** `.actrc` already disables the docker-socket mount (`--container-daemon-socket -`)
|
|
167
|
+
**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.
|
|
153
168
|
|
|
154
|
-
**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
|
|
169
|
+
**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.sh`) silently see zero files instead of erroring. Verified clean end-to-end (`🏁 Job succeeded`) from a plain clone.
|
|
155
170
|
|
|
156
|
-
|
|
171
|
+
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.
|
|
4
|
-
"description": "Shared workflows, actions and tooling for
|
|
3
|
+
"version": "0.8.3",
|
|
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
|
}
|
package/playwright/index.mjs
CHANGED