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.
Screenshot: GitHub App installation permissions screen showing repository access options.
Permissions required: Specmark requests read-only access to repository metadata, contents (README and config files), and commit history. We do not request write access or access to your source code.
Step 2: Wait for Initial Scan (60 seconds)
After installation, Specmark will automatically scan all repositories in your organization. The initial scan takes approximately 60 seconds for an org with 20-50 repositories. You'll receive a webhook confirmation once the scan is complete.
Screenshot: Post-install redirect page showing "Scanning your repositories..." progress indicator.
Step 3: View Your Catalog
Visit specmark.app/your-org to see your public catalog. Each repository is graded A-F based on our default scorecard rules. The catalog displays:
- Repository name and description
- Overall grade and numeric score
- Passing/failing rule counts
- Last scan timestamp
Screenshot: Catalog page showing a grid of repository cards with grades and scores.
Step 4: Drill Down into a Repository
Click any repository card to see a detailed breakdown of scorecard results. The drilldown page shows:
- All rules evaluated (passing, failing, and skipped)
- Observed values (e.g., "README.md found", "No CODEOWNERS file")
- Rule weights and categories (documentation, testing, CI, security, etc.)
- Fix suggestions for failing rules
Screenshot: Repository drilldown page showing tabular rule results grouped by category.
Step 5: Copy and Embed a Badge
At the top of the drilldown page, you'll see a badge preview and Markdown snippet. Copy the snippet and paste it into your README. The badge displays your current grade and updates automatically every 6 hours (or on push). Clicking the badge takes readers to your public scorecard drilldown.
Screenshot: Badge preview with copy button and rendered badge example in a GitHub README.
Step 6 (Optional): Add a Custom Scorecard
Create a .specmark.yml file in the root of any repository to define custom rules. Custom rules are merged with the default scorecard. See the Custom Scorecards reference for all supported check types.
Step 7 (Optional): Configure Slack Notifications
To receive alerts when a repository's score drops by one or more letter grades:
- Visit your catalog page and click Settings (top-right).
- Under Integrations, add a Slack webhook URL.
- Test the integration by clicking Send Test Notification.
Screenshot: Integrations settings page showing Slack webhook URL input field.
Common Questions
Q: Can I hide repositories from the public catalog?
Not yet. All installed repositories appear in your public catalog. Private repository scorecards are publicly visible (but source code is not). We're adding per-repo visibility controls in a future update.
Q: How often are scores updated?
Automatically every 6 hours for all repositories, plus within 60 seconds of a push to the default branch.
Q: What if I don't want a specific rule?
Use a custom .specmark.yml to override the default scorecard. You can set weights to zero or omit rules entirely.
Q: Can I use Specmark with GitLab or Bitbucket?
Not yet. Specmark currently supports GitHub only. GitLab and Bitbucket support is on the roadmap for late 2026.
Q: How do I uninstall Specmark?
Go to your organization's GitHub settings, navigate to Installed GitHub Apps, and click Uninstall next to Specmark. Your data will be deleted 30 days after uninstallation.
Q: Where can I report a bug or request a feature?
Open an issue on our GitHub repository or email [email protected].