ECHO Certification Forge

Evidence-backed commit, release, and deployment certification with signed GitHub checks.

This repository is the deployable, auditable runtime for the public ECHO Certification Forge registration. Its committed manifest is the least-privilege contract: only listed events are processed, and credentials are supplied at runtime from a secret manager.

Governed runtime

• Validates X-Hub-Signature-256 over the original bytes and rejects oversized or malformed requests.
• Claims each GitHub delivery in a durable SQLite queue; retries cannot execute the action twice.
• Maps the committed app manifest to one fixed action. Webhook data cannot select code, commands, capabilities, or credentials.
• Requires repository opt-in in .echo/apps.json and a bounded exact-revision journey in .echo/certification.json, then obtains Sovereign Action Broker authorization for the exact app/action/scope.
• Uses short-lived installation tokens only inside the effect boundary, waits a bounded interval for the signed terminal verdict, and maps only PRODUCTION_READY to a successful GitHub check.
• Seals succeeded, failed, ignored, and recovered jobs into an append-only hash-chained receipt ledger.
• Loads webhook, private-key, SDK-key, and HMAC material from protected files only; direct secret environment variables fail startup.

Enable in a repository

{
  "version": 1,
  "apps": {
    "<app-key>": {"enabled": true}
  }
}

Install the GitHub App for the account or selected repositories, commit the opt-in, and inspect the terminal result at https://github.echo-op.com/receipts/<app-key>/<delivery-id>.

Certification also fails closed unless the exact target revision commits a journey manifest and its referenced script:

{
  "version": 1,
  "journey": ["python", "-B", "scripts/certforge_journey.py"]
}

The runtime accepts only a bounded Python argv, verifies the script exists at the same target SHA, and passes the argv array directly to Certification Forge without a shell.

Verify locally

python -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[test]"
python -m pytest -q
python -m compileall -q src app.py

A production process also needs the file-mounted secret paths and persistent ledger documented in Operations.

See Architecture, Operations, and Security Policy for the full contract.