ghinstallation

To use this library, you need two specific identifiers from GitHub:

1. App ID: The unique identifier for your GitHub App. Found in your GitHub App settings under: Settings > Developer > settings > GitHub App > About item.
2. Installation ID: The ID of the specific installation of your app. This is typically found in the payload of a Webhook request sent by GitHub:

WebHook request
...
  "installation": {
    "id": `installation ID`
  }

Install the ghinstallation package using go get to enable automatic authentication for GitHub Apps in your Go applications.

go get -u github.com/bradleyfalzon/ghinstallation/v2

If you need to use keys stored in an external system like a KMS, you can implement the Signer interface and pass it to NewAppsTransportWithOptions. This allows you to control how the JWTs used for authentication are signed. You can then create a transport from this AppsTransport using NewFromAppsTransport.

// Example of using a custom signer (e.g., for KMS integration)
signer := &myCustomSigner{
  key: "https://url/to/key/vault",
}

// Create the AppsTransport with the custom signer
atr := NewAppsTransportWithOptions(http.DefaultTransport, 1, WithSigner(signer))

// Create the final transport for a specific installation
tr := NewFromAppsTransport(atr, 99)

The Transport struct includes an InstallationTokenOptions field (of type *github.InstallationTokenOptions). You can use this to restrict the scope of the generated access token by specifying required permissions or repository access.

// Note: This requires importing github.com/google/go-github/v88/github
options := &github.InstallationTokenOptions{
    // Add specific options here as defined by the GitHub API
}

// To use these options, you must manually construct the Transport
// or use a pattern that allows setting this field before the first token fetch.
transport.InstallationTokenOptions = options

Because Transport implements http.RoundTripper, you can use it directly in an http.Client. This allows you to make standard HTTP requests that are automatically signed with the correct GitHub App installation token.

When RoundTrip is called, the Transport checks if the current token is expired (or near expiration) and refreshes it if necessary before proceeding with the request.

// Create the transport
transport, err := ghinstallation.NewKeyFromFile(http.DefaultTransport, appID, installationID, "key.pem")
if err != nil {
    log.Fatal(err)
}

// Use it in a standard http.Client
client := &http.Client{
    Transport: transport,
}

// This request will automatically include the 'Authorization: token <token>' header
resp, err := client.Get("https://api.github.com/repos/owner/repo")

Signs the provided JWT claims using the RSA key and method configured in the RSASigner instance.

Parameters:

• claims: An object implementing the jwt.Claims interface.

Returns:

• A signed JWT token as a string.
• An error if the signing process fails.

func (s *RSASigner) Sign(claims jwt.Claims) (string, error)

Once a Transport has successfully performed its first request (or you manually trigger a token refresh), you can inspect the permissions and repositories associated with the current installation token using the Permissions() and Repositories() methods.

permissions, err := transport.Permissions()
if err != nil {
    // handle error
}

repos, err := transport.Repositories()
if err != nil {
    // handle error
}

The Signer interface provides a way to sign JWT claims using predetermined key material. It is a wrapper around jwt.SigningMethod that simplifies the signing process by abstracting away the specific key and method details. To use it, implement the Sign(claims jwt.Claims) (string, error) method.

type Signer interface {
	Sign(claims jwt.Claims) (string, error)
}

If a token refresh fails (e.g., due to network issues or invalid credentials), the Transport returns an *HTTPError. This error type allows you to inspect the root cause and the original HTTP response from GitHub.

// Example of checking for HTTPError
if err != nil {
    var httpErr *ghinstallation.HTTPError
    if errors.As(err, &httpErr) {
        fmt.Printf("Error: %s\n", httpErr.Message)
        fmt.Printf("Status: %s\n", httpErr.Response.Status)
        fmt.Printf("Root Cause: %v\n", httpErr.RootCause)
    }
}