Heimdall integrates with GitHub using OAuth 2.0 for seamless repository access and webhook-triggered scans.
OAuth App Setup
To enable GitHub integration, create a GitHub OAuth App:
- Go to GitHub Settings → Developer settings → OAuth Apps → New OAuth App
- Fill in the application details:
- Application name:
Heimdall Security Scanner (or your preferred name)
- Homepage URL:
http://localhost:8080 (or your deployment URL)
- Authorization callback URL:
http://localhost:8080/api/auth/github/callback
- Click Register application
- Copy the Client ID and generate a Client Secret
Environment Configuration
Add the following to your .env file:
GITHUB_CLIENT_ID=your_client_id_here
GITHUB_CLIENT_SECRET=your_client_secret_here
GITHUB_REDIRECT_URI=http://localhost:8080/api/auth/github/callback
For production deployments, update GITHUB_REDIRECT_URI to match your public domain (e.g., https://heimdall.example.com/api/auth/github/callback).
Repository Connection
Once OAuth is configured, users can connect their GitHub repositories:
Authorization Flow
- Navigate to Repositories → Connect Repository
- Click Connect with GitHub
- Authorize Heimdall to access your repositories
- Select the repository you want to scan
OAuth Scopes
Heimdall requests the following GitHub scopes:
| Scope | Purpose |
|---|
read:user | Read basic user profile information |
user:email | Access verified email addresses |
repo | Access private repositories for cloning |
Linking to Existing Accounts
If you already have a Heimdall account (email/password), the GitHub OAuth flow will:
- Match by email: If your GitHub email matches an existing Heimdall account, the GitHub connection is linked to that account
- Create new account: If no match is found, a new account is created using your GitHub profile
- Prevent conflicts: If the GitHub account is already linked to another user, you’ll be redirected with an error
See src/routes/auth.rs:934-958 for the account linking logic.
Webhook Configuration
Webhooks enable automatic scans when you push to GitHub.
Setting Up Webhooks
-
Generate a webhook secret:
-
Add to your
.env:
WEBHOOK_SECRET=your_generated_secret_here
-
In your GitHub repository, go to Settings → Webhooks → Add webhook
-
Configure the webhook:
- Payload URL:
https://heimdall.example.com/webhooks/github
- Content type:
application/json
- Secret: The same value as
WEBHOOK_SECRET from step 1
- SSL verification: Enable (recommended)
-
Select events:
- Choose Just the push event (only
push events trigger scans)
-
Click Add webhook
Signature Verification
Heimdall verifies all incoming webhooks using HMAC-SHA256 signature validation:
- GitHub sends the signature in the
X-Hub-Signature-256 header
- Heimdall computes the expected signature using your
WEBHOOK_SECRET
- Mismatched signatures return
401 Unauthorized
See src/routes/webhooks.rs:327-343 for the verification implementation.
Supported Events
Currently supported:
| Event | Description | Action |
|---|
push | Code pushed to a branch | Triggers full scan at the pushed commit SHA |
pull_request, issues) are accepted but ignored with a 200 OK response.
Issue Integration
GitHub Issues integration is planned for a future release. Track progress in the roadmap.
Troubleshooting
OAuth Flow Fails
Symptom: Redirected to login page after authorizing GitHub
Solutions:
- Verify
GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET match your OAuth app
- Check that
GITHUB_REDIRECT_URI exactly matches the callback URL in GitHub settings (including protocol and trailing path)
- Ensure your server is reachable at the redirect URI
Webhook Deliveries Fail
Symptom: GitHub shows “Failed to deliver” in webhook delivery history
Solutions:
- Check the Recent Deliveries tab for error details
- Verify
WEBHOOK_SECRET matches between GitHub and Heimdall
- Ensure
/webhooks/github endpoint is publicly accessible (no auth required)
- Review Heimdall logs:
docker compose logs -f heimdall | grep webhook
Repository Not Found After OAuth
Symptom: Connected GitHub but repository doesn’t appear
Solutions:
- Verify the repository matches the
clone_url from the push webhook
- Check database:
SELECT * FROM repos WHERE remote_url LIKE '%github.com%';
- Re-connect the repository through the UI
API Reference
| Endpoint | Method | Description |
|---|
/api/auth/github/authorize | GET | Initiate GitHub OAuth flow |
/api/auth/github/callback | GET | OAuth callback (called by GitHub) |
/webhooks/github | POST | GitHub webhook receiver (public) |