Documentation
¶
Overview ¶
Package ghook is a small GitHub webhook receiver that maps pull-request lifecycle events to pgbranch branches (branch-per-PR): opened/reopened → ensure branch pr-<number> exists, synchronize → ensure (and optionally reset), closed → destroy. It talks to branchd through internal/apiclient and, when GitHub credentials are configured (App or PAT), reports back to the PR: a pgbranch/branch commit status around every branch operation and a live connect-info comment kept current in place.
Index ¶
- func ParseAppPrivateKey(pemBytes []byte) (*rsa.PrivateKey, error)
- type AppAuth
- type Config
- type EnvConfig
- type GitHub
- func (g *GitHub) ForInstallation(id int64) *GitHub
- func (g *GitHub) SetStatus(ctx context.Context, repo, sha, state, desc string) error
- func (g *GitHub) UpdateComment(ctx context.Context, repo string, number int, body string) error
- func (g *GitHub) UpsertComment(ctx context.Context, repo string, number int, body string) error
- type Service
- type TokenProvider
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ParseAppPrivateKey ¶ added in v0.3.0
func ParseAppPrivateKey(pemBytes []byte) (*rsa.PrivateKey, error)
ParseAppPrivateKey parses the App's RSA private key from PEM (GitHub downloads PKCS#1 "RSA PRIVATE KEY" files; PKCS#8 is accepted too for keys that went through openssl).
Types ¶
type AppAuth ¶ added in v0.3.0
type AppAuth struct {
// contains filtered or unexported fields
}
AppAuth mints and caches GitHub App installation tokens. Its Token method is a TokenProvider for the GitHub client.
func NewAppAuth ¶ added in v0.3.0
type Config ¶
type Config struct {
WebhookSecret string // HMAC key for X-Hub-Signature-256 (required)
Source string // pgbranch source to branch from (required)
TTLSeconds int // branch TTL passed on create (0 = no TTL)
ResetOnPush bool // synchronize resets the branch when true
Repos []string // "owner/name" allow-list; empty allows all
ProxyHost string // host[:port] of the pgbranch proxy, for comments
// BranchNaming picks the pgbranch branch name for a pull request:
// "pr-number" (default): pr-<number>
// "git-branch": the PR's head ref, sanitized (e.g. feat/login -> feat-login).
// git-branch lets preview platforms derive the name from the git ref
// they already know (Vercel's VERCEL_GIT_COMMIT_REF is present from the
// very first build, before the PR association exists).
BranchNaming string
}
Config is the static service configuration (see cmd/pgbranch-github for the GHOOK_* environment mapping).
type EnvConfig ¶
type EnvConfig struct {
Config
Listen string // GHOOK_LISTEN, default :8080
PGBranchServer string // GHOOK_PGBRANCH_SERVER (required)
PGBranchToken string // GHOOK_PGBRANCH_TOKEN
GitHubToken string // GHOOK_GITHUB_TOKEN (PAT mode; empty = no comments/statuses)
GitHubAPI string // GHOOK_GITHUB_API, default https://api.github.com
// GitHub App auth (mutually exclusive with GitHubToken): the service
// mints installation tokens from the App's private key.
AppID string // GHOOK_APP_ID
AppPrivateKey string // PEM, from GHOOK_APP_PRIVATE_KEY or GHOOK_APP_PRIVATE_KEY_FILE
}
EnvConfig is the full GHOOK_* environment configuration for the pgbranch-github binary: the service Config plus wiring (listen address, pgbranch server, GitHub credentials).
type GitHub ¶
type GitHub struct {
BaseURL string // e.g. https://api.github.com (overridable for tests)
Token TokenProvider
HTTP *http.Client
// contains filtered or unexported fields
}
GitHub is a minimal REST client for what this service does on GitHub: the live connect-info comment and the pgbranch/branch commit status. No SDK dependency.
func (*GitHub) ForInstallation ¶ added in v0.3.0
ForInstallation returns a shallow copy of the client bound to the given installation id (from the webhook payload). Safe for the PAT provider, which ignores it.
func (*GitHub) SetStatus ¶ added in v0.3.0
SetStatus sets the pgbranch/branch commit status on a commit: pending while a branch operation runs, then success or failure. CI consumers gate on the context instead of polling the branch with psql retry loops. Descriptions are truncated to GitHub's 140-character limit.
func (*GitHub) UpdateComment ¶ added in v0.3.0
UpdateComment rewrites the marker comment when present and does nothing when it isn't — closing a PR that never got a comment shouldn't create one just to say the branch is gone.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
type TokenProvider ¶ added in v0.3.0
TokenProvider supplies the bearer token for a GitHub API call. PAT mode is a constant provider (StaticToken); App mode mints per-installation tokens (AppAuth.Token) keyed by the webhook delivery's installation id.
func StaticToken ¶ added in v0.3.0
func StaticToken(token string) TokenProvider
StaticToken is the PAT-mode TokenProvider: always the same token, whatever the installation.