Documentation
¶
Overview ¶
Package githubapp implements the GitHub App manifest flow for "github" connectors: each connector creates its own private GitHub App in one click, then mints short-lived installation tokens for cloning private repos and validating webhooks.
Index ¶
- Variables
- func PlanKey(stackID, prNum string) string
- func RepoFull(gitURL string) string
- type CIVerdict
- type Client
- func (c *Client) Begin(ctx context.Context, orgID, ghOrg string) (action, manifest string, err error)
- func (c *Client) Behind(ctx context.Context, cn *repo.Connector, repoFull, sha, ref string) (behind int, onBranch bool, err error)
- func (c *Client) CIState(ctx context.Context, cn *repo.Connector, repoFull, sha string) (CIVerdict, string, error)
- func (c *Client) CloneAuth(ctx context.Context, tile *repo.Tile) []string
- func (c *Client) Commit(ctx context.Context, cn *repo.Connector, repoFull, sha string) (gitlog.Commit, error)
- func (c *Client) Commits(ctx context.Context, cn *repo.Connector, repoFull, ref string, n int) ([]gitlog.Commit, error)
- func (c *Client) Complete(ctx context.Context, code, state string) (*repo.Connector, error)
- func (c *Client) ConnectorForTile(ctx context.Context, tile *repo.Tile) *repo.Connector
- func (c *Client) DefaultBranch(ctx context.Context, cn *repo.Connector, repoFull string) (string, error)
- func (c *Client) DeployFinished(ctx context.Context, tile *repo.Tile, d *repo.Deployment)
- func (c *Client) FileContents(ctx context.Context, cn *repo.Connector, repoFull, ref, path string) ([]byte, error)
- func (c *Client) HeadSHA(ctx context.Context, cn *repo.Connector, repoFull, ref string) (string, error)
- func (c *Client) ListBranches(ctx context.Context, cn *repo.Connector, repoFull string) ([]string, error)
- func (c *Client) ListRepos(ctx context.Context, cn *repo.Connector) ([]Repo, error)
- func (c *Client) RefreshPRComment(ctx context.Context, cn *repo.Connector, repoFull, prNum, stackID string, ...)
- func (c *Client) RegistryAuth(ctx context.Context, tile *repo.Tile) (user, pass string)
- func (c *Client) Token(ctx context.Context, cn *repo.Connector) (string, error)
- type Config
- type Repo
Constants ¶
This section is empty.
Variables ¶
var ErrNoChecksPerm = errors.New("connector lacks checks:read; approve the updated app permissions on GitHub")
ErrNoChecksPerm: the installation lacks checks:read. New connectors get it from the manifest; existing ones need the owner to approve the updated permissions on GitHub once.
Functions ¶
Types ¶
type CIVerdict ¶
type CIVerdict string
CIVerdict is the merged state of everything CI reported on a commit.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
func (*Client) Begin ¶
func (c *Client) Begin(ctx context.Context, orgID, ghOrg string) (action, manifest string, err error)
Begin creates a pending github connector in the org and returns the GitHub form action plus the manifest JSON to POST there. The connector id rides inside the state so the callback can find it. A non-empty ghOrg creates the app under that GitHub organization (requires org admin), private apps are only installable on their owning account, so org repos need an org-owned app.
func (*Client) Behind ¶
func (c *Client) Behind(ctx context.Context, cn *repo.Connector, repoFull, sha, ref string) (behind int, onBranch bool, err error)
Behind is how many commits on ref sha lacks, through the compare API. onBranch is false when the two have diverged: sha is not on ref at all.
func (*Client) CIState ¶
func (c *Client) CIState(ctx context.Context, cn *repo.Connector, repoFull, sha string) (CIVerdict, string, error)
CIState merges GitHub's two reporting channels for one commit: check runs (Actions and other check-suite apps) and legacy commit statuses. Passing means every check run completed success/neutral/skipped AND the combined status is green.
func (*Client) CloneAuth ¶
CloneAuth returns GIT_CONFIG_* environment lines that authenticate an HTTPS github.com fetch for the tile, env, not -c flags, so the token never shows in /proc/*/cmdline or .git/config. Resolution: the tile's connector, else the org's sole github connector. silent nil on any failure, the clone then runs unauthenticated and its own error surfaces in the deploy log.
func (*Client) Commit ¶
func (c *Client) Commit(ctx context.Context, cn *repo.Connector, repoFull, sha string) (gitlog.Commit, error)
Commit reads one commit by sha: what the log shows for a commit older than the ten it lists.
func (*Client) Commits ¶
func (c *Client) Commits(ctx context.Context, cn *repo.Connector, repoFull, ref string, n int) ([]gitlog.Commit, error)
Commits lists the last n commits on ref, newest first.
func (*Client) Complete ¶
Complete exchanges the callback code for app credentials and stores them on the pending connector identified by state ("<connectorID>.<nonce>"). It returns the connector so the caller can send the browser back to the org that owns it.
func (*Client) ConnectorForTile ¶
ConnectorForTile resolves the tile's git connector (explicit connector_id, else the org's sole connected github connector). Nil when none applies.
func (*Client) DefaultBranch ¶
func (c *Client) DefaultBranch(ctx context.Context, cn *repo.Connector, repoFull string) (string, error)
DefaultBranch fetches the repo's default branch.
func (*Client) DeployFinished ¶
DeployFinished posts PR feedback after a deployment reaches a terminal status: a commit status on the PR head plus a sticky preview comment. Best-effort, no-ops unless the tile is a github-tracked git tile inside a pr-N ephemeral environment with a usable connector.
func (*Client) FileContents ¶
func (c *Client) FileContents(ctx context.Context, cn *repo.Connector, repoFull, ref, path string) ([]byte, error)
tokAPI calls the GitHub API with an installation token, optionally JSON encoding a request body and decoding the response. FileContents fetches one file from a repo at a ref via the connector's installation token. Returns nil, nil when the file doesn't exist.
func (*Client) HeadSHA ¶
func (c *Client) HeadSHA(ctx context.Context, cn *repo.Connector, repoFull, ref string) (string, error)
HeadSHA resolves a ref (branch or tag) to the commit it points at, so a plan records exactly which commit it reviewed.
func (*Client) ListBranches ¶
func (c *Client) ListBranches(ctx context.Context, cn *repo.Connector, repoFull string) ([]string, error)
ListBranches names the branches of one repo, for the config-as-code branch field to autocomplete from. first 100 only, same as ListRepos, paginate when someone has more.
func (*Client) ListRepos ¶
ListRepos lists repositories the connector's app is installed on. first 100 only, paginate when someone actually has more.
func (*Client) RefreshPRComment ¶
func (c *Client) RefreshPRComment(ctx context.Context, cn *repo.Connector, repoFull, prNum, stackID string, env *repo.Environment)
RefreshPRComment re-renders and upserts the sticky PR comment outside the deploy path, used when a push updates the config plan preview. env is the PR's ephemeral environment when it exists (nil is fine: plan-only comment).
func (*Client) RegistryAuth ¶
RegistryAuth returns docker credentials for ghcr.io pulls through the tile's connector ("", "" when unavailable).
func (*Client) Token ¶
Token returns a cached installation access token for the connector, minting a new one when missing or near expiry. The lock only guards the cache map, minting happens unlocked so a slow GitHub call never blocks other connectors (worst case two goroutines mint concurrently; harmless). uses the app's first installation, fine for a personal app.
type Config ¶
type Config struct {
AppID int64 `json:"app_id"`
Slug string `json:"slug"`
PEM string `json:"pem"`
WebhookSecret string `json:"webhook_secret"`
State string `json:"state,omitempty"` // pending manifest-flow nonce
}
Config is the JSON stored in a github connector's config column.
func ParseConfig ¶
ParseConfig decodes a connector's config column.