GitHub Collector
Automatically collect GitHub repository settings, branch protection rules, and access permissions. Enforce VCS standards across your organization.
github to your lunar-config.yml:uses: github://earthly/lunar-lib/collectors/github@v1.0.0
What This Integration Collects
This integration includes 3 collectors that gather metadata from your systems.
repository
Fetches basic repository settings from the GitHub API including visibility (public/private/internal), default branch name, topics, and allowed merge strategies (merge commit, squash, rebase). Writes to .vcs.provider, .vcs.visibility, .vcs.default_branch, .vcs.topics, and .vcs.merge_strategies.
branch-protection
Fetches branch protection rules for the default branch from the GitHub API. Collects required approvals, code owner review, dismiss stale reviews, required status checks, force push/deletion restrictions, linear history requirements, signed commit requirements, and push restrictions (users, teams, apps). Writes comprehensive settings to .vcs.branch_protection.
access-permissions
Fetches repository access permissions from the GitHub API with pagination support. Collects direct collaborators (login, permission level, type) and teams with access (slug, name, permission). Does not expand team memberships for performance. Writes to .vcs.access.collaborators and .vcs.access.teams.
How Collectors Fit into Lunar
Lunar watches your code and CI/CD systems to collect SDLC data from config files, test results, IaC, deployment configurations, security scans, and more.
Collectors are the automatic data-gathering layer. They extract structured metadata from your repositories and pipelines, feeding it into Lunar's centralized database where guardrails evaluate it to enforce your engineering standards.
Learn How Lunar Works →Example Collected Data
This collector writes structured metadata to the Component JSON. Here's an example of the data it produces:
{
"vcs": {
"provider": "github",
"default_branch": "main",
"visibility": "private",
"topics": ["backend", "api", "microservice"],
"merge_strategies": {
"allow_merge_commit": true,
"allow_squash_merge": true,
"allow_rebase_merge": false
},
"branch_protection": {
"enabled": true,
"branch": "main",
"require_pr": true,
"required_approvals": 2,
"require_codeowner_review": true,
"dismiss_stale_reviews": true,
"require_status_checks": true,
"required_checks": ["ci/build", "ci/test", "security/scan"],
"require_branches_up_to_date": true,
"allow_force_push": false,
"allow_deletions": false,
"require_linear_history": false,
"require_signed_commits": true,
"restrictions": {
"users": ["deployment-bot"],
"teams": ["platform-team"],
"apps": ["github-actions"]
}
},
"access": {
"collaborators": [
{
"login": "alice",
"permission": "admin",
"type": "User"
},
{
"login": "deployment-bot",
"permission": "write",
"type": "Bot"
}
],
"teams": [
{"slug": "backend-team", "name": "Backend Team", "permission": "write"},
{"slug": "platform-team", "name": "Platform Team", "permission": "admin"}
]
}
}
}Configuration
Configure this collector in your lunar-config.yml.
Secrets
This collector requires the following secrets to be configured in Lunar:
| Secret | Description |
|---|---|
GH_TOKEN
|
GitHub personal access token with `repo` scope for API authentication |
Documentation
View on GitHubGitHub Collector
Collects GitHub repository settings and branch protection rules via the GitHub API.
Overview
This collector queries the GitHub API to gather version control system (VCS) configuration data including repository visibility, default branch, topics, merge strategies, comprehensive branch protection rules, and access permissions for direct collaborators and teams. It runs on a cron schedule and requires the LUNAR_SECRET_GH_TOKEN environment variable for API authentication.
Collected Data
This collector writes to the following Component JSON paths:
| Path | Type | Description |
|---|---|---|
.vcs.provider |
string | VCS provider name (always "github") |
.vcs.default_branch |
string | Default branch name (e.g., "main", "master") |
.vcs.visibility |
string | Repository visibility (public, private, internal) |
.vcs.topics |
array | Repository topics/tags |
.vcs.merge_strategies |
object | Allowed merge strategies for pull requests |
.vcs.branch_protection |
object | Branch protection rules and restrictions |
.vcs.access |
object | Repository access permissions for users and teams |
Collectors
This plugin provides the following collectors (use include to select a subset):
| Collector | Description |
|---|---|
repository |
Collects basic repository settings including visibility, default branch, topics, and allowed merge strategies |
branch-protection |
Collects branch protection rules including required approvals, status checks, force push restrictions, commit signing requirements, and push access restrictions |
access-permissions |
Collects repository access permissions including direct collaborators and teams (does not expand team memberships) |
Installation
Add to your lunar-config.yml:
collectors:
- uses: github://earthly/lunar-lib/collectors/github@v1.0.0
on: ["domain:your-domain"] # Or use tags like [backend, kubernetes]
# include: [repository] # Only run specific checks (omit to run all)
Open Source
This collector is open source and available on GitHub. Contribute improvements, report issues, or fork it for your own use.
Common Use Cases
Explore guardrails that use data from GitHub Collector.
Ready to Automate Your Standards?
See how Lunar can turn your engineering wiki, compliance docs, or postmortem action items into automated guardrails with our 100+ built-in guardrails.
Infrastructure conventions
Post-mortem action items
Security & compliance policies
Testing & quality requirements