Deploy on every push

From a first deployment by hand to one on every push, from GitHub Actions or GitLab CI/CD, with a credential that cannot do more, and what happens when a release fails.

Half an hour. By the end a push to your main branch deploys by itself, the job goes red when the release is bad, and a bad release does not take the site down.

Before you start

  • The CLI, installed and signed in. See Installing the CLI.
  • A repository on GitHub or GitLab, connected to your organization. isogrid repos list must show it, with create-app and deploy in the YOU column. See Git repositories.
  • jq on your machine, for step 2.

This tutorial calls the application shop and the repository acme/shop.

1. Deploy once by hand

isogrid apps create --name shop --url https://github.com/acme/shop \
  --replicas 2 --public --wait

You should see Build #1 succeeded., then shop is running. and its address. Open it.

Do not skip this step. A pipeline that fails on its first run may be failing because of the credential, the variables or the application. Deployed by hand first, only the application can be wrong.

Two copies, not one. With a single copy there is nowhere to start the new version while the old one serves, so every deployment has a gap of a few seconds.

2. Mint a credential for the pipeline

Not yours. One for CI alone, which can be revoked without signing you out:

export ISOGRID_CONFIG_HOME="$(mktemp -d)"
isogrid --api https://api.isogrid.skyvault.pro login \
  --scope application:write-any \
  --name shop-ci

The browser opens on the approval page. Check the organization shown there: the credential is pinned to it and is refused anywhere else. Approve, then print the token and remove the temporary configuration:

jq -r '.contexts[].token' "$ISOGRID_CONFIG_HOME/config.json"
rm -rf "$ISOGRID_CONFIG_HOME"
unset ISOGRID_CONFIG_HOME

You should see one long line: the token. Copy it now.

Do not forget the last line. Without it, this terminal keeps looking for your sign-in in a directory that no longer exists.

The scope is deliberately short. The application exists, so the pipeline does not need application:create, and a typo in its name fails instead of creating a second application. application:deploy-any is narrower still, and enough as long as the pipeline passes no settings: no environment file, no change of branch.

A credential lasts 90 days unless you chose a shorter life on the approval page. Put the date in your calendar.

3. Give it to the CI system

GitHub, under Settings → Secrets and variables → Actions: a secret named ISOGRID_TOKEN, and a variable named ISOGRID_API_URL with the value https://api.isogrid.skyvault.pro.

GitLab, under Settings → CI/CD → Variables: ISOGRID_TOKEN, marked Masked, and ISOGRID_API_URL.

Mark the token Protected only if the branch that deploys is protected. A protected variable is not passed to other branches, and the job then says not signed in.

4. Add the pipeline

At the root of the repository:

isogrid ci init github --app shop
isogrid ci init gitlab --app shop

Run the one for your code host. You should see Wrote .github/workflows/isogrid-deploy.yml (or .gitlab-ci.yml), followed by the two settings from step 3. Commit the file and push.

--app must be the name from step 1. Left out, the pipeline uses the repository's name. If the two differ, it looks for an application that does not exist, tries to create it, and is refused, which is what the short scope is for.

An existing file is not overwritten. --output - prints the pipeline instead, so you can merge the job into the one you have.

5. Watch the first run

The push starts it. In the job's log you should see the CLI's version, then Started build, Build … succeeded. and shop is running. The job is green.

What it did: asked whether shop exists, built the exact commit you pushed rather than whatever the branch points to by then, and waited for the result.

If it goes red before building anything, make isogrid whoami the first command of the job. It prints who the credential belongs to, its organization and what it may do. not signed in means the token did not reach the job. A permission error means the scope.

6. Push a release that fails

Once, on purpose. Make the application exit at startup, and push.

You should see the job fail with shop was rolled back to the previous version, and the reason after it. Now open the address: the previous version still answers.

A red job with the site still up is the platform working. The new version never became healthy, so the old one was put back.

To see why, then fix it and push again:

isogrid apps status shop
isogrid apps logs shop

A build that fails stops the job earlier, and nothing is deployed at all.

7. Decide what a failure does

On the application's page, open Failed deploys.

  • Roll back automatically is the default: the previous version is restored as soon as a new copy fails.
  • Stop and let me decide stops the rollout at the first failed copy. Copies not yet replaced keep the previous version.
  • Never roll back gives every copy the new version even if some fail. Useful for debugging a release; the application may be down until you fix it.

Watch window (seconds) is how long a new copy must stay up to count as healthy: 30 by default, from 5 to 300. Raise it for an application that is slow to start, or a version that was going to be fine keeps being rolled back. Save policy; it applies from the next deployment.

None of this catches a release that starts correctly and is simply wrong. For that, the Roll back button at the top of the page returns to the version that ran before the last deployment: image, environment, secrets and size together. Then revert the commit and push. The next deployment applies the current settings again, and the next push would bring the bad commit back.

What to read next