@taraxvoid/voidflow 0.8.1 → 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.
Files changed (2) hide show
  1. package/README.md +38 -25
  2. package/package.json +23 -1
package/README.md CHANGED
@@ -1,10 +1,22 @@
1
1
  # voidflow
2
2
 
3
- Semi-opinionated GitHub Actions workflows for my personal sites and consultancy shop [RavenFlight Industries, LLC](https://rvnflt.com/github)
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` in your configuration to a workflow, e.g. in your `.github/workflows/ci.yml`
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@main
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@main
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.6.0 unlighthouse-runner --dir dist"
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,8 +88,8 @@ import { definePreviewConfig } from '@taraxvoid/voidflow/playwright'
76
88
  export default definePreviewConfig({ ciPort: 4141 })
77
89
  ```
78
90
 
79
- The same release is also published unscoped as `voidflow` (identical
80
- contents and version), so `bun add -d voidflow` and
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
81
93
  `import ... from 'voidflow/playwright'` work too. `@taraxvoid/voidflow` is the
82
94
  canonical name.
83
95
 
@@ -90,7 +102,7 @@ Options: `ciPort` (required in CI), `runner` (default `bun`, e.g. `pnpm`),
90
102
  Example deployment job added to your workflow above. `resolve-env` maps the
91
103
  branch to dev/staging/prod once, up front, so its output can be used both to
92
104
  drive the deploy and to label the job (`Deploy [dev]`, `Deploy [staging]`,
93
- `Deploy [prod]`) — a job's `name:` can reference `needs.<job>.outputs.*` but
105
+ `Deploy [prod]`). A job's `name:` can reference `needs.<job>.outputs.*` but
94
106
  not a step output from within itself, hence the split:
95
107
 
96
108
  ```yaml
@@ -98,7 +110,7 @@ jobs:
98
110
  resolve-env:
99
111
  needs: validate
100
112
  if: github.event_name == 'push'
101
- uses: taraxvoid/voidflow/.github/workflows/resolve-env.yml@main
113
+ uses: taraxvoid/voidflow/.github/workflows/resolve-env.yml@15caea203066d42cb7be021eedb6356fac6ffdec # v0.8.1
102
114
 
103
115
  deploy:
104
116
  name: Deploy [${{ needs.resolve-env.outputs.env }}]
@@ -106,8 +118,8 @@ jobs:
106
118
  if: github.event_name == 'push'
107
119
  environment: ${{ needs.resolve-env.outputs.env }}
108
120
  steps:
109
- - uses: actions/checkout@v7.0.1
110
- - uses: taraxvoid/voidflow/actions/cloudflare-deploy@main
121
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
122
+ - uses: taraxvoid/voidflow/actions/cloudflare-deploy@15caea203066d42cb7be021eedb6356fac6ffdec # v0.8.1
111
123
  with:
112
124
  env: ${{ needs.resolve-env.outputs.env }}
113
125
  cloudflare-api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
@@ -117,27 +129,28 @@ jobs:
117
129
 
118
130
  This project uses semver, released with [release-please](https://github.com/googleapis/release-please)
119
131
  ([`release-please.yml`](.github/workflows/release-please.yml)). It keeps a standing
120
- `chore(release): X.Y.Z` PR open against `main`, updated as commits land. Merging it bumps
132
+ `chore(main): release X.Y.Z` PR open against `main`, updated as commits land. Merging it bumps
121
133
  `package.json` and [`CHANGELOG.md`](CHANGELOG.md), tags `vX.Y.Z`, creates the GitHub release,
122
134
  and publishes to npm. The PR is opened with the org's release-bot GitHub App token
123
135
  (`RELEASE_BOT_CLIENT_ID` / `RELEASE_BOT_APP_PRIVATE_KEY`) so CI runs on it.
124
136
 
125
- Commit messages should follow [Conventional Commits](https://www.conventionalcommits.org) —
137
+ Commit messages should follow [Conventional Commits](https://www.conventionalcommits.org),
126
138
  enforced loosely, as an advisory `commit-msg` hint (see
127
139
  [`scripts/check-commit-msg.sh`](scripts/check-commit-msg.sh)), not a blocking check. They
128
140
  drive the version bump and generated changelog.
129
141
 
130
- Treat `@main` as unstable. Consumers should pin to an exact release tag, e.g. `@v0.3.0` —
131
- there is no floating major-version tag (`@v1`) to track yet.
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.
132
145
 
133
146
  ## Self-validation
134
147
 
135
148
  This repo validates its own workflows and composite actions (`.github/workflows/ci.yml`):
136
149
 
137
- - **actionlint** — workflow schema/logic; also shellchecks `run:` steps in `.github/workflows/*.yml` automatically (`shellcheck` ships on `ubuntu-latest`)
138
- - **check-jsonschema** — schema-checks `actions/**/action.yml` and the workflow files against [SchemaStore](https://www.schemastore.org/)'s `github-action.json` / `github-workflow.json`
139
- - **shellcheck** (`scripts/shellcheck-actions.sh`) — checks `run:` steps inside `actions/**/action.yml`, which actionlint doesn't reach
140
- - **zizmor** — security audit (unpinned refs, script injection via `${{ }}` in `run:`, excess permissions, etc.)
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.)
141
154
 
142
155
  ### Local dev setup
143
156
 
@@ -146,13 +159,13 @@ brew install just lefthook actionlint shellcheck yq act uv
146
159
  lefthook install
147
160
  ```
148
161
 
149
- - `just validate` — run everything CI runs, locally
150
- - `just lint-workflows` / `lint-actions` / `lint-shell` / `security` — run one check at a time
151
- - `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`
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`
152
165
  - lefthook runs the fast checks (`lint-workflows`, `lint-actions`, `lint-shell`) on `pre-commit`, and `zizmor` on `pre-push`
153
166
 
154
- **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.
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.
155
168
 
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 — `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.
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.
157
170
 
158
- YMMV, caveat emptor, your satisfaction **not** guaranteed
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.8.1",
3
+ "version": "0.8.3",
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
  }