Appearance
Source:
docs/adr/0010-release-contract.md. Edit it there; this page is generated at build time.
A release is a v* tag on main that CI already passed, deployed by Deployer on the box, and a rollback is a flip that skips any release that never went live
The pieces were settled one ticket at a time: tag-triggered releases and a self-hosted runner (map #13), Deployer with local_archive (#18), migrations before the flip (#17), the encrypted env (ADR 0007), the layout (ADR 0008), the runner's job guard (#19) and the worker and cron (ADR 0009). This records them as one sequence, as .github/workflows/deploy.yml and deploy.php implement it. Everything here was rehearsed end to end on 2026-09-19 with Deployer 8.0.5 against a scratch box: two releases, a failed deploy, a rollback and a retry. Only the MySQL dump, systemd and crontab were stubbed, because the rehearsal ran on a Mac with SQLite. The rehearsal found three mistakes the design had on paper, and all three are fixed below.
From tag to live
git tag v1.4.0 && git push origin v1.4.0
│
├─ gate GitHub's runner. Fails without touching the box.
│ ├─ the tag is vMAJOR.MINOR.PATCH
│ ├─ the tagged commit is on main
│ └─ CI's push run on main passed for this commit (waits up to 20 min if it's still running)
│
├─ deploy the box, as `deploy`. Environment `production`.
│ ├─ checkout at the tag, install the pinned Deployer phar (checksummed)
│ └─ dep deploy production --tag=v1.4.0
│ ├─ lock, new release dir (releases/<n>), git archive of the tag
│ ├─ verify_revision REVISION must equal GITHUB_SHA
│ ├─ shared/ links, ACLs for www-data (ADR 0008)
│ ├─ composer install --no-dev
│ ├─ env:decrypt → shared/.env, 0600, via a temp file (ADR 0007)
│ ├─ npm ci, npm run build
│ ├─ storage:link, optimize (config/route/view/event/Filament caches)
│ ├─ migrate --pretend the SQL, into the Actions log
│ ├─ db:dump only if migrations are pending
│ ├─ migrate --force `current` still serves the old release
│ ├─ db:seed ShieldSeeder idempotent
│ ├─ ── FLIP ── current → releases/<n>, atomic rename
│ ├─ worker:install, crontab:sync (ADR 0009), schedule-monitor:sync
│ ├─ unlock, keep newest 5 releases
│ └─ artisan reload queue:restart + schedule:interrupt
│ └─ curl /up
│
└─ release-notes GitHub's runner; `gh release create --generate-notes`, skipped on a redeployTags are plain vMAJOR.MINOR.PATCH, on main, and the gate trusts CI instead of re-running it. The tagged commit is a commit on main, so CI's push run on it tested exactly the tree being released, and running Playwright a second time would prove nothing new. The gate waits for that run, because the natural sequence is to merge and then tag while CI is still going. It fails if the run failed, was cancelled, or doesn't exist. A tag on a branch commit fails at merge-base. CI's own concurrency cancels its run on an older commit when a newer push lands, so tag the newest commit on main. Redeploying a tag older than the Actions run retention period fails the gate. For that case, roll back instead.
--tag, plus a check, rather than --revision=$GITHUB_SHA. The research recommended --revision to pin the commit, but Deployer then logs the SHA as the release's target and dep releases stops showing tags, which is what ADR 0008 promised for reading the box. So the deploy passes the tag, and deploy:verify_revision fails the release unless Deployer's REVISION equals the commit the workflow was triggered for. A tag moved between push and checkout fails there. Rehearsed.
env:decrypt runs after deploy:vendors, not after deploy:shared as ADR 0007 has it. The rehearsal failed there: artisan cannot boot without vendor/. composer install runs package:discover against whatever shared/.env holds at that moment, and that is harmless because discovery doesn't read env values. What still matters is that decryption happens before artisan:optimize, which caches the config.
The config rolls back with the code even though .env is shared. optimize writes bootstrap/cache/config.php into each release (ADR 0008 keeps bootstrap/cache per release), and nothing outside config/ calls env(). So a flip back to an older release runs on the config that release was built with, and the newer shared/.env it leaves behind is never read. This is what ADR 0007's argument that "a tag carries the config it shipped with" rests on for rollback. env() in a controller would break it silently.
The dump happens only when a migration is pending. migrate:status --pending=2 exits 2 when there's pending work, and exit 1 (no migrations table, the first deploy) also takes a dump. It is written by app:dump-database, not by a mysqldump line, because the only copy of the password is the decrypted, cached config: the command writes it to a 0600 option file, never to argv. MySQL 8.0.46's own parser confirmed the quoting with a quote, a backslash and a #. The dump pipes through bash -o pipefail so that a half-finished dump fails the deploy rather than leaving a truncated file that looks like a backup. The newest ten are kept in /var/backups/blog-filament (ADR 0008).
ShieldSeeder runs on every deploy. It is firstOrCreate plus a sync of super_admin's own list, so re-running it is safe. Without it, a release that adds a resource ships something nobody, super_admin included, can see until someone remembers to seed.
schedule-monitor:sync runs after the flip, and not on rollback. It deletes monitors, along with their history, for tasks that are no longer scheduled. Running it after the flip means a deploy that fails earlier leaves the history alone. After a rollback, the Scheduler page reports the newer release's added tasks as late until the next deploy. That is true, since they are no longer running, and it is cheaper than discarding their history at the moment someone is investigating why the release was rolled back.
No maintenance mode. Migrations are additive against the previous release (CLAUDE.md), so the old code keeps serving while they run, and the flip is a single rename. down would add downtime and protect nothing.
One deploy at a time, never cancelled. The workflow's concurrency group is production, with cancel-in-progress: false, because a cancelled deploy can stop between migrate and the flip. GitHub keeps only one waiting run per group, so a third tag pushed while one run is deploying and another is waiting replaces the waiting one.
The production Environment has no required reviewers. Required reviewers aren't available on this plan for a private repo, and pushing a tag is already the deliberate act. The Environment is still where each deploy, its commit and its logs are listed, and its URL makes the Production tab link to the site.
Release notes come from GitHub's generator, after the deploy succeeds, on GitHub's runner. That keeps the box from ever holding a token that can write to the repo. They are generated from PR titles, which here already say what changed.
Where failure leaves things
- Before the flip (gate, build, decrypt, npm, dump, migrate): the old release keeps serving, and that holds by construction because nothing before
deploy:symlinktouchescurrent. The half-built release is markedBAD_RELEASE, thereleasesymlink is removed and the lock is released. Re-running the job is the whole recovery, and it gets a new release number (ADR 0008). Ifmigrateitself failed partway, MySQL has no transactional DDL, so the schema may be half-changed. The dump from that deploy is in/var/backups/blog-filament. - After the flip (worker, cron, sync, reload,
/up): the new release is live and the job is red. Nothing is marked bad, because it went live. Look at why before deciding to roll back.
Marking the failed release is not optional. The rehearsal showed that Deployer's rollback walks back through every logged release and skips only those marked BAD_RELEASE. So after a failed deploy, rollback picked the half-built release and flipped the site onto a directory with no vendor/. It also showed that the release symlink a failed deploy leaves behind makes every later artisan task run against the broken release, including the reload after a rollback. deploy:mark_failed handles both and runs only while the release symlink exists, which is only before the flip. tests/Feature/DeployContractTest.php pins it.
The lock is released on failure. The earlier lean was to leave it, but the Actions concurrency group already serialises deploys, so the lock protects nothing a retry could break. Leaving it would turn every flaky npm ci into an SSH session to run dep deploy:unlock.
Rolling back
Rolling back flips current to the previous release that went live, marks the release it left BAD_RELEASE, and then runs artisan reload so the worker follows (ADR 0009). It never touches the database. That is safe because every migration is additive against the release before it, and it is why the drop half of a destructive migration ships a release later (CLAUDE.md).
- From GitHub: Actions → Deploy → Run workflow, choosing any tag under "Use workflow from" (the runner refuses the job if it runs from
main), and tickrollback. - From the box, when GitHub is down:
cd /var/www/blog-filament/current && ~/.local/bin/dep rollback production.
Both run the same command, from the live release's own deploy.php. Every release carries one, and the pinned phar lives in ~/.local/bin, outside both the release tree and the runner's workspace, so neither needs GitHub. Redeploying an older tag through the workflow, without rollback ticked, is the other way back. It builds that tag fresh with its own encrypted env, and its migrations are a no-op because the schema is already ahead.
What this gives up: a rollback cannot undo a schema change, and a dump restore loses every write since the deploy. The first deploy, and any deploy before issue #23 enables the vhost, has a /up check that reaches whatever currently answers for the domain, which is not this release.