CI

A fresh Google Cloud for every job.

The CloudBurrow GitHub Action starts a kind cluster, exports the SDK environment for every later step, and deletes the cluster when the job ends. Plain shell works on any other runner with Docker.

Get started
Test workflow

Choose a runner and follow the job.

Use the pinned GitHub Action or the shell recipe, then see how setup, test calls and cleanup fit together.

  • Pin the GitHub Action by commit SHA.
  • Use the shell recipe on other runners.
  • Follow setup and cleanup in the same job.
CloudBurrow Test workflow
At a glance

CI job outline

Provision
A local instance for the job
Connect
Export cloudburrow env
Finish
Clean up the instance
Inside test workflow

Go straight to the detail you need.

The workflow

From docs/ci.md at 0ea2594, verbatim except the version pin, which names the latest release, v0.4.0. Pin the action by commit SHA.

.github/workflows/test.ymlYAML
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      # kind and kubectl. Docker is already on GitHub's Ubuntu runners.
      - uses: helm/kind-action@06c1ae10762d3b9c1644e7fe69596ae519e015a2 # v1.15.0
        with:
          install_only: true
          version: v0.33.0
      - name: Install kubectl
        run: |
          curl -fsSLo kubectl "https://dl.k8s.io/release/v1.36.4/bin/linux/amd64/kubectl"
          chmod +x kubectl && sudo mv kubectl /usr/local/bin/

      # Pin the action by commit SHA, as for any third-party action.
      - uses: cloudburrow/cloudburrow@<commit-sha>
        with:
          version: v0.4.0            # or latest, or source (needs actions/setup-go)
          services: storage,pubsub   # default: CloudBurrow's defaults

      # STORAGE_EMULATOR_HOST, PUBSUB_EMULATOR_HOST, GOOGLE_CLOUD_PROJECT and the
      # rest of `cloudburrow env` are now set for every later step.
      - run: go test ./...

The action verifies the release archive's checksum and can verify its build attestation with a GitHub token. It checks Docker, kind and kubectl, starts the cluster and appends cloudburrow env to $GITHUB_ENV. Services without a standard emulator variable need the documented endpoint option.

Inputs

InputDefaultWhat it does
version latest Release tag to install (such as v0.4.0), latest, or source to build the repository the action was checked out from, which needs Go. Any release from v0.1.0 on works: the action passes only the flags the installed CLI has (docs/ci.md lists them).
services empty Comma-separated services to start. Empty starts CloudBurrow's defaults.
mode ephemeral State mode: ephemeral or persistent.
name empty Instance name. Empty means ci-<run id>-<job id>, so jobs never share one, even on a single self-hosted runner.
port-base empty Moves every fixed host port so the layout starts here (control at the base, ingress at base+80, console at base+90), as --port-base does. Empty keeps the defaults, from 9000. A distinct name gives each job its own cluster but not its own ports, so jobs sharing a self-hosted runner need a different base each, such as 9100 and 9200. Needs a CLI newer than v0.1.0: with v0.1.0 the step fails before starting anything.
timeout 10m How long to wait for the instance to become ready.
github-token ${{ github.token }} Used only to verify a release's build attestation with gh. Without one, the checksum is still verified.

The action ref and the installed CLI version are separate pins. The current action checks the installed version before using flags. Jobs sharing a self-hosted runner need separate port ranges, and the port-base input requires v0.3.0 or later; v0.1.0 has no --port-base. See version compatibility.

Afterwards, always

The cluster is deleted when the job ends, whether or not it passed.

A CI job with CloudBurrow One job lane: checkout, then cloudburrow/cloudburrow@<sha> (up), then your tests, then diagnose on failure, then cluster deleted (always). job checkout cloudburrow/cloudburrow@<sha> up your tests diagnose on failure cluster deleted always

To keep diagnostics from a failed run, write cloudburrow diagnose's redacted bundle in a step that runs only on failure. Keeping logs from a failed run

Other runners

Plain shell works on any runner with Docker, kind and kubectl.

ci.shShell
set -eu
# Install, verifying the checksum (and the attestation when gh is present).
curl -fsSL https://raw.githubusercontent.com/cloudburrow/cloudburrow/main/scripts/install.sh | sh -s -- --prefix "$HOME/.local"
export PATH="$HOME/.local/bin:$PATH"

NAME="ci-${CI_JOB_ID:-$$}"
FLAGS="--name $NAME --mode ephemeral --services storage,pubsub"

# Delete the cluster however the script exits.
trap 'cloudburrow delete $FLAGS' EXIT

cloudburrow up --detach $FLAGS        # exits 0 only once ready; 1 failed, 2 timed out
cloudburrow wait --timeout 1m $FLAGS
eval "$(cloudburrow env $FLAGS)"

go test ./...

Any runner, in shell, in docs/ci.md

How CloudBurrow tests itself

On every merge, the acceptance test deploys a Knative worker with kubectl. It uses official Go clients to upload an object, publish its name to Pub/Sub and check the worker’s output in Storage. Separate Go, Python and Node.js suites run against a live instance. The action's own tests cover a source build, the latest release and cleanup after a test fails. See the action self-test.

The acceptance flow Five steps in the local acceptance test: Upload an object, then Publish to Pub/Sub, then Cloud Run worker reads it, then Writes a result, then Result read back. Step 1 Upload an object official Go SDK Step 2 Publish to Pub/Sub official Go SDK Step 3 Cloud Run workerreads it Pub/Sub push Step 4 Writes a result official Go SDK Step 5 Result read back official Go SDK

Follow the acceptance test in the blog.

Develop locally

Build against Google Cloud APIs, locally

Free and open source under Apache-2.0. No account, no sign-up, no Google Cloud bill.

Get started