Step 1: Install the GitHub App
Navigate to the Specmark GitHub App installation page and authorize it for your organization. You can grant access to all repositories or select specific ones.
Permissions requested:
- Contents: Read (detect file presence — README, CODEOWNERS, workflows)
- Actions: Read (verify CI workflow status)
- Administration: Read + Write (check and fix branch protection rules)
- Pull requests: Read + Write (open auto-fix PRs)
- Issues: Read + Write (create violation issues when needed)
- Secret scanning alerts: Read (detect exposed secrets)
- Members: Read (count active contributors for billing)
Step 2: Automatic Repo Discovery
Once installed, Specmark automatically discovers all repositories in your organization. No configuration file is needed — repos are detected via the GitHub App installation event. Discovery takes a few seconds regardless of org size.
Step 3: Standards Check Runs
Immediately after discovery, Specmark runs its default standards checks against every repository. The checks evaluate:
- Branch protection rules (require reviews, dismiss stale approvals)
- CODEOWNERS file presence
- CI workflow configured (GitHub Actions)
- Secret scanning enabled
- Dependabot alerts enabled
- README present
- License file present
Each check produces a pass or fail result with a severity level (critical, high, or medium).
Step 4: View Your Compliance Dashboard
Visit specmark.app/your-org to see your organization's compliance dashboard. The dashboard shows:
- Overall compliance percentage across all repos
- Per-repo pass/fail breakdown
- Critical violations requiring immediate attention
- Trend over time (how compliance changes week-over-week)
Step 5: Fix Violations with One-Click Actions
For many violations, Specmark offers self-service fix actions directly from the dashboard:
- Enable branch protection — applies recommended rules to your default branch
- Add CODEOWNERS — opens a PR with a starter CODEOWNERS file
- Enable secret scanning — turns on GitHub secret scanning via the API
- Enable Dependabot — creates a dependabot.yml with sensible defaults
Each action either applies the fix directly (for settings changes) or opens a pull request for review (for file additions).
What Happens Next?
After the initial setup, Specmark continuously monitors your organization via webhook events. When a new repo is created, a branch protection rule is changed, or a workflow is deleted, Specmark re-evaluates compliance in real time and alerts you to any drift.
To customize which standards are enforced and at what severity, see the Standards & Rules documentation.