Documentation
¶
Overview ¶
Package catalogueapp is what creating a catalogue App leaves behind: the App's record, and its key.
One Secret holds every catalogue App, each under its catalogue id. An installed App is three keys — `<id>.github_app_id`, `<id>.github_app_installation_id`, `<id>.github_app_private_key` — beside its record, `<id>.record.json`, so a deployment can copy one App anywhere (into a secret manager with an External Secrets PushSecret, for one) by naming keys, without reshaping a document, and a restore of the Secret alone brings every App back.
An App created and not yet installed keeps its key under another name, `<id>.pending_private_key`, so the three keys never exist without an installation: a copy made in between never hands anybody an App that cannot mint a token.
The service reads the key to ask GitHub what the App and its installation hold now, and to uninstall it on Disconnect. A token exchange reads it by id, with the installation beside it.
Index ¶
- Constants
- Variables
- func Encode(r Record, privateKey string) (map[string][]byte, error)
- func Key(id, property string) string
- func Keys(id string) []string
- func OfRecordKey(key string) (string, bool)
- func PrivateKeyOf(data map[string][]byte, id string) (string, bool)
- func RecordKey(id string) string
- func SecretName(release string) string
- func WebhookSecretOf(data map[string][]byte, id string) (string, bool)
- type Record
- type Store
Constants ¶
const ( AppIDProperty = "github_app_id" InstallationIDProperty = "github_app_installation_id" PrivateKeyProperty = "github_app_private_key" RecordProperty = "record.json" // PendingKeyProperty holds the key of an App not installed yet. PendingKeyProperty = "pending_private_key" // WebhookSecretProperty holds the secret GitHub signs the App's webhook // deliveries with, for an App whose catalogue entry declares a webhook. // It is kept whether or not the App is installed, and a rewrite of the // App's other keys leaves it alone. WebhookSecretProperty = "webhook_secret" )
The property names of one App.
const Version = 1
Version is the record version this build writes and reads.
Variables ¶
var ErrVersion = errors.New("catalogueapp: unsupported record version")
ErrVersion is a record of a version this build does not read.
Functions ¶
func Encode ¶
Encode writes one App: its record, and its three properties once it is installed, or its pending key until then. Keys lists every key an App can have, so a writer removes those first.
func OfRecordKey ¶
OfRecordKey reads the id back out of a record key.
func PrivateKeyOf ¶
PrivateKeyOf reads one App's key from the Secret's data, installed or pending.
func SecretName ¶
SecretName is the object holding every catalogue App.
Types ¶
type Record ¶
type Record struct {
Version int `json:"version"`
ID string `json:"id"`
Org string `json:"org"`
AppID int64 `json:"app_id"`
AppSlug string `json:"app_slug"`
// Purpose is always `catalogue`: Encode sets it. A record written before
// it existed has none and is read as a catalogue App's all the same.
Purpose appid.Purpose `json:"purpose,omitempty"`
// Labels are the App's own, for a reader that selects Apps by them.
Labels map[string]string `json:"labels,omitempty"`
// InstallationID is zero between Create and Install.
InstallationID int64 `json:"installation_id,omitempty"`
HTMLURL string `json:"html_url,omitempty"`
ConnectedAt time.Time `json:"connected_at"`
ConnectedBy string `json:"connected_by"`
// WebhookURL is where GitHub was last told to deliver this App's events.
// For a Kargo receiver it is derived from the secret, so it moves when
// the secret does. Not a secret itself: it is what a drift check reads
// GitHub's configuration against.
WebhookURL string `json:"webhook_url,omitempty"`
// HookRotatedAt is when the webhook's secret was last set on GitHub: the
// creation, or the latest rotation.
HookRotatedAt time.Time `json:"hook_rotated_at,omitzero"`
}
Record is one catalogue App, as the console shows it. Never the key.
type Store ¶ added in v1.76.0
type Store interface {
Put(ctx context.Context, record Record, privateKey string) error
List(ctx context.Context) ([]Record, error)
// Get is one App's record and its key, installed or pending.
Get(ctx context.Context, id string) (Record, string, bool, error)
Delete(ctx context.Context, id string) error
// PutWebhookSecret keeps the secret GitHub signs one App's webhook with,
// beside its key and surviving every later Put of the App. The App must
// have been Put. Where the App is exported the secret is in its document
// (`webhook_secret`), which is where a consumer reads it.
PutWebhookSecret(ctx context.Context, id, secret string) error
// WebhookSecret reads it back; false is an App with none.
WebhookSecret(ctx context.Context, id string) (string, bool, error)
}
Store is where catalogue Apps are kept: every App's record and key, by its catalogue id.
Source Files