Team setup
This guide covers establishing a consistent contract baseline across multiple repositories. It is aimed at a team lead or platform engineer rolling out ticketyboo to a team or organisation.
The goal
A well-governed team has:
- A
devcontract.jsonin every production repository. - A shared understanding of what the standard gates mean and why they exist.
- CI workflows that fail on blocking gate violations.
- A process for reviewing and updating contracts when standards change.
Step 1: Define your baseline standards
Before rolling out contracts, agree with your team on the minimum standards for all services. A useful starting point:
| Category | Severity | Threshold | Blocking | Rationale |
|---|---|---|---|---|
| secret | critical | 0 | Yes | Hardcoded secrets are never acceptable |
| sast | high | 0 | Yes | High/critical code vulnerabilities must be fixed |
| dependency | high | 0 | Yes | Known high CVEs in direct dependencies |
| governance | medium | 0 | No | README and CI expected; informational |
Write these down as your team's minimum contract. Individual services may add gates on top of this baseline.
Step 2: Create a reference contract
Create a reference devcontract.json in a shared documentation repository or wiki. This is the template that engineers use when starting a new service. Document the rationale for each gate's threshold in the description field.
The reference contract can be an archetype. You can submit the archetype instantiation request yourself and commit the output as the team's starting template.
Step 3: Roll out to existing repositories
For existing repositories with no contract:
- Run a shallow scan first to get a baseline finding count in each category.
- Set thresholds in the contract to match the current finding counts. This prevents immediate failures on existing debt.
- Set blocking gates only on categories with zero current findings (typically secrets and critical SAST on clean services).
- Commit the contract and add CI integration.
- Plan a sprint to reduce thresholds in each service towards the team baseline over time.
Step 4: Distribute the extension
Install the ticketyboo-gate extension across the team. Share the ticketyboo.apiBase value (default: https://api.ticketyboo.dev) and instruct each developer to generate their own API key from their account page.
API keys are personal. Each developer should generate their own key. Do not share a single team key; it makes it impossible to track which account's credits are being used and creates a single point of failure if the key is rotated.
Step 5: Add CI integration to each repository
Add the GitHub Actions workflow from the CI integration guide to each repository. Use a dedicated CI API key (from a service account or shared team account) stored as a GitHub Actions secret. This keeps CI credits separate from developer credits.
Keeping contracts current
Contracts should evolve with services. Establish a process for:
- New service setup: contract is part of the service creation checklist. Use the Brief Wizard to generate the initial file.
- Threshold reduction: schedule a quarterly review to lower thresholds as tech debt is addressed. The contract's git history records progress.
- Standard changes: when team security standards change (for example, adding a license gate for all services), update the reference contract and file a PR per service to roll out the change.
- Post-incident: after a security incident, review whether the relevant finding category was covered by the contract and whether the threshold was appropriate.
Business plan and per-seat billing
The business plan ($40/seat/month) allocates 40 credits per seat per month. For teams running CI scans at high frequency, calculate expected monthly scan volume before choosing a plan. Each scan (shallow or deep) consumes one credit from the account that submitted it.
To check current credit balance and plan: GET /api/account/me.