CI Pipeline

This page covers the typical layout for incorporating Tazuna into a CI / CD pipeline in a repository that holds tazuna.yaml. Tazuna can be used both to apply from your local machine and to apply from CI. This page primarily focuses on the latter.

Typical Setup

By role, the pipeline divides into the following three stages.

“Verify” is fine to run on every PR. “Apply” is usually triggered by pushes to main. We recommend not making “Remove” a permanent fixture in CI (see Operating tazuna destroy).

Verification Stage

If you put tazuna.yaml on CI, the minimum bar to clear is to run tazuna check. It runs without touching the cluster, so the PR cost is nearly zero.

# GitHub Actions example (essentials only)
- name: tazuna check
  run: tazuna check -f tazuna.yaml

- name: tazuna build (preview)
  run: tazuna build -f tazuna.yaml > rendered.yaml

Keeping build output as an artifact on PRs lets reviewers verify “what will ultimately be applied” from the rendered result. If you use type: oras, you can also consider running with --offline to leverage a pre-warmed cache (see tazuna build).

Apply Stage

The basic setup runs tazuna apply triggered by pushes to main.

on:
  push:
    branches: ["main"]

jobs:
  apply:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write   # if you connect to the cluster via OIDC
    steps:
      - uses: actions/checkout@v6
      - name: install tazuna
        run: |
          curl -L https://github.com/pepabo/tazuna/releases/download/v0.1.0/tazuna_Linux_x86_64.tar.gz \
            | tar xz -C /usr/local/bin tazuna
      - name: configure kubeconfig
        run: |
          # Set current-context using aws-iam-authenticator / gke-gcloud-auth-plugin
          # / kubeconfig secret etc., depending on cluster-side specifics
          aws eks update-kubeconfig --name prod-tokyo --region ap-northeast-1
      - name: tazuna apply
        run: tazuna apply -f tazuna.yaml

Points to note:

• The current-context for tazuna apply is exactly the kubeconfig current-context. In CI, always explicitly include a step that sets the current-context.
• Including spec.context_matches in tazuna.yaml makes the system fail fast if it would apply against a kubeconfig pointing to the wrong cluster. It is a useful safety net in CI as well.
• Tazuna exits non-zero on failure, so no special error handling is needed on the CI side (see CLI - Exit Codes).

apply or state sync

There are two commands you can run in CI.

Rough guidance:

• Bootstrap phase / small number of Manifests: tazuna apply is simple and predictable.
• Manifest count grows and a single apply becomes heavy: switch to tazuna state sync to narrow down to differences only.
• You want automatic removed deletion: state sync + TAZUNA_STATE_SYNC_DELETE=true. Balance against the risk of accidental deletion.

Whether to Use --atomic

When you pass tazuna state sync --atomic, it exits without updating State if any resource errors out. The apply itself still progresses partway, so CI cannot treat the run as binary “either everything went in or nothing did,” but State-level consistency is preserved. See tazuna state sync for details.

Removal Stage

We do not recommend running tazuna destroy from CI.

• Setting the environment variable TAZUNA_DESTROY_EXECUTABLE=true permanently in CI leaves only the prompt as a guard against accidental firing (and since CI cannot respond to prompts, combined with --force it would delete unconditionally).
• If you absolutely need to delete from CI, create a dedicated manually-triggered workflow and pass the env var only for that job.

See Operating tazuna destroy for details.

Phased Apply With Tags

tazuna apply --tags lets you narrow down which Manifests CI applies. For example, this fits patterns like “run the infrastructure layer and the application layer in separate CI passes” or “run experimental add-ons in a separate job.”

tazuna apply --tags infra        # Install the foundation first
tazuna apply --tags application  # Then the application side

Tag design happens on the tazuna.yaml side via manifests[].tags.

Wiring Up Monitoring and Notifications

The recommended setup is to run periodic tazuna state diff on a separate path from CI. See Drift Monitoring for details. If you only watch the success/failure of CI apply, you will miss cases where drift occurs without any tazuna.yaml update.

Related

• Spec: tazuna apply / tazuna build / tazuna check / tazuna state sync
• Incident prevention: Operating tazuna destroy
• Drift detection: Drift Monitoring