Sync from deal-sage/deal-sage@13a420d134

2026-09-25 17:56:38 +00:00
commit 36aeaf65c3
13 changed files with 804 additions and 0 deletions
@@ -0,0 +1,77 @@
+# ci-actions — the platform-owned custom-app pipeline
+
+This directory is synced verbatim into the `dealsage-platform/ci-actions` repo on
+each environment's Gitea by `infra/gitea/gitea-org.sh` (the same way
+`templates/custom-app` is synced into the template repo), and tagged `v1` plus
+`v<VERSION>` from the `VERSION` file. App repos call it from a one-step
+workflow:
+
+```yaml
+- uses: https://git.dealsage.io/dealsage-platform/ci-actions/pipeline@v1
+  with:
+    publish-token: ${{ secrets.PUBLISH_TOKEN }}
+```
+
+Why it exists: an app repo receives its workflow once, when it is generated
+from the template, and never again. Keeping the pipeline here means a fix ships
+to every app on its next push, instead of being patched repo by repo.
+
+## What `pipeline` does
+
+| Step | Script | Notes |
+|---|---|---|
+| Tooling | `scripts/ensure-tools.sh` | curl + jq; AWS CLI only for the S3 upload path |
+| Manifest | `scripts/manifest.sh` | validates `.dealsage/app.json`, exports `APP_ID`, `CHECKS_JSON` |
+| Install | (action input) | `npm install --no-audit --no-fund` by default |
+| Checks | `scripts/run-checks.sh` | runs each declared check, posts every result to `record-app-check`; a failed **required** check stops here |
+| Build | `scripts/build.sh` | `npm run build` with `VITE_SUPABASE_URL/ANON_KEY` from org variables; recorded as the `build` check |
+| Publish | `scripts/publish.sh` | allocate → upload → promote request; DealSage applies the app's publish policy |
+
+The action never decides whether a build goes live. `record-app-version`'s
+`promote` action does, from the app's `publish_policy` and default branch, and
+answers `promoted: true|false` plus the channel the version landed on
+(`live` or `branch/<name>`). Every build of every branch becomes a version, so
+any of them can be opened by URL and promoted later.
+
+## The manifest (`.dealsage/app.json`)
+
+Owned by the app's team; schema in `manifest.schema.json`.
+
+```json
+{
+  "appId": "…",
+  "checks": [
+    { "id": "typecheck", "name": "TypeScript", "run": "npm run typecheck" },
+    { "id": "test", "name": "Unit tests", "run": "npm test -- --run", "required": true },
+    { "id": "conventions", "uses": "conventions", "required": false }
+  ],
+  "dependencies": { "objectTypes": [ { "apiName": "contract_agreement", "schemaVersion": 2 } ] }
+}
+```
+
+`required` defaults to true. Platform checks (`uses`) live in `pipeline/checks/`
+and run inside the same job; `conventions` verifies the repo still has the
+shape the platform relies on.
+
+## Environment the caller provides
+
+From org variables: `DEALSAGE_FUNCTIONS_URL`, `SUPABASE_URL`,
+`SUPABASE_ANON_KEY`, and either `CUSTOM_APPS_WORKER_URL` (bundles are PUT
+through the serving Worker with the short-lived upload token from `allocate`,
+so CI holds no R2 key) or `R2_ACCOUNT_ID` + `R2_BUCKET` with the
+`R2_ACCESS_KEY_ID` / `R2_SECRET_ACCESS_KEY` secrets (S3 sync, the path prod
+uses today). `PUBLISH_TOKEN` is the app's own repo secret.
+
+## Testing locally
+
+`test/run-local.sh` builds a throwaway app repo and runs the scripts against a
+stub DealSage (`test/stub_server.py`) for three scenarios: auto policy, a
+failing required check, and manual policy. Run it after any change here; it
+needs bash, jq, git, node and python3.
+
+## Releasing a change
+
+Bump `VERSION` for anything user-visible. Non-breaking changes keep the `v1`
+tag moving; a breaking change (new required input, different env contract)
+gets `v2` and a stub update in the template plus a platform-files refresh for
+existing apps.