appsetup

Documentation

Overview

Package appsetup handles creating and installing per-role GitHub Apps using the manifest flow. It checks for existing app installations before creating new ones, and supports reusing apps whose private keys are already stored as secrets.

Index

• func ExpectedAppSlug(org, role string) string
• type AppCredentials
• type BrowserOpener
• type DefaultBrowser
  • func (DefaultBrowser) Open(_ context.Context, url string) error
• type Prompter
• type SecretExistsFunc
• type Setup
  • func NewSetup(client forge.Client, prompter Prompter, browser BrowserOpener, ...) *Setup
  • func (s *Setup) PermissionErrors() error
  • func (s *Setup) Run(ctx context.Context, org, role string) (*AppCredentials, error)
  • func (s *Setup) WithKnownSlugs(slugs map[string]string) *Setup
  • func (s *Setup) WithSecretExists(fn SecretExistsFunc) *Setup
  • func (s *Setup) WithStoreSecret(fn StoreSecretFunc) *Setup
• type StdinPrompter
  • func (StdinPrompter) Confirm(prompt string) (bool, error)
  • func (StdinPrompter) WaitForEnter(prompt string) error
• type StoreSecretFunc

Functions

func ExpectedAppSlug

func ExpectedAppSlug(org, role string) string

ExpectedAppSlug returns the conventional app slug for a given org and role. The convention is simply <org>-<role> for all roles. Used during uninstall to infer app names when config.yaml is unavailable.

Types

type AppCredentials

type AppCredentials struct {
	AppID         int
	Slug          string
	Name          string
	PEM           string
	ClientID      string
	ClientSecret  string
	WebhookSecret *string
	HTMLURL       string
}

AppCredentials holds the credentials returned from the manifest flow.

type BrowserOpener

type BrowserOpener interface {
	Open(ctx context.Context, url string) error
}

BrowserOpener opens URLs in the user's browser.

type DefaultBrowser

type DefaultBrowser struct{}

DefaultBrowser opens URLs using platform-specific commands.

func (DefaultBrowser) Open

func (DefaultBrowser) Open(_ context.Context, url string) error

type Prompter

type Prompter interface {
	WaitForEnter(prompt string) error
	Confirm(prompt string) (bool, error)
}

Prompter handles user interaction during app setup.

type SecretExistsFunc

type SecretExistsFunc func(role string) (bool, error)

SecretExistsFunc checks if a secret exists for a given role.

type Setup

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

Setup orchestrates the creation or reuse of GitHub Apps for agent roles.

func NewSetup

func NewSetup(client forge.Client, prompter Prompter, browser BrowserOpener, printer *ui.Printer) *Setup

NewSetup creates a new Setup instance.

func (*Setup) PermissionErrors

func (s *Setup) PermissionErrors() error

checkPermissions warns if the installed app is missing permissions that the current manifest expects. PermissionErrors returns a combined error if any apps have stale permissions, or nil if all permissions are up to date. Call after all roles have been processed so the user sees every mismatch at once.

func (*Setup) Run

func (s *Setup) Run(ctx context.Context, org, role string) (*AppCredentials, error)

Run creates or reuses a GitHub App for the given org and role.

The flow:

1. Check for an existing installation matching this org/role.
2. If found and the PEM secret exists, offer to reuse.
3. If found but PEM is lost, return an error.
4. If not installed but app exists (PEM stored, installation missing), resume by installing the existing app on the org.
5. If not found, run the manifest flow to create a new app.
6. After creation, store the PEM immediately, then install on the org.

func (*Setup) WithKnownSlugs

func (s *Setup) WithKnownSlugs(slugs map[string]string) *Setup

WithKnownSlugs sets a mapping of role → app slug for matching existing installations that don't follow the default naming convention.

func (*Setup) WithSecretExists

func (s *Setup) WithSecretExists(fn SecretExistsFunc) *Setup

WithSecretExists sets the function used to check whether a private key secret already exists for a given role.

func (*Setup) WithStoreSecret

func (s *Setup) WithStoreSecret(fn StoreSecretFunc) *Setup

WithStoreSecret sets the function used to store a PEM secret immediately after creating a new app, before proceeding to the next role.

type StdinPrompter

type StdinPrompter struct{}

StdinPrompter reads user input from stdin.

func (StdinPrompter) Confirm

func (StdinPrompter) Confirm(prompt string) (bool, error)

func (StdinPrompter) WaitForEnter

func (StdinPrompter) WaitForEnter(prompt string) error

type StoreSecretFunc

type StoreSecretFunc func(ctx context.Context, role, pem string) error

StoreSecretFunc stores a PEM secret for a given role immediately after app creation.