Contributing to cMCP

August 20, 2026 ยท View on GitHub

Thank you for contributing. This document covers everything you need to get started.

Before you start

cMCP is a hardware-attested policy gateway. Changes to the TEE boundary, signing path, audit chain, or TRACE Claim generation require extra care: these are security-critical components. When in doubt, open an issue first.

Developer certificate of origin

All commits must include a Signed-off-by line. This is a lightweight way to certify you wrote the code or have the right to contribute it. No CLA required.

git commit -s -m "feat: your change"

The sign-off certifies the Developer Certificate of Origin v1.1.

Development setup

Requires Python 3.11+.

git clone https://github.com/agentrust-io/cmcp
cd cmcp
pip install -e ".[dev]"

Running checks locally

ruff check src/ tests/        # lint
mypy src/cmcp_gateway/        # type check
bandit -r src/ -c pyproject.toml  # security scan
pytest tests/unit/ -v          # unit tests

All four must pass before a PR is mergeable.

Release artifact verification

The PyPI workflow installs the exact wheel and source distribution into separate clean environments before upload. It checks release-tag/version agreement, metadata and runtime versions, import provenance outside the checkout, core configuration construction, and the installed cmcp console entry point.

Release container build

The release container uses a multi-stage build: the builder creates a wheelhouse from production dependencies only, while the runtime installs it offline and runs as numeric UID/GID 10001. Do not add editable installs, the dev extra, or root execution to the runtime stage. Dockerfile, schema, and container-workflow pull requests build the image without registry credentials or a push; publishing, signing, and provenance attestation remain restricted to version tags.

Commit format

Follow Conventional Commits:

feat: add sev-snp provider
fix: correct nonce encoding in RuntimeInfo
docs: clarify TRACE profile envelope structure
test: add coverage for stale attestation path
refactor: extract _build_policy helper

Keep commits small and focused. One logical change per commit. Do not bundle unrelated fixes.

Pull request process

  1. Branch from main: git checkout -b feat/your-change
  2. Write tests for new behaviour: the test suite must pass
  3. Run all four checks locally (see above)
  4. Open a PR against main with the template filled in
  5. At least one maintainer must approve before merge
  6. Squash if the commit history is noisy; preserve meaningful commits

Security-critical components

Changes to these paths require two maintainer approvals and a comment explaining the security impact:

  • src/cmcp_gateway/audit/: signing, audit chain, TRACE Claim generation
  • src/cmcp_gateway/tee/: TEE provider integration
  • src/cmcp_gateway/policy/: Cedar policy evaluation

Reporting security vulnerabilities

Do not open a public issue. Use GitHub Security Advisories for private disclosure. See SECURITY.md.

Code conventions

  • Python 3.11+ syntax throughout (X | Y, match, etc.)
  • ruff enforces style; do not add # noqa without a comment explaining why
  • mypy --strict on src/cmcp_gateway/; new public functions need type annotations
  • No comments that describe what the code does: only why when non-obvious
  • Tests live in tests/unit/ and follow the existing test_<module>.py naming

Questions

Open a GitHub Discussion for design questions or proposals before writing code.