GitHub Integration & Scanning

GitHub App Installation

Spec This connects to your repositories through a GitHub App. The app requests read-only access to repository contents and metadata — it never writes to your code.

Install the App

From your Spec This dashboard, click Connect Repository. You will be redirected to GitHub to install the Spec This GitHub App on your personal account or organization.

Select Repositories

Choose which repositories to grant access to. You can select all repositories or pick specific ones. You can change this later in your GitHub settings.

Authorize

Approve the permissions and you will be redirected back to Spec This. Your selected repositories will appear in the dashboard, ready for their first scan.

How Scanning Works

A scan analyzes your repository in four stages. The process is non-destructive and read-only.

File Analysis — Source files are identified and read. Non-code files (images, binaries, lock files) are skipped.
Symbol Extraction — Functions, classes, and methods are extracted using tree-sitter parsers. This produces a structured map of your codebase.
Metric Calculation — Complexity, nesting depth, line counts, and other metrics are computed for each symbol and file.
Alert Generation — Metrics are compared against your configured thresholds. Alerts are created for any metric that exceeds its threshold.

Scan Triggers

Scans can be triggered in two ways.

Manual Scan

Click the Run Scan button on any connected repository's dashboard page. The scan runs immediately and results appear within minutes depending on repository size.

Automatic on Merge

When configured with GitHub Actions, scans trigger automatically when code is merged to the parent branch (e.g., main or develop). This ensures your metrics stay current without manual intervention.

Note: Scans are triggered on merge to the parent branch, not on every commit. This keeps scan volume manageable while ensuring your main branch is always measured.

Rate Limits

Scan frequency and repository size are limited by plan tier.

Limit	Hobby	Pro
Scans per day	10	100
Max repo size	250 MB	1 GB
Max file count	5,000	50,000

Scan API Keys

Scan API keys authenticate scan uploads from GitHub Actions and the CLI. Keys are scoped to upload-only access — they cannot read your data or modify configuration.

Key Details

Keys use the st_scan_ prefix for easy identification
Keys are SHA-256 hashed before storage — the plaintext is shown only once at creation
Each key is scoped to upload-only permissions
Keys can be revoked at any time from Organization Settings

Important: Copy your API key immediately after creation. It cannot be retrieved later because only the hash is stored. If you lose a key, revoke it and generate a new one.

GitHub Actions Setup

The recommended way to automate scanning is through GitHub Actions. Spec This provides a setup wizard that generates the workflow YAML for you.

Quick Setup

Go to your repository settings in Spec This and click Setup GitHub Actions
The wizard generates a workflow YAML file
Copy the YAML into .github/workflows/specthis-scan.yml in your repository
Add your scan API key as a GitHub secret named SPECTHIS_SCAN_KEY
Merge to your main branch — scans will trigger automatically on future merges

Example Workflow

name: Spec This Scan
on:
  push:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Spec This Scan
        uses: specthis/scan-action@v1
        with:
          api-key: ${{ secrets.SPECTHIS_SCAN_KEY }}

Scanning Model by Plan

Hobby (Free)

Scans run on GitHub Actions infrastructure — you pay for GitHub compute. Alternatively, use the CLI for manual scans from your local machine.

Pro

Scans run on Spec This managed infrastructure (we pay for compute). GitHub Actions is still available as an opt-in for organizations that prefer to keep code on their own runners for security reasons.

CLI Scanning

As an alternative to GitHub Actions, you can scan repositories manually using the Spec This CLI. This is useful for local testing, one-off scans, or environments without GitHub Actions.

# Install the CLI
npm install -g @specthis/cli

# Authenticate with your scan API key
specthis auth --key st_scan_your_key_here

# Run a scan from your repository root
specthis scan

For full CLI documentation, see the CLI Setup guide.

Next Steps

Alerts & Monitoring — Configure thresholds for your scans Dashboard & Trends — View your scan results and track trends Plans & Billing — Understand rate limits and scanning tiers