The repository now lives in the poli0981org organization, and this makes it at home there. - main was red since 2026-11-18: RUSTSEC-2026-0543 (chrono), in Cargo.lock only through serde_with's weak features and compiled into nothing; ignored with its reason and exit condition. - Supersedes #113–#118 (Rust 1.100.0, rusqlite 0.42.0, Tauri 2.12.6, code-health pins, actions, npm) plus jsdom 31.0.1; minimatch 11 closes GHSA-g3hv-75wg-m249. rfd 0.18 (#112) is held again until tauri-plugin-dialog moves. - Dependabot's tauri groups never worked (it picks the most specific group); exclude-patterns on the catch-alls fix it. - CI is self-contained: no workflow calls poli0981/.github; every action is pinned by commit; notify.yml vendors the Discord notifier. - npm licences: scripts/check-licenses.mjs, deny.toml's allowlist for the npm half. Required, with cargo deny and tauri lockstep — eight required checks. - Qodana in two parts (Rust, TS/JS), full scans, a triaged Rust baseline, fail on anything new. The Rust container needed its toolchain and CARGO_HOME pointed somewhere writable before it analysed anything. - SonarQube Cloud analyses into poli0981org_pipdock; every npm ci runs with --ignore-scripts (S6505). - Every repository URL points at the organization. README's attestation command for 1.4.0/1.5.0 had stopped working; it now says --owner poli0981 --signer-repo poli0981/pipdock. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
119 lines
20 KiB
Markdown
119 lines
20 KiB
Markdown
# PipDock — Release & CI
|
|
|
|
*Version 0.3 · 2026-11-21 · Every workflow is project-local. Until the repository moved to the poli0981org organization (2026-11-21) four of them were callers into the owner's personal ops repo, `poli0981/.github`, at `@main`; §1 says what replaced each and why.*
|
|
|
|
## 1. Workflows (`.github/workflows/`)
|
|
|
|
| Workflow | Triggers | Jobs |
|
|
|---|---|---|
|
|
| `ci-rust.yml` | PR, push main | `fmt · clippy · test` (`windows-latest`): `cargo fmt --check`, clippy `-D warnings`, `cargo test --workspace --locked`. `cargo audit` (`ubuntu-latest`): a prebuilt `cargo-audit`, `--deny warnings`. `cargo deny` (`ubuntu-latest`): licences, sources, bans (`deny.toml`) |
|
|
| `ci-node.yml` | PR, push main | `lint · typecheck · test · build` (Node 26, `npm ci`, ESLint, `tsc`, Vitest, `vite build`); `npm audit --audit-level=high` (after `npm ci --ignore-scripts`); `npm licences` (`scripts/check-licenses.mjs` and its `node --test` suite — §2); `tauri lockstep` (`scripts/check-tauri-lockstep.mjs`) |
|
|
| `ci-integration.yml` | PR touching what its end-to-end steps run through (the path list is in the file), nightly, Mondays, dispatch | Windows runner, Python 3.10 and 3.14: the disposable-venv suite (TESTING L2); Mondays and dispatch only, the fixture-drift re-capture against the newest pip and uv |
|
|
| `codeql.yml` | PR, push main, weekly | `Analyze (<language>)` for `javascript-typescript`, `rust` and `actions`, all `build-mode: none` |
|
|
| `qodana.yml` | PR, push main, dispatch | `tokens present` → `qodana · rust` (Docker, `qodana-rust.yaml`) and `qodana · ts/js` (native, `qodana-js.yaml`), one Qodana Cloud project and token each; skipped without a token, like `sonar.yml` |
|
|
| `security-scan.yml` | daily, dispatch | `cargo audit` and `npm audit` against `main` (SECURITY §7) |
|
|
| `sonar.yml` | PR, push main, dispatch (`main` only) | `token present` (`ubuntu-latest`) → `coverage · analysis` (`windows-latest`): vitest and `cargo llvm-cov` LCOV, clippy's JSON, then `sonarqube-scan-action` with `sonar.projectVersion` from `package.json` and `sonar.qualitygate.wait`. Skipped when the run has no `SONAR_TOKEN` (Dependabot and fork PRs), and for a dispatch from any branch but `main` — the plan analyses `main` and PRs only. `sonar-project.properties` holds the scope and the project, `poli0981org_pipdock` since 2026-11-21 |
|
|
| `release.yml` | tag `v*`; dispatch (`tag`, `dry_run`) | `Build · checksum` (`windows-latest`, read-only) → `Attest · draft` (`ubuntu-latest`); see §3 |
|
|
| `notify.yml` | `workflow_run` of the workflows above, **by name**; release published; dispatch (`tag`, to announce again) | `ci-failure` → `DISCORD_CI_WEBHOOK`; `announce` → `DISCORD_RELEASES_WEBHOOK` and `DISCORD_REPO_WEBHOOK`, both through `.github/scripts/discord_notify.py` (standard library; `DRY_RUN=1` prints instead of posting) |
|
|
|
|
**`notify.yml` names its workflows, and a new workflow is added to it by its exact `name:`.** `workflows: ['*']` — the ops repo's old caller example — is not a wildcard to `workflow_run`: it matched nothing, so `main` stayed red from 2026-09-23 with every failure unreported. It reports a failure from any event but a pull request, filtering on the event alone — never on a branch name, which a fork controls. CodeQL, Qodana and Release are listed: the ops-repo notifier skipped anything named like CodeQL or Release because of "dedicated notifiers" PipDock never had, so a failed Release run reached no channel at all.
|
|
|
|
**Why nothing calls the ops repo any more (2026-11-21).** The repository moved to the poli0981org organization so that the projects the owner maintains seriously sit apart from the ones made for fun, and a project in the organization should not run code another account can change. The four callers were exactly that: `@main` of `poli0981/.github`, unpinned, and its notifier checked out that repository's `main` and ran *its* Python script with PipDock's Discord webhooks in the environment. Each was small enough to copy, as OmniDeck — the organization's other project — had already done:
|
|
|
|
- `reusable-web-react.yml` became `ci-node.yml`'s `lint · typecheck · test · build` job. It took two things with it: the `pages: write` and `id-token: write` grants its always-skipped Pages job forced on the caller (permissions are validated at startup regardless of `if:`), and the `dist` artifact nothing downloaded. Its missing `working-directory` input was why `package.json` sits at the repository root; the layout stays, because SonarCloud, Qodana, the scripts and Tauri's configuration all assume it now (ARCHITECTURE §2).
|
|
- `reusable-codeql.yml` became `codeql.yml`'s matrix job, with `codeql-action` pinned by commit where the reusable used `@v4`, and the same `category` values, so the alerts keep their history. Rust and Actions run as they did through the reusable, which handed `languages` straight to the action.
|
|
- `notify-ci-failure.yml` and `announce-release.yml` became `notify.yml`, with the script vendored from OmniDeck's self-contained notifier.
|
|
|
|
**Every action is pinned by commit**, with its version in a comment for Dependabot to update — GitHub's own `actions/*` included, which had used major tags. A write permission sits on the job that needs it, never the workflow (SonarCloud S8233):
|
|
|
|
```yaml
|
|
# every workflow
|
|
permissions: { contents: read }
|
|
# codeql.yml — analyze
|
|
permissions: { actions: read, contents: read, packages: read, security-events: write }
|
|
# qodana.yml — rust, js
|
|
permissions: { contents: read, checks: write, pull-requests: write, security-events: write }
|
|
# release.yml — publish (§3)
|
|
permissions: { contents: write, id-token: write, attestations: write }
|
|
```
|
|
|
|
## 2. Branch & version policy
|
|
|
|
`main` protected (PR + green CI required). SemVer; tags `vX.Y.Z`, and `release.yml` refuses a tag that does not match all five version fields (§3). Commit subjects follow Conventional Commits, but nothing generates a changelog from them — this line said a generator did. `changelog/` is written by hand, for a user, under the rules in `changelog/README.md`; a draft release's notes are GitHub's generated list of merged pull requests.
|
|
|
|
**Protection was applied 2026-08-14, and had been false until then** — `/branches/main/protection` returned 404 for four milestones, which is also why `gh pr merge --auto` merged immediately on this repo rather than waiting: with no required checks there is nothing for auto-merge to wait on. Exact settings:
|
|
|
|
| Setting | Value | Why |
|
|
|---|---|---|
|
|
| Required checks | `fmt · clippy · test`, `cargo audit`, `cargo deny`, `lint · typecheck · test · build`, `npm audit`, `npm licences`, `tauri lockstep`, `Analyze (javascript-typescript)` | eight, all running on **every** PR (below) |
|
|
| Check app | pinned to `app_id: 15368` (`github-actions`) | a check from another app cannot satisfy a requirement |
|
|
| `enforce_admins` | `true` | the owner is the only contributor; protection that exempts them protects nothing |
|
|
| Required approvals | **0** | a solo owner cannot approve their own PR, so 1 would deadlock. A PR is still required |
|
|
| `strict` | `false` | up-to-date-before-merge is friction on a repo that rebase-merges |
|
|
| Linear history | `true` | matches rebase-merge |
|
|
| Conversation resolution | `true` | a review thread left open blocks the merge — read from the API on 2026-11-10; this table did not list it |
|
|
| Force pushes / deletions | `false` | |
|
|
|
|
**`CI / Integration` is deliberately excluded, and this is the trap worth remembering:** its `pull_request` trigger is `paths:`-filtered, so on a docs-only or UI-only PR it never starts — and a required check that never starts stays *pending forever*. Requiring it would deadlock exactly the PRs it has no opinion about. `Re-capture against the latest engines` runs on no PR at all (Mondays and dispatch only) and is excluded for the same reason. The bare `CodeQL` check belongs to the `github-advanced-security` app rather than Actions and is left out too.
|
|
|
|
**The payload has had two shapes.** The first, set on 2026-08-14, held five checks — `fmt · clippy · test`, `cargo audit`, `lint · typecheck · test · build / build`, `npm audit` and `analyze / Analyze (javascript-typescript)` — and two of those names were the ops repo's: a reusable workflow's check is `<caller job> / <callee job>`, so a rename upstream would have deadlocked every PipDock PR with no failing check to point at. The second, set on 2026-11-21 when the callers became local jobs, renames those two to `lint · typecheck · test · build` and `Analyze (javascript-typescript)` and adds three that had run on every PR since 1.4.0 as advice rather than gates: `cargo deny`, `npm licences` (new that day) and `tauri lockstep`, whose whole purpose is to stop one half of a Tauri bump merging alone. **A required name is now this repository's alone, so renaming a job means changing this payload in the same change.**
|
|
|
|
**Still not required, and why.** CodeQL's `Analyze (rust)` and `Analyze (actions)` run on every PR and stay advice. `Security scan` runs on no PR and can never be required. SonarQube Cloud is not required in either form: `SonarCloud Code Analysis` is reported by the SonarCloud app, which the payload's `app_id` pin would not accept, and `sonar.yml`'s `coverage · analysis` is *skipped* on every PR without a token — Dependabot's — and a skipped job satisfies a requirement, so requiring it would gate exactly the PRs it never looks at. Qodana is not required for the same reason, and because one of its two linters is a JetBrains early-access build behind an external service.
|
|
|
|
**If protection wedges**, `PUT` the same endpoint with `enforce_admins: false`, or `DELETE /branches/main/protection`. Worth knowing before it is needed rather than discovering it during an incident.
|
|
|
|
Dependency updates use **Dependabot** (`.github/dependabot.yml`) — the standard of the owner's ops repo when the CI was set up, and of the poli0981org organization now; nothing here uses Renovate. **Five ecosystems**, weekly on Mondays: `cargo`, `npm`, `github-actions`, `pip` at `/tools` (the Code Health pins) and, since 1.4.0, `rust-toolchain` — the `rust-toolchain.toml` channel, in a PR of its own because a toolchain brings new clippy lints. Minor and patch updates are grouped per ecosystem; security advisories arrive as **immediate, ungrouped** PRs (Dependabot's default for security updates), and the `pip` ecosystem stays its own group so Code Health pin bumps are reviewable in isolation — a bump there also needs `tools/tools-constraints.txt` regenerated (the command is in its header), and `cargo test` fails until it is (CODE-HEALTH-SPEC §2). Watching `pip`/`uv` releases to trigger the parser-fixture job is the scheduled job in `ci-integration.yml`, not the dependency bot. Since 1.4.0:
|
|
|
|
- **Cooldowns.** A release must be 3 days old before cargo or npm proposes it (14 for a major), and 7 for Actions and the tool pins. Most yanked or compromised releases are pulled inside that window, and nothing here needs a dependency the day it ships.
|
|
- **Tauri moves in lockstep.** The `tauri` crate and `@tauri-apps/api` must share a minor or the app refuses to start, and Dependabot bumps Cargo and npm in separate PRs, each green on its own. So each ecosystem groups its Tauri packages (`tauri`, `tauri-*`; `@tauri-apps/*`) apart from its catch-all group — by `exclude-patterns` on the catch-all, since 2026-11-21: Dependabot gives a dependency to the *most specific* matching group, it counts a group with `update-types` as more specific than one with patterns alone, and so the order this bullet used to rely on did nothing (that week's Tauri bumps landed in #116 and #118, the catch-alls) — and `ci-node.yml`'s `tauri lockstep` job fails either PR until its counterpart lands beside it, comparing the core and each plugin with its npm package on `Cargo.lock` and `package-lock.json` — what is built, not what the manifests ask for. **A multi-ecosystem group was considered and not used:** it would put both halves in one PR, but what it does to the dependencies outside its patterns is undocumented, and a wrong guess would silently stop every other update.
|
|
- **TypeScript is held below 6.1** (`ignore: typescript >=6.1.0`): typescript-eslint 8.71 peers `typescript >=4.8.4 <6.1.0`, so a 6.1 bump fails `npm ci` with ERESOLVE before a single check runs. Remove it once typescript-eslint widens its range (8.73 still peers `<6.1.0`, re-read 2026-11-21, with TypeScript at 7.0).
|
|
- **rfd is held below 0.18** (`ignore: rfd >=0.18.0`, cargo): src-tauri takes rfd only because tauri-plugin-dialog compiles it, and 2.8.4, the newest, still requires `^0.17` — so #112's rfd 0.18 alone would have put a second rfd in the binary. Remove it when the plugin moves, and bump both together.
|
|
- **Vitest moves as one** (group `vitest`: `vitest`, `@vitest/*`, every update type). `@vitest/coverage-v8`, which `sonar.yml` needs, peers `vitest` at its exact version, so a bump of either alone fails `npm ci` the way the TypeScript one would.
|
|
- **Labels.** PRs are labelled `dependencies` plus `rust`, `frontend`, `ci` or `code-health`, and the labels must exist in the repository or Dependabot opens its PRs without them (§5).
|
|
|
|
## 3. Release pipeline (tag `v*`)
|
|
|
|
Two jobs, so the token that can write a release never runs the build (SECURITY §5).
|
|
|
|
1. **`Build · checksum`** — Windows runner, a read-only token, and no credentials kept in the checkout (`persist-credentials: false`).
|
|
- **The tag and all five version fields must agree** — `Cargo.toml`, `Cargo.lock` (`pipdock-core`'s entry), `package.json`, `package-lock.json` and `tauri.conf.json` — or the job stops before building. A tag pushed ahead of its bump commit, or a bump that missed a file, would otherwise build an installer whose About states another version.
|
|
- `npm ci` → **`npm run bundle`**, producing NSIS `.exe` + `.msi`. That one script owns the whole recipe so the workflow cannot drift from what a developer runs locally, and it encodes two things that are easy to get wrong:
|
|
- **`--locked` goes after `--`.** It is cargo's flag; `tauri build` rejects it as its own with *"unexpected argument"* before a single crate compiles.
|
|
- **The CLI sidecar is declared in an overlay** (`src-tauri/tauri.bundle.conf.json`, merged with `--config`), not in `tauri.conf.json`. `tauri-build` validates `externalBin` at build-script time, so declaring it in the base config makes plain `cargo clippy` and `cargo test` fail in a fresh clone with *"resource path … doesn't exist"* — a bundling concern leaking into every compile.
|
|
|
|
The frontend is built by tauri's `beforeBuildCommand`, so the workflow does not run `vite build` itself.
|
|
- **`SHA256SUMS.txt`**, LF line endings, written byte for byte: `Set-Content` wrote CRLF, and `sha256sum -c` on any other platform reads the CR as part of the file name and reports the file missing.
|
|
- The installers and the checksums are uploaded as the `release-artifacts` workflow artifact.
|
|
2. **`Attest · draft`** — Ubuntu runner, the only job granted `contents`, `id-token` and `attestations` write. It downloads the build, attests build provenance for the `.exe` and the `.msi` (`actions/attest-build-provenance`, verifiable with `gh attestation verify <file> --repo poli0981org/pipdock`; an attestation stays with the account that made it, so 1.4.0 and 1.5.0, built before the move to the organization, verify with `--owner poli0981 --signer-repo poli0981/pipdock` and no longer with any `--repo`), and drafts the GitHub release with GitHub's generated notes and all three files (`softprops/action-gh-release`). Both actions are pinned by commit.
|
|
3. **Publishing the draft is a human decision**, taken per release; publishing fires `notify.yml`'s Discord announcement. For 1.4.0 the owner approved the plan and instructed the assistant to check the installers against `SHA256SUMS.txt` and then publish — `docs/AI-DISCLOSURE.md` records who did what.
|
|
|
|
**A dry run** — `workflow_dispatch` with `dry_run` — builds and checksums any ref, a branch before it merges included, and attests and drafts nothing, so the release recipe is tested before a tag depends on it. Without `dry_run`, dispatch builds a version tag only (the `tag` input re-runs one); a branch is refused.
|
|
|
|
This list had a fourth step — a post-release checklist issue, opened automatically, for SmartScreen behaviour and an EN/VI spot-check of the shipped build. No workflow has ever opened one. Those checks belong to the per-release manual charter (TESTING §4).
|
|
|
|
There is no signing step. **PipDock does not update itself** (SECURITY §5), so no `latest.json` is produced, no artifact is code-signed, and no keypair exists to manage. The attestation is signed through Sigstore with a short-lived certificate bound to the workflow run — which is why the publish job needs `id-token: write` — so it adds no key either.
|
|
|
|
Secrets bootstrap: set per repository with `gh secret set`, none at the organization — the Discord webhooks `notify.yml` posts to (`DISCORD_RELEASES_WEBHOOK`, `DISCORD_REPO_WEBHOOK`, `DISCORD_CI_WEBHOOK`), `SONAR_TOKEN` for `sonar.yml` (re-issued for the `poli0981org` SonarQube Cloud organization on 2026-11-21), and `QODANA_TOKEN_RUST` and `QODANA_TOKEN_TS_JS` for the two Qodana Cloud projects `qodana.yml` reports to. That is the whole list; a transfer between owners keeps a repository's secrets, and it kept these.
|
|
|
|
## 4. Artifact & support policy
|
|
|
|
Two active lines at most: latest release gets features; previous minor gets security-only patches for 90 days. Users move between versions by downloading from the Releases page — there is no update channel to target. MSI provided for org deployment; winget manifest submission is P2 (tracked in ROADMAP), and would be the natural place to add an upgrade path that is not PipDock's own code.
|
|
|
|
## 5. Repo scaffolding checklist (day one)
|
|
|
|
- [x] GPL-3.0 `LICENSE` at root; `legal/` committed **publicly** (the in-app legal gate links to these GitHub URLs — CommandForge lesson: don't leave them gitignored).
|
|
- [x] `.github/ISSUE_TEMPLATE/bug_report.yml` (shipped in this suite) + `config.yml` disabling blank issues.
|
|
- [x] `.github/dependabot.yml` covering cargo, npm, github-actions and the Code Health pins — and the Rust toolchain since 1.4.0.
|
|
- [x] `rust-toolchain.toml`, `.nvmrc` (26 — it said 24 until 1.5.0, a month after every workflow had moved to 26), `Cargo.lock`/`package-lock.json` committed.
|
|
- [x] **Repo settings (owner, via the GitHub UI or `gh` — not committable):** branch protection on `main`; disable Advanced Security → CodeQL *Default setup* (`codeql.yml` is an advanced setup, and is rejected at upload time otherwise); enable Discussions for the issue-template contact links.
|
|
- [x] **Secrets via `gh secret set`:** the Discord webhooks (`DISCORD_RELEASES_WEBHOOK`, `DISCORD_REPO_WEBHOOK`, `DISCORD_CI_WEBHOOK`), `SONAR_TOKEN`, `QODANA_TOKEN_RUST`, `QODANA_TOKEN_TS_JS` (§3). No signing key — see §3.
|
|
- [x] App icon settled (`src-tauri/icons/`). It was called a placeholder because nobody had chosen it; the owner chose it in Phase 4, which is what "a brand decision" needed.
|
|
- [x] README badges: CI, CodeQL, release, license.
|
|
- [x] **Labels (owner, repo settings — opened by 1.4.0):** `dependencies`, `rust`, `frontend`, `ci` and `code-health` for Dependabot (§2), and `triage` for `bug_report.yml`. None existed on 2026-10-17; all six did by 2026-11-10, when `accessibility` joined them for `accessibility.yml`.
|
|
- [x] **Community health files (1.5.0):** `ACCESSIBILITY.md`, `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1) at the root; `.github/PULL_REQUEST_TEMPLATE.md` and `.github/ISSUE_TEMPLATE/accessibility.yml`; and a repository description. The ops repo's description says it carries community health files and it carries none, so nothing was inherited. `bug_report.yml` keeps its name: `crates/pipdock-core/src/report.rs` builds the in-app *Report bug* link from it.
|
|
|
|
**Closed 2026-08-14, and three of the last four were already true.** CodeQL *Default setup* read
|
|
`not-configured` and Discussions were already on — both had been done and never ticked, which is
|
|
its own small lesson about a checklist nobody reads back. The Discord secrets were set the same
|
|
day. Branch protection was the only genuinely outstanding item; §2's exact settings are above.
|