Skip to main content

CI Integration

This page wires the DAGZ pytest plugin into your CI pipeline so test runs report to your team deployment.

Prerequisites​

1. Install the plugin​

pip install dagz

dagz is published on PyPI; no auth or extra index is needed. Bake this into your CI worker image or run it as a setup step before installing your project's dependencies.

2. Point the plugin at the deployment​

Set one env var on each CI worker:

DAGZ_URL=https://<your-dagz-web-host>

This is the only required configuration env var. The plugin discovers the rest from the URL.

3. Mount the collector TLS certificate​

The plugin uses an mTLS client certificate to talk to the deployment. The Helm chart deploys a Kubernetes secret named collector-tls-cert in the user namespace you set in dagz_values.yaml; mount it into each CI worker pod so the plugin can read it.

The plugin looks for the certificate at ${DAGZ_HOME}/collector/tls, where DAGZ_HOME defaults to ~/.dagz/run.env. Either mount the secret under that default path, or set DAGZ_HOME to a directory of your choice whose collector/tls subdirectory holds the secret.

Example pod spec snippet (using the default DAGZ_HOME):

volumes:
  - name: collector-tls
    secret:
      secretName: collector-tls-cert
containers:
  - name: ci-worker
    volumeMounts:
      - name: collector-tls
        mountPath: /root/.dagz/run.env/collector/tls
        readOnly: true

For Docker Compose deployments, copy the certificate files from the deployment host onto each runner machine and bind-mount them at the same path.

4. Make git metadata available​

DAGZ keys baselines on the branch and commit hash.

  • Running on a git worktree: DAGZ picks up the values from git automatically.

  • Running on GitHub Actions or GitLab CI: DAGZ picks up the standard CI env vars automatically.

  • Anywhere else: set these explicitly:

    GIT_BRANCH=<short branch name, no `refs/...` prefix>
    GIT_COMMIT_HASH=<full git commit hash>

5. Run pytest with the plugin​

Add --dagz to your existing pytest command:

pytest --dagz

On the first run, DAGZ records a baseline. On subsequent runs, it selects only the tests affected by the change.

Common flags:

  • --dagz: enable DAGZ test selection and coverage collection.
  • --dagz-workers N: set the number of parallel worker processes. Default is computed from the host's CPU configuration.
  • --dagz-debug: print full debug logs to the console.
  • --dagz-capture=0: disable PTY capture of test stdout/stderr.

The full list is in Pytest options.

Verify​

After the first run completes, open the DAGZ console. The Jobs tab should show the run, and the Dashboard should populate with results in the selected period.

If pytest fails to start with a connection or auth error, check:

  • The TLS secret isn't at ${DAGZ_HOME}/collector/tls (default ~/.dagz/run.env/collector/tls).
  • DAGZ_URL is wrong, unreachable from the runner network, or doesn't match the hostname on the deployment's TLS certificate.
  • The runner's clock is far off — mTLS handshake rejects the connection.

Each of these prevents the run from starting; pytest exits before any tests execute.