Documentation
¶
Overview ¶
Package catalogue is GitHub Apps declared as data: what each App is called, which organisation owns it, what it may do, and — for a later exchange that mints installation tokens — which groups may ask for how much of it.
The deployment declares a catalogue; an operator creates and installs each App from the console in two clicks, and the service keeps its key. The roster's own Apps (an organisation's controller App, the link App, a runner App) are expressed in the same shape, so one manifest builder serves them all.
A catalogue is read once, at start, and a malformed one stops the service: an App declared wrongly and created anyway is an App with the wrong permissions that nobody can change from here — GitHub has no API for that.
Index ¶
Constants ¶
const ( // InstallationAll is every repository in the organisation, now and // later. InstallationAll = "all" // InstallationSelected is the repositories the installer picks. InstallationSelected = "selected" )
The two installation scopes an App can be declared with. Informational: GitHub's install page is where the installer chooses, and this says which choice the deployment expects.
const ( LevelRead = "read" LevelWrite = "write" LevelAdmin = "admin" )
The permission levels GitHub grants, in order: each includes the ones before it.
const NameLimit = 34
NameLimit is GitHub's length limit on an App's name.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type App ¶
type App struct {
// ID names the App here: it is the storage key and never changes for
// the life of the App.
ID string `yaml:"id"`
// Org is the organisation the App is created under.
Org string `yaml:"org"`
// Name is the App's name on GitHub. Empty is "<org>-<id>", cut to
// GitHub's limit.
Name string `yaml:"name,omitempty"`
Description string `yaml:"description,omitempty"`
// Public lets any account install the App. A private App installs only
// on the organisation that owns it.
Public bool `yaml:"public,omitempty"`
// Permissions are GitHub permission names to read, write or admin.
Permissions map[string]string `yaml:"permissions"`
// Events are the webhook events the App subscribes to. The webhook
// itself stays inactive: nothing here receives one.
Events []string `yaml:"events,omitempty"`
// Installation is all or selected; empty is selected.
Installation string `yaml:"installation,omitempty"`
// Grants say which groups may ask for tokens of this App, for which
// repositories and with at most which permissions.
Grants []Grant `yaml:"grants,omitempty"`
}
App is one declared App.
func (*App) DisplayName ¶
DisplayName is the App's name on GitHub: the declared one, or "<org>-<id>" cut to GitHub's limit.
func (*App) InstallationScope ¶
InstallationScope is the declared scope, defaulted.
type Catalogue ¶
type Catalogue struct {
Apps []App `yaml:"apps"`
}
Catalogue is every declared App, in declaration order.
func Parse ¶
Parse reads a catalogue strictly — an unknown key is an error, because a misspelt permission block would otherwise create an App with none — and validates it.
func (*Catalogue) GrantGroups ¶
GrantGroups are every group named by some App's grant, deduplicated, in no particular order. It is [UndeclaredGroups]'s mirror image: that one reads the policy to find a grant naming a group the policy never declared; this one hands the policy the groups its own grants name, so the root policy package's Unconsumed lint (its catalogueGroups parameter — see policy.Policy.Unconsumed's doc comment) can stop reporting a group that exists ONLY to let some identity mint an App's installation token — the catalogue is the one place that actually consumes it, and the policy package cannot read this file for itself.
func (*Catalogue) UndeclaredGroups ¶
UndeclaredGroups are the grants' groups for which declared says false: the policy's groups, checked at start by the caller that has the policy.
type Grant ¶
type Grant struct {
// Group is a group the policy declares.
Group string `yaml:"group"`
// Repositories are names or path.Match globs within the App's
// organisation; "*" is every one.
Repositories []string `yaml:"repositories"`
// Permissions are the most a token may carry, each within the App's
// own.
Permissions map[string]string `yaml:"permissions"`
}
Grant is what one group may ask of an App.
Source Files