Who this is for. Developers and leads who ship code to a Core dna site. Afterwards you can predict exactly what a push changes on the server, read a deploy's result, and prove which commit a site is running.
There is no upload step and no deploy button. Each environment of a site can be connected to one repository and one branch, in the Version Control part of the environment's details (Repository, Branch), and a push to that branch deploys it. Knowing exactly what the deploy does explains most deploy surprises.
What a push does
- The repository host calls the platform with the repository and the branch of the push. Bitbucket and GitHub webhooks are both understood.
- The platform finds every environment connected to that repository and branch, adds an entry to each one's Deployments list with the status
pending, and queues one deploy job for each. A push to a branch that no environment is connected to deploys nothing; the platform answers the webhook with "No sites setup for the repo … and branch …", which the repository host's webhook history shows. - Each job brings the environment's folder to the branch. It fetches, switches the folder to the branch if it was on another one, and resets it hard to the branch as it stands on the remote at that moment. Every file git tracks becomes what the branch says, whatever was on the server before (FTP and tracked files). Files git does not track are left alone.
- It clears the caches of every environment that shares the folder: the stored pages and their CDN copies, the compiled templates and the CDN's copies of theme files (what a deploy clears).
- It sets the entry's status to
successorfailed.
The jobs run on the platform's background queue, so a deploy takes effect shortly after the push, not at the moment of it, and later when the queue is busy. Because the job takes the branch as it is when the job runs, two pushes close together can both deploy the later commit. Nothing is built on the server: what is committed is what is served (Build before you push).
Branches and environments
Which branch feeds which environment is part of each environment's configuration. A typical site:
| Branch | Environment | Hostname |
|---|---|---|
master | Production, the site's primary environment | www.example.com |
staging | Staging | staging.example.com |
| Feature branches | None | Reviewed through pull requests, then merged into staging |
Two consequences follow. Merging into master is releasing to production: there is no further gate. And because the environments of a site share one database, staging shows production's content running staging's code (Environments).
The Deployments list
Each environment in the admin has a Deployments list, newest first, with the columns Created, Status, Repository, Branch, Commit, Author and Message. The git output of the deploy is not shown there. When a change is not live, it is the first place to look:
- No entry for the push: the branch or the repository is not the one this environment is connected to, or the webhook did not reach the platform. The repository host's webhook history shows the request and the platform's answer.
- An entry still
pending: the job has not run yet, or did not finish. Wait for the queue; if it stays pending, ask Core dna support to look at the job. - An entry marked
failed: the deploy did not complete, usually because the repository could not be fetched. Ask Core dna support for the job's output; the change is not live. - An entry marked
success, and the change is still not visible: the change was not in the commit (an unbuilt bundle is the classic case), or a browser or CDN is showing an old copy (is this copy stale).
Seeing which commit is live
$_currentSite->getLastVcsHash() returns the first seven characters of the commit of the current environment's newest Deployments entry, and getVcsBranch() the branch the environment is connected to. Use the hash as the version on asset URLs, so that every deploy makes browsers fetch the new files, and print it where you can read it: