HTTP Round Tripper to authenticate to GitHub as GitHub app and utilities for WebHook Verification. Supports authenticating with Installation Token and JWT.
// SPDX-FileCopyrightText: Copyright 2024 Prasad Tengse
// SPDX-License-Identifier: MIT
package main
import (
"log"
"net/http"
"github.com/tprasadtp/go-githubapp"
)
func main() {
transport, err := githubapp.NewTransport(ctx, appID, signer,
githubapp.WithOwner("username"),
githubapp.WithRepositories("repository"),
githubapp.WithPermissions("contents:read"),
)
// Build an HTTP client with custom round tripper.
client := &http.Client{
Transport: transport,
}
// Try to fetch README for the repository.
response, err := client.Get("/repos/<username>/<repository>/readme")
// Handle error
if err != nil {
log.Fatal(err)
}
// Process Response from API....
}
- This library is designed to provide automatic authentication for google/go-github, github.com/shurcooL/githubv4 or your own HTTP client.
- Transport implements http.RoundTripper which can authenticate transparently.
It will override
Authorization
header. None of the other headers are modified. It is user's responsibility to set appropriate headers (like user agent etc.) as required.
See API docs for more info and examples.
App ID can be found at
Settings -> Developer -> settings -> GitHub App -> About item.
Be sure to select the correct organization if you are a member of multiple organizations.
This library delegates JWT signing to type implementing crypto.Signer interface. Thus, it may be backed by KMS/TPM or other secure key store. Optionally github.com/tprasadtp/cryptokms can be used.
Typically extracted from webhook request headers. If using VerifyWebHookRequest,
returned WebHook includes InstallationID
. This is not required if an owner is already
specified.
WithPermissions can be used to limit permissions on the created tokens.
WithPermissions accepts permissions in <scope>:<level>
format.
Please check with GitHub API documentation on supported scopes. Requested
permissions cannot permissions existing on the installation.
WithRepositories can be used to limit the scope of created access tokens to the list of
repositories specified. Repositories MUST belong to a single installation i.e., MUST have
a single owner. This accepts repositories in {owner}/{repo}
format or just name of the
repository. If only name is specified, then it MUST be used with WithOwner or
WithInstallationID.
WithEndpoint can be used to use custom GitHub REST endpoint. This endpoint will ONLY be used for token renewals and verifying app installation and not http client using the Transport.
When none of the installation options WithOwner, WithInstallationID or WithRepositories are specified, Transport authenticates as an app. Some API endpoints like listing installations are only accessible to app.
VerifyWebHookRequest provides a way to verify webhook payload and extract event data from headers. See API docs for more info.