Deployments

A deploy has two halves. A build turns one commit into a release: a packed copy of your application, made once. A deployment puts a release on an environment. Keeping them apart is what makes staging and production run the same bytes rather than two builds of the same commit, and what makes going back a matter of deploying an older release rather than building one again.

Connecting your repository

A repository host is connected once, on the team, and every project on the team can then use it. It needs the Admin role.

Host	How it connects	Self-hosted
GitHub	Install the Vallic GitHub App, from the team's settings, on the repositories you choose	No — github.com only
GitLab	An access token with read access, and the address of the instance	Yes
Gitea	The same	Yes

GitHub needs nothing else: the App receives your pushes by itself.

GitLab and Gitea need a webhook adding on the host. When you save the connection, the console shows the webhook address and its secret once. Add a push webhook with both, because without it pushes never reach us. The token is checked against the host before it is kept, and is stored encrypted and never shown again.

Then attach a repository to the project. A project's repository cannot be changed afterwards — its releases, its history and its branches all belong to that repository. If the code has moved, reconnect (for a renamed repository or a reinstalled App, which is safe — pushes are matched by the host's own repository id, not its name) or create a project for the new one.

Which branch, and deploying on push

Each environment tracks one branch, chosen under Source on the environment. Two environments of one project cannot track the same branch: they would be two copies of one site, both built from every push.

Deploy on push is off until you turn it on — production included. When it is on, a push to the tracked branch builds that commit and deploys it to every environment that tracks the branch and has it switched on.

When it is off, a push does nothing, not even a build. You deploy when you decide to, from the console.

• Only branches. Pushing a tag deploys nothing.
• The same commit twice is not two deploys on GitLab and Gitea: a push of a commit already built from that branch is skipped. Use Redeploy.
• Switching the branch does not move what is running. The next push, or the next deploy you ask for, builds from the new one. Until then the old branch's release can still be redeployed, but not rolled back to an older one of that branch.
• On GitHub, deleting a branch deletes the development environments built from it, along with their backups — a feature branch that has been merged and deleted takes its environment with it. GitLab and Gitea do not do this.

Deploying by hand

Deploy on the environment asks one question first:

• Build the latest from branch — shows the commit the branch points at and its message, builds it now and deploys it here when the build is done, whether or not Deploy on push is on.
• Deploy an existing release — the last ten releases built from this environment's branch, each with its number, commit, message and age. The one running now is marked; choosing it deploys it again. The last three this environment unpacked are marked on the machine and go live at once; older ones say from storage and are downloaded again first.

Skip deploy steps applies to either: a new build goes live without them when it finishes, and only here — another environment watching the branch runs its own. vallic build --deploy --skip-steps does the same.

Each environment numbers its own releases. Production's release 4 and staging's release 12 can be the same build, or different branches entirely: an environment counts the builds of the branch it runs and anything deployed to it. The numbers on an environment's pages, in its notifications and in vallic release list <environment> are that environment's; it is also what vallic deploy --release takes. The API keeps the project's own number as number, and gives every environment's under numbers.

An environment only runs its own branch. A release built from another branch is not offered, and the API refuses it too. To get main onto a development environment, merge main into that environment's branch and push; to get a feature into production, merge it into production's branch. What an environment runs is always what its branch says.

You cannot build an arbitrary commit from the console. Push it to a branch.

One deployment at a time per environment. While one is queued or running, another is refused, not queued behind it — including one started by a push. A push whose build finishes while the environment is busy is not deployed there; deploy it by hand when the first is done.

Deploying needs the Developer role, on every environment.

What a deploy does

The build runs first, on one of your project's own machines:

1. The repository is cloned at the exact commit.
2. The build steps from vallic.yaml run, and nothing else — nothing is guessed from your files.
3. The result is packed, checksummed and stored. That is the release.

A build has 25 minutes. Its log is under Activity.

Then, on the environment:

1. vallic.yaml is read at the deployed commit. A missing variable, an unknown service or anything else it cannot satisfy refuses the deploy before anything changes, listing every reason at once.
2. If the release asks for a service the environment does not run yet, or a different runtime version, that is set up first.
3. The release is downloaded, its checksum verified, and unpacked beside the one that is running. The directories that outlive a release — your framework's files directory, and any mounts — are linked into it.
4. The switch. The current link is moved to the new release in one step. There is no moment where half the files are old and half are new.
5. PHP-FPM is reloaded gracefully. Requests in flight finish on the old code; the next ones get the new. Workers and non-PHP applications are restarted.
6. The deploy steps run — against the release that is already live.
7. The health path is asked until it answers, if you named one.
8. Cron is written for the new release, and old releases are tidied away.

If the new release's stack will not start at step 5, the switch is undone and the previous release keeps serving.

Your site stays up

The platform does not put your site into maintenance mode during a deploy, and does not take it offline. Visitors are served throughout — by the old release up to the switch, and by the new one after it.

The consequence is step 6: your migrations run while the new code is already answering requests. For most changes that is the right trade — a site that never goes down for a deploy — but a migration the new code cannot run without will see a few requests arrive before it has finished. If a change needs the site quiet, turn on your framework's own maintenance mode as the first deploy step and off as the last, or take the site offline yourself from the Routing tab.

When a deploy step fails

The deployment is marked failed, and by default the new release stays live: its code is already serving, and the platform does not guess whether going back is safer than staying.

With on_failure: rollback in vallic.yaml, the previous release is put back instead. See Configuration.

Either way your database is not touched. A migration that ran half-way has changed the schema, and no release switch undoes that — which is what the backup you take before a risky migration is for.

The first deploy

An environment's first release skips the deploy steps when the environment has a database. Nothing is installed in it yet, so a step that updates a schema — drush deploy, artisan migrate — would fail and take the release with it. Install the site or import a database once the release is serving; every deploy after that runs the steps. Retrying a failed first deploy skips them too.

Any deploy can skip them on request: tick Skip deploy steps in the Deploy dialog, run vallic deploy --skip-steps, or send {"skip_steps": true} to the API. Use it for a step that is failing, or before importing a database.

More than one web machine

One machine deploys first and is the only one that runs the deploy steps and cron, so a migration runs once rather than once per machine. The others then follow one at a time, each taken out of rotation while it switches where the load balancer allows it, so the site never has all its machines switching at once. If the first machine fails, the rest are not deployed.

Going back

Open Deploy and choose an earlier release of the environment's branch. It is deployed like any other: the same artifact, the same switch, the deploy steps run again.

That makes it quick, because nothing is built. It also means going back is code only. Nothing reverses a migration; if the release you are leaving changed the schema, the older code meets the newer schema. Deploy steps that are safe to run twice — drush deploy, migrate — are what keep that survivable.

Redeploy deploys the running release again — to re-run deploy steps that failed for a reason that has since gone, for example.

How far back

Each machine keeps the live release and the two before it on disk. Older releases are kept in storage: the five newest always, and others for up to 30 days, to at most ten — never counting away one that is deployed somewhere. A release older than that has expired and can no longer be deployed — build it again from its commit.

Following a deploy

Activity on the team lists every build and deployment, with a filter for them. Each one shows its full log, including what your build and deploy steps printed. Anyone on the team can read it.

On GitHub, each commit gets check runs: Vallic / build for the build, and Vallic / environment for each deployment it went to, linking back to the log. GitLab and Gitea get no commit statuses.

Who can do what

	Role needed
Read builds, deployments and their logs	Viewer
Deploy, redeploy, go back	Developer
Change an environment's branch or Deploy on push	Developer — Owner on a protected environment
Connect a host, attach a repository	Admin

See Teams.

Next

• Configuration — the build, deploy and health keys
• Backups — the copy to take before a risky migration