Skip to content

HTTP Round Tripper for GitHub Apps - Authenticate as an Installation Workflow

License

Notifications You must be signed in to change notification settings

bradleyfalzon/ghinstallation

Repository files navigation

ghinstallation

GoDoc

ghinstallation provides Transport, which implements http.RoundTripper to provide authentication as an installation for GitHub Apps.

This library is designed to provide automatic authentication for https://github.com/google/go-github or your own HTTP client.

See https://developer.github.com/apps/building-integrations/setting-up-and-registering-github-apps/about-authentication-options-for-github-apps/

Installation

Get the package:

GO111MODULE=on go get -u github.com/bradleyfalzon/ghinstallation/v2

GitHub Example

import "github.com/bradleyfalzon/ghinstallation/v2"

func main() {
    // Shared transport to reuse TCP connections.
    tr := http.DefaultTransport

    // Wrap the shared transport for use with the app ID 1 authenticating with installation ID 99.
    itr, err := ghinstallation.NewKeyFromFile(tr, 1, 99, "2016-10-19.private-key.pem")
    if err != nil {
        log.Fatal(err)
    }

    // Use installation transport with github.com/google/go-github
    client := github.NewClient(&http.Client{Transport: itr})
}

You can also use New() to load a key directly from a []byte.

GitHub Enterprise Example

For clients using GitHub Enterprise, set the base URL as follows:

import "github.com/bradleyfalzon/ghinstallation/v2"

const GitHubEnterpriseURL = "https://github.example.com/api/v3"

func main() {
    // Shared transport to reuse TCP connections.
    tr := http.DefaultTransport

    // Wrap the shared transport for use with the app ID 1 authenticating with installation ID 99.
    itr, err := ghinstallation.NewKeyFromFile(tr, 1, 99, "2016-10-19.private-key.pem")
    if err != nil {
        log.Fatal(err)
    }
    itr.BaseURL = GitHubEnterpriseURL

    // Use installation transport with github.com/google/go-github
    client := github.NewEnterpriseClient(GitHubEnterpriseURL, GitHubEnterpriseURL, &http.Client{Transport: itr})
}

What is app ID and installation ID

app ID is the GitHub App ID.
You can check as following :
Settings > Developer > settings > GitHub App > About item

installation ID is a part of WebHook request.
You can get the number to check the request.
Settings > Developer > settings > GitHub Apps > Advanced > Payload in Request tab

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

Customizing signing behavior

Users can customize signing behavior by passing in a Signer implementation when creating an AppsTransport. For example, this can be used to create tokens backed by keys in a KMS system.

signer := &myCustomSigner{
  key: "https://url/to/key/vault",
}
atr := NewAppsTransportWithOptions(http.DefaultTransport, 1, WithSigner(signer))
tr := NewFromAppsTransport(atr, 99)

License

Apache 2.0

Dependencies