Automated Deployments with GitHub Actions

An app deploys one branch of a GitHub repository to the Spark servers you choose, and Carpathian fetches, builds and switches each release for you. One app can run on several servers, and one server can run several apps. Nothing has to be cloned or prepared on the server first. A release that fails to build never replaces the one that is serving, and an earlier release can be restored in one step.

Connect GitHub

Connect the GitHub account or organization that owns the repository once, and every app in your organization can deploy from it.

1. Open Deployments, then GitHub Accounts, and choose Connect GitHub. You can also start from New App. GitHub opens in a new tab.
2. On GitHub, install the Carpathian app on your personal account or an organization. GitHub asks which repositories the app can see. Choose Only select repositories and pick the ones you will deploy; one is enough. All repositories also works, and includes repositories you create later. Either way, each deployment can only read the one repository it deploys.
3. GitHub asks you to sign in to confirm it is you, then shows the account connected. Switch back to the tab you started in and the account is there.

If the app is already installed on a GitHub account, choose Use an Existing Installation and pick the account from the list. Connecting needs the Connect GitHub permission and two-factor authentication.

To give Carpathian access to more repositories later, change the app's repository access on GitHub.

Disconnecting an account stops every app that deploys from its repositories until it is connected again.

Create an app

Open Deployments and choose New App, or choose Deploy an App from a server's menu to start with that server already picked.

App. Give the app a name, such as storefront or api.

Repository. Choose the GitHub account, the repository, and the branch to deploy.

Servers. Add each server the app runs on. App directory is where its releases live on that server, /var/www/<app name> when left empty. Two apps on the same server need different directories.

Deploying.

• Deployment on turns deployments for this server on or off.
• Deploy on push deploys every push to the branch.
• Wait for checks to pass holds each deployment until the commit's GitHub checks finish, and skips the commit if any of them fail.

Releases.

• Releases to keep is how many finished releases stay on each server for rollback.
• Health check URL is an address the server must answer after each restart, for example http://127.0.0.1:8000/health. Leave it empty to skip the check.
• Shared files are paths, one per line, that stay the same across releases, such as .env or storage/. A path ending in / is a folder.

Steps. Each step builds and restarts one part of your app. Pick a framework to fill in common commands, or write your own. Folder in repository is where that part lives in a repository that holds more than one app, such as backend or frontend. Each step has a build command and a restart command, plus optional commands before the build and after the restart.

Around every deploy. Commands that run once per deployment, before the build starts and after everything has restarted, such as turning a maintenance page on and off.

Choose Create App and the app's page opens. Change anything later under its Settings tab.

What happens on every deploy

Each server is deployed on its own, so one server failing a build or a health check does not affect the others.

1. Carpathian connects to the server and creates releases/ and shared/ inside the app directory. If git is missing it is installed.
2. The exact commit is fetched into a new folder, releases/<date>-<commit>. Only that commit is downloaded, and no GitHub credentials are left on the server.
3. Shared files are linked into the new release.
4. Your before-deploy command runs in the release that is live now.
5. Each step builds inside the new release. If a build fails, the new release is removed and the live release keeps serving.
6. current is switched to the new release in a single step, so there is never a half-switched moment.
7. Each step restarts from current, your after-deploy command runs, and the health check runs.
8. If a restart, the after-deploy command, or the health check fails, current is switched back to the previous release and restarted. The deployment shows Rolled back and you are notified.
9. Releases beyond the number you keep are removed. The live release and the one before it are always kept.

Point your web server and services at <app directory>/current, for example /var/www/app/current/backend, so they follow each switch.

Every command can read CARPATHIAN_APP_ROOT, CARPATHIAN_RELEASE_DIR, CARPATHIAN_COMMIT and CARPATHIAN_BRANCH.

Releases, redeploy and roll back

An app's Servers tab shows each server with its latest deployment, and History lists every deployment with its status: Waiting on checks, Queued, Deploying with the step it is on, Live, Failed, Rolled back, or Cancelled. A queued deployment is cancelled when a newer commit is queued for the same app on the same server, so only the latest one ships. A server's own Deployments tab lists the apps on it and their history.

• Deploy Now deploys the branch's latest commit to one server, and Deploy to All to every server of the app.
• Redeploy builds and ships the same commit again as a new release.
• Roll Back switches that server back to a release that went live earlier, without rebuilding it. It is offered while that release is still on the server.
• View Log shows the output of every step.

Each deployment also appears on the commit in GitHub, with a link back to the server.

Waiting for checks to pass

With Wait for checks to pass on, a pushed commit is held until its GitHub checks and commit statuses finish. It deploys once they pass, or straight away when the commit has no checks. A failed check cancels it and you are notified. A commit whose checks are still running after an hour is cancelled.

Deploying from your own CI

If your pipeline should decide when to ship, turn Deploy on push off and call the deployment API with a deployment key for the server. Create the key under API Keys with the deployment scope.

# .github/workflows/deploy.yml
name: Deploy to Carpathian
on:
  workflow_run:
    workflows: [Tests]
    types: [completed]
jobs:
  deploy:
    if: github.event.workflow_run.conclusion == 'success'
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        env:
          CARPATHIAN_API_KEY: ${{ secrets.CARPATHIAN_API_KEY }}
          APP: your-app-id
          COMMIT: ${{ github.event.workflow_run.head_sha }}
        run: |
          curl -fsS -X POST https://api.carpathian.ai/api/v1/deployment/trigger \
            -H "Authorization: Bearer $CARPATHIAN_API_KEY" \
            -H "Content-Type: application/json" \
            -d "{\"app\": \"$APP\", \"commit\": \"$COMMIT\"}"

The key deploys to its own server. app is the app's id, the last part of its page address, and can be left out when only one app runs on that server. commit is optional and must be the full 40-character commit; without it, the branch's latest commit is deployed. The response includes a deployment_id; follow it with GET /api/v1/deployment/status/<deployment_id> and GET/api/v1/deployment/logs/<deployment_id>.

Moving a server from the old setup

Each server that deployed by pulling a copy already on the server became an app named after its repository, with that server and its old deploy directory. It is turned off until a repository is connected. To move one over:

1. Connect GitHub, then open the app under Deployments and go to Settings.
2. Choose the repository and branch, and check the server's App directory.
3. Turn Deployment on and save, then choose Deploy Now on the Servers tab.
4. Point your services and web server at <app directory>/current instead of the old directory.

If <app directory>/current already exists as a folder, the first deployment stops and asks you to move it aside.