Managing GitHub App Permissions for Secure Repository Automation

using System.IdentityModel.Tokens.Jwt;
using Microsoft.IdentityModel.Tokens;
using System.Security.Cryptography;
using System.Security.Claims;

public class GitHubAppTokenService
{
    private readonly string _appId;
    private readonly string _privateKey;

    public GitHubAppTokenService(
        string appId,
        string privateKey)
    {
        _appId = appId;
        _privateKey = privateKey;
    }

    public string GenerateJwt()
    {
        using var rsa = RSA.Create();

        rsa.ImportFromPem(_privateKey);

        var securityKey = new RsaSecurityKey(rsa);

        var credentials = new SigningCredentials(
            securityKey,
            SecurityAlgorithms.RsaSha256
        );

        var now = DateTimeOffset.UtcNow;

        var claims = new[]
        {
            new Claim(
                JwtRegisteredClaimNames.Iss,
                _appId
            )
        };

        var token = new JwtSecurityToken(
            claims: claims,
            notBefore: now.AddSeconds(-30).UtcDateTime,
            expires: now.AddMinutes(8).UtcDateTime,
            signingCredentials: credentials
        );

        return new JwtSecurityTokenHandler()
            .WriteToken(token);
    }
}

GitHub App JWTs should use the application's identifier as the issuer, be signed using the registered private key, and have a short validity period. The example uses an eight-minute lifetime, within GitHub's supported JWT expiration limit.

Next, exchange the JWT for an installation access token:

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json.Serialization;

public class GitHubInstallationTokenService
{
    private readonly HttpClient _httpClient;

    public GitHubInstallationTokenService(
        HttpClient httpClient)
    {
        _httpClient = httpClient;
    }

    public async Task<string> CreateTokenAsync(
        string jwt,
        long installationId,
        long repositoryId,
        CancellationToken cancellationToken)
    {
        var request = new HttpRequestMessage(
            HttpMethod.Post,
            $"https://api.github.com/app/installations/" +
            $"{installationId}/access_tokens"
        );

        request.Headers.Authorization =
            new AuthenticationHeaderValue(
                "Bearer",
                jwt
            );

        request.Headers.UserAgent.ParseAdd(
            "RepositoryAutomationApp"
        );

        request.Headers.Accept.ParseAdd(
            "application/vnd.github+json"
        );

        request.Content = JsonContent.Create(
            new
            {
                repository_ids = new[] { repositoryId },
                permissions = new
                {
                    contents = "read",
                    pull_requests = "write"
                }
            }
        );

        using var response = await _httpClient.SendAsync(
            request,
            cancellationToken
        );

        response.EnsureSuccessStatusCode();

        var result = await response.Content
            .ReadFromJsonAsync<InstallationTokenResponse>(
                cancellationToken
            );

        return result?.Token
            ?? throw new InvalidOperationException(
                "GitHub did not return an installation token."
            );
    }

    private sealed class InstallationTokenResponse
    {
        [JsonPropertyName("token")]
        public string? Token { get; set; }
    }
}

Register the HttpClient through dependency injection:

builder.Services.AddHttpClient<
    GitHubInstallationTokenService>();

The example demonstrates the authentication and token-restriction flow. Production implementations should also validate the installation ID and repository ID, handle API errors, cache valid installation tokens, and manage private-key access securely.

The private key must never be included in source control, distributed to clients, or written to application logs.

Understanding Installation Tokens and User Access Tokens

GitHub Apps support different token types for different authentication scenarios.

The most important distinction is whether the application is acting independently or performing an operation on behalf of a user.

When to use an installation access token

Use an installation access token when an application performs automated operations independently of a specific user.

Examples include:

• Automatically creating release pull requests.

• Updating repository configuration.

• Synchronizing repository metadata.

• Publishing automated release information.

• Responding to repository webhooks.

When to use a user access token

Use a user access token when an application needs to perform operations on behalf of an authenticated user.

For example, suppose a user signs in to a development portal and asks the application to create a pull request using their GitHub access.

A user access token is more appropriate because the operation should respect the user's permissions.

GitHub restricts a user access token based on both the app's permissions and the user's permissions.

An installation access token, on the other hand, is based on the app installation's permissions.

Choosing the wrong token type can result in an application performing operations with broader authority than the requesting user should have.

Securing GitHub App Credentials

A GitHub App's private key is one of its most sensitive assets.

The private key allows the application to generate JWTs and request installation access tokens for the accounts where the app is installed.

If an attacker obtains the private key, they may be able to authenticate as the application and request new installation tokens.

Follow these practices to protect it.

Store private keys in a secure vault

Avoid storing private keys directly in application source code or configuration files committed to Git.

For production applications, use a dedicated secret-management service such as Azure Key Vault or an equivalent platform.

The application should retrieve the key only when required and should restrict access to the service identity that needs it.

Rotate private keys

GitHub App private keys do not automatically expire.

You must manage their lifecycle and revoke keys that are no longer needed.

GitHub supports multiple private keys for an application, which allows rotation without requiring an immediate application outage.

A practical rotation process is:

1. Generate a replacement private key.

2. Store it securely.

3. Update the application to use the new key.

4. Verify that JWT generation and token creation work.

5. Revoke the old key.

6. Review logs and access activity.

Use short-lived installation access tokens

Installation access tokens expire after one hour.

This reduces the period during which a stolen token can remain usable.

Do not store installation tokens permanently or treat them like long-lived API credentials.

Cache them securely and request a replacement when they are close to expiration.

Never log authentication values

Avoid logging:

• Private keys.

• Application JWTs.

• Installation access tokens.

• User access tokens.

• Client secrets.

• Webhook secrets.

For troubleshooting, log safe metadata such as the installation identifier, repository identifier, operation name, response status, and correlation identifier.

Managing Permission Changes and Installation Approvals

Application permissions can change as automation requirements evolve.

For example, an application may initially read repository information but later need to create pull requests.

Adding new permissions can require installation owners to review and approve the changes.

Until the updated permissions are accepted, the installation continues to operate with the previously approved permissions.

This behavior matters when releasing new application functionality.

Do not assume that changing the permission configuration immediately grants new access to every existing installation.

Handle permission changes gracefully

A production application should be able to detect when it lacks the permissions required for an operation.

For example, an API request may return a 403 response when the application does not have sufficient permissions.

Instead of repeatedly retrying the request, the application should:

1. Identify the missing permission.

2. Record a safe diagnostic message.

3. Explain that the installation requires updated permissions.

4. Provide the appropriate installation or permission-review flow.

5. Continue supporting operations that still work with the existing permissions.

GitHub also provides installation-related webhook events that can help applications respond to installation changes and permission approval.

For example, the installation webhook can report when new permissions have been accepted.

This is useful when an application supports multiple organizations with different approval timelines.

Restricting GitHub App Installations Across an Organization

Organization owners can control who is allowed to install GitHub Apps.

By default, repository administrators may be able to install certain apps on repositories within an organization, depending on the permissions requested by the application and the organization's policies.

An organization can restrict installations so that only organization owners can install GitHub Apps.

This helps prevent individual repository administrators from introducing unapproved automation integrations.

A controlled approval process might look like this:

Developer requests GitHub App
          |
          v
Organization owner reviews app
          |
          v
Review requested permissions
          |
          v
Approve required repository access
          |
          v
Install on selected repositories
          |
          v
Monitor application activity

For larger organizations, maintain an approved-app inventory containing:

• Application name.

• Application owner.

• Business purpose.

• Requested permissions.

• Installed repositories.

• Responsible team.

• Review date.

• Credential rotation status.

This inventory makes it easier to identify unnecessary integrations and applications that no longer require access.

Common Mistakes to Avoid

Best Practices for Secure GitHub App Automation

A secure GitHub App should be designed around restricted access, controlled authentication, and continuous monitoring.

The following practices provide a useful foundation:

• Apply the principle of least privilege to repository, organization, and account permissions.

• Separate permission scope from repository installation scope.

• Install applications only on repositories they actually need.

• Use installation access tokens for independent automation.

• Use user access tokens for operations performed on behalf of users.

• Restrict installation tokens to the required repositories and permissions.

• Store private keys and client secrets in a secure secret-management service.

• Rotate private keys and revoke credentials that are no longer required.

• Use short-lived access tokens wherever supported.

• Subscribe only to the webhook events required by the application.

• Validate incoming webhook signatures.

• Review application permissions periodically.

• Monitor authentication, installation, and permission changes.

• Maintain an incident-response plan for compromised credentials.

Conclusion

GitHub Apps provide a flexible way to automate repository operations, but their security depends on how permissions, installations, and credentials are managed.

Granting broad access may make initial development easier, but it also increases the impact of a compromised application or token. A better approach is to identify the exact operations an application needs, request only the required permissions, and restrict installation access to selected repositories.

Installation access tokens provide another security boundary because they can be limited to specific repositories and permissions. Combined with secure private-key storage, short-lived tokens, webhook validation, and organization-level approval controls, they help create a safer automation environment.

The most important principle is simple: a GitHub App should have enough access to perform its intended task, but no more than that. This makes repository automation easier to govern and reduces unnecessary security exposure as organizations scale their development workflows.