GitHub Apps help developers automate repository management, integrate external services, and build tools that interact with GitHub through APIs. However, an application that receives more permissions than it needs can create unnecessary security risks. If its credentials are compromised, excessive permissions may allow an attacker to perform actions far beyond the application's original purpose.
GitHub has introduced several improvements to GitHub Apps that help developers reduce unnecessary access and manage application permissions more effectively. The updates include dedicated permissions for repository creation and installation management, improved repository-level installation controls, support for refreshing expiring user access tokens, and a redesigned credential management interface.
These changes are particularly useful for organizations that want to move away from classic personal access tokens (PATs) and adopt more controlled, application-based authentication.
In this article, we will examine the permission changes, explain how they support the principle of least privilege, and explore practical ways to apply them when building and maintaining GitHub Apps.
What Is the Principle of Least Privilege?
The principle of least privilege means giving an application, user, or service only the permissions necessary to perform its assigned tasks.
For example, a GitHub App that creates repositories should not automatically receive permission to delete or transfer repositories if those operations are not part of its responsibilities.
Similarly, an application that reads pull requests should not need write access to repository contents merely because another feature might use it in the future.
GitHub Apps support fine-grained permissions for different resources, including repository contents, pull requests, issues, and organization settings. Developers select the permissions their applications require, and administrators approve installations according to their organization's policies.
The objective is to limit the potential impact of compromised credentials, implementation errors, and unintended API operations.
What's New in GitHub App Permissions?
GitHub's October 13, 2026 announcement introduced several improvements related to permissions and application management.
1. Dedicated Permission for Repository Creation
GitHub introduced the repository_creation:write permission for GitHub Apps and fine-grained personal access tokens.
Previously, creating a repository required the broader repository_administration:write permission. That permission also enables other administrative operations, including repository deletion and transfer.
The new permission allows an application to create repositories without automatically receiving those additional administrative capabilities.
This is an important distinction for automation platforms that provision repositories for new projects. The application can perform its intended task without requesting unrelated administrative access.
An application using this permission still requires an organization administrator to install the app.
2. Permission for Managing Installation Repositories
GitHub also introduced installation_repositories:write, a repository-level fine-grained permission for managing which repositories are associated with an organization's GitHub App installations.
The relevant installation management APIs now support GitHub Apps and fine-grained personal access tokens rather than relying exclusively on the broader classic repo scope.
This allows organizations to build automation that adds or removes repositories from app installations without relying on an administrator's broadly scoped personal access token.
For example, an internal provisioning service could manage which repositories are available to an approved code analysis application as projects are created or retired.
3. Easier Installation of Approved Apps
Repository administrators can now add their repositories to an existing organization-level GitHub App installation when the organization has already approved that app.
Previously, repository administrators were blocked from adding repositories to apps requesting organization-level access, even when an organization owner had already approved the application.
The updated behavior reduces unnecessary approval steps without granting repository administrators additional organization-level permissions.
Organization owners can still restrict repository administrators from installing GitHub Apps through the organization's settings.
4. Support for the offline_access Scope
GitHub Apps now support the offline_access scope for user authorization.
GitHub Apps use short-lived, rotating user access tokens by default, but some applications previously disabled expiration for convenience.
With offline_access, an application can receive a refresh token alongside an expiring user access token. It can then obtain a new access token without requiring the user to authorize every session again.
This support helps developers migrate gradually toward expiring tokens. The scope affects the specific authorization flow; it does not replace the app's configured permissions.
5. Improved Credential Management
GitHub has moved GitHub App credentials into a dedicated Credentials tab.
The interface separates client secrets and key pairs from the rest of the application configuration. This makes credentials easier to locate and manage while preparing the interface for additional credential options.
The updates are scheduled for GitHub Enterprise Server 3.24, except for offline_access support, which is included in GitHub Enterprise Server 3.23.
Comparing the New Permissions
The following table summarizes the key differences.
Permission or feature | Purpose | Security benefit |
|---|
repository_creation:write
| Create repositories | Avoids requiring broader repository administration access |
installation_repositories:write
| Add or remove repositories from an app installation | Supports more controlled installation management |
Repository-level installation controls | Add repositories to already approved organization apps | Reduces unnecessary approval steps |
offline_access
| Refresh expiring user access tokens | Supports migration to short-lived tokens |
Dedicated Credentials tab | Manage client secrets and key pairs | Improves credential administration |
These features address different parts of application security. Permissions determine what an application can do, installation settings determine which repositories it can access, and token expiration limits how long an access token remains valid.
How to Apply Least-Privilege Permissions
Consider an internal developer platform that creates repositories and registers them with an approved automation application.
A secure implementation should separate repository creation from installation management rather than assigning broad administrative permissions to a single application without considering its responsibilities.
Step 1: Identify the Required Operations
Before registering the app, list the operations it must perform.
For example:
Create a repository for a new project.
Add an eligible repository to an existing app installation.
Read repository metadata when provisioning completes.
Avoid deleting or transferring repositories unless explicitly required.
This inventory helps prevent permission requests from expanding beyond the application's actual purpose.
Step 2: Select the Narrowest Appropriate Permissions
Use repository_creation:write when the application needs to create repositories.
Use installation_repositories:write when it needs to manage repository membership in an installation.
Add other permissions only when required by specific API operations. Repository creation and installation management are separate capabilities, so one should not be assumed to grant the other.
Step 3: Separate Responsibilities in the Application
Application code should keep repository provisioning separate from installation management.
The following C# example illustrates a simple application-level policy for separating these responsibilities. It is not a GitHub authorization mechanism; GitHub must still enforce the actual permissions associated with the app and its tokens.
public enum RepositoryOperation
{
Create,
AddToInstallation,
RemoveFromInstallation
}
public static class RepositoryOperationPolicy
{
public static string GetRequiredPermission(
RepositoryOperation operation)
{
return operation switch
{
RepositoryOperation.Create =>
"repository_creation:write",
RepositoryOperation.AddToInstallation =>
"installation_repositories:write",
RepositoryOperation.RemoveFromInstallation =>
"installation_repositories:write",
_ => throw new ArgumentOutOfRangeException(
nameof(operation))
};
}
}
The method makes the intended permission requirement explicit for each supported operation. A larger application could use this mapping when validating its configuration or generating an installation checklist.
However, a local policy does not grant access to GitHub. The application must still authenticate correctly, use an appropriately scoped token, and handle authorization failures returned by the API.
Step 4: Test With Restricted Access
Test the application against a dedicated test organization or repository before enabling it in production.
Verify that repository creation succeeds with the intended permission and that unrelated administrative operations are not available through the app's authorization.
Also test installation management separately. A successful repository creation request does not prove that the application can add that repository to an installation.
Step 5: Review Credentials and Token Expiration
Store private keys, client secrets, and refresh tokens in an appropriate secrets manager. Do not commit them to source control or print them in application logs.
For user authorization flows, evaluate offline_access and short-lived tokens when persistent access is required.
Refresh tokens should be protected like other sensitive credentials, and applications must handle expiration, refresh failures, and revoked authorization.
Best Practices for GitHub App Security
1. Request Permissions Based on Actual Requirements
Do not request broad permissions simply because they might be useful later.
Start with the minimum permissions required for the current functionality. Add permissions only when a concrete feature requires them.
2. Limit Repository Access
Where possible, restrict an app installation to the repositories it needs rather than granting access to every repository in an organization.
Review installation access when projects are archived, transferred, or removed from the application's workflow.
3. Use Short-Lived Tokens
Prefer expiring tokens where supported. Short-lived tokens reduce the period during which a stolen token can be reused.
Implement token refresh carefully and avoid assuming that a refresh token remains valid indefinitely.
4. Rotate and Protect Credentials
Keep private keys and client secrets out of source code, build logs, and application configuration files committed to source control.
Establish a rotation procedure and remove credentials that are no longer needed. Ensure that applications can handle credential rotation without exposing secrets during deployment.
5. Monitor Permission Changes
Review application permission requests and installation changes through the available administrative controls and audit records.
A permission change should trigger a review of whether the application genuinely needs the additional access.
Advantages and Disadvantages
Advantages
Reduced administrative access: Repository creation no longer requires the broader repository administration permission.
More controlled installation management: The new permission supports automation for adding and removing repositories from app installations.
Simpler administration: Repository administrators can work with organization-approved apps without repeating the same approval process.
Improved token lifecycle management: offline_access supports the transition to expiring user access tokens.
Clearer credential management: The dedicated Credentials tab makes secrets and key pairs easier to manage.
Disadvantages
Permission planning is required: Developers must identify which permissions each operation needs.
Migration work may be necessary: Existing applications that depend on broader permissions or non-expiring user tokens may need changes.
Administrative policies still apply: The new permissions do not bypass organization approval requirements.
More credential lifecycle logic: Applications using expiring tokens must handle refresh failures, token rotation, and revocation.
Common Mistakes and Troubleshooting
Repository Creation Fails
Check whether the app has the required repository creation permission and whether the installation has been approved by an organization administrator.
Also verify that the API request is being made against the correct account and endpoint.
The App Cannot Add a Repository to an Installation
Confirm that the app has installation_repositories:write and that the authenticated identity is authorized to perform the operation.
Repository creation and installation management are separate operations and may require separate permissions.
Token Refresh Fails
Verify that the application requested offline_access through the appropriate authorization flow and securely retained the refresh token.
Handle expired, revoked, or otherwise invalid refresh tokens by requiring authorization again when necessary.
An App Requests Too Many Permissions
Review the application's feature requirements and identify which API operations actually require elevated access.
Replace broader permissions with narrower alternatives where available, then test the application to confirm that its required functionality still works.
Summary
GitHub's GitHub App improvements give developers more precise control over repository creation, installation management, and user token lifecycles. The new repository_creation:write permission reduces the need for broad repository administration access, while installation_repositories:write supports more controlled automation of installation membership.
The improvements to approved app installations, offline_access, and credential management also help teams maintain secure integrations with less administrative friction.
For developers, the main lesson is to treat permissions, repository access, and credential lifetime as separate security controls. Select only the permissions required by each application, protect credentials carefully, and test authorization boundaries before deploying automation to production.
Join the conversation! Your thoughts help the community grow.