Skip to content
Specor

GitHub Integration

The GitHub integration connects Specor to a GitHub repository via a GitHub App installation. It covers two use cases:

  • Brownfield sync — read a codebase at HEAD and generate a draft product graph from what already exists in code.
  • PR drift detection — link a GitHub PR to a Specor merge request and run a drift analysis to find gaps in both directions (code not in spec; spec not covered by the PR).

Prerequisites

  • A Specor workspace on a plan with GitHub integration enabled (Team or above).
  • Owner or Admin access to the GitHub organisation that owns the repo.

Setting up the GitHub App

1. Install the GitHub App

In Specor, go to Workspace Settings → Integrations → GitHub and click Connect GitHub.

You will be redirected to GitHub to install the Specor GitHub App. Select the repositories you want to grant access to, then confirm. GitHub redirects you back to Specor automatically.

The App requests the following permissions:

PermissionScopeWhy
ContentsReadFetch file tree and source code for brownfield sync
Pull requestsReadRead PR diffs for drift analysis
ChecksWritePost drift analysis results as a Check Run on the PR
MetadataReadRequired by GitHub for all Apps

2. Select connected repos

After installation, Specor shows the repos you granted access to. Select the ones you want to use for brownfield sync or PR sync.

Brownfield sync

Brownfield sync reads a repo at a given ref (branch, tag, or commit SHA) and builds a draft product graph from the codebase structure — route handlers, service classes, data models, permission checks, and configuration.

How it works

  1. Specor fetches the full file tree in a single GitHub API call.
  2. Files are filtered by type (.py, .ts, .tsx, .go, and others) — test directories, build outputs, lock files, and generated code are excluded automatically.
  3. Each file is distilled to its skeleton: function signatures, class definitions, and docstrings. Implementation bodies are elided. This keeps token costs low and avoids exposing sensitive logic to the LLM.
  4. The distilled codebase is analysed by an AI agent that groups related declarations into product concerns (Feature, Rule, Flow, Persona, Need), producing the same SemanticGroup objects used by the transcript and chat ingestion flows.
  5. You review the proposed groups on a draft branch using the same group-card UI as any other ingestion. Accept what looks right, edit what needs adjustment, and commit to your main branch when satisfied.

Running a brownfield sync

  1. Open Smart Ingestions in your workspace.
  2. Select From GitHub repo.
  3. Pick the connected repo and the ref to read from (default: main).
  4. Optionally set include or exclude glob patterns — e.g. exclude src/generated/** or include only src/api/**.
  5. Click Analyse. Specor shows a cost estimate (tokens) before the LLM call is made. Confirm to proceed.
  6. Review the proposed groups and accept the ones that should become spec nodes.

What gets included

By default Specor reads:

  • Python, TypeScript, TSX, JavaScript, Go, Rust, Java, Ruby, PHP, C#, Kotlin, C/C++
  • Markdown and MDX documentation files (passed through unchanged — they often describe intent)
  • JSON/YAML config files, GraphQL schemas, Protobuf definitions

By default Specor skips:

  • node_modules/, vendor/, dist/, build/, .venv/
  • Lock files (*.lock, package-lock.json)
  • Compiled or minified files (*.min.js, *.map)
  • Migration directories (alembic/versions/, db/migrations/)
  • Test directories (tests/, **/*.test.*, **/*.spec.*)
  • Generated code (generated/, __generated__/)
  • Files larger than 100 KB

You can override these with include_globs and exclude_globs in the UI.

PR drift detection

PR drift detection compares a GitHub pull request against your Specor product graph and surfaces gaps in both directions: code that was written but has no spec node, and spec nodes that should be covered by the PR but aren’t.

Results appear inside a Specor merge request, not in the global suggestions feed. This keeps the analysis scoped to the change being reviewed.

  1. Open the Specor merge request you are working on.
  2. Click Link GitHub PR and paste the GitHub PR URL (e.g. https://github.com/acme/my-app/pull/42).
  3. Click Run drift analysis to trigger the analysis. Specor returns immediately (202) and runs the analysis in the background.

You can re-run the analysis at any time by clicking Run drift analysis again — for example after addressing gaps and pushing new commits.

Automatic re-analysis on new commits

When the linked GitHub PR receives new commits (pull_request.synchronize webhook event), Specor re-runs the drift analysis automatically. The Specor MR is updated without any manual action.

What the analysis produces

Code → Spec gaps

For each changed file in the PR, Specor distils the diff and computes semantic similarity against every node in your product graph. Code that has no close match — a new route with no Feature, a validation rule with no Rule node — surfaces as a proposed node on the MR’s branch, ready to review and accept.

Spec → Code gaps

Specor checks every Feature, Rule, Flow, AcceptanceCriteria, and Persona on your main branch against the PR diff. Nodes that should be in scope for this PR but have no corresponding code appear as MR test cases — the same pass/fail checklist mechanism used for merge test cases.

Example: if your spec says “Guest Checkout Flow” is a feature, and this PR is modifying the checkout code, the analysis asks: “Is this flow implemented in the diff?”

Unlinking a PR

To remove the link, open the Specor MR and click Unlink GitHub PR. This removes the association but does not close either the GitHub PR or the Specor MR.

Security

  • The GitHub App uses short-lived installation access tokens (60-minute TTL, cached for 55 minutes) rather than long-lived personal access tokens or OAuth tokens.
  • Source code is fetched as base64 blobs over HTTPS from api.github.com. Specor never clones the repository or executes any code.
  • File distillation uses tree-sitter, a pure parser. It never runs, evaluates, or interprets code.
  • Specor only calls api.github.com — no URLs found inside source files are followed.
  • The GitHub App can be uninstalled from GitHub at any time. After uninstallation, Specor can no longer fetch new content but existing spec nodes are unaffected.

Permissions required

The integration endpoints enforce the following role requirements:

ActionMinimum role
View integration statusViewer
Connect / disconnect GitHubAdmin
Run brownfield syncEditor
Link / unlink a GitHub PREditor
Trigger drift analysisEditor