GitHub Integration
The GitHub connector uses a Personal Access Token (or a GitHub App installation token) to scan your organisation's repositories for branch protection coverage and open code scanning alerts. This evidence supports secure development lifecycle and change management controls.
repo, read:org
Minimum token scopes
Bearer
Authentication method
A.8.25, A.8.29
Example ISO 27001 control mappings
Prerequisites
Create a GitHub Personal Access Token
Use a machine account (bot user) rather than a personal GitHub account so the token is not tied to an individual.
Classic token (simplest)
In GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic).
- Note: "aisec-evidence-collector"
- Expiry: 90 days (set a renewal reminder)
- Scopes: repo (full — needed to read branch protection rules on private repos), read:org
- Copy the token value immediately — shown once only
Fine-grained token (recommended)
Fine-grained tokens are scoped to specific repositories and resource types.
- Resource owner: your GitHub organisation
- Repository access: All repositories or selected repositories
- Permissions: Repository → Administration: Read-only, Code scanning alerts: Read-only
- Organisation permissions: Members: Read-only
Configuration
Connect GitHub in AISEC
Enter the token and your GitHub org or username in Settings → Integrations → GitHub → Configure.
Step-by-step
- Personal Access Token: the token value you copied from GitHub
- Org / User: your GitHub organisation login name (e.g. my-org) or personal username
- Repos (optional): comma-separated list of repository names to scan (e.g. api,frontend,infra). Leave blank to scan all repositories (up to 100 discovered, 50 checked for branch protection, 20 for code scanning).
- Sync frequency: daily is suitable for most teams
- GitHub Enterprise Server: if using GHES, enter your server URL in the API Base URL field (optional, defaults to https://api.github.com)
- Click Connect, then Sync now
Evidence collected
What appears in your evidence register
Two evidence items are produced per sync.
Branch Protection Coverage
Percentage of repositories with default-branch protection enabled. Lists repos missing protection.
- Maps to ISO 27001: A.8.25, A.8.29, A.8.32
- Maps to SOC 2: CC8.1
Code Scanning Alerts
Total open code scanning alerts across sampled repositories, grouped by repository.
- Maps to ISO 27001: A.8.8, A.8.29
- Maps to SOC 2: CC8.1
Troubleshooting
Common issues
- 401 Unauthorized — token has expired or been revoked; generate a new one in GitHub.
- 403 on branch protection — the token lacks the repo scope; classic tokens need full repo scope to read protection rules on private repos.
- Empty repository list — if the org has no public repos and the token lacks read:org, discovery falls back to listing user repos; check token scopes.
- Code scanning 404 — code scanning may not be enabled on the repository; this is expected and the connector continues without failing.
Ready to connect?
Create a machine account in GitHub, generate a PAT with repo and read:org scopes, then enter the details in AISEC.