catalogue

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 is
	// active only when Webhook says where it goes; without it the App
	// subscribes to events nothing receives.
	Events []string `yaml:"events,omitempty"`
	// Webhook is where GitHub delivers the events: one URL, or a Kargo
	// receiver. Unset leaves the webhook inactive.
	Webhook *Webhook `yaml:"webhook,omitempty"`
	// Installation is all or selected; empty is selected.
	Installation string `yaml:"installation,omitempty"`
	// Export places an installed App's key at external/github/<id> for a
	// consumer to read (layout v4, ADR 0041). Unset keeps the key internal.
	// A runner App is always exported, and is not in the catalogue.
	Export bool `yaml:"export,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"`
}

type Catalogue struct {
	Apps []App `yaml:"apps"`
}

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

type Kargo struct {
	// Base is where Kargo's receivers are served, e.g.
	// `https://kargo-webhooks.example`; the path below it is derived.
	Base string `yaml:"base"`
	// Receiver is the receiver's name in the Kargo project.
	Receiver string `yaml:"receiver"`
	// Project is the Kargo project, empty for a cluster-scoped receiver.
	Project string `yaml:"project,omitempty"`
}

type Webhook struct {
	// URL is the endpoint every delivery is POSTed to, e.g. Argo CD's
	// `https://argocd.example/api/webhook`.
	URL string `yaml:"url,omitempty"`
	// Kargo is a Kargo receiver. Kargo derives a receiver's path from its
	// secret, so the URL moves whenever the secret does.
	Kargo *Kargo `yaml:"kargo,omitempty"`
}