ghook

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Jun 11, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

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

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

func NewAppAuth(appID string, key *rsa.PrivateKey, baseURL string, hc *http.Client) *AppAuth

func (*AppAuth) Token added in v0.3.0

func (a *AppAuth) Token(ctx context.Context, installationID int64) (string, error)

Token returns an installation access token for installationID, minting a fresh one when the cached token is gone or within 5 minutes of expiry.

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).

func LoadEnv

func LoadEnv(getenv func(string) string) (*EnvConfig, error)

LoadEnv builds the configuration from getenv (os.Getenv in production, a map lookup in tests) and validates required values.

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

func (g *GitHub) ForInstallation(id int64) *GitHub

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

func (g *GitHub) SetStatus(ctx context.Context, repo, sha, state, desc string) error

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

func (g *GitHub) UpdateComment(ctx context.Context, repo string, number int, body string) error

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.

func (*GitHub) UpsertComment added in v0.3.0

func (g *GitHub) UpsertComment(ctx context.Context, repo string, number int, body string) error

UpsertComment makes the marker comment on repo#number carry body: PATCH in place when it exists, POST otherwise.

type Service

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

func New

func New(cfg Config, pg *apiclient.Client, gh *GitHub, log *slog.Logger) *Service

func (*Service) Handler

func (s *Service) Handler() http.Handler

Handler returns the HTTP surface: POST /webhook and GET /healthz.

func (*Service) Wait added in v0.3.0

func (s *Service) Wait()

Wait blocks until all detached branch operations have finished. Call after the HTTP server has shut down so in-flight work completes before exit.

type TokenProvider added in v0.3.0

type TokenProvider func(ctx context.Context, installationID int64) (string, error)

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.

Jump to

Keyboard shortcuts

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