githubreconciler

package
v0.9.21 Latest Latest
Warning

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

 Go to latest Published: Jul 21, 2026 License: Apache-2.0 Imports: 35 Imported by: 0

Documentation

Overview

Package githubreconciler provides a workqueue-based reconciliation framework for GitHub pull requests.

The reconciler processes pull request keys from a workqueue, parses them into structured PR references, and invokes a user-supplied ReconcilerFunc for each one. It integrates with GitHub's API for cloning, committing, and status reporting via check runs.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func AppMain added in v0.2.0 

func AppMain[T any](ctx context.Context, f Functor[T], opts ...MainOption) error

AppMain is the entrypoint for reconcilers that authenticate using a dedicated GitHub App. It reads GITHUB_APP_ID and GITHUB_APP_KEY (a gcpkms:// URI) from the environment, creates the app token source, and delegates to Main. OCTO_IDENTITY is still required and used as the reconciler identity (e.g. for PR author names and bot display names).

func BranchSuffixToPath added in v0.2.0 

func BranchSuffixToPath(suffix string) string

BranchSuffixToPath reverses PathToBranchSuffix, converting a sanitized branch name suffix back to the original file path.

func CLIMain added in v0.2.0 

func CLIMain[T any](ctx context.Context, f Functor[T], cfg T, keys []string, opts ...MainOption) error

CLIMain runs a reconciler locally in a loop. Each key is reconciled in its own goroutine with a 1m delay between iterations. The function blocks until ctx is cancelled.

Use WithIdentity and WithTokenSourceFuncFactory to supply the reconciler identity and GitHub credentials respectively.

func Main added in v0.2.0 

func Main[T any](ctx context.Context, f Functor[T], opts ...MainOption) error

Main is the core entrypoint for GitHub reconcilers. It parses environment configuration, sets up metrics and tracing, creates the gRPC server, and runs the reconciler.

The token source and reconciler options are configured via MainOption functional options. Use RepoMain or OrgMain for the common Octo STS cases, or pass WithTokenSourceFuncFactory and related options directly for custom authentication (e.g. a dedicated GitHub App).

OCTO_IDENTITY is required and is read from the environment and passed to the token source factory.

func NewOrgTokenSource 

func NewOrgTokenSource(ctx context.Context, identity, org string) oauth2.TokenSource

NewOrgTokenSource creates a new token source for org-scoped GitHub credentials. Token-source construction and caching come from the SDK primitive; this wrapper adds the workqueue-aware NotFound→RequeueAfter behaviour that DAF reconcilers depend on.

func NewRepoTokenSource 

func NewRepoTokenSource(ctx context.Context, identity, org, repo string) oauth2.TokenSource

NewRepoTokenSource creates a new token source for repo-scoped GitHub credentials. Token-source construction and caching come from the SDK primitive; this wrapper adds the workqueue-aware NotFound→RequeueAfter behaviour that DAF reconcilers depend on.

func OrgMain added in v0.2.0 

func OrgMain[T any](ctx context.Context, f Functor[T], opts ...MainOption) error

OrgMain is the entrypoint for reconcilers that use org-scoped GitHub credentials via Octo STS. It is a convenience wrapper around Main.

func PathToBranchSuffix added in v0.2.0 

func PathToBranchSuffix(path string) string

PathToBranchSuffix sanitizes a file path for use as a git branch name suffix. Git rejects ref names where a path component starts with "." (a "funny refname"), so this function replaces leading dots with "_dot_" in each path component.

func RepoMain added in v0.2.0 

func RepoMain[T any](ctx context.Context, f Functor[T], opts ...MainOption) error

RepoMain is the entrypoint for reconcilers that use repo-scoped GitHub credentials via Octo STS. It is a convenience wrapper around Main.

Types

type App added in v0.2.0 

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

App holds the transport and installation ID cache for a GitHub App. Construct one with NewApp and use its methods.

func NewApp added in v0.2.0 

func NewApp(ctx context.Context, appID int64, keyURI string) (*App, error)

NewApp creates an App from a gcpkms:// key URI. The returned App caches installation ID lookups for the lifetime of the instance.

func (*App) Client added in v0.2.0 

func (a *App) Client() *github.Client

Client returns a GitHub client authenticated as the app using a JWT (not an installation token). Use this for app-level API calls such as listing installations and their repositories. Unlike the clients vended by ClientCache, this client is not scoped to a specific installation.

func (*App) ID added in v0.3.0 

func (a *App) ID() int64

ID returns the GitHub App ID.

func (*App) LookupInstallID added in v0.2.0 

func (a *App) LookupInstallID(ctx context.Context, org string) (int64, error)

LookupInstallID returns the GitHub App installation ID for org. Results are cached for the lifetime of the App. Concurrent lookups for the same org are coalesced into a single GitHub API call.

func (*App) TokenSourceFunc added in v0.2.0 

func (a *App) TokenSourceFunc() TokenSourceFunc

TokenSourceFunc returns a TokenSourceFunc that mints installation tokens scoped to the requested org/repo.

type ClientCache 

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

ClientCache manages GitHub clients for multiple org/repo combinations.

func NewClientCache 

func NewClientCache(tokenSourceFunc TokenSourceFunc) *ClientCache

NewClientCache creates a new client cache with the provided token source function.

func (*ClientCache) Clear 

func (cc *ClientCache) Clear()

Clear removes all cached clients and token sources.

func (*ClientCache) Get 

func (cc *ClientCache) Get(ctx context.Context, org, repo string) (*github.Client, error)

Get returns a GitHub client for the given org/repo, creating one if needed.

func (*ClientCache) LookupInstallID added in v0.9.3 

func (cc *ClientCache) LookupInstallID(ctx context.Context, org string) (int64, error)

LookupInstallID returns the GitHub App installation ID for org, reusing the underlying App's cached lookup (the same one used to mint installation tokens). It returns an error when the cache was not created from a GitHub App entrypoint (AppMain), since only then is an App available to resolve it.

func (*ClientCache) TokenSourceFor added in v0.2.0 

func (cc *ClientCache) TokenSourceFor(ctx context.Context, org, repo string) (oauth2.TokenSource, error)

TokenSourceFor returns an OAuth2 token source for the given org/repo combination. This allows callers that need raw token sources (e.g., for git clone operations) to reuse the same token source function that backs the client cache.

type Functor added in v0.2.0 

type Functor[T any] func(
	ctx context.Context,
	identity string,
	cc *ClientCache,
	cfg T,
) (ReconcilerFunc, error)

Functor constructs a ReconcilerFunc from the given context, identity, client cache, and user-provided configuration. The type parameter T is the user's config struct which is populated via envconfig.

type MainOption added in v0.2.0 

type MainOption func(*mainOptions)

MainOption configures the behavior of Main and its wrappers.

func WithIdentity added in v0.2.0 

func WithIdentity(identity string) MainOption

WithIdentity sets the reconciler identity, overriding the OCTO_IDENTITY environment variable. Exactly one of WithIdentity or OCTO_IDENTITY must be provided.

func WithInterceptors added in v0.2.0 

func WithInterceptors(inter ...grpc.UnaryServerInterceptor) MainOption

WithInterceptors adds gRPC unary server interceptors that run before the default metrics and recovery interceptors.

func WithMiddleware added in v0.2.0 

func WithMiddleware(m ...Middleware) MainOption

WithMiddleware appends middleware layers applied to the ReconcilerFunc before it is invoked. The first argument is outermost: WithMiddleware(A, B) produces A(B(rec)), matching gRPC interceptor ordering.

func WithTokenSourceFuncFactory added in v0.2.0 

func WithTokenSourceFuncFactory(f func(identity string) TokenSourceFunc) MainOption

WithTokenSourceFuncFactory sets the factory that maps an identity string to a TokenSourceFunc. The identity is read from the OCTO_IDENTITY environment variable at startup and forwarded to f, which returns the TokenSourceFunc used to authenticate GitHub API calls.

Use this to supply custom authentication; for the standard Octo STS cases prefer RepoMain or OrgMain.

type Middleware added in v0.2.0 

type Middleware func(ReconcilerFunc) ReconcilerFunc

Middleware wraps a ReconcilerFunc, allowing callers to inject logic before and/or after each reconcile invocation. Layers are composed so that the first argument to WithMiddleware is outermost: WithMiddleware(A, B) produces A(B(rec)), matching gRPC interceptor ordering.

type Option 

type Option func(*Reconciler)

Option configures a Reconciler.

func WithOrgScopedCredentials 

func WithOrgScopedCredentials() Option

WithOrgScopedCredentials configures the reconciler to use org-scoped credentials instead of repo-scoped credentials. When enabled, the same GitHub client will be used for all repositories within an organization.

func WithReconciler 

func WithReconciler(f ReconcilerFunc) Option

WithReconciler sets the reconciler function for all resource types.

type Reconciler 

type Reconciler struct {
	workqueue.UnimplementedWorkqueueServiceServer
	// contains filtered or unexported fields
}

Reconciler manages the reconciliation of GitHub resources.

func NewReconciler 

func NewReconciler(cc *ClientCache, opts ...Option) *Reconciler

NewReconciler creates a new Reconciler with the given options.

func (*Reconciler) Process 

func (r *Reconciler) Process(ctx context.Context, req *workqueue.ProcessRequest) (*workqueue.ProcessResponse, error)

Process implements the WorkqueueService.Process RPC.

func (*Reconciler) Reconcile 

func (r *Reconciler) Reconcile(ctx context.Context, url string) error

Reconcile processes the given resource URL.

type ReconcilerFunc 

type ReconcilerFunc func(ctx context.Context, res *Resource, gh *github.Client) error

ReconcilerFunc is the function signature for GitHub resource reconcilers. It receives the parsed resource information and appropriate GitHub client, and returns an error if reconciliation fails.

type Resource 

type Resource struct {
	// Owner is the GitHub organization or user.
	Owner string

	// Repo is the repository name.
	Repo string

	// Number is the issue or pull request number.
	// Only set for ResourceTypeIssue and ResourceTypePullRequest.
	Number int

	// Type indicates the resource type.
	Type ResourceType

	// URL is the original URL that was parsed.
	URL string

	// Ref is the branch, tag, or commit SHA.
	// Only set for ResourceTypePath.
	Ref string

	// Path is the file or directory path.
	// Only set for ResourceTypePath.
	Path string
}

Resource represents a parsed GitHub resource (issue, pull request, or path).

func ParseURL 

func ParseURL(uri string) (*Resource, error)

ParseURL parses a GitHub resource URL and extracts the components.

Expected formats:

func (*Resource) String 

func (r *Resource) String() string

String returns the string representation of the resource.

Example

ExampleResource_String demonstrates the string representation of a GitHub pull request resource. 

package main

import (
	"fmt"

	"chainguard.dev/driftlessaf/reconcilers/githubreconciler"
)

func main() {
	res := &githubreconciler.Resource{
		Owner:  "chainguard-dev",
		Repo:   "enterprise-packages",
		Number: 42,
		Type:   githubreconciler.ResourceTypePullRequest,
	}
	fmt.Println(res.String())
}

Output:
chainguard-dev/enterprise-packages#42
Example (Path)

ExampleResource_String_path demonstrates the string representation of a path resource. 

package main

import (
	"fmt"

	"chainguard.dev/driftlessaf/reconcilers/githubreconciler"
)

func main() {
	res := &githubreconciler.Resource{
		Owner: "chainguard-dev",
		Repo:  "enterprise-packages",
		Ref:   "main",
		Path:  "packages/glibc",
		Type:  githubreconciler.ResourceTypePath,
	}
	fmt.Println(res.String())
}

Output:
chainguard-dev/enterprise-packages@main:packages/glibc

type ResourceType 

type ResourceType string

ResourceType represents the type of GitHub resource. 

const (
	// ResourceTypeIssue represents a GitHub issue.
	ResourceTypeIssue ResourceType = "issue"

	// ResourceTypePullRequest represents a GitHub pull request.
	ResourceTypePullRequest ResourceType = "pull_request"

	// ResourceTypePath represents a file or directory path in a repository.
	ResourceTypePath ResourceType = "path"
)

type TokenSourceFunc 

type TokenSourceFunc func(ctx context.Context, org, repo string) (oauth2.TokenSource, error)

TokenSourceFunc is a function that creates an OAuth2 token source for a given org/repo.

Source Files

View all Source files

Directories

Path Synopsis
Package branchreconciler provides a workqueue reconciler for iterative branch-based workflows without pull requests.
 Package branchreconciler provides a workqueue reconciler for iterative branch-based workflows without pull requests.
Package changemanager provides an abstraction for managing GitHub Pull Request lifecycle operations, similar to how the statusmanager handles GitHub Check Runs.
 Package changemanager provides an abstraction for managing GitHub Pull Request lifecycle operations, similar to how the statusmanager handles GitHub Check Runs.
Package clonemanager provides pooled git clones tailored for reconciler style workloads.
 Package clonemanager provides pooled git clones tailored for reconciler style workloads.
worktreefs
Package worktreefs implements io/fs.FS backed by callbacks.WorktreeCallbacks.
 Package worktreefs implements io/fs.FS backed by callbacks.WorktreeCallbacks.
Package gitsign provides a git commit signer backed by Sigstore keyless signing.
 Package gitsign provides a git commit signer backed by Sigstore keyless signing.
Package graphqlclient provides a thin wrapper around the GitHub GraphQL API client with Prometheus metrics instrumentation.
 Package graphqlclient provides a thin wrapper around the GitHub GraphQL API client with Prometheus metrics instrumentation.
internal
template
Package template provides template execution and data embedding/extraction capabilities for GitHub reconcilers.
 Package template provides template execution and data embedding/extraction capabilities for GitHub reconcilers.
Package issuemanager provides a reconciler-style abstraction for managing GitHub Issues based on desired state.
 Package issuemanager provides a reconciler-style abstraction for managing GitHub Issues based on desired state.
Package metapathreconciler provides generic reconcilers for GitHub path handlers.
 Package metapathreconciler provides generic reconcilers for GitHub path handlers.
Package metareconciler provides a generic reconciler for metaagent-based GitHub issue handlers.
 Package metareconciler provides a generic reconciler for metaagent-based GitHub issue handlers.
Package statusmanager provides Kubernetes-style status management for GitHub reconcilers using GitHub Check Runs API.
 Package statusmanager provides Kubernetes-style status management for GitHub reconcilers using GitHub Check Runs API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.