Developer CI/CD guide

This page explains how to add or change CI/CD safely in dpone. It belongs in Developer docs because workflow changes are implementation changes: they affect release safety, contributor UX, security posture, and public artifacts.

Principles

• Keep the default PR gate deterministic and credential-free.
• Keep vendor credentials in manual or scheduled gates only.
• Use least-privilege workflow permissions.
• Prefer explicit artifacts over hidden logs.
• Make every new workflow reproducible locally or document why it cannot be.
• Update user docs and runbooks in the same PR as workflow changes.
• Keep master as the default branch in workflow triggers and docs.

When to add a new workflow

Add a workflow only when one of these is true:

Case	Prefer
Fast deterministic quality check	Extend .github/workflows/ci.yml.
Documentation build/deploy behavior	Extend .github/workflows/pages.yml.
Public package publishing	Extend .github/workflows/release.yml.
Long-running source/sink or connector certification	Manual/scheduled workflow.
Vendor credentials required	Manual/scheduled workflow with explicit secrets and docs.
Security/supply-chain posture	Dedicated security workflow with least-privilege permissions.

Do not add a new always-on PR workflow for slow, flaky, vendor-dependent, or credential-dependent tests.

New workflow checklist

Before opening a PR:

• Choose the trigger: push, pull_request, workflow_dispatch, schedule, or tag.
• Choose minimum permissions. Start with contents: read.
• Decide whether the workflow must run on master, PRs, tags, schedule, or manual dispatch.
• Add local reproduction commands to Workflow reference.
• Add failure recovery to Failure runbooks.
• Add artifact names and retention expectations.
• Add or update tests that protect the docs/workflow contract.
• Confirm no job writes secrets to logs or artifacts.

Changing the default CI gate

Default CI changes affect all contributors. Keep them boring and reproducible.

Required local gate:

uv sync --all-extras
uv run ruff check .
uv run ruff format --check .
uv run mypy --config-file mypy.ini
uv run pytest -m "not integration_live" --cov=src/dpone --cov-report=xml
uv build

Rules:

• Do not require Docker for the default quality matrix unless the job is isolated like postgres-xmin.
• Do not require cloud/vendor credentials.
• Keep optional integration markers opt-in.
• If coverage minimum changes, document the rationale in the PR.

Adding a manual integration gate

Use this pattern for broad matrix, stress, benchmark, or connector certification workflows:

on:
  workflow_dispatch:
    inputs:
      run_mode:
        type: choice
        options: [mock_contract, mock_local, vendor_live]

permissions:
  contents: read

Design requirements:

• All input names must be documented.
• Every run writes artifacts even on failure with if: always().
• mock_contract and mock_local must not require external vendor credentials.
• vendor_live must clearly list required secrets.
• Use focused filters such as DPONE_MATRIX_CASE_ID for debugging.

Adding secrets

Before adding a secret:

1. Ask whether Trusted Publishing, OIDC, or local mock mode can avoid the secret.
2. Scope the secret to the smallest provider/project/package possible.
3. Use it only in the workflow/job that needs it.
4. Redact diagnostics and artifacts.
5. Add rotation instructions to the relevant runbook.

Never add secrets to ordinary PR CI from forks.

Adding artifacts

Artifacts should answer: what ran, with what inputs, what passed/failed, and what evidence exists.

Recommended artifact content:

• command and workflow inputs;
• source/sink/strategy coverage;
• row counts and checksums for data movement tests;
• warnings and skipped cases with reason;
• environment summary without secrets;
• JUnit XML when pytest is involved.

Recommended paths:

test_artifacts/integration_matrix/
test_artifacts/connectors/
test_artifacts/benchmarks/
test_artifacts/certification/suite/
test_artifacts/observability/
test_artifacts/supply-chain/

Adding certification suite automation

Use Certification suite automation when a workflow needs to combine matrix correctness, benchmark regression, lineage, dbt lineage, and evidence checksums.

Recommended flow:

uv run dpone ops certification-run \
  --artifact-dir test_artifacts/certification/current

uv run dpone ops benchmark-baseline \
  --output-dir test_artifacts/benchmarks/current \
  --metrics-json "$METRICS_JSON" \
  --baseline-json "$BASELINE_JSON"

uv run dpone ops certification-suite \
  --output-dir test_artifacts/certification/suite \
  --suite-id "$GITHUB_RUN_ID" \
  --certification-report test_artifacts/certification/current/certification_report.json \
  --benchmark-baseline test_artifacts/benchmarks/current/benchmark_baseline.json \
  --require-benchmark \
  --format json

Rules:

• Keep this workflow manual or scheduled unless it is credential-free and fast.
• Upload test_artifacts/certification/suite/ with if: always().
• Upload test_artifacts/observability/ with if: always() when a workflow exports runtime metrics.
• Add required secrets only to vendor-live jobs.
• Update Developer certification suite when adding evidence types.

Adding observability artifacts

Use Runtime observability when a workflow needs Prometheus/OpenTelemetry evidence for a run.

Recommended flow:

uv run dpone run "$MANIFEST" --format json > test_artifacts/runs/run_report.json

uv run dpone observability metrics-export \
  --run-report test_artifacts/runs/run_report.json \
  --output-dir test_artifacts/observability/current \
  --label ci_run_id="$GITHUB_RUN_ID" \
  --label branch="$GITHUB_REF_NAME" \
  --format json

Rules:

• Keep labels secret-free and low-cardinality.
• Keep collector upload optional; artifact generation must work locally.
• Link any new failure mode to Failure runbooks.
• Update Developer observability guide when adding renderers or metric sources.

Adding supply-chain evidence

Use Supply-chain evidence when a release workflow needs SBOM, provenance, signature envelope, and checksum evidence.

Recommended flow:

uv build
uv tool run twine check dist/*

uv run dpone supply-chain attest \
  --release "$GITHUB_REF_NAME" \
  --subject dist/dpone-*.whl \
  --subject dist/dpone-*.tar.gz \
  --repository "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY" \
  --commit-sha "$GITHUB_SHA" \
  --builder-id "github-actions:$GITHUB_RUN_ID" \
  --signing-key "$DPONE_LOCAL_ATTESTATION_KEY" \
  --signing-key-id github-actions \
  --output-dir test_artifacts/supply-chain/current \
  --format json

Rules:

• Upload test_artifacts/supply-chain/ with if: always().
• Do not store local HMAC signing keys in artifacts or logs.
• Use GitHub artifact attestations or Sigstore/cosign for public identity-backed trust.
• Update Developer supply-chain guide when adding formats or signers.

Docs contract tests

When CI/CD documentation changes, add or update docs contract tests. A good test verifies:

• public workflow files are named in docs;
• default branch remains master;
• runbooks mention every required workflow;
• developer docs link to CI/CD implementation guidance.

PR description template for CI/CD changes

## CI/CD change

- Workflow(s):
- Trigger(s):
- Permissions:
- Secrets required:
- Artifacts produced:
- Local reproduction:
- Failure runbook updated:
- Docs updated:

Related docs

• CI/CD index
• Workflow reference
• Failure runbooks
• Release and Pages automation
• Testing
• Connector certification