github

Documentation

Overview

Package github wraps the GitHub App authentication + REST API calls CronFoundry needs for repo sync and writeback. Higher-level orchestration (the sync loop, dispatcher) lives in internal/sync and internal/scheduler.

Index

• func AppJWT(appID string, privateKeyPEM []byte) (string, error)
• func CloneAtSHA(ctx context.Context, cloneURL, installToken, sha, destDir string) error
• func GetBranchHead(ctx context.Context, client *http.Client, ...) (string, error)
• func ReadPEM(value string) ([]byte, error)
• func VerifyWebhookSignature(secret, body []byte, sig string) error
• type InstallationCache
  • func NewInstallationCache(cfg InstallationCacheConfig) *InstallationCache
  • func (c *InstallationCache) Token(ctx context.Context, installID int64) (string, error)
• type InstallationCacheConfig
• type PushPayload

Functions

func AppJWT

func AppJWT(appID string, privateKeyPEM []byte) (string, error)

AppJWT mints a short-lived (9-minute) JWT signed with the GitHub App's private key. Use this token as the Authorization bearer when calling GitHub App-level endpoints — specifically to exchange for per-installation access tokens.

The returned JWT includes:

• iss = appID (numeric App identifier, passed as a string)
• iat = now - 60s (clock-skew tolerance)
• exp = iat + 9min (≈ now + 8min; GitHub caps at 10min so this leaves a 2min cushion)

Accepts PKCS#1 ("RSA PRIVATE KEY") or PKCS#8 ("PRIVATE KEY") PEM blocks.

func CloneAtSHA

func CloneAtSHA(ctx context.Context, cloneURL, installToken, sha, destDir string) error

CloneAtSHA performs a shallow (depth=1) single-branch clone and checks out the specific commit SHA. installToken is the GitHub installation access token, used as basic-auth password. For file:// URLs (tests), pass "".

destDir must be an empty (or nonexistent) directory. The function creates a fresh clone; it does not mutate an existing checkout.

func GetBranchHead

func GetBranchHead(
	ctx context.Context,
	client *http.Client,
	baseURL, installToken, owner, name, branch string,
) (string, error)

GetBranchHead returns the commit SHA at the tip of the named branch. installToken is the short-lived token minted via InstallationCache.

Path segments (owner/name/branch) are URL-escaped so branches containing `/` (e.g. `feat/my-work`) don't get mis-parsed as additional path segments by GitHub.

func ReadPEM

func ReadPEM(value string) ([]byte, error)

ReadPEM returns the PEM bytes for a GitHub App private key.

If value starts with "-----BEGIN" (after trimming leading whitespace) it is treated as the inline contents of a PEM block — this is the form produced by Azure Container Apps when a Key Vault secret is mapped directly into an environment variable.

Otherwise value is treated as a filesystem path and read with os.ReadFile — this is the local-dev / docker-compose form where the operator mounts a `.pem` file and points the env var at its path.

func VerifyWebhookSignature

func VerifyWebhookSignature(secret, body []byte, sig string) error

VerifyWebhookSignature checks the GitHub-supplied X-Hub-Signature-256 header against an HMAC-SHA256 of body using secret. sig must be "sha256=<hex>".

Types

type InstallationCache

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

InstallationCache holds per-installation access tokens and mints new ones via the GitHub App JWT when cached tokens expire.

Thread-safe; one cache per process.

func NewInstallationCache

func NewInstallationCache(cfg InstallationCacheConfig) *InstallationCache

NewInstallationCache constructs a cache with defaults applied for any zero-valued Config field.

func (*InstallationCache) Token

func (c *InstallationCache) Token(ctx context.Context, installID int64) (string, error)

Token returns an installation access token for installID, minting a fresh one via the GitHub App JWT exchange when the cache entry is missing or expired.

type InstallationCacheConfig

type InstallationCacheConfig struct {
	AppID      string
	PrivateKey []byte           // PEM bytes
	BaseURL    string           // default: "https://api.github.com"
	HTTPClient *http.Client     // default: http.DefaultClient
	Clock      func() time.Time // default: time.Now
	TokenTTL   time.Duration    // default: 50 * time.Minute
}

InstallationCacheConfig configures a cache. Only AppID and PrivateKey are required; the rest have sensible defaults for production use.

type PushPayload

type PushPayload struct {
	Ref        string `json:"ref"`
	After      string `json:"after"`
	Repository struct {
		Name  string `json:"name"`
		Owner struct {
			Login string `json:"login"`
		} `json:"owner"`
		DefaultBranch string `json:"default_branch"`
	} `json:"repository"`
	Installation struct {
		ID int64 `json:"id"`
	} `json:"installation"`
}

PushPayload is the subset of the GitHub push event we care about.