dev-deploy

Generic dev deployments for your repositories. When update-manager pushes a branch update-manager/<stamp> to a repo, that repo's workflow checks it and deploys it to https://<repo>.<DEV_DOMAIN> on the dev server. One slot per repo: the newest branch replaces the previous one.

What a run does (templates/dev.yml):

1. check: delete node_modules + package-lock.json, npm install, then typecheck, test, build (each skipped if the project has no such script). A failure stops the run; nothing is deployed.
2. deploy: regenerate package-lock.json from scratch (no install), then dev-deploy.sh: docker compose -p dev-<repo> up -d --build with a generated override that publishes no host ports, puts the web service behind Traefik, and swaps every env_file for the dev env. The Dockerfile's npm ci then builds exactly the dependency set the check job tested. Finally it waits until the app answers.
3. notify: optional Telegram message.

Confirming an update (button "Confirm update" on the project page, newest open branch only): update-manager merges the branch into its base branch (--no-ff, commit trailer Update-Manager-Merged: <branch>), pushes the base branch and deletes the update branch. That push starts templates/dev-cleanup.yml, which runs dev-teardown.sh: it removes every container, volume, network and dev-built image of dev-<repo> (found by the compose project label), so Traefik drops the route too. Ordinary pushes to the base branch don't touch dev. The deploy key needs write access to the base branch (not protected against it).

One-time setup (shared by all repos, in Forgejo user settings -> Actions)

Variables: DEV_DOMAIN (e.g. dev.domain.tld; optional TRAEFIK_NETWORK if not frontend). Secrets: DEV_REGISTRY_USER + DEV_REGISTRY_TOKEN (a Forgejo token with read:package, so compose can pull your private images; optional DEV_TELEGRAM_BOT_TOKEN / DEV_TELEGRAM_CHAT_ID.) DNS: wildcard *.dev.domain.tld -> dev server. Create a public repo gonereng/dev-deploy containing the contents of this folder (the template clones it; it holds no secrets).

Adding a repo

1. Copy templates/dev.yml and templates/dev-cleanup.yml to <repo>/.forgejo/workflows/ (both must exist on the base branch update-manager branches from and merges into).
2. Add .env.dev to the repo: dev settings that are not secret. It replaces .env for dev, so the compose file's own .env is never used. Add .env.dev to .dockerignore.
3. Secrets for that repo go into a Forgejo repo secret DEV_ENV (plain env-file lines, multi-line is fine). It is appended after .env.dev, so it wins on duplicate keys.
4. Optional in the workflow's deploy step: DEV_SERVICE, DEV_PORT, DEV_HEALTH_PATH (defaults: first service that publishes a port, its container port, /).

Compose file requirements

• Use named volumes, not ./relative bind mounts: the compose CLI runs in a job container, so relative paths would not exist on the host daemon.
• Host ports: are ignored in dev (removed by the override); Traefik reaches the web service on the shared network. Fixed container_name values can collide between projects, so avoid them.
• Private images from the Forgejo registry work through the DEV_REGISTRY_* secrets.

Reference

dev-deploy.sh documents all environment variables at the top. gen-override.mjs builds the override. dev-teardown.sh removes a dev instance (set DEV_SLUG there too if you set it for the deploy). Reset a repo's dev data: docker compose -p dev-<repo> down -v on the dev server.