githubapp

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 16, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
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

func PlanKey

func PlanKey(stackID, prNum string) string

PlanKey is the settings key holding the rendered plan-preview markdown for one PR (written by the webhook handler, cleared on PR close).

func RepoFull

func RepoFull(gitURL string) string

RepoFull extracts "owner/repo" from an https or ssh GitHub URL ("" if it isn't one).

Types

type CIVerdict

type CIVerdict string

CIVerdict is the merged state of everything CI reported on a commit.

const (
	CIPassing CIVerdict = "success"
	CIFailing CIVerdict = "failure"
	CIPending CIVerdict = "pending"
	// CINone: no check runs and no commit statuses at all, the repo may
	// simply have no CI. Callers decide how long to wait before shrugging.
	CINone CIVerdict = "none"
)

type Client

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

func New

func New(store repo.Store, baseURL string) *Client

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

func (c *Client) CloneAuth(ctx context.Context, tile *repo.Tile) []string

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

func (c *Client) Complete(ctx context.Context, code, state string) (*repo.Connector, error)

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

func (c *Client) ConnectorForTile(ctx context.Context, tile *repo.Tile) *repo.Connector

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

func (c *Client) DeployFinished(ctx context.Context, tile *repo.Tile, d *repo.Deployment)

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

func (c *Client) ListRepos(ctx context.Context, cn *repo.Connector) ([]Repo, error)

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

func (c *Client) RegistryAuth(ctx context.Context, tile *repo.Tile) (user, pass string)

RegistryAuth returns docker credentials for ghcr.io pulls through the tile's connector ("", "" when unavailable).

func (*Client) Token

func (c *Client) Token(ctx context.Context, cn *repo.Connector) (string, error)

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

func ParseConfig(raw string) Config

ParseConfig decodes a connector's config column.

func (Config) Connected

func (c Config) Connected() bool

Connected reports whether the manifest flow finished for this config.

type Repo

type Repo struct {
	FullName      string `json:"full_name"`
	Private       bool   `json:"private"`
	DefaultBranch string `json:"default_branch"`
}

Repo is a repository visible to a connector's installation.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL