sdk-infra

Shared infrastructure for Camunda SDK repositories. This repo provides reusable GitHub Actions workflows, composite actions, CLI tools, and shared configuration to eliminate duplication across SDK repos.

What's included

Directory	Purpose
.github/workflows/	Reusable CI workflows (spec bundling, commitlint, integration testing, agent example coverage)
actions/	Composite GitHub Actions (start Camunda stack, sync snippets, check coverage, set up toolchain)
docker/	Shared Docker Compose files for integration testing
scripts/	Unified CLI tools (snippet sync, example coverage check, operation detection)
configs/	Shared commitlint and semantic-release base configurations
schema/	JSON schema for operation-map.json validation
policies/	Canonical contributor guidelines (AGENTS.md)

Quick start for SDK repos

1. Spec bundling (reusable workflow)

# .github/workflows/ci.yml
jobs:
  bundle:
    uses: camunda/sdk-infra/.github/workflows/sdk-bundle-spec.yml@v1
    with:
      spec-ref: stable/8.9

2. Commitlint (reusable workflow)

  commitlint:
    uses: camunda/sdk-infra/.github/workflows/sdk-commitlint.yml@v1

3. Start Camunda for integration tests (composite action)

  integration:
    steps:
      - uses: camunda/sdk-infra/actions/start-camunda@v1
        with:
          stack: full
          version: 8.10.0

4. Sync README snippets (composite action)

  snippets:
    steps:
      - uses: camunda/sdk-infra/actions/sync-readme-snippets@v1
        with:
          lang: python
          check: true

5. Check example coverage (composite action)

  coverage:
    steps:
      - uses: camunda/sdk-infra/actions/check-example-coverage@v1
        with:
          operation-map: examples/operation-map.json

6. Agent example coverage (reusable workflows)

When the daily coverage check files a "Missing example coverage" issue, these run the Copilot CLI against the repo and open a pull request with the examples. The caller owns only the triggers, the permissions, and the commands that define "verified" here.

# .github/workflows/agent-example-coverage.yml
on:
  issues:
    types: [labeled]

permissions: {}

jobs:
  implement:
    if: github.event.label.name == 'new-operations'
    permissions:
      contents: read
      id-token: write
      copilot-requests: write
      issues: write
    uses: camunda/sdk-infra/.github/workflows/sdk-agent-example-coverage.yml@v1
    secrets:
      VAULT_ADDR: ${{ secrets.VAULT_ADDR }}
      VAULT_JWT_PATH: ${{ secrets.VAULT_JWT_PATH }}
      VAULT_JWT_ROLE: ${{ secrets.VAULT_JWT_ROLE }}
      VAULT_JWT_AUDIENCE: ${{ secrets.VAULT_JWT_AUDIENCE }}
    with:
      language: go
      issue-number: ${{ github.event.issue.number }}
      verify-commands: |
        make check

A companion sdk-agent-pr-followup.yml reacts to feedback on the resulting pull request — a /agent fix comment, a failing CI run, or a review from another bot. The bot-review path runs on an hourly schedule rather than on pull_request_review, because GitHub parks any run the Copilot actor triggers behind manual approval.

Declare any tracked file the verify commands legitimately regenerate (a lockfile, a recorded fixture) in verify-artifacts; anything they touch outside that allow-list fails the run rather than being swept into the commit.

In the SDKs that bundle the spec fresh on every CI run — js, python and csharp — a new upstream operation fails the coverage check on every open pull request at once, none of which caused it. sdk-coverage-gap-dispatch.yml reacts to that by dispatching the detector above, so the gap is fixed once against main, and leaves a single comment explaining the red check rather than pushing a commit onto someone else's branch.

7. Shared configs

// commitlint.config.cjs
module.exports = require('@camunda8/sdk-infra/configs/commitlint.config.base.cjs');

// release.config.cjs
const base = require('@camunda8/sdk-infra/configs/release.config.base.cjs');
module.exports = { ...base, plugins: [...base.plugins, /* language-specific */] };

Local development tools

The scripts in scripts/ can be run directly with Python 3.10+:

# Sync README snippets
python3 scripts/sync-readme-snippets.py --lang csharp --readme ../my-sdk/README.md --examples-dir ../my-sdk/docs/examples --check

# Check example coverage
python3 scripts/check-example-coverage.py --spec ../my-sdk/external-spec/bundled/rest-api.bundle.json --map ../my-sdk/examples/operation-map.json

Versioning

The two distribution channels are versioned separately.

• npm package (@camunda8/sdk-infra) — released by semantic-release from main. The version in package.json is a sentinel and is never edited by hand.
• Reusable workflows and composite actions — the moving major tag v1 only. SDK repos pin to it (@v1), and the Release workflow moves the tag forward on every push to main. A breaking change to a workflow's or action's interface gets a new major tag (v2) and consumers are migrated deliberately; additive changes stay within the current major.

The two channels share one tag namespace. vX.Y.Z belongs to semantic-release and is never created by hand — see AGENTS.md for why a manual one silently costs an npm release.

Language-specific notes

Python SDK

• Release config: Python uses python-semantic-release (configured in pyproject.toml), not Node.js semantic-release. The shared release.config.base.cjs does not apply to Python.
• Docker stack: Python only uses the lightweight (single-service) Docker stack. The stack: full option is not applicable.

TypeScript/JS SDK

• Snippet files: The JS SDK stores import-only snippets in .txt files (e.g., readme-imports.txt). The unified sync script includes .txt in the TypeScript file extensions.
• Multi-source markers: Composite regions spanning multiple source files use comma-separated paths in the snippet marker (e.g., examples/readme-imports.txt,examples/readme.ts).

C# SDK

• Additional CI checks: The C# SDK has a check-overwrite-completeness.js guard that is C#-specific and not included in shared infra.