GitHub Integration
CodeStax integrates deeply with GitHub for repository scanning, PR reviews, and webhook automation.
Connecting GitHub
During Signup
Click Continue with GitHub on the signup page. This authorizes CodeStax with the required permissions and connects your GitHub account automatically.
After Signup
- Go to Settings on the dashboard
- Navigate to Integrations or API Keys tab
- Click Connect GitHub
- Authorize the CodeStax app on GitHub
Permissions
CodeStax requests standard GitHub OAuth scopes for repository access, profile information, and webhook management.
Features
Repository Import
Once connected, you can import any repository you have access to (personal and organization repos). CodeStax fetches your repository list and lets you select which ones to import.
Automated PR Reviews
When you open or update a pull request, GitHub sends a webhook to CodeStax, which:
- Analyzes the PR diff for security issues
- Scores the PR risk level (0-100)
- Records findings in your dashboard
Webhook Events
CodeStax listens for relevant GitHub webhook events including pull request and push events to trigger automated reviews and scans.
Webhook Security
All GitHub webhooks are verified using HMAC SHA-256 signatures. CodeStax checks the X-Hub-Signature-256 header to ensure the request originates from GitHub.
Authentication for Scans
When scanning GitHub repositories, CodeStax uses your stored OAuth token to:
- Clone private repositories securely
- Access repository contents without requiring SSH keys
- Refresh tokens automatically when they expire
Webhook Troubleshooting
| Problem | Solution |
|---|---|
| Webhooks not firing | Check if the webhook is registered in your GitHub repo settings → Webhooks |
| Delivery failures | Verify your CodeStax instance is reachable from the internet |
401 Unauthorized | Re-connect your GitHub account to refresh the webhook secret |
Quality-Gate Check Run
When the CodeStax GitHub App is installed + a quality gate is configured, every completed scan posts a Check Run on the scanned commit:
- Check name:
CodeStax Quality Gate - Conclusion mapping:
| Gate status | Block-merge-on-fail OFF (default) | Block-merge-on-fail ON |
|---|---|---|
| passed | success ✓ | success ✓ |
| failed | neutral (visible, non-blocking) | failure ✗ (branch protection blocks merge) |
| not_configured | skipped | skipped |
- Summary includes violations table (top 20), new-in-PR count, and a link to the full scan detail page
- Click-through URL goes to
FRONTEND_URL/dashboard/scans/:scan_id
Making the Check Required
To actually block merges on gate failure:
- Flip on Block merge on fail in Settings → Policies → Quality Gates
- In GitHub → Repo Settings → Branches → Branch protection rule → Require status checks to pass → add
CodeStax Quality Gate
Without branch protection, failure posts but doesn’t block.
Quality-Gate PR Comment
Alongside the Check Run, CodeStax posts a top-level PR comment with violations + per-rule fix hints. The comment is upserted by a marker — re-scans update the existing comment rather than posting new ones. Your PR timeline stays clean.
- Silent on green first time — no spam when the gate passes from the start
- Updates in place on re-scan
- Survives edits — if a user edits the comment, next scan creates a new one (can’t silently stomp user content)
Disable this flow entirely by setting SCANNER_PR_COMMENT_ENABLED=0 on the scanner server.