Overview

This matrix shows how GitHub repository and organization permissions map to CircleCI functionality when using the GitHub OAuth integration. CircleCI inherits and mirrors permissions from GitHub, meaning your GitHub role determines your CircleCI capabilities.

GitHub Repository Permissions → CircleCI Capabilities

GitHub Permission Level	Repository Access	CircleCI Project Actions	CircleCI Build Controls	CircleCI Settings Access
No Access	Cannot see repo	❌ Cannot see project	❌ Cannot view builds	❌ No access
Read	View code, issues, PRs	✅ View project ✅ View build logs ✅ View pipeline history	❌ Cannot trigger builds ❌ Cannot rebuild ❌ Cannot SSH debug	❌ Cannot modify settings
Triage	Read + manage issues/PRs	✅ View project ✅ View build logs ✅ View pipeline history	❌ Cannot trigger builds ❌ Cannot rebuild ❌ Cannot SSH debug	❌ Cannot modify settings
Write	Read + push code	✅ View project ✅ View build logs ✅ View pipeline history ✅ Add project to CircleCI	✅ Trigger builds ✅ Rebuild jobs ✅ Rebuild with SSH ✅ Cancel builds	⚠️ Limited project settings ❌ Cannot manage contexts
Maintain	Write + manage repo settings	✅ All Write permissions ✅ Manage project settings	✅ All build controls ✅ Advanced debugging	✅ Project configuration ✅ Environment variables
Admin	Full repository control	✅ All project access ✅ Delete projects	✅ All build controls ✅ Full debugging access	✅ All project settings ✅ SSH keys management ✅ Webhook configuration

GitHub Organization Permissions → CircleCI Organization Controls

GitHub Org Role	CircleCI Org Role	Organization Management	Context Management	Plan & Billing	Insights & Analytics
Member	Contributor	✅ View org settings ❌ Cannot modify org	✅ View contexts ✅ Use contexts ✅ Edit context variables	❌ Cannot view plan<br>❌ Cannot manage billing	✅ View org insights
Owner	Admin	✅ Full org management ✅ Manage connections ✅ View audit logs ✅ Manage policies	✅ Full context control ✅ Create restricted contexts ✅ Manage context permissions	✅ View & manage plan ✅ Billing management ✅ Usage analytics	✅ Full insights access ✅ Export capabilities

Specific Feature Access Matrix

Context Management

GitHub Permission	Create Context	View Context	Edit Variables	Use in Builds	Restricted Contexts
Read	❌	✅	❌	❌	❌
Write	✅*	✅	✅*	✅	❌
Admin/Owner	✅	✅	✅	✅	✅

*Requires write permissions to at least one project in the organization

Pipeline & Build Operations

GitHub Permission	View Pipelines	Trigger Builds	Rebuild	SSH Debug	Edit Config	Manage Triggers
Read	✅	❌	❌	❌	❌	❌
Write	✅	✅	✅	✅	✅	❌
Admin	✅	✅	✅	✅	✅	✅

Project Configuration

GitHub Permission	Add Project	Project Settings	Environment Variables	SSH Keys	Webhooks	Notifications
Read	❌	❌	❌	❌	❌	❌
Write	✅	⚠️ Limited	⚠️ Limited	❌	❌	✅
Admin	✅	✅ Full	✅ Full	✅	✅	✅

OAuth Scopes Requested by CircleCI

CircleCI requests these broad GitHub OAuth scopes:

OAuth Scope	Purpose	Access Level
`repo`	Repository access	Full read/write access to all public and private repos
`user:email`	User identification	Read user email addresses
`read:org`	Organization info	Read organization membership and team info
`admin:repo_hook`	Webhooks	Create and manage repository webhooks
`admin:org_hook`	Org webhooks	Create and manage organization webhooks

GitHub App vs OAuth Permissions

Feature	GitHub OAuth App	GitHub App
Repository Access	All repos user has access to	✅ Selective repository access
Permission Granularity	❌ Broad scopes (read/write/admin)	✅ Fine-grained permissions
Token Security	❌ Long-lived tokens	✅ Short-lived tokens
Organization Control	❌ User-level authorization	✅ Organization-level control
Audit Trail	⚠️ Limited	✅ Enhanced logging

Important Notes & Limitations

Permission Inheritance (when using the CircleCI GitHub OAuth Integration)

CircleCI mirrors GitHub permissions: Your GitHub role directly determines CircleCI access
No permission escalation: CircleCI cannot grant access beyond what you have in GitHub
Real-time sync: Permissions are checked on each page load
Single OAuth token: One token per user across all organizations

Common Issues

Broad OAuth scopes - CircleCI requires extensive permissions even for simple CI/CD
Organization-wide access - OAuth grants access to all repos user can access
No read-only CI - Even viewing builds requires significant GitHub permissions
Third-party restrictions - GitHub org owners can block OAuth apps

Security Considerations

CircleCI can access any repository the authenticated user can access
Write permissions allow CircleCI to modify code and repository settings
Consider using GitHub Apps for better security and granular control
Regularly audit OAuth application permissions in GitHub settings

Migration Recommendations

For better security and control:

Consider GitHub App Integration - Provides fine-grained permissions and better security
Use service accounts - Create dedicated GitHub users with minimal required permissions
Enable org restrictions - Use GitHub's third-party application access policies
Regular permission audits - Review and revoke unnecessary access periodically