Set up health checks, release retention and deployment alerts

A deployment that finishes is not necessarily a deployment that works. SrvYard therefore does a few things around the script: after the new release goes live it makes one request to your site to see that it answers, it prunes old releases so the disk does not fill, it keeps the folders that must survive (uploads, .env) in a shared place, and it tells people what happened. All of it is configured in Settings > Deployments and Settings > Notifications of the site.

This article covers each of those settings, what exactly the health check requests and when it passes, what retention removes and what it never touches, the shared paths, and the alert channels. The deploy hook address that sits on the same page is explained in Deploy from GitHub Actions and other CI.

Before you begin#

• A site that has deployed at least once. Most of these settings only matter once there are releases.
• A page that answers publicly or locally. Pick a path such as /up that returns a 2xx answer without logging in. Laravel ships a /up route in new applications.
• Permission to manage deployments. Members who can only view see the cards but not the buttons.
• A zero-downtime site for retention and shared paths. A site that deploys in place has no releases to keep; the Shared paths card says "Only used by zero-downtime deployments."

1. The health check#

Open Settings and choose Deployments. The Health checks card is the one with the switch.

1. Check the site after each deployment. Turn it on or off. The text under the title says "Any answer from 200 to 399 passes."
2. URL or path. "A path such as /up, or a full URL on one of this site's own domains. Empty checks the home page." Press Save to apply.

What SrvYard does, after the new release has been made live and PHP-FPM reloaded:

• With a path (or empty), it requests the page from the server itself, at http://127.0.0.1 with the primary domain as the Host header. It does not go through DNS, your CDN or the certificate, so it works before DNS points at the server and when HTTPS is misconfigured. Nginx still handles it, so password rules and redirects apply.
• With a full URL, it requests exactly that address from the server, which does go through DNS and HTTPS.
• It makes up to three attempts, three seconds apart, each limited to 20 seconds. Any answer from 200 to 399 on any attempt passes.
• If there is no primary domain and no URL, or the check cannot run at all, it is recorded as skipped and the deployment is not affected.

The deployment then ends as Finished (check passed or skipped) or Failed (check failed).

1. The failure message. "The health check returned HTTP 502 after the release was switched." A 502 or 504 usually means PHP-FPM or your application did not come up; "no response" means the request timed out.

The log ends with "The release is live but the health check failed. SrvYard does not roll back automatically: use Rollback on an earlier deployment if needed." The failed release is serving visitors, so decide quickly: fix forward, or roll back as described in Zero-downtime releases and rollbacks. A failed health check also sends the "site down" alert described below.

2. Release retention#

The Deployment retention card controls how many releases stay on the server.

1. Deployments to keep. A number from 1 to 50. A new site starts with 4. After each successful zero-downtime deployment SrvYard removes releases older than this number.
2. Save. Stores it.

Rules worth knowing:

• The live release and the one before it are never removed, so a rollback is always possible, even with the number set to 1.
• A lower number takes effect, and older releases are removed, at the next deployment, not when you save.
• A removed release cannot be rolled back to. In the history its name is struck through with "(removed)", and the rollback button explains: "This release was removed when older releases were pruned."
• Each release is a full copy of your application, including vendor and built assets. Multiply a release's size by the number you keep to see the disk you need.

The Deployments tab shows the current state as Releases kept (for example "4 of 4").

3. Shared paths#

Files that must not change with a release (uploaded files, the .env, logs) live once in a shared folder and are linked into every release.

1. The paths. The list shows what is shared now. Laravel, Statamic and other Laravel-based sites always share storage and .env; Symfony shares .env and var/log; other types share nothing until you add paths.
2. Manage. Opens the sheet (or View for members who cannot change it).

1. Always shared. The defaults for the site type. They cannot be removed.
2. Your paths. Type a path relative to the release, for example public/uploads: no leading slash, no .., up to 120 characters. Names such as releases, current and auth.json, and anything starting with .git, are refused.
3. Add. Adds it to the list.
4. Save shared paths. Applies from the next deployment. If the folder already exists inside a release, its content is copied to the shared folder the first time and then replaced by a link.

4. Get told what happened#

Open Settings > Notifications.

1. Email when a deployment fails. On by default for sites that deploy. Emails about this site's deployments go to the person who started it and to the organisation's owners and admins. It includes failed health checks. "Emails for successful deployments are not available yet."
2. Add channel. Sends the site's deployment events somewhere else.

1. Type. Slack, Discord, Telegram, Webhook or Email. Each shows its own fields, such as an incoming webhook URL (https only; private addresses are refused), a Telegram chat or a list of addresses. The webhook secret needs at least 16 characters and the payload is signed. Addresses and tokens are stored encrypted and never shown again.
2. Name. A label for the list, for example #deploys.
3. Events. Deployment started, Deployment finished and Deployment failed. Finished and failed are ticked by default; started is not.

Every failure is sent to the site's channels. A channel message names the site, the branch, the commit and the error.

5. GitHub deployments#

When the site's repository comes from a GitHub connection, the GitHub deployments card appears in the same Deployments section. With Create deployments in GitHub on, SrvYard creates a deployment record on the repository for every deploy with in-progress, success and failure statuses, so it shows on the repository and in pull requests. It needs a token with the repo scope. It is best effort: a token without the right access is skipped and never fails a deployment.

Troubleshooting#

• The health check fails but the site works in a browser. A path check hits 127.0.0.1 with the primary domain as host. If your application redirects every request to HTTPS or to another host, the answer is a 301 (which passes) but a 401, 403 or 404 does not. Use a public path such as /up.
• The health check always passes but the site is broken. It is checking the wrong thing. A static page answers even if the application is down; point it at a route that boots the application.
• "The health check returned HTTP 502". PHP-FPM is down or the new release fails to boot. Read the Laravel log on the Logs tab and fix or roll back.
• Old releases are not removed. Retention runs after a successful deployment. A failed or cancelled run does not prune.
• The disk is full of releases. Lower Deployments to keep and deploy once, or delete large build output from the deploy.
• No emails arrive. Check the Email when a deployment fails switch and the address of the person who started the run. Channels work independently of email.
• A shared path is refused. Remove the leading slash, any .. and names such as releases or current.

Related#

• Write and test a deploy script: what runs before the health check.
• Zero-downtime releases and rollbacks: what to do when a release is live but broken.
• Read a deployment log and find the failing step: where the health check result is written.
• Notification channels: email, Slack, Discord, webhooks: the organisation-wide channels.