DRAFT — this page is pending review and may change before publication.
Skip to content

Quickstart

Four steps to get from zero to a running scan and a configured extension. No account required for step one.

Step 1: Scan a public GitHub repository

The ticketyboo scanner (Gatekeep) analyses any public GitHub repository without requiring an account. Go to /scan/, paste a GitHub URL in the form, and click Run scan.

Example URLs you can try:

Example repositories 
https://github.com/pallets/flask
https://github.com/psf/requests
https://github.com/expressjs/express

The scan accepts a repo_url (required) and an optional deep flag. A shallow scan checks five categories: governance, dependency, code quality, security, and IaC. A deep scan runs all six analysis layers and computes a health score. Deep scans are rate-limited to 3 per IP per 7-day window.

The scan creates a record, fires asynchronously, and returns a scan_id. Poll GET /api/scan/{scan_id} for status. The scan page handles this automatically.

Note

Only public GitHub repositories are supported. Private repositories and non-GitHub hosts are not supported.

Step 2: Install the VS Code extension

The ticketyboo extension is named ticketyboo DevContract Gate (publisher: ticketyboo-dev, extension ID: ticketyboo-gate). Install it from either marketplace:

The extension requires VS Code version 1.85.0 or later.

After installation, open the Command Palette (Ctrl+Shift+P on Windows/Linux, Cmd+Shift+P on macOS) and run:

Command palette 
ticketyboo: Open Brief Wizard

The Brief Wizard connects to the ticketyboo API to fetch available contract archetypes, prompts you to select one, asks for a service name, and writes a devcontract.json file at the workspace root. See Extension docs for configuration.

Configuration required

The Brief Wizard needs your API key to call the archetypes endpoint. Set ticketyboo.apiKey in VS Code settings before running the wizard. See Configuration for details.

Step 3: Create your first Contract

A ticketyboo Contract is a devcontract.json file that defines what your code must satisfy before a PR merges. Contracts contain gates: conditions that are evaluated against the repository.

The quickest way to create a Contract is via the Brief Wizard (step 2 above). For a manual approach, see First Contract guide.

Key concepts:

  • Gate: a single check condition (e.g. no critical severity findings, test coverage above threshold)
  • Archetype: a pre-built Contract template for a category of service (e.g. Python API, Node.js frontend)
  • Severity: findings are graded critical, high, medium, low, or info
  • Threshold: numeric limit applied to a severity level

Full Contracts documentation: Contracts section.

Step 4: Run Gatekeep on a repository

Gatekeep is the detective component. It scans a repository, runs the applicable analysis layers, and produces a structured report. The report includes findings (category, severity, title, description, remediation), a health score (deep scans only), and per-layer timing metadata.

Gatekeep can be triggered:

  • Via the scanner UI: go to /scan/ and paste a GitHub URL
  • Via the API: POST /api/scan with {"repo_url": "https://github.com/owner/repo"}
  • Via CI: call the API endpoint from a GitHub Actions step. See CI integration guide

The six deep scan layers are: dependency (vulnerability and unpinned-version analysis), secret (regex and entropy-based detection), SAST (static application security testing), IaC (Terraform and CloudFormation), license (classification and copyleft detection), and quality (cyclomatic complexity, type hint coverage, long functions).

Full Gatekeep documentation: Gatekeep section.

Next steps

ticketyboo documentation · Apache 2.0 Back to site