Path A: Start from GitHub Repos
The fastest way to get started with SGD. Install the GitHub App, let the platform scan your repositories, review the suggested capability model, and you are live.
Time to first results: 5-10 minutes.
Brownfield or greenfield?
How you onboard depends on whether the repo already has code in it. SGD supports both — pick the path that matches your repo.
| Brownfield — existing repos | Greenfield — brand-new repos | |
|---|---|---|
| Situation | An estate of repos that already have code, history, and conventions | A repo you are about to start, or one that is still close to empty |
| How SGD onboards | The GitHub App scans and infers — it detects tech stacks, scores health, and reverse-engineers a suggested capability model from the code that already exists | You scaffold first with the sgd-init bootstrapper, which lays the SGD governance structure down before the code is written |
| Starting posture | Governance is advisory at first (graceful degradation) — you see drift and coherence scores immediately, and tighten to blocking as the model is confirmed | Governance is blocking from day one because there is no legacy debt to grandfather in — you build clean against the standards from the first commit |
| Use this section | Steps 1–4 below | The greenfield quick-start, just below |
Most estates are brownfield
If you are connecting an existing GitHub organisation, follow the brownfield path (Steps 1–4). The scan is read-only and never blocks you — it shows you where you are before you decide what to enforce.
Greenfield quick-start
For a new or near-empty repo, wire up SGD in under 60 seconds — no app installation required:
npx @repo-sentry/sgd-initThis copies the GitHub Actions workflows, enforcement docs, and the pre-push hook into your repo, and migrates frontmatter on any existing .feature files. Useful flags:
npx @repo-sentry/sgd-init --phase=c # start at Phase C — the greenfield default, blocking from the first commit
npx @repo-sentry/sgd-init --dry-run # preview the changes without writing any files
npx @repo-sentry/sgd-init --skip-hooks # CI enforcement only, no local pre-push hookOnce the repo has its first capabilities and specs, install the GitHub App (Step 1) to bring it into the org-wide dashboard alongside your brownfield repos. From that point the two paths converge on the same governance model.
Step 1: Install the SGD GitHub App
Navigate to Settings > Integrations and click Connect GitHub Organisation. You will be redirected to GitHub to authorise the SGD App.
You have two choices:
| Option | When to use |
|---|---|
| All repositories | You want full visibility across the estate. Recommended for first-time setup. |
| Select repositories | You want to start with a subset (e.g., one team or domain). |
Start broad, refine later
Install on all repositories. You can always remove repos from governance later, but you cannot govern what you cannot see. The initial scan is read-only — nothing changes in your repos.
Once authorised, the platform receives webhook events and begins scanning immediately.
Step 2: Automatic Scanning
Within 2-5 minutes (depending on estate size), the platform analyses every connected repository across five dimensions:
What gets detected:
- Tech stack — Languages (TypeScript, C#, Python, Go, etc.), package managers, build tools, runtime versions
- Framework — Express, Next.js, FastAPI, ASP.NET, Spring Boot, etc.
- Cloud provider — Azure, AWS, GCP based on IaC templates, SDK usage, CI/CD targets
- Health score — 0-100 score across nine dimensions (compliance, drift, CI/CD, documentation, infrastructure, observability, security, freshness, AI-readiness)
- Capability inference — Logical groupings based on naming patterns, shared dependencies, code references, and repository topics
No code leaves your environment
The scan reads metadata, file structures, and configuration files. Source code is analysed in place via the GitHub API — nothing is copied or stored outside your GitHub organisation.
Step 3: Review the Suggested Capability Model
Once scanning completes, the platform presents a suggested capability model. This is a tree of your organisation's business capabilities with repositories mapped underneath.
The Uncategorised node (shown in amber) contains repositories the platform could not confidently map to a business capability. This is normal — tooling repos, scripts, and legacy code often do not fit neatly.
What you can do on this screen:
- Drag repositories between capabilities
- Rename capabilities to match your organisation's language
- Merge two capabilities into one
- Create new capabilities and drag repos into them
- Leave Uncategorised repos alone — they still get health scores and compliance checks, just without capability-level governance
Don't over-engineer the model
Spend 10-15 minutes reviewing. The model evolves — you can restructure later without losing history. A rough model today is better than a perfect model next quarter.
Step 4: Confirm and Go
Click Confirm Capability Model and the platform activates governance:
- Health scores begin tracking over time
- PR governance checks are enabled for all connected repos
- CLAUDE.md files are generated with capability context
- The ROI dashboard starts recording baseline metrics
You are now live.
What's next?
- Prefer to start from your issue tracker? See Path B: Start from Jira / ADO / GitHub Issues
- Want to understand the capability model in depth? See Your First Capability Model
- Ready to write a feature spec? See Writing Your First Feature Spec