githubapp

func NewInstallationToken ¶

func NewInstallationToken(ctx context.Context, appid uint64, signer crypto.Signer, opts ...Option) (InstallationToken, error)

NewInstallationToken returns new installation access token. This takes same options as Transport.

func NewJWT ¶

func NewJWT(ctx context.Context, appid uint64, signer crypto.Signer) (JWT, error)

NewJWT returns new JWT bearer token signed by the signer.

Returned JWT is valid for at least 5min. Ensure that your machine's clock is accurate.

• Unlike NewTransport, this does not validate app id and signer. This simply mints the JWT as required by GitHub app authentication.
• RSA keys of length less than 2048 bits are not supported.
• Only RSA keys are supported. Using ECDSA, ED25519 or other keys will return error.

func Options ¶

func Options(options ...Option) Option

Options takes a variadic slice of Options and returns a single Options which includes all the given options. This is useful for sharing presets. If conflicting options are specified, last-specified wins. As a special case, if no options are specified or all specified options are nil, this will returns nil.

func WithEndpoint ¶

func WithEndpoint(endpoint string) Option

WithEndpoint configures Transport to use custom REST API(v3) endpoint. for authenticating as app, obtaining installation metadata and creating installation access tokens. This MUST be REST(v3) endpoint even though a client might be using GitHub GraphQL API.

When not specified or empty, "https://api.github.com/" is used.

func WithInstallationID ¶

func WithInstallationID(id uint64) Option

WithInstallationID configures Transport to use installation id specified.

This is useful if it is required to access all repositories available for an installation without specifying them individually or if building Transport from data provided by WebHook.

func WithOwner ¶

func WithOwner(username string) Option

WithOwner configures the installation owner to use.

func WithPermissions ¶

func WithPermissions(permissions ...string) Option

WithPermissions configures permission scopes. This is useful when app has a broader set of permissions, a scoped access token is required.

Permissions MUST be specified in "<scope>:<access>" or "<scope>=<access>" format. Where scope is permission scope like "issues" and access can be one of "read", "write" or "admin".

For example, to request permissions to write issues and pull request can be specified as,

githubapp.WithPermissions("issues:write", "pull_requests:write")

func WithRepositories ¶

func WithRepositories(repos ...string) Option

WithRepositories configures Transport to use installation for repos specified. Unlike other installation options, this can be used multiple times.

func WithRoundTripper ¶

func WithRoundTripper(next http.RoundTripper) Option

WithRoundTripper configures Transport to use next as next http.RoundTripper.

This can be used to further customize headers, add logging or retries. This only applies to authentication API calls and not the http client using the Transport.

func WithUserAgent ¶

func WithUserAgent(ua string) Option

WithUserAgent configures user agent header to use for token related API requests.

Typically, Transport which implements http.RoundTripper will re-use the User-Agent header specified by the http.Request. However, when building the Transport several HTTP requests need to be made to verify and configure it. User agent specified here will be used during bootstrapping. This is also as fallback for token renewal requests.

func NewTransport ¶

func NewTransport(ctx context.Context, appid uint64, signer crypto.Signer, opts ...Option) (*Transport, error)

NewTransport creates a new Transport for authenticating as an app/installation.

How Transport authenticates depends on installation options specified.

• If no installation options are specified, then Transport can only authenticate as app (using JWT). This is not something you want typically, as a very limited number of actions like accessing available installations.
• Use WithInstallationID to have access to all permissions available to the installation including organization scopes and repositories. This can be used together with WithPermissions to limit the scope of access tokens. A typical example would be to close all stale issues for all repositories in an organization. This task does not require access to code, thus "issues:write" permission should be sufficient.
• Use WithOwner if your app has only access to organization/user permissions and none of the repositories belonging to the owner. A typical example would be an app, which manages self-hosted runners in an organization or manages organization level projects.
• Use WithRepositories if your app intends to access only a set of repositories. Do note that if app has access to organization permissions, they will also be available to the access token, unless limited with WithPermissions.
• WithPermissions can be used to limit the scope of permissions available to the access token.

Access token and JWT are automatically refreshed whenever required.

If only installation access token or JWT is required but not the round tripper, use NewInstallationToken or NewJWT respectively.

func VerifyWebHookRequest ¶

func VerifyWebHookRequest(secret string, req *http.Request) (WebHook, error)

VerifyWebHookRequest is a simple function to verify webhook HMAC-SHA256 signature.

This functions assumes that headers are canonical by default and have not been modified. Only HMAC-SHA256 signatures are considered for verification and SHA1 signature headers are ignored.

Typically, HMAC secret would be []byte, but as it may be updated via web interface, which can only accept strings. Returned value is only valid if error is nil.

• ErrWebHookRequest is returned when request is invalid and is missing or malformed headers like 'X-GitHub-Event', 'X-Hub-Signature-256' and more.
• ErrWebHookMethod is returned when webhook request is not a PUT request.
• ErrWebHookContentType is returned when content type header is not set to 'application/json'. Though GitHub supports 'application/x-www-form-urlencoded', it is NOT supported by this library.
• ErrWebhookSignature is returned when signature does not match.

An example HTTP handler which returns appropriate http status code is shown below.

mux.HandleFunc("/webhook", func(w http.ResponseWriter, r *http.Request) {
    webhook, err := githubapp.VerifyWebHookRequest(secret, r)
    if err != nil {
        switch {
        case errors.Is(err, githubapp.ErrWebhookSignature):
            w.WriteHeader(http.StatusUnauthorized)
        case errors.Is(err, githubapp.ErrWebHookRequest):
            w.WriteHeader(http.StatusBadRequest)
        case errors.Is(err, githubapp.ErrWebHookContentType):
            w.WriteHeader(http.StatusUnsupportedMediaType)
        case errors.Is(err, githubapp.ErrWebHookMethod):
            w.WriteHeader(http.StatusMethodNotAllowed)
        default:
            // This is non-reachable code.
            w.WriteHeader(http.StatusNotImplemented)
        }
        _, _ = w.Write([]byte(err.Error()))
        return
    }

    // Do something with webhook, for example, put it in SQS or PubSub.
    err = doSomething(r.Context(), webhook)
    if err != nil {
        w.WriteHeader(http.StatusInternalServerError)
        return
    }

	// Return HTTP status 2xx.
    w.WriteHeader(http.StatusAccepted)
})