Your first contract

This guide walks through creating a devcontract.json for an existing repository, committing it, and verifying that Gatekeep evaluates it on the next scan. Estimated time: 10 minutes.

Prerequisites

• A ticketyboo account (free plan is sufficient)
• VS Code with the ticketyboo-gate extension installed (see Installation)
• An API key configured in the extension (see Configuration)
• A public GitHub repository with the code you want to govern
• The repository cloned locally and open in VS Code

Step 1: Open the Brief Wizard

Open the VS Code Command Palette with Ctrl+Shift+P (or Cmd+Shift+P on macOS) and type ticketyboo. Select ticketyboo: Open Brief Wizard.

The extension calls GET /v1/archetypes with your API key and displays the available archetypes in a Quick Pick list.

Step 2: Select an archetype

Choose the archetype that most closely matches your service type. For example:

• python-lambda for a Python AWS Lambda function
• nodejs-service for a Node.js or JavaScript service
• terraform-iac for a Terraform infrastructure repository
• oss-library for an open source library

If none of the archetypes closely match, choose the closest one and edit the generated file afterwards.

Step 3: Enter your service name

The wizard prompts for a service name. Enter a short identifier for the repository (for example payments-api or infra-core). This becomes the service_name field in the contract.

The extension calls POST /v1/archetypes/{name}/instantiate with your service name and writes the result to devcontract.json at the workspace root.

Step 4: Review and customise

Open the generated devcontract.json. Review each gate:

• Are the categories appropriate for this service? A service without Terraform does not need an iac gate.
• Are the severity levels right? Consider whether medium findings should block or just warn.
• Are the thresholds realistic? If the service has known tech debt, set a higher initial threshold and plan to reduce it.
• Update the description on each gate to explain its intent in plain language.

For example, you might adjust the archetype default from:

{
  "category": "code_quality",
  "severity": "medium",
  "threshold": 0,
  "blocking": true
}

to:

{
  "category": "code_quality",
  "severity": "medium",
  "threshold": 8,
  "blocking": false,
  "description": "Non-blocking while team addresses existing quality debt. Target: 0 by end of Q3."
}

Step 5: Commit the contract

Add devcontract.json to version control:

git add devcontract.json
git commit -m "chore: add devcontract.json governance contract"
git push

The contract is now part of your repository history. Future changes to the contract are code-reviewed like any other file.

Step 6: Run a scan and verify Gatekeep

Go to ticketyboo.dev/scan/ and submit your repository URL. Once the scan completes, the result should include a Gatekeep section with a verdict of passed, passed_with_warnings, or failed.

If the verdict is not_evaluated, check that devcontract.json is at the repository root and that the most recent commit has been pushed.

If the verdict is failed, the report will show which gates fired and how many findings exceeded the threshold. Use this to either fix the findings or adjust the contract thresholds to reflect the current codebase baseline.

Next steps

• Add scan submission to your CI pipeline
• Threshold ratcheting strategy
• Understanding scan results in detail