https://github.com/bradleyfalzon/ghinstallation
HTTP Round Tripper for GitHub Apps - Authenticate as an Installation Workflow
https://github.com/bradleyfalzon/ghinstallation
github github-enterprise go
Last synced: 5 days ago
JSON representation
HTTP Round Tripper for GitHub Apps - Authenticate as an Installation Workflow
- Host: GitHub
- URL: https://github.com/bradleyfalzon/ghinstallation
- Owner: bradleyfalzon
- License: apache-2.0
- Created: 2016-10-26T11:24:09.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2026-05-25T22:51:13.000Z (20 days ago)
- Last Synced: 2026-06-02T10:04:28.936Z (12 days ago)
- Topics: github, github-enterprise, go
- Language: Go
- Homepage:
- Size: 160 KB
- Stars: 370
- Watchers: 6
- Forks: 111
- Open Issues: 25
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Authors: AUTHORS
Awesome Lists containing this project
README
# ghinstallation
[](https://pkg.go.dev/github.com/bradleyfalzon/ghinstallation/v2)
`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://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app
## Installation
Get the package:
```bash
go get -u github.com/bradleyfalzon/ghinstallation/v2
```
## GitHub Example
```go
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()`](https://pkg.go.dev/github.com/bradleyfalzon/ghinstallation/v2#New) to load a key directly from a `[]byte`.
## GitHub Enterprise Example
For clients using GitHub Enterprise, set the base URL as follows:
```go
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](https://pkg.go.dev/github.com/bradleyfalzon/ghinstallation/v2#Signer)
implementation when creating an
[AppsTransport](https://pkg.go.dev/github.com/bradleyfalzon/ghinstallation/v2#AppsTransport).
For example, this can be used to create tokens backed by keys in a KMS system.
```go
signer := &myCustomSigner{
key: "https://url/to/key/vault",
}
atr := NewAppsTransportWithOptions(http.DefaultTransport, 1, WithSigner(signer))
tr := NewFromAppsTransport(atr, 99)
```
## License
[Apache 2.0](LICENSE)
## Dependencies
- [github.com/golang-jwt/jwt-go](https://github.com/golang-jwt/jwt-go)