Use hart in CI

A pipeline can drive a workspace the way you do: pull the new commit, Sync, prepare, test and run. hart reads its settings from environment variables, never asks a question it cannot answer, and exits with a code your pipeline can branch on.

Create an API key for the pipelineCopy Anchor Link

1. In the console, open Account settings → API keys and click Add API key.
2. Name it after the pipeline, for example CI shop, and pick an expiry.
3. Copy the key; it is shown once. Store it as a secret of your CI system, for example HART_TOKEN.

The key acts as you, with your roles. Running stages and Sync needs the Editor role on the workspace.

Tell hart where to goCopy Anchor Link

Set these variables in the pipeline; nothing else is needed, no hart login:

hart whoami checks them. The ids are in the console's addresses and in hart ws list -o json.

A pipeline scriptCopy Anchor Link

set -euo pipefail

hart whoami
hart ws wake --wait
hart git pull
hart sync --yes --wait
hart prepare -f
hart test -f
hart run

• hart ws wake --wait wakes the workspace if it sleeps: Sync and git pull work on the workspace's IDE, which reads harthelm.yml.
• hart git pull fast-forwards /data/app to the branch's new commit.
• hart sync --yes --wait applies the plan without asking and waits until the services have rolled out. With --yes a secret without a value fails the Sync instead of prompting; set secrets beforehand with hart secret set.
• hart prepare -f and hart test -f follow the output and fail when the stage fails.
• hart run starts the services.

Use hart sync --dry-run in a pull-request job to print the plan without changing anything.

An example workflowCopy Anchor Link

The same steps in a GitHub Actions-style workflow. Get hart from wherever your installation keeps its release archives; the address below is a placeholder.

name: deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      HART_API: https://console.example.com
      HART_TOKEN: ${{ secrets.HART_TOKEN }}
      HART_TEAM: "7"
      HART_WORKSPACE: "42"
    steps:
      - name: Install hart
        run: |
          curl -fsSL -o hart.tar.gz "https://downloads.example.com/hart_1.0.2_linux_amd64.tar.gz"
          tar -xzf hart.tar.gz hart
          sudo install -m 0755 hart /usr/local/bin/hart
      - name: Deploy
        run: |
          hart ws wake --wait
          hart git pull
          hart sync --yes --wait
          hart prepare -f
          hart test -f
          hart run

Check the archive against the release's SHA256SUMS file as in Install hart.

Exit codesCopy Anchor Link

The full list is under Exit codes. Messages go to stderr; -o json puts results on stdout for jq.

Wake and quotaCopy Anchor Link

hart ws wake reports why something cannot wake: the team's quota or the cluster has no room, or its nodes are switched off for the night. Retry later or make room. See Sleep and wake.

Next stepsCopy Anchor Link