Your first release report.

Edit assurance/examples/http-contract.json to describe your staging routes, expected statuses and JSON assertions. The example checks /health and /obligations; adapt these to your service.

Set CUSTOMER_API_URL and CUSTOMER_API_TOKEN through your shell or CI secret store. Remove the header binding if the target does not require authentication.

node assurance/cli.mjs run --config assurance/examples/http-contract.json --output assurance-report.json

HTTPS is required for remote targets. HTTP is supported only on loopback. Redirects are not followed. Write methods require explicit opt-in in your configuration; only use authorised test systems with synthetic data. Government production hosts are excluded by the runner's destination policy.

Checks are numbered in configuration order. The runner fingerprints the configuration so changed test definitions do not silently compare as the same suite. Changing an environment variable does not change the fingerprint: use a separate project for each target integration.

The HMRC VAT obligations template performs read-only checks directly against HMRC's sandbox. Create a project with this matching template. You need a subscribed sandbox application and a VAT-enrolled test user with an authorised access token.

Set HMRC_ACCESS_TOKEN, HMRC_TEST_VRN, HMRC_FROM_DATE, HMRC_TO_DATE and HMRC_TEST_SCENARIO. The documented example uses QUARTERLY_NONE_MET.

node assurance/cli.mjs run --config assurance/examples/hmrc-vat-obligations.json --output vat-report.json

These responses may be canned. This template tests the documented response contract; it does not prove persistence, tax calculations, your customer's implementation or production readiness. Use the HTTP contract template for your own integration.

HMRC VAT API documentation · Understanding sandbox behaviour

Run the same command in CI. It returns 0 for passed checks, 1 for failed assertions and 2 for a blocked run or configuration error. Preserve the report as a CI artifact even when the run fails.

For automated CLI uploads, get your API key from the dashboard after signing in. Set GOVBRIDGE_URL to your API origin and GOVBRIDGE_API_KEY in your CI secret store. Copy the project ID from the workspace, then run:

node assurance/cli.mjs upload --project YOUR-PROJECT-UUID --report assurance-report.json

Uploading does not change a failed test into a pass. Preserve the run command's exit status as your release gate. The downloaded README includes a CI example. Uploading the same report again is idempotent; changing evidence under the same run ID is rejected.

Failed checks take precedence over blocked checks in the overall status. Comparisons use the previous imported report in the same project, environment and suite version. They follow upload order, which may differ from execution order.

The workspace stores client-reported evidence, not independently witnessed test execution. It rejects raw payload fields and common credential patterns. Do not put secrets, taxpayer identifiers or personal data in names, versions or messages.

Download the evidence and compare its SHA-256 checksum with the digest shown on the run. The digest covers the exact server-exported JSON bytes, which may differ in formatting from the local file. It proves stored-byte integrity, not the truth of the reported checks.

Projects belong to your API-key identity. Rotating that key preserves your projects; deleting a project removes all its runs. The preview allows 20 projects, 200 runs per project and 1,000 runs per account. Export evidence before deleting anything you need to retain.