Documentation
¶
Overview ¶
Package github is Octomaton's code host: it authenticates as the Octomaton GitHub App, implements ci.CodeHost over GitHub's REST API (a report is a check run, carrying its trigger in a hidden marker) and decodes webhook deliveries into ci.Events. Only the owners it is configured with are served: their installations, repositories and events.
Index ¶
- Constants
- Variables
- func CheckPermissions(permissions map[string]string) error
- func DecodeMarker(text string) (t ci.Trigger, found bool, err error)
- func Marker(t ci.Trigger) (string, error)
- func Truncate(s string, limit int) string
- func WithMarker(s string, limit int, t ci.Trigger) string
- type App
- func (a *App) Accounts(ctx context.Context) ([]ci.Account, error)
- func (a *App) CheckPermissions(permissions map[string]string) error
- func (a *App) Decode(event, delivery string, body []byte) (ci.Event, string, error)
- func (a *App) Handles(event string) bool
- func (a *App) ID() int64
- func (a *App) Installation(id int64) ci.Installation
- func (a *App) InstallationToken(ctx context.Context, installationID int64, permissions map[string]string) (ci.Token, error)
- func (a *App) RepositoryToken(ctx context.Context, installationID, repositoryID int64, ...) (ci.Token, error)
- type Option
- type Retries
Constants ¶
const (
// DefaultBaseURL is the GitHub REST API endpoint.
DefaultBaseURL = "https://api.github.com/"
)
const MaxOutputLength = 65535
MaxOutputLength is GitHub's limit for a check run's output summary and text.
const MaxSummaryLength = 60000
MaxSummaryLength caps the summaries and comments Octomaton writes, below GitHub's limit.
Variables ¶
DefaultRetries rides out a GitHub blip of about half a minute: 6 attempts, 31 s of waits between them, at most 3.5 minutes with every attempt timing out. A longer outage fails the call, and the event's failure is reported, with retries of its own.
Functions ¶
func CheckPermissions ¶
CheckPermissions reports permissions GitHub cannot grant an installation token: unknown names and access levels other than read, write and admin.
func DecodeMarker ¶
DecodeMarker extracts the trigger from the last marker in text. found is false when text holds no marker.
func Marker ¶
Marker serializes a trigger into an HTML comment, invisible in rendered check-run output. Base64 keeps the payload free of "-->" and Markdown syntax.
Types ¶
type App ¶
type App struct {
// contains filtered or unexported fields
}
App is the Octomaton GitHub App. Installation tokens are cached, and refreshed shortly before they expire, by ghinstallation: one transport per installation. Every request, a token's included, is retried per its Retries.
func (*App) CheckPermissions ¶
CheckPermissions reports permissions GitHub cannot grant an installation token.
func (*App) Decode ¶
Decode turns a verified webhook delivery into a ci.Event. It returns no event, and the reason, when the delivery is not for Octomaton: an event or action it ignores, a repository that is a fork or a pull request from one, a repository owner it does not serve, another App's check run, an incomplete payload. It returns an error when the payload cannot be parsed.
func (*App) Installation ¶
func (a *App) Installation(id int64) ci.Installation
Installation returns the (cached) API of an installation.
func (*App) InstallationToken ¶
func (a *App) InstallationToken(ctx context.Context, installationID int64, permissions map[string]string) (ci.Token, error)
InstallationToken mints a short-lived installation token for every repository the installation can reach. With no permissions it grants contents:read only.
func (*App) RepositoryToken ¶
func (a *App) RepositoryToken(ctx context.Context, installationID, repositoryID int64, permissions map[string]string) (ci.Token, error)
RepositoryToken mints a short-lived installation token restricted to one repository. With no permissions it grants contents:read only.
type Option ¶
type Option func(*App)
Option customizes an App.
func WithBaseURL ¶
WithBaseURL points the App at another GitHub API endpoint (used by tests).
func WithLogger ¶
WithLogger logs requests' retries on l instead of slog's default logger.
func WithMetrics ¶
WithMetrics counts failed check-run calls on m.
func WithOwners ¶
WithOwners serves only the installations on, the repositories of, and the events from these users and organizations; without it, every owner is served.
func WithRetries ¶
WithRetries retries requests per r instead of DefaultRetries.
func WithTransport ¶
func WithTransport(rt http.RoundTripper) Option
WithTransport sets the HTTP transport of every GitHub request.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package githubtest provides an in-process fake of the GitHub REST endpoints Octomaton uses, for tests.
|
Package githubtest provides an in-process fake of the GitHub REST endpoints Octomaton uses, for tests. |