ghinstallation

https://pkg.go.dev/github.com/bradleyfalzon/ghinstallation/v2
Admin
ghinstallation is a Go package that provides HTTP transport authentication for GitHub Apps using...
Tokens:1,880
Snippets:27
Trust Score:9.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install the package

Source: https://pkg.go.dev/github.com/bradleyfalzon/ghinstallation/v2

Use the go get command to add the package to your project.

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

--------------------------------

### Authenticate with GitHub

Source: https://pkg.go.dev/github.com/bradleyfalzon/ghinstallation/v2

Wraps the default transport to authenticate requests using a private key file for a specific installation.

```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})
}
```

--------------------------------

### Identify installation ID in WebHook

Source: https://pkg.go.dev/github.com/bradleyfalzon/ghinstallation/v2

The installation ID is found within the installation object of a WebHook request payload.

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

--------------------------------

### Initialize Transport

Source: https://pkg.go.dev/github.com/bradleyfalzon/ghinstallation/v2

Constructors for creating a new Transport instance.

```go
func New(tr http.RoundTripper, appID, installationID int64, privateKey []byte) (*Transport, error)
```

```go
func NewFromAppsTransport(atr *AppsTransport, installationID int64) *Transport
```

```go
func NewKeyFromFile(tr http.RoundTripper, appID, installationID int64, privateKeyFile string) (*Transport, error)
```

--------------------------------

### AppsTransport Options

Source: https://pkg.go.dev/github.com/bradleyfalzon/ghinstallation/v2

Configuration options for AppsTransport.

```go
type AppsTransportOption func(*AppsTransport)
```

```go
func WithSigner(signer Signer) AppsTransportOption
```

--------------------------------

### Create AppsTransport

Source: https://pkg.go.dev/github.com/bradleyfalzon/ghinstallation/v2

Constructors for creating an AppsTransport instance using different key sources or options.

```go
func NewAppsTransport(tr http.RoundTripper, appID int64, privateKey []byte) (*AppsTransport, error)
```

```go
func NewAppsTransportFromPrivateKey(tr http.RoundTripper, appID int64, key *rsa.PrivateKey) *AppsTransport
```

```go
func NewAppsTransportKeyFromFile(tr http.RoundTripper, appID int64, privateKeyFile string) (*AppsTransport, error)
```

```go
func NewAppsTransportWithOptions(tr http.RoundTripper, appID int64, opts ...AppsTransportOption) (*AppsTransport, error)
```

--------------------------------

### Client Interface

Source: https://pkg.go.dev/github.com/bradleyfalzon/ghinstallation/v2

Interface for an HTTP client that sends requests and returns responses.

```go
type Client interface {
	Do(*http.Request) (*http.Response, error)
}
```

--------------------------------

### Transport methods

Source: https://pkg.go.dev/github.com/bradleyfalzon/ghinstallation/v2

Methods for interacting with the Transport, including token management and metadata retrieval.

```go
func (t *Transport) AppID() int64
```

```go
func (t *Transport) Expiry() (expiresAt time.Time, refreshAt time.Time, err error)
```

```go
func (t *Transport) InstallationID() int64
```

```go
func (t *Transport) Permissions() (github.InstallationPermissions, error)
```

```go
func (t *Transport) Repositories() ([]github.Repository, error)
```

```go
func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)
```

```go
func (t *Transport) Token(ctx context.Context) (string, error)
```

--------------------------------

### Customize signing behavior

Source: https://pkg.go.dev/github.com/bradleyfalzon/ghinstallation/v2

Implements a custom signer to support external key management systems like KMS.

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

--------------------------------

### AppsTransport Methods

Source: https://pkg.go.dev/github.com/bradleyfalzon/ghinstallation/v2

Methods for interacting with an AppsTransport instance.

```go
func (t *AppsTransport) AppID() int64
```

```go
func (t *AppsTransport) RoundTrip(req *http.Request) (*http.Response, error)
```

--------------------------------

### Implement Error and Unwrap for HTTPError

Source: https://pkg.go.dev/github.com/bradleyfalzon/ghinstallation/v2

Standard error interface implementation and error wrapping support.

```go
func (e *HTTPError) Error() string
```

```go
func (e *HTTPError) Unwrap() error
```

--------------------------------

### Authenticate with GitHub Enterprise

Source: https://pkg.go.dev/github.com/bradleyfalzon/ghinstallation/v2

Configures the transport to point to a custom GitHub Enterprise API base URL.

```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})
}
```

--------------------------------

### Define RSASigner and Signer interface

Source: https://pkg.go.dev/github.com/bradleyfalzon/ghinstallation/v2

Structures and interfaces for signing JWT tokens using RSA keys.

```go
type RSASigner struct {
	// contains filtered or unexported fields
}
```

```go
func NewRSASigner(method *jwt.SigningMethodRSA, key *rsa.PrivateKey) *RSASigner
```

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

```go
type Signer interface {
	// Sign signs the given claims and returns a JWT token string, as specified
	// by [jwt.Token.SignedString]
	Sign(claims jwt.Claims) (string, error)
}
```

--------------------------------

### Define Transport struct

Source: https://pkg.go.dev/github.com/bradleyfalzon/ghinstallation/v2

Provides a http.RoundTripper for GitHub Apps authentication.

```go
type Transport struct {
	BaseURL string // BaseURL is the scheme and host for GitHub API, defaults to https://api.github.com
	Client  Client // Client to use to refresh tokens, defaults to http.Client with provided transport

	InstallationTokenOptions *github.InstallationTokenOptions // parameters restrict a token's access
	// contains filtered or unexported fields
}
```

--------------------------------

### AppsTransport Structure

Source: https://pkg.go.dev/github.com/bradleyfalzon/ghinstallation/v2

Provides a http.RoundTripper by wrapping an existing http.RoundTripper and provides GitHub Apps authentication.

```go
type AppsTransport struct {
	BaseURL string // BaseURL is the scheme and host for GitHub API, defaults to https://api.github.com
	Client  Client // Client to use to refresh tokens, defaults to http.Client with provided transport
	// contains filtered or unexported fields
}
```

--------------------------------

### Convert interface to ReadWriter

Source: https://pkg.go.dev/github.com/bradleyfalzon/ghinstallation/v2

Converts a body interface into an io.ReadWriter object.

```go
func GetReadWriter(i interface{}) (io.ReadWriter, error)
```

--------------------------------

### Define HTTPError struct

Source: https://pkg.go.dev/github.com/bradleyfalzon/ghinstallation/v2

Represents a custom error for failing HTTP operations, allowing inspection of the root cause and response.

```go
type HTTPError struct {
	Message        string
	RootCause      error
	InstallationID int64
	Response       *http.Response
}
```
Tokens:
Raw