GitHub App Permissions#

The Dosu GitHub App implements a granular permission model that enables feature-based access control across issues, pull requests, and discussions. The permission model distinguishes between read-only access for code inspection and repository metadata, and read-write access for interactive features like responding to issues, applying labels, and managing pull requests.

Permissions are organized into two categories: read access includes repository contents, metadata, administration, actions, checks, and commit statuses; read-write access covers issues and issue comments, pull requests and pull request reviews, and discussions and discussion comments. This separation allows organizations to grant Dosu the minimum necessary permissions for their intended use cases, supporting a principle of least privilege approach to integration security.

The system implements graceful degradation patterns to handle permission failures, suspended installations, and authentication issues. Multi-layered authentication with GitHub App installation tokens as the primary method and personal access tokens as fallback ensures continued operation even when installations face issues. Automatic suspension detection and database state tracking enable the system to skip suspended repositories during operations, preventing repeated failures and optimizing resource utilization.

Permission Model#

Requested Permissions#

The Dosu GitHub App requests specific permissions during installation:

Read Access:

• Repository contents, metadata, and administration
• Actions, checks, and commit statuses

Read-Write Access:

• Issues and issue comments
• Pull requests and pull request reviews
• Discussions and discussion comments

These permissions enable Dosu to read code and conversations, respond to issues and discussions, and apply labels to issues and pull requests. Pull request permissions allow Dosu to read PR metadata and file changes, apply labels, power Self-Documenting PRs, and sync documentation changes back to repositories.

Authentication Architecture#

The authentication system uses JWT-based tokens to generate installation-specific access tokens, issued with a 10-minute expiration and a 30-second backdated timestamp to avoid clock skew issues. Installation access tokens are valid for one hour and automatically refreshed as needed.

The get_app_access_token function retrieves installation-specific access tokens with automatic retry logic, retrying up to 5 times with exponential backoff except for 403, 404, 410 errors and installation suspension/token-not-found exceptions. This selective retry strategy prevents wasted resources on operations that will never succeed.

Role-Based Access Control#

The system defines role-based access levels for repository operations:

• MAINTAINER_ROLES: ADMIN, MAINTAIN, WRITE, and TRIAGE
• WRITE_ACCESS_ROLES: ADMIN, MAINTAIN, and WRITE

To create a GitHub data source or deployment, users must have Triage permission or higher on the repository, or be the user who installed the Dosu GitHub App. Read-only collaborators cannot create data sources or deployments.

Feature-Based Access Control#

Issues Configuration#

Issues configuration controls how Dosu interacts with repository issues through several features:

Agent Reply Modes:

• Mention: Dosu only responds when explicitly tagged with @dosu
• Auto Draft: Dosu generates response drafts for review in the Review page
• Auto Reply: Dosu posts responses automatically without review

These modes provide progressive levels of automation, allowing teams to start conservatively and increase automation as they gain confidence.

Auto-Labeling:
Analyzes label taxonomy, historical patterns, and issue content to apply relevant labels. The configuration schema supports include/exclude lists to control which labels Dosu considers, custom instructions to guide labeling decisions, and an ignore list that prevents auto-labeling when certain labels are already present.

Stale Bot:
Posts summary comments, applies stale labels, and automatically closes inactive issues based on configurable thresholds.

Issue Voting:
Applies 👍 reactions to new issues to encourage community engagement.

Pull Requests Configuration#

Pull request configuration mirrors the issues setup with agent reply modes and includes additional PR-specific features:

Auto-Labeling:
Analyzes PR title, body, diff summary, and changed files to apply appropriate labels.

LGTM Label:
Automatically applies an "lgtm" label after maintainer approval.

Size Labels:
Automatically applied based on total line changes (XS to XXL), excluding auto-generated files detected via .gitattributes.

Self-Documenting PRs:
Monitors file paths using glob patterns to detect documentation staleness and can automatically update documentation. The monitored_paths configuration parameter accepts an array of glob pattern strings. When monitored_paths is empty, all file changes are monitored; otherwise, only matching paths trigger checks.

Discussions Configuration#

Discussions configuration provides agent reply modes identical to issues with an additional category selection feature:

Category Selection:
Allows administrators to specify which discussion categories trigger Dosu responses, defaulting to "Q&A" and "Questions" categories. This selectivity prevents Dosu from responding in announcement or general discussion categories.

Permission Checking Before Execution#

The agent tool system implements permission checking via AgentToolPermission, returning permission status before tool execution. Write operations require WRITE permissions:

• Documentation generation requires WRITE permissions
• Documentation updates require WRITE permissions
• Saving answers to the knowledge base requires WRITE permissions

Graceful Degradation Patterns#

Suspended Installation Handling#

The system implements comprehensive mechanisms to detect and handle suspended GitHub App installations:

Detection:
The http_403_indicates_installation_suspension function checks if HTTP 403 errors indicate suspended installations by parsing the error body for the message "This installation has been suspended".

Automatic Database Marking:
When a 403 error indicates installation suspension, the system automatically marks the repository as suspended in the database and raises an InstallationSuspended exception.

Webhook Lifecycle Management:
The system responds to suspend and unsuspend webhook actions. When suspended, all repositories are marked as suspended and associated deployments are disabled. When unsuspended, repositories are reactivated and labels are re-synced.

Proactive Skipping:
Suspended repositories are automatically skipped during syncing operations and webhook event handlers check suspension status before processing events, preventing repeated failures.

The GithubRepositoryInstallation model tracks suspension state with is_suspended and new_permissions_accepted boolean fields.

Multi-Tiered Authentication Fallback#

The system implements a multi-layered authentication strategy:

Primary Method:
GitHub App installation tokens are attempted first via get_app_access_token().

Fallback Strategy:
When InstallationTokenNotFound or InstallationSuspended exceptions are caught, the system falls back to personal access tokens or a shared token configured at the environment level. This allows continued operation with potentially reduced permissions rather than complete failure.

This fallback pattern is consistently applied in both get_access_token() and create_api_client() functions.

Permission-Related Error Handling#

Permission Denied Detection:
The is_permission_denied_error() function checks for GraphQL errors with type "FORBIDDEN" or messages containing "You do not have permission to".

Graceful Operation Skipping:
When syncing collaborators, permission denied errors are logged and the operation is skipped rather than failing the entire process.

Installation Event Handling:
During repository installation, permission errors during API client initialization result in suspending the installation rather than crashing.

Retry Logic and Error Recovery#

Exponential Backoff with Selective Retry:

Auth operations retry up to 5 times with exponential backoff, but specifically exclude 403, 404, and 410 errors, as well as InstallationSuspended and InstallationTokenNotFound exceptions. This prevents retrying unrecoverable errors.

GraphQL client operations retry up to 10 times but only for server errors (500+), connect timeouts, and read timeouts via the should_retry() function.

REST API operations use gh_api_retry with 5 retries and exponential backoff, excluding 404, 403, and 410 errors.

Rate Limit Handling:
The http_403_indicates_rate_limit() function checks if a 403 error contains "API rate limit exceeded". When syncing PR commits, rate limit errors are detected and re-raised as GitHubRateLimitError to trigger retry logic with backoff.

Installation and Lifecycle Management#

Installation Process#

Installation is performed through GitHub's app installation interface, where administrators can choose to grant Dosu access to all repositories in their account or organization, or limit access to specific repositories. This granular control allows organizations to start with limited scope and expand access as confidence grows.

After installation, Dosu automatically syncs three types of repository data: the list of accessible repositories, collaborators for each repository (used to control access in the Dosu dashboard), and labels for each repository (used for auto-labeling features).

Importantly, repositories are not automatically added as data sources or deployments after installation—users must explicitly create these configurations through the Dosu dashboard.

Lifecycle Events#

The installation event handler manages five lifecycle actions:

• CREATED: Establishes repository installations in the database and syncs collaborators and labels
• DELETED: Removes all repositories associated with the installation
• SUSPEND: Marks repositories as suspended when the installation is suspended
• UNSUSPEND: Reactivates repositories and re-syncs their labels
• NEW_PERMISSIONS_ACCEPTED: Updates the new_permissions_accepted flag and timestamp

Deployment Management#

Deployment status management enables administrators to pause deployments temporarily (suspending all automated actions), resume paused deployments, or delete deployments entirely. When an installation is suspended, all associated deployments are automatically disabled via SQL queries that set enabled = FALSE.

Why Pull Request Permissions Are Required#

Dosu requests pull request permissions for several specific purposes:

1. Read PR metadata and file changes: Essential for understanding what the PR changes
2. Apply PR labels: Auto-labeling, size labels, LGTM labels
3. Power Self-Documenting PRs: Detect documentation staleness based on code changes
4. Sync documentation changes: Create PRs to sync documentation updates back to repositories

Dosu may create pull requests in two scenarios:

1. When documentation changes that originated from a synced GitHub file are accepted, Dosu creates a PR to sync changes back to the source file
2. When a knowledge store is configured, Dosu's agent can create PRs to update documentation pages

Dosu does not push code changes or merge pull requests for regular code or features—the only other writes Dosu performs in GitHub are labels, reactions, and comments.

Relevant Code Files#

Related Topics#

• GitHub Integration - Broader architecture covering data sources, deployments, and webhook processing
• Auto-Labeling - Machine learning-based labeling system that depends on write permissions
• Role-Based Access Control (RBAC) - General access control patterns across Dosu
• Deployment Configuration - Configuration options for Issues, PRs, and Discussions
• Data Sources - Repository indexing and knowledge management