Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.
CI/CD - GitHub Actions
Workflows
| Workflow | Runs on | Purpose |
|---|---|---|
ci.yml |
Pull requests, pushes to any branch except main, manual |
Type check, lint, test, build and bundle before anything reaches main |
deploy-backend.yml |
Pushes to main that touch the backend, manual |
Type check and test the backend, then deploy the Worker |
deploy-frontend.yml |
Pushes to main that touch the frontend, manual |
Type check and test the frontend, then build and deploy the app to Pages |
deploy-site.yml |
Pushes to main that touch the site, manual |
Type check and test the public site, then build and deploy it to Pages |
publish-scheduled.yml |
Minutes 7, 22, 37 and 52 of every hour (when GitHub starts them), manual | Publish due Instagram posts (fallback for the Worker cron) |
No workflow runs database migrations. The owner applies supabase/migrations/ with npm run db:check and npm run db:push before merging code that needs them (docs/workflows/DEPLOYMENT.md), and a change under supabase/ alone deploys nothing. CI checks the migration files through npm test (backend/tests/database/migrations.test.ts: names, real UTC versions, opening sentences, order, rollback pairs, repeatable baselines, closed functions, and a schema tree in supabase/schemas/ that matches the migrations) without a database. The supabase CLI is a root dev dependency, so npm ci installs it in every workflow, but no workflow calls it.
Nothing compiles TypeScript ahead of time: Wrangler and Vite strip the types while bundling, and Node strips them when it runs tests and scripts/publish-scheduled.ts. None of those steps checks types, so each workflow that ships code runs tsc first.
ci.yml
Trigger: pull_request (any branch), push to every branch except main, and workflow_dispatch. There are no path filters: every pull request and branch push is checked.
What it does (one job, "Type check, lint, test, build"):
- Checkout repo
actions/setup-node@v4with Node 24 and the npm cache keyed on the rootpackage-lock.jsonnpm ciat the repository root, thennode scripts/check-platform-packages.ts, which installs once more when npm skipped a platform packagenpm run typecheck- every TypeScript project: backend, backend tests, frontend, frontend tooling and tests, site, site build files and tests, scriptsnpm run lint- ESLint over the whole repositorynpm test- backend, frontend, then site testsnpm run build- Vite production builds of the frontend (without theVITE_*secrets) and then the sitenpx wrangler deploy --dry-run --outdir distinbackend/- bundles the Worker without deploying, which catches import and bundling errors
Required GitHub secrets: none.
Required status check. The repository ruleset Protect main requires this job, by its name Type check, lint, test, build, to pass on a pull request before it can merge into main, with the branch up to date. Renaming the job or the workflow's name: breaks that rule, so change the ruleset's required check in the same pull request (Settings, Rules, Rulesets, Protect main). See docs/workflows/GIT.md for the other rules.
deploy-backend.yml
Trigger: Push to main branch, when files under backend/** or shared/**, tsconfig.base.json, the root package.json, the root package-lock.json or .github/workflows/deploy-backend.yml change; also workflow_dispatch for a manual run
What it does:
- Checkout repo
actions/setup-node@v4with Node 24 and the npm cache keyed on the rootpackage-lock.jsonnpm ciat the repository root, which installs every workspace, including Wrangler, thennode scripts/check-platform-packages.ts, which installs once more when npm skipped a platform packagenpm run typecheck --workspace backend- checks the Worker source and the backend testsnpm test --workspace backend- Run
wrangler deployviacloudflare/wrangler-action@v4withworkingDirectory: backend. The action finds the Wrangler installed from the root lockfile (Wrangler 4, ADR-039) and uses it instead of installing its own default version.
A type error or failing test stops the run before the deploy step.
Required GitHub secrets:
CLOUDFLARE_API_TOKEN- API token with Worker deploy permissionCLOUDFLARE_ACCOUNT_ID- your Cloudflare account ID
The workflow does not set the Worker's own secrets (SUPABASE_*, FRONTEND_URL, the optional ALLOWED_ORIGINS, the optional email secrets SEND_EMAIL_HOOK_SECRET, RESEND_API_KEY, EMAIL_FROM and EMAIL_DAILY_LIMIT, the optional automation settings INSTAGRAM_WEBHOOK_VERIFY_TOKEN, META_APP_SECRET and AUTOMATION_*, the optional Claude settings TOKEN_ENCRYPTION_KEY, MCP_OAUTH_ENABLED, CLOUDINARY_API_KEY and CLOUDINARY_API_SECRET, the optional YouTube publishing settings GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET, and the rest). They are set once with npx wrangler secret put and kept across deploys; see WORKERS.md.
Does not redeploy on frontend-only changes, documentation changes, or script changes.
deploy-frontend.yml
Trigger: Push to main branch, when files under frontend/** or shared/**, tsconfig.base.json, the root package.json, the root package-lock.json or .github/workflows/deploy-frontend.yml change; also workflow_dispatch for a manual run
What it does:
- Checkout repo
actions/setup-node@v4with Node 24 and the npm cache keyed on the rootpackage-lock.jsonnpm ciat the repository root, which installs every workspace, thennode scripts/check-platform-packages.ts, which installs once more when npm skipped a platform packagenpm run typecheck --workspace frontend- checksfrontend/src(tsconfig.json) andvite.config.tsplus the frontend tests (tsconfig.node.json)npm test --workspace frontendnpm run build --workspace frontend- Vite builds tofrontend/dist/- Deploy
dist/to Cloudflare Pages viawrangler pages deploy(cloudflare/wrangler-action@v4withworkingDirectory: frontend, using the Wrangler from the lockfile)
Required GitHub secrets:
CLOUDFLARE_API_TOKENCLOUDFLARE_ACCOUNT_IDVITE_SUPABASE_URL- injected at build timeVITE_SUPABASE_ANON_KEY- injected at build timeVITE_API_URL- injected at build time (the Worker URL)VITE_ADMIN_EMAIL- optional, injected at build time; the administrator contact shown in the appVITE_GOOGLE_CLIENT_ID- optional, injected at build time; enables the Sign in with Google button
Note: VITE_* variables are baked into the built bundle at build time. They are not runtime environment variables.
deploy-site.yml
Trigger: Push to main branch, when files under site/**, tsconfig.base.json, the root package.json, the root package-lock.json or .github/workflows/deploy-site.yml change; also workflow_dispatch for a manual run
What it does:
- Checkout repo
actions/setup-node@v4with Node 24 and the npm cache keyed on the rootpackage-lock.jsonnpm ciat the repository root, which installs every workspace, including Wrangler, thennode scripts/check-platform-packages.ts, which installs once more when npm skipped a platform packagenpm run typecheck --workspace site- checkssite/src(tsconfig.json) andvite.config.ts,site/buildand the site tests (tsconfig.node.json)npm test --workspace sitenpm run build --workspace site- Vite builds tosite/dist/, and the docs plugin addssitemap.xmlandllms.txt- Deploy
dist/to the Cloudflare Pages projecttwiligent-siteviawrangler pages deploy dist --project-name=twiligent-site(cloudflare/wrangler-action@v4withworkingDirectory: site)
Required GitHub secrets:
CLOUDFLARE_API_TOKENCLOUDFLARE_ACCOUNT_ID
The site needs no other secret: every value it shows is public and lives in the source. The twiligent-site project must exist before the first run; see PAGES.md.
publish-scheduled.yml
Trigger:
schedule: cron('7,22,37,52 * * * *')- every 15 minutes, away from the top of the hourworkflow_dispatch- manual trigger from GitHub Actions UI
Run limits:
concurrency: { group: publish-scheduled, cancel-in-progress: false }- one run at a time; a run that starts while another is busy waits instead of cancelling ittimeout-minutes: 14- under the 20 minute claim lease, so a later run never takes over a post this run is still publishing. The script stops its Instagram calls at 12 minutes so every claimed post still gets its outcome saved
Timing is best effort. GitHub's documentation says scheduled runs can be delayed under high load, most of all at the start of every hour, and that queued runs can be dropped. Over two days this repository's runs came every 3 to 5 hours. The minutes 7, 22, 37 and 52 follow GitHub's advice to avoid the top of the hour, but the workflow still only catches what the Worker missed when GitHub gets to it.
What it does:
- Checkout repo
actions/setup-node@v4with Node 24 (no npm cache and no install: the script has no dependencies)node scripts/publish-scheduled.ts- Node runs the TypeScript file directly by stripping the types (Node 22.18 or newer; the workflow uses 24)
Required GitHub secrets:
SUPABASE_URL- the Supabase project URLSUPABASE_SERVICE_KEY- service-role key (needed to query all users' posts)
This is the GitHub Actions fallback for the Worker cron. Both this workflow and the Worker cron (*/5, publishing on the quarter hour) run the same publishing logic against the same Supabase table. A conditional claim with a 20 minute lease prevents double-publishing and lets a later run take over a post whose run died; see docs/architecture/data-flows/SCHEDULING.md.
The script imports the shared rules from backend/lib/scheduledPublishing.ts by relative path, and the workflow runs whatever is on the default branch, so a change to that file reaches this workflow on its next run without a deploy.
The script is type-checked by npm run typecheck (scripts/tsconfig.json) in ci.yml, not by this workflow.
Path Filtering
The deploy workflows use path filters; ci.yml does not.
- Editing
frontend/only -> triggersdeploy-frontend.yml, notdeploy-backend.ymlordeploy-site.yml - Editing
backend/only -> triggersdeploy-backend.yml, notdeploy-frontend.ymlordeploy-site.yml - Editing
site/only (including the docs pages insite/content/docs/) -> triggersdeploy-site.ymlonly - Editing
shared/-> triggers the backend and frontend deploys, because both apps import the shared types; the site does not use them - Editing
tsconfig.base.json-> triggers all three deploys, because every workspace extends the base config - Editing the root
package.jsonorpackage-lock.json-> triggers all three deploys, because the single lockfile pins the dependencies of every workspace - Editing root tooling config (
eslint.config.mjs,.prettierrc.json,.editorconfig) -> triggers no deploy;ci.ymlchecks it on the branch or pull request before it reachesmain - Editing
scripts/-> triggers neither deploy workflow (onlypublish-scheduled.ymlon its cron) - Editing
docs/-> triggers no deploy - Editing
CLAUDE.md,DECISIONS.md, etc. -> triggers no deploy
ci.yml runs on every pull request and every push to a branch other than main, whatever changed.
Deployment Verification
After a deploy, verify:
Backend:
curl https://twiligent.ujjwalkrai.workers.dev/api/health
# Should return: {"status":"ok","timestamp":"..."}
Frontend (the app):
Open https://app.twiligent.ujjwal.fyi - verify login page loads, accounts load after auth. Open https://app.twiligent.ujjwal.fyi/docs/self-host - verify it lands on the same page of the public docs.
Site:
Open https://twiligent.ujjwal.fyi - verify the home page renders, then open https://twiligent.ujjwal.fyi/docs and search for a term such as redis. Check that https://twiligent.ujjwal.fyi/sitemap.xml and https://twiligent.ujjwal.fyi/llms.txt load, and that https://twiligent.ujjwal.fyi/login redirects to the app.
Publisher:
Trigger publish-scheduled.yml manually via GitHub Actions UI -> Actions -> "Instagram Scheduled Publisher" -> "Run workflow" -> check the run log for expected output.
Platform Packages After Install
Native binaries such as workerd, esbuild, rollup, lightningcss and Tailwind's oxide are optional dependencies, one package per platform. npm skips an optional package it fails to download and still reports a successful install, so a run could reach the Worker bundle without @cloudflare/workerd-linux-64 (this happened once, on PR #81). scripts/check-platform-packages.ts reads the root package-lock.json, keeps the optional packages whose os, cpu and libc match the machine (the glibc and musl builds are told apart by name when the lockfile has no libc field), and exits 1 naming any that are missing. Every workflow runs it after npm ci and, if it fails, runs npm ci and the check once more; a second failure stops the job. Run it locally with node scripts/check-platform-packages.ts.
Pinned Actions
Every third-party action is pinned to a full commit SHA, with the tag it came from in a comment (actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4). Whoever controls an action's repository can move a tag to different code; a commit cannot change, so a compromised action release cannot reach the deploy secrets without a change to this repository. The @v4 mentions above name the version each pin came from.
Every workflow also sets permissions: contents: read, so the GITHUB_TOKEN a step receives can read the repository and nothing else; the deploys and the publisher reach Cloudflare, Supabase and Instagram with their own secrets.
To update a pin, resolve the new tag to its commit and replace the SHA and the comment together:
gh api repos/actions/checkout/commits/v4 --jq .sha
Adding a New Workflow
- Create
.github/workflows/my-workflow.yml - Add appropriate path filters to avoid unnecessary runs
- Pin every action to a full commit SHA with its tag in a comment (see Pinned Actions)
- If the workflow needs project dependencies, run
actions/setup-nodewith Node 24,cache-dependency-path: package-lock.jsonand the install step the other workflows use (npm ciat the repository root, thennode scripts/check-platform-packages.ts, installing again once if it fails); there are no lockfiles insidebackend/,frontend/orsite/ - If it ships code, run
npm run typecheck(or the workspace'stypecheckscript) before the deploy step - Document it in
docs/architecture/cloudflare/CI_CD.md(this file) - Add any required secrets via GitHub repo -> Settings -> Secrets -> Actions