A build turns one commit into a release: a packed copy of your application, made once. A deployment puts a release on an environment.
Connecting your repository
Connect a repository host once, on the team, for every project on 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. GitLab and Gitea need a push webhook:
- Save the connection. The console shows the webhook address and its secret once.
- Add a push webhook on the host with both. Without it, pushes never reach us.
The token is checked against the host before it is kept, then stored encrypted and never shown again.
Then attach a repository to the project. A project's repository cannot be changed afterwards. If the repository was renamed or the App reinstalled, reconnect: that is safe. For a new repository, create a project.
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.
Deploy on push is off until you turn it on, production included.
| Deploy on push | A push to the tracked branch |
|---|---|
| On | Builds that commit and deploys it to every environment that tracks the branch and has it switched on |
| Off | Does nothing, not even a build. You deploy from the console. |
- Only branches. Pushing a tag deploys nothing.
- 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 unprotected staging and development environments built from it, along with their backups. Protected ones are kept. GitLab and Gitea do not do this. See Protected environments.
Deploying by hand
Open Deploy on the environment and choose one:
| Choice | What it does |
|---|---|
| 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 | Lists the last ten releases built from this environment's branch, each with its number, commit, message and age |
In the list, the release 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 choice: a new build goes live without
them when it finishes. It applies only here: another environment watching the
branch runs its own. vallic build --deploy --skip-steps does the same.
Each environment numbers its own releases. It counts the builds of the
branch it runs and anything deployed to it, so production's release 4 and
staging's release 12 can be the same build, or different branches entirely.
Its pages, its notifications and vallic release list <environment> show that
number, and vallic deploy --release takes it. 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.
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, and the Admin role on production.
What a deploy does
The build runs first, on one of your project's own machines:
- The repository is cloned at the exact commit.
- The
buildsteps fromvallic.yamlrun, and nothing else. - 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:
vallic.yamlis 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.- A service the environment does not run yet, or a different runtime version, is set up if the release asks for it.
- The release is downloaded, its checksum verified, and unpacked beside the
running one. The directories that outlive a release are linked into it:
your framework's files directory and any
mounts. - The switch. The
currentlink is moved to the new release in one step. - 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.
- The
deploysteps run, against the release that is already live. - The
healthpath is asked until it answers, if you named one. - 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 get the old release up to the switch, and the new one after it.
Your migrations run at step 6, while the new code is already answering requests. A migration the new code cannot run without sees a few requests 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. By default the new release stays
live. 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. Take a backup before a risky migration.
The first deploy
A Drupal or WordPress 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 the site, drush deploy or wp core update-db, would fail. Retrying
a failed first deploy skips them too. Install the site or import a database
once the release is serving. Every deploy after that runs the steps, so a
script in them can do the install itself, as
Drupal's does.
Every other project runs its steps on the first release as on any other.
Laravel's artisan migrate, Doctrine's migrations, Django's migrate,
Alembic's upgrade, Rails's db:prepare and a Go, Node or Rust server's own
migrate create the schema in an empty database. Skipping them leaves the
site with no tables. A PHP application whose steps need an installed site
first, as a CMS's do, ticks Skip deploy steps on its first deploy.
Any deploy can skip its deploy steps, for a step that is failing or before importing a database:
- Console: tick Skip deploy steps in the Deploy dialog.
- CLI: run
vallic deploy --skip-steps. - API: send
{"skip_steps": true}.
Until a release has gone live, with nothing restored or synced into it, a
vallic.yaml naming PostgreSQL where the environment was created with
MariaDB, or the reverse, switches the database. After that the database is
fixed. See Configuration.
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. The others follow one at a time, each taken out of rotation while it switches where the load balancer allows it. If the first machine fails, the rest are not deployed.
Going back
Going back is code only: nothing reverses a migration.
Open Deploy and choose an earlier release of the environment's branch. It is deployed like any other, and the deploy steps run again. Nothing is built.
If the release you are leaving changed the schema, the older code meets the
newer schema. Deploy steps that are safe to run twice, such as drush deploy
and migrate, keep that survivable.
Redeploy deploys the running release again, for example to re-run deploy steps that failed for a reason that has since gone.
How far back
Each machine keeps the live release and the two before it on disk. Storage keeps the three newest successful builds, however old, and any release an environment is serving. Those are what Deploy offers. An older release has expired: it stays in the list of builds, and can be deployed again by building it 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 that link back to the log: Vallic / build for the build, and Vallic / environment for each deployment it went to. 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 — Admin on production |
| Change an environment's branch or Deploy on push | Developer — Owner on production |
| Protect a staging or development environment | Developer |
| Remove its protection | Admin |
| Connect a host, attach a repository | Admin |
See Teams.
Next
- Configuration — the
build,deployandhealthkeys - Backups — the copy to take before a risky migration
Thank you. Good to know it helped.
Thanks — tell us what was missing. Open a ticket from Support in the console, and we answer on the ticket. Open the console