githubapp

README

githubapp

A small Go package for handling authentication with a Github App using owner login and repository names instead of UUIDs. Installations and repositories are cached internally and refreshed (lazily) on a set interval, to reduce the number of List* API calls against the Apps API.

Usage

package main

import (
	"github.com/telia-oss/githubapp"

	"github.com/google/go-github/v45/github"
)

func main() {
    client, err := githubapp.NewClient(911, []byte("private-key"))
    if err != nil {
        panic(err)
    }

    app := githubapp.New(client)

    token, err := app.CreateInstallationToken(
        "telia-oss",
        []string{"githubapp"},
		&githubapp.Permissions{
            Metadata: github.String("read"),
        },
    )
    if err != nil {
        panic(err)
    }
}

Documentation

Overview

Package githubapp provides a convenient interface for handling Github App authentication.

Index

• func WithInstallationClientFactory(f func(token string) AppsTokenAPI) option
• func WithUpdateInterval(duration time.Duration) option
• type App
  • func New(client AppsJWTAPI, options ...option) *App
  • func (a *App) CreateInstallationToken(owner string, repositories []string, permissions *Permissions) (*Token, error)
  • func (a *App) RateLimits() (*github.RateLimits, *github.Response, error)
• type AppsJWTAPI
  • func NewClient(integrationID int64, privateKey []byte) (AppsJWTAPI, error)
• type AppsTokenAPI
• type ErrInstallationNotFound
  • func (e ErrInstallationNotFound) Error() string
• type InstallationClient
  • func NewInstallationClient(token string) *InstallationClient
• type Permissions
• type Token

Functions

func WithInstallationClientFactory

func WithInstallationClientFactory(f func(token string) AppsTokenAPI) option

WithInstallationClientFactory sets the function used to create new installation clients internally, and can be used to inject test fakes.

func WithUpdateInterval

func WithUpdateInterval(duration time.Duration) option

WithUpdateInterval can be used to override the default update interval for installations and repositories.

Types

type App

type App struct {
	// contains filtered or unexported fields
}

App wraps the AppsAPI client and caches the installations and repositories for the installation.

func New

func New(client AppsJWTAPI, options ...option) *App

New returns a new App.

func (*App) CreateInstallationToken

func (a *App) CreateInstallationToken(owner string, repositories []string, permissions *Permissions) (*Token, error)

CreateInstallationToken returns a new installation token for the given owner, scoped to the provided repositories and permissions.

func (*App) RateLimits

func (a *App) RateLimits() (*github.RateLimits, *github.Response, error)

RateLimits returns the rate limits for the githubClient.

type AppsJWTAPI

type AppsJWTAPI interface {
	ListInstallations(ctx context.Context, opt *github.ListOptions) ([]*github.Installation, *github.Response, error)
	CreateInstallationToken(ctx context.Context, id int64, opt *github.InstallationTokenOptions) (*github.InstallationToken, *github.Response, error)
	RateLimits(ctx context.Context) (*github.RateLimits, *github.Response, error)
}

AppsJWTAPI is the interface that is satisfied by the Apps client when authenticated with a JWT.

func NewClient

func NewClient(integrationID int64, privateKey []byte) (AppsJWTAPI, error)

NewClient returns a client for the Github V3 (REST) AppsAPI authenticated with a private key.

type AppsTokenAPI

type AppsTokenAPI interface {
	ListRepos(ctx context.Context, opts *github.ListOptions) (*github.ListRepositories, *github.Response, error)
}

AppsTokenAPI is the interface that is satisfied by the Apps client when authenticated with an installation token.

type ErrInstallationNotFound

type ErrInstallationNotFound string

ErrInstallationNotFound is returned if the requested App installation is not found.

func (ErrInstallationNotFound) Error

func (e ErrInstallationNotFound) Error() string

type InstallationClient

type InstallationClient struct {
	V3 *github.Client
	V4 *githubv4.Client
}

InstallationClient is authenticated with an installation token and includes a client for both the V3 and V4 Github APIs.

func NewInstallationClient

func NewInstallationClient(token string) *InstallationClient

NewInstallationClient returns a new client.

type Permissions

type Permissions github.InstallationPermissions

Permissions is re-exported to prevent issues with conflicting go-github versions.

type Token

type Token struct {
	*github.InstallationToken
}

Token is re-exported to prevent issues with conflicting go-github versions.