forge

package
v0.44.0 Latest Latest
Warning

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

Go to latest
Published: Oct 1, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package forge defines the interface for interacting with git forges (GitHub, GitLab, Forgejo). All forge-specific operations flow through the Client interface, keeping the rest of the codebase forge-agnostic.

Index

Constants

View Source
const (
	// Managed variables — GitHub.
	VarMintURL        = "FULLSEND_MINT_URL"
	VarGCPRegion      = "FULLSEND_GCP_REGION"
	VarReviewClientID = "FULLSEND_REVIEW_CLIENT_ID"
	VarAppSet         = "FULLSEND_APP_SET"

	// Retired GitLab poller state variables. Superseded by HMAC-signed
	// state.json on fullsend-poll-state-slash / fullsend-poll-state-events.
	// Install no longer seeds them; converge migrate-then-deletes them.
	VarLastPollAtFast     = "FULLSEND_LAST_POLL_AT_FAST"
	VarLastPollAtFull     = "FULLSEND_LAST_POLL_AT_FULL"
	VarLabelState         = "FULLSEND_LABEL_STATE"
	VarDispatchedKeysFast = "FULLSEND_DISPATCHED_KEYS_FAST"
	VarDispatchedKeysFull = "FULLSEND_DISPATCHED_KEYS_FULL"
	VarFailedKeysFast     = "FULLSEND_FAILED_KEYS_FAST"
	VarFailedKeysFull     = "FULLSEND_FAILED_KEYS_FULL"

	// Secrets — both forges.
	SecretGCPProjectID   = "FULLSEND_GCP_PROJECT_ID"
	SecretGCPWIFProvider = "FULLSEND_GCP_WIF_PROVIDER"

	// Secrets — GitLab only.
	SecretForgeToken = "FULLSEND_FORGE_TOKEN"

	// Optional GitLab role credentials (docs/contributing/gitlab-role-credentials.md).
	// These are absent on an installation that has not yet completed role
	// provisioning; FULLSEND_FORGE_TOKEN may still be present as leftover
	// state from an installation predating the role-only model, but current
	// runtime jobs require their selected role credential and fail closed
	// when it is missing: gitlabroles.Resolve returns ErrUnconfigured, and
	// select-gitlab-role-token.sh errors out rather than falling back to
	// FULLSEND_FORGE_TOKEN. requiredSecretsForForge (internal/repos)
	// deliberately omits these secrets, so probe/converge do not treat
	// their absence as health drift; GitLab role readiness is tracked
	// separately through the role registry/status path
	// (gitlabroles.CheckBuiltinReadiness, `repos status`). Built-in names
	// are fixed; custom roles derive FULLSEND_GITLAB_ROLE_<NAME>_TOKEN.
	// Provisioning is #7498; job routing is #7499
	// (`internal/gitlabroles.Select`).
	SecretGitLabPollerToken  = "FULLSEND_GITLAB_POLLER_TOKEN"
	SecretGitLabAnalystToken = "FULLSEND_GITLAB_ANALYST_TOKEN"
	SecretGitLabCoderToken   = "FULLSEND_GITLAB_CODER_TOKEN"

	// SecretDispatch is the shared HMAC secret used to sign dispatch
	// variables and poll-state documents. GitLab install/converge
	// auto-provisions it as a masked, protected CI/CD variable so
	// signing is on by default; see poll.EnsureDispatchSecret.
	SecretDispatch = "FULLSEND_DISPATCH_SECRET"

	// SecretTriggerToken is the GitLab pipeline trigger token used by
	// the webhook fast-path dispatcher. Provisioned as a masked,
	// protected CI/CD variable. Never logged.
	SecretTriggerToken = "FULLSEND_TRIGGER_TOKEN"

	// SecretWebhookSecret is the GitLab project-webhook secret
	// (X-Gitlab-Token) used by the webhook fast-path. Provisioned as a
	// masked, protected CI/CD variable. Never logged.
	SecretWebhookSecret = "FULLSEND_WEBHOOK_SECRET"

	// Opt-in OpenAI static-key secret (ADR 0092), GitHub only: never part
	// of requiredSecrets/requiredSecretsForForge — a repository with no
	// OpenAI WIF and no static key configured is not unhealthy. Uninstall
	// deletes it if present so a torn-down repo doesn't keep a long-lived
	// key around. It's a dedicated, FULLSEND_-namespaced secret (via
	// `fullsend github set` or pasted directly into GitHub settings)
	// fullsend can safely delete regardless of who created it — unlike
	// GitLab's unprefixed, potentially-shared OPENAI_API_KEY CI/CD
	// variable, which fullsend never forwards and does not delete on
	// uninstall — see gitlabUninstallSecrets
	// in internal/repos/uninstall.go for why that one is deliberately not
	// deleted.
	SecretOpenAIAPIKey = "FULLSEND_OPENAI_API_KEY"

	// Legacy uninstall-only variables — GitLab.
	VarLegacyBotTokenSecret = "FULLSEND_BOT_TOKEN_SECRET"
	VarLegacySA             = "FULLSEND_SA"
	VarLegacyWIFProvider    = "FULLSEND_WIF_PROVIDER"
	VarLegacyForge          = "FULLSEND_FORGE"

	// Poll/CI runtime variables.
	VarDispatchHMAC   = "FULLSEND_DISPATCH_HMAC"
	VarPollJobURL     = "FULLSEND_POLL_JOB_URL"
	VarPollMode       = "FULLSEND_POLL_MODE"
	VarGitLabBotToken = "FULLSEND_GITLAB_BOT_TOKEN"

	// VarGitLabRoleRegistry is the administrator-controlled GitLab role
	// registry (JSON policy and credential *references*, never raw
	// secret values). Absent or empty means built-in roles only. Must
	// be a protected CI/CD variable, not repository or merge-request
	// content. See internal/gitlabroles.
	VarGitLabRoleRegistry = "FULLSEND_GITLAB_ROLE_REGISTRY"

	// VarGitLabRoleRotation is the protected, unmasked rotation-state
	// document (per-role lock, token IDs, expiry dates, phase). It
	// never stores token values. See internal/gitlabroles and #7500.
	VarGitLabRoleRotation = "FULLSEND_GITLAB_ROLE_ROTATION"
)

Repo management variable and secret names.

These constants cover every FULLSEND_* name used by repos install, repos status, repos converge, uninstall, and the GitLab poller. Using constants instead of bare string literals ensures that additions, renames, or typos are caught at compile time.

View Source
const (
	// PipelineVarOverrideNoOneAllowed rejects every user-defined pipeline
	// variable, including those sent by an Owner PAT via CreatePipeline.
	PipelineVarOverrideNoOneAllowed = "no_one_allowed"
	PipelineVarOverrideDeveloper    = "developer"
	PipelineVarOverrideMaintainer   = "maintainer"
	PipelineVarOverrideOwner        = "owner"
)

GitLab CI pipeline-variable minimum-override roles.

These are the documented values of GitLab's ci_pipeline_variables_minimum_override_role project setting (GitLab >= 17.1). The setting is a minimum-role gate: only identities at that role or above may pass user-defined variables on pipeline create/trigger. GitHub has no equivalent; its client returns ErrNotSupported.

View Source
const ChangesRequestedMarker = "<!-- fullsend:changes-requested -->"

ChangesRequestedMarker is the hidden HTML comment the GitLab review bot embeds in REQUEST_CHANGES MR notes. The poller retains bot-authored notes that contain this marker, and the dispatch router routes them to the fix stage. GitHub uses the native pull_request_review event instead. Keep this value in one place so the poster, poller, and router cannot silently diverge.

View Source
const ConfigRepoName = ".fullsend"

ConfigRepoName is the conventional name for the org-level fullsend configuration repository. See ADR-0003.

View Source
const ForceCommitFixedBaseSHA = "0000000000000000000000000000000000000001"

ForceCommitFixedBaseSHA is the synthetic parent SHA of every FakeClient force-re-root commit. The GitLab implementation uses the repository's root commit; tests assert the fake always re-roots on this same base.

View Source
const PerRepoGuardVar = "FULLSEND_PER_REPO_INSTALL"

PerRepoGuardVar is the repo variable set by per-repo install to prevent per-org enrollment from overriding a per-repo installation.

Variables

View Source
var ErrAlreadyExists = errors.New("already exists")

ErrAlreadyExists indicates that the resource already exists.

View Source
var ErrBranchProtected = errors.New("branch is protected")

ErrBranchProtected indicates that a ref update failed because the target branch has protection rules that prevent direct pushes.

View Source
var ErrForbidden = errors.New("forbidden")

ErrForbidden indicates that the operation was denied due to insufficient permissions (e.g., the user lacks push access).

View Source
var ErrInvalidPipelineVarOverrideRole = errors.New("invalid pipeline variable override role")

ErrInvalidPipelineVarOverrideRole indicates that a caller supplied a value for ci_pipeline_variables_minimum_override_role that is not one of the four documented roles.

View Source
var ErrNoChanges = errors.New("no changes between branches")

ErrNoChanges indicates that a change proposal could not be created because there are no differences between the head and base branches.

View Source
var ErrNonFastForward = errors.New("non-fast-forward update")

ErrNonFastForward indicates that a commit-files operation failed due to a concurrent modification race. This includes ref updates rejected as non-fast-forward and stale-object errors (e.g. "Tree SHA does not exist") that occur when the base tree changes between read and write. commitFilesWithRetry uses this as the canonical retriable signal.

View Source
var ErrNotFork = errors.New("repository exists but is not a fork of the source")

ErrNotFork indicates that a repository with the requested fork name already exists but is not a fork of the expected source repository.

View Source
var ErrNotFound = errors.New("not found")

ErrNotFound indicates a requested resource was not found on the forge.

View Source
var ErrNotSupported = errors.New("operation not supported by this forge")

ErrNotSupported indicates that the forge implementation does not support the requested operation.

View Source
var ErrTreeTruncated = errors.New("tree truncated")

ErrTreeTruncated indicates that the repository's Git tree is too large to retrieve in a single API call. Callers that receive this error should fall back to per-path existence checks.

Functions

func DetectForge added in v0.30.0

func DetectForge(remoteURL string) (string, error)

DetectForge identifies which forge platform a git remote URL points to. Returns "github" or "gitlab". Returns an error for unknown hosts with a suggestion to use the --forge flag.

Note: this detects the forge from a remote URL, which is distinct from IsSupportedForge (which gates fetch support in harness validation). URL parsing uses isRecognizedForge; a forge may be parseable before fetch support is implemented.

func FormatSignOffTrailer added in v0.37.0

func FormatSignOffTrailer(name, email string) (string, error)

FormatSignOffTrailer builds a "Signed-off-by: name <email>" string. Newline characters (\n, \r) and angle brackets (< and >) are stripped from both fields to prevent trailer injection via crafted forge profile names and malformed trailers. Returns an error if name or email is empty after sanitization.

func IsAlreadyExists added in v0.18.0

func IsAlreadyExists(err error) bool

IsAlreadyExists reports whether err indicates a duplicate resource.

func IsBranchProtected added in v0.18.0

func IsBranchProtected(err error) bool

IsBranchProtected reports whether err indicates a branch protection failure.

func IsForbidden added in v0.24.0

func IsForbidden(err error) bool

IsForbidden reports whether err indicates a permission denial.

func IsNoChanges added in v0.19.0

func IsNoChanges(err error) bool

IsNoChanges reports whether err indicates a no-diff PR creation attempt.

func IsNonFastForward added in v0.28.0

func IsNonFastForward(err error) bool

IsNonFastForward reports whether err indicates a non-fast-forward rejection.

func IsNotFork added in v0.32.0

func IsNotFork(err error) bool

IsNotFork reports whether err indicates a non-fork name collision.

func IsNotFound

func IsNotFound(err error) bool

IsNotFound reports whether err indicates a resource was not found.

func IsNotSupported added in v0.31.0

func IsNotSupported(err error) bool

IsNotSupported reports whether err indicates an unsupported operation.

func IsSupportedForge added in v0.17.0

func IsSupportedForge(hostname string) bool

IsSupportedForge returns true if the hostname belongs to a forge with full fetch/clone support. Use this for validating user-facing URLs (e.g., skill references) where the system must actually be able to retrieve content.

func IsTransient added in v0.37.0

func IsTransient(err error) bool

IsTransient reports whether err represents a transient failure that may succeed on retry. It checks for:

  • non-fast-forward race conditions (ErrNonFastForward)
  • forge-specific API errors that self-report transient-ness via the transientReporter interface (e.g., HTTP 429, 500–504)
  • HTTP client/network timeouts
  • unexpected connection closures (io.EOF, io.ErrUnexpectedEOF)

Callers can use this to decide whether retrying an operation is worthwhile before falling back to a log-and-continue strategy.

func IsTreeTruncated added in v0.30.0

func IsTreeTruncated(err error) bool

IsTreeTruncated reports whether err indicates a truncated tree response.

func ValidatePipelineVarOverrideRole added in v0.44.0

func ValidatePipelineVarOverrideRole(role string) error

ValidatePipelineVarOverrideRole reports an error if role is not one of the documented ci_pipeline_variables_minimum_override_role values (PipelineVarOverrideNoOneAllowed, PipelineVarOverrideDeveloper, PipelineVarOverrideMaintainer, PipelineVarOverrideOwner). Shared by the GitLab LiveClient and FakeClient so both reject typos and unknown values the same way before persisting or sending them.

Types

type Annotation added in v0.13.0

type Annotation struct {
	Level   string // "notice", "warning", "failure"
	Message string
}

Annotation represents a check-run annotation (e.g. from ::notice:: or ::warning:: workflow commands).

type BranchSHARecord added in v0.34.0

type BranchSHARecord struct {
	Owner, Repo, Branch, SHA string
}

BranchSHARecord records a CreateBranchFromSHA call.

type ChangeProposal

type ChangeProposal struct {
	URL    string
	Title  string
	Number int
	Head   string
	// HeadRepo identifies the repository the head branch lives in, as
	// "owner/repo" on both GitHub and GitLab (GitLab resolves a fork's
	// numeric source project ID to its path_with_namespace). Empty when
	// the forge doesn't report it (e.g. a deleted fork). Used to tell a
	// same-named branch in an unrelated fork apart from one in the repo
	// actually being checked, since Head alone is just a bare ref name.
	HeadRepo string
	Base     string
	Author   string // login of the user who opened the PR/MR
}

ChangeProposal represents a pull request or merge request.

type Client

type Client interface {
	// Repository operations
	// ListOrgRepos returns repositories eligible for fullsend enrollment.
	// It excludes archived repos (no active development) and forks.
	//
	// When includePrivate is false, private repos are also excluded.
	// This is the appropriate setting for per-org mode because the
	// default .fullsend config repo is public and agent workflows
	// dispatched to it run with public logs. Enrolling a private repo
	// would expose its code in those logs when agents check out and
	// process the repo content.
	//
	// When includePrivate is true, private repos are included in the
	// result. This is appropriate for per-repo mode where agents run
	// on the target repo itself, so public log exposure does not apply.
	//
	// Forks are excluded because fullsend's trust model is org-centric:
	// trust derives from org repository permissions and CODEOWNERS
	// governance. Forks may live outside the org's permission boundary
	// or lack the same CODEOWNERS configuration, which could bypass
	// human-approval gates. Installing on both a fork and its upstream
	// also risks duplicate agent PRs and conflicting changes.
	ListOrgRepos(ctx context.Context, org string, includePrivate bool) ([]Repository, error)
	GetRepo(ctx context.Context, owner, repo string) (*Repository, error)
	CreateRepo(ctx context.Context, org, name, description string, private bool) (*Repository, error)
	// UpdateRepoVisibility sets a repository's visibility to public or private.
	UpdateRepoVisibility(ctx context.Context, owner, repo string, private bool) error
	DeleteRepo(ctx context.Context, owner, repo string) error

	// FindExistingFork checks whether the authenticated user already has
	// a fork of owner/repo. It returns the fork owner login and repo
	// name if found, or empty strings when no fork exists. The repo
	// name may differ from the upstream name when the user already has
	// an unrelated repo with the same name (GitHub appends a suffix
	// like "-1"). Only actual API errors are returned as err; "not
	// found" is not an error.
	//
	// Cross-forge contract: implementations must check for an existing
	// fork owned by the authenticated user. The semantics of "fork" are
	// platform-specific (e.g., GitHub forks vs GitLab project forks).
	// Returning ("", "", nil) signals no fork exists. Implementations
	// must not return ErrNotFound for missing forks — that is the
	// empty-string convention.
	FindExistingFork(ctx context.Context, owner, repo string) (forkOwner, forkRepo string, err error)

	// CreateFork creates a fork of the given repository under the
	// authenticated user's account. It returns the fork owner login
	// and the actual repo name of the fork. The repo name may differ
	// from the upstream name when the user already has an unrelated
	// repo with the same name (GitHub appends a suffix like "-1").
	// If a fork already exists, it returns the existing fork's owner
	// and repo name without error (idempotent).
	//
	// Cross-forge contract: implementations must create a personal
	// fork of the upstream repo. The call must be idempotent — if the
	// fork already exists, return its metadata without error.
	// Implementations should return both owner and repo name from the
	// API response, not assume the repo name matches the upstream.
	CreateFork(ctx context.Context, owner, repo string) (forkOwner, forkRepo string, err error)

	// CreateForkInOrg creates a fork of the given repository under
	// the specified organization with the given name. It returns the
	// actual repo name of the created fork. The call is idempotent —
	// if a fork of the source with the given name already exists
	// under the org, it returns without error.
	//
	// If a repository with the given name already exists under the
	// org but is not a fork of the source repository, the call
	// returns ErrNotFork. This prevents silent name collisions
	// with unrelated repositories.
	//
	// Cross-forge contract: implementations must create an
	// organization-scoped fork of the upstream repo. Unlike
	// CreateFork (which targets the authenticated user's account),
	// this targets a specific org and allows the caller to choose
	// the fork name. Implementations should return the repo name
	// from the API response, not assume it matches the requested
	// name. Implementations must check for existing non-fork repos
	// with the target name and return ErrNotFork when found.
	CreateForkInOrg(ctx context.Context, owner, repo, org, forkName string) (forkRepo string, err error)

	// File operations
	CreateFile(ctx context.Context, owner, repo, path, message string, content []byte) error

	// CreateOrUpdateFile creates a file or updates it if it already exists.
	// On GitHub, updating an existing file requires the current file's SHA
	// (optimistic concurrency control). The GitHub implementation handles
	// this by fetching the existing SHA before writing. Without it, the
	// API returns a 422 "sha wasn't supplied" error.
	CreateOrUpdateFile(ctx context.Context, owner, repo, path, message string, content []byte) error

	GetFileContent(ctx context.Context, owner, repo, path string) ([]byte, error)
	DeleteFile(ctx context.Context, owner, repo, path, message string) error

	// DeleteFiles atomically removes multiple paths in a single commit via the
	// Git Trees API. Missing paths are skipped. Returns the number of paths
	// removed, or (0, nil) when none of the paths exist.
	DeleteFiles(ctx context.Context, owner, repo, message string, paths []string) (deleted int, err error)

	// ListDirectoryContents returns all files and subdirectories at the given
	// path in a repository at the specified ref (commit SHA, branch, or tag).
	// When recursive is true, nested subdirectories are flattened into the
	// result with paths relative to the listed directory.
	// Returns forge.ErrNotFound if the path does not exist or is not a directory.
	ListDirectoryContents(ctx context.Context, owner, repo, path, ref string, recursive bool) ([]DirectoryEntry, error)

	// ListRepositoryFiles returns all file paths in the repository's default
	// branch. This retrieves the entire tree in a single API call, making it
	// efficient for batch path-existence checks.
	// Returns ErrNotFound if the repository does not exist.
	// Returns ErrTreeTruncated if the repository tree is too large to retrieve
	// in a single call; callers should fall back to per-path checks.
	ListRepositoryFiles(ctx context.Context, owner, repo string) ([]string, error)

	// GetFileContentAtRef retrieves the content of a file at a specific ref
	// (commit SHA, branch, or tag). Unlike GetFileContent which reads from
	// the default branch, this reads from the specified ref.
	// Returns forge.ErrNotFound if the file or ref does not exist.
	GetFileContentAtRef(ctx context.Context, owner, repo, path, ref string) ([]byte, error)

	// CommitFiles atomically commits multiple files to the repository's
	// default branch in a single commit. It is idempotent: if all files
	// already have the expected content and mode, no commit is created
	// and it returns (false, nil).
	CommitFiles(ctx context.Context, owner, repo, message string, files []TreeFile) (committed bool, err error)

	// CommitFilesToBranch atomically commits multiple files to a specific
	// branch. Like CommitFiles, it is idempotent: if all files already
	// have the expected content, no commit is created.
	CommitFilesToBranch(ctx context.Context, owner, repo, branch, message string, files []TreeFile) (committed bool, err error)

	// ForceCommitFileToBranch force-updates branch to a single-file commit
	// re-rooted on a fixed base SHA (the repository's root commit). The
	// target branch is created if it does not exist. History is pruned:
	// each call leaves the branch at base + 1 commit. The commit message
	// is suffixed with [skip ci] if not already present.
	//
	// This is used for GitLab poll-state branch seeding on Developer-writable
	// unprotected branches. Runtime persist uses a conflict-detecting commit
	// (poll.GitLabClient.CommitFileToBranch). GitHub returns ErrNotSupported.
	ForceCommitFileToBranch(ctx context.Context, owner, repo, branch, path, message string, content []byte) error

	// Ref operations
	// GetRef returns the commit SHA for the given ref path (e.g., "heads/main", "tags/v0").
	// Returns forge.ErrNotFound if the ref does not exist.
	GetRef(ctx context.Context, owner, repo, refPath string) (sha string, err error)

	// Branch operations
	// GetBranchRef returns the HEAD commit SHA for the named branch.
	// Returns forge.ErrNotFound if the branch does not exist.
	GetBranchRef(ctx context.Context, owner, repo, branch string) (sha string, err error)
	CreateBranch(ctx context.Context, owner, repo, branchName string) error

	// CreateBranchFromSHA creates a new branch pointing at the given commit
	// SHA. Unlike CreateBranch (which resolves the repo's default branch),
	// this allows the caller to specify an explicit starting point — for
	// example, an upstream HEAD when creating a branch on a stale fork.
	// Returns forge.ErrAlreadyExists if the branch already exists,
	// and forge.ErrForbidden on insufficient permissions.
	CreateBranchFromSHA(ctx context.Context, owner, repo, branchName, sha string) error

	// DeleteBranch deletes the named git branch.
	// Returns forge.ErrNotFound if the branch does not exist.
	//
	// This is a destructive operation. Callers must verify ownership
	// or authorization at the call site before invoking it, especially
	// when the branch name is predictable (for example
	// fullsend/scaffold-install).
	DeleteBranch(ctx context.Context, owner, repo, branchName string) error

	// DeleteRef deletes a git ref (e.g., "heads/my-branch", "tags/v1.0").
	// Returns forge.ErrNotFound if the ref does not exist.
	DeleteRef(ctx context.Context, owner, repo, refPath string) error
	CreateFileOnBranch(ctx context.Context, owner, repo, branch, path, message string, content []byte) error
	// CreateOrUpdateFileOnBranch creates or updates a file on a specific branch.
	// Combines SHA-aware upsert with branch targeting.
	CreateOrUpdateFileOnBranch(ctx context.Context, owner, repo, branch, path, message string, content []byte) error

	// Change proposals (PRs/MRs)
	CreateChangeProposal(ctx context.Context, owner, repo, title, body, head, base string) (*ChangeProposal, error)

	// CreateCrossRepoChangeProposal opens a pull request where the head
	// branch lives in a different repository than the base. This is
	// necessary for same-owner forks where the REST API's "owner:branch"
	// head format is ambiguous. Implementations should use a mechanism
	// that can explicitly identify the head repository (e.g., GraphQL
	// createPullRequest with headRepositoryId on GitHub).
	CreateCrossRepoChangeProposal(ctx context.Context, baseOwner, baseRepo, headOwner, headRepo, title, body, headBranch, baseBranch string) (*ChangeProposal, error)

	ListRepoPullRequests(ctx context.Context, owner, repo string) ([]ChangeProposal, error)

	// CloseChangeProposal closes an open pull request / merge request by
	// number without merging it. This is used to clean up stale PRs
	// (e.g., scaffold PRs left over from a previous install mode).
	CloseChangeProposal(ctx context.Context, owner, repo string, number int) error

	// Organization metadata
	// GetOrgPlan returns the billing plan name for the org (e.g. "free", "team", "enterprise").
	GetOrgPlan(ctx context.Context, org string) (string, error)

	// Authentication
	GetAuthenticatedUser(ctx context.Context) (string, error)

	// GetAuthenticatedUserIdentity returns the display name and email of
	// the authenticated user. This is used to construct Signed-off-by
	// trailers for commits created via the forge API.
	//
	// Returns ErrNotFound when the identity cannot be determined (e.g.,
	// GitHub App installation tokens that cannot call /user).
	GetAuthenticatedUserIdentity(ctx context.Context) (*UserIdentity, error)

	// GetTokenScopes returns the OAuth scopes granted to the current token.
	// On GitHub, this is read from the X-OAuth-Scopes response header.
	// Returns nil (not an error) if the forge doesn't support scope introspection.
	GetTokenScopes(ctx context.Context) ([]string, error)

	// IsInstallationToken reports whether the current token is a GitHub App
	// installation access token (as opposed to a user PAT or OAuth token).
	// Used to skip OAuth scope preflight, which does not apply to installation tokens.
	IsInstallationToken(ctx context.Context) (bool, error)

	// Secrets and variables
	CreateRepoSecret(ctx context.Context, owner, repo, name, value string) error
	RepoSecretExists(ctx context.Context, owner, repo, name string) (bool, error)
	DeleteRepoSecret(ctx context.Context, owner, repo, name string) error
	CreateOrUpdateRepoVariable(ctx context.Context, owner, repo, name, value string) error
	RepoVariableExists(ctx context.Context, owner, repo, name string) (bool, error)
	GetRepoVariable(ctx context.Context, owner, repo, name string) (string, bool, error)
	ListRepoVariables(ctx context.Context, owner, repo string) (map[string]string, error)
	DeleteRepoVariable(ctx context.Context, owner, repo, name string) error

	// Org-level secrets (for cross-repo dispatch tokens)
	CreateOrgSecret(ctx context.Context, org, name, value string, selectedRepoIDs []int64) error
	OrgSecretExists(ctx context.Context, org, name string) (bool, error)
	DeleteOrgSecret(ctx context.Context, org, name string) error
	SetOrgSecretRepos(ctx context.Context, org, name string, repoIDs []int64) error
	// GetOrgSecretRepos returns the list of repository IDs that have access
	// to the given org-level secret.
	GetOrgSecretRepos(ctx context.Context, org, name string) ([]int64, error)

	// Org-level variables (for dispatch function URL)
	CreateOrUpdateOrgVariable(ctx context.Context, org, name, value string, selectedRepoIDs []int64) error
	// CreateOrUpdateOrgVariableAll creates or updates an org-wide Actions variable
	// (visibility all). Used for mint FOREIGN policy variables read via the org API.
	CreateOrUpdateOrgVariableAll(ctx context.Context, org, name, value string) error
	OrgVariableExists(ctx context.Context, org, name string) (bool, error)
	GetOrgVariable(ctx context.Context, org, name string) (value string, exists bool, err error)
	ListOrgVariables(ctx context.Context, org string) ([]OrgVariable, error)
	DeleteOrgVariable(ctx context.Context, org, name string) error
	SetOrgVariableRepos(ctx context.Context, org, name string, repoIDs []int64) error
	// GetOrgVariableRepos returns the list of repository IDs that have access
	// to the given org-level variable.
	GetOrgVariableRepos(ctx context.Context, org, name string) ([]int64, error)

	// CI/Workflow operations
	GetWorkflow(ctx context.Context, owner, repo, workflowFile string) (*Workflow, error)
	GetLatestWorkflowRun(ctx context.Context, owner, repo, workflowFile string) (*WorkflowRun, error)
	GetWorkflowRun(ctx context.Context, owner, repo string, runID int) (*WorkflowRun, error)
	DispatchWorkflow(ctx context.Context, owner, repo, workflowFile, ref string, inputs map[string]string) error

	// Issue operations
	CreateIssue(ctx context.Context, owner, repo, title, body string, labels ...string) (*Issue, error)
	AddIssueLabels(ctx context.Context, owner, repo string, number int, labels ...string) error
	GetIssue(ctx context.Context, owner, repo string, number int) (*Issue, error)
	CloseIssue(ctx context.Context, owner, repo string, number int) error
	ListOpenIssues(ctx context.Context, owner, repo string, labels ...string) ([]Issue, error)
	ListIssueComments(ctx context.Context, owner, repo string, number int) ([]IssueComment, error)
	CreateIssueComment(ctx context.Context, owner, repo string, number int, body string) (*IssueComment, error)
	UpdateIssueComment(ctx context.Context, owner, repo string, commentID int, body string) error
	DeleteIssueComment(ctx context.Context, owner, repo string, commentID int) error
	MinimizeComment(ctx context.Context, nodeID, reason string) error

	// AddIssueReaction adds an emoji reaction to an issue or pull request.
	// content must be one of the values accepted by the forge: on GitHub,
	// "+1", "-1", "laugh", "confused", "heart", "hooray", "rocket", "eyes".
	// It returns the reaction's ID, used to remove it later via
	// DeleteIssueReaction. Unlike comments, reactions do not generate
	// GitHub notifications, making them useful for low-noise status
	// signaling. Returns forge.ErrNotSupported if the forge has no
	// equivalent concept.
	AddIssueReaction(ctx context.Context, owner, repo string, number int, content string) (id int64, err error)

	// DeleteIssueReaction removes a previously added reaction by ID.
	// Returns forge.ErrNotSupported if the forge has no equivalent concept.
	DeleteIssueReaction(ctx context.Context, owner, repo string, number int, reactionID int64) error

	// AddIssueCommentReaction adds an emoji reaction to a specific comment,
	// rather than the issue/PR itself. Used when a run was triggered by a
	// slash command, so the reaction targets the comment that invoked the
	// agent instead of the issue/PR. See AddIssueReaction for content
	// values. Returns forge.ErrNotSupported if the forge has no equivalent
	// concept.
	AddIssueCommentReaction(ctx context.Context, owner, repo string, commentID int, content string) (id int64, err error)

	// DeleteIssueCommentReaction removes a previously added comment
	// reaction by ID. Returns forge.ErrNotSupported if the forge has no
	// equivalent concept.
	DeleteIssueCommentReaction(ctx context.Context, owner, repo string, commentID int, reactionID int64) error

	// ListIssueReactions returns the emoji reactions on an issue or
	// pull request. Returns forge.ErrNotSupported if the forge has no
	// equivalent concept.
	ListIssueReactions(ctx context.Context, owner, repo string, number int) ([]Reaction, error)

	// Pull request operations
	GetPullRequestInfo(ctx context.Context, owner, repo string, number int) (*PullRequestInfo, error)
	GetPullRequestHeadSHA(ctx context.Context, owner, repo string, number int) (string, error)
	// ListPullRequestFiles returns the relative file paths changed by a pull
	// request. On GitHub, the API caps results at 3000 files total.
	ListPullRequestFiles(ctx context.Context, owner, repo string, number int) ([]string, error)
	// ListPullRequestFileDiffs returns the files changed by a pull request
	// along with their unified diff patches. Use this when you need to
	// determine which lines are within diff hunks (e.g. for inline comments).
	ListPullRequestFileDiffs(ctx context.Context, owner, repo string, number int) ([]PullRequestFileDiff, error)

	// Pull request review operations.
	// commitSHA, when non-empty, pins the review to a specific commit.
	// GitHub rejects the request if the commit is not the PR's current HEAD.
	// comments, when non-nil, attaches inline diff comments to the review.
	CreatePullRequestReview(ctx context.Context, owner, repo string, number int, event, body, commitSHA string, comments []ReviewComment) error
	ListPullRequestReviews(ctx context.Context, owner, repo string, number int) ([]PullRequestReview, error)
	DismissPullRequestReview(ctx context.Context, owner, repo string, number, reviewID int, message string) error

	// Change proposal merge
	MergeChangeProposal(ctx context.Context, owner, repo string, number int) error

	// UpdatePullRequestBranch updates a pull request's head branch by
	// merging the base branch into it (equivalent to clicking "Update branch"
	// on GitHub). This is needed when the base branch has advanced and the
	// PR branch is out of date, which causes merge 409 errors.
	UpdatePullRequestBranch(ctx context.Context, owner, repo string, number int) error

	// Workflow run listing
	ListWorkflowRuns(ctx context.Context, owner, repo, workflowFile string) ([]WorkflowRun, error)
	// ListRecentWorkflowRuns returns recent workflow runs across all workflows.
	ListRecentWorkflowRuns(ctx context.Context, owner, repo string, perPage int) ([]WorkflowRun, error)

	// ListWorkflowRunJobs returns the jobs within a workflow run.
	ListWorkflowRunJobs(ctx context.Context, owner, repo string, runID int) ([]WorkflowJob, error)

	// ListWorkflowRunArtifacts returns artifacts uploaded by a workflow run.
	ListWorkflowRunArtifacts(ctx context.Context, owner, repo string, runID int) ([]WorkflowArtifact, error)
	// DownloadWorkflowRunArtifact returns the zip archive for a workflow artifact.
	DownloadWorkflowRunArtifact(ctx context.Context, owner, repo string, artifactID int) ([]byte, error)
	// ListRepositoryArtifacts returns recent artifacts stored for a repository.
	ListRepositoryArtifacts(ctx context.Context, owner, repo string, perPage int) ([]RepositoryArtifact, error)

	// GetWorkflowRunLogs downloads the logs for a workflow run as plain text.
	// On GitHub, this fetches job logs for each job in the run.
	GetWorkflowRunLogs(ctx context.Context, owner, repo string, runID int) (string, error)

	// GetWorkflowRunAnnotations returns annotations (::notice::, ::warning::,
	// etc.) from all jobs in a workflow run.
	GetWorkflowRunAnnotations(ctx context.Context, owner, repo string, runID int) ([]Annotation, error)

	// Branch protection
	// IsProtectedBranch returns true if the given branch has protection
	// rules enabled. Returns ErrNotSupported if the forge does not
	// expose branch-protection queries.
	IsProtectedBranch(ctx context.Context, owner, repo, branch string) (bool, error)

	// GetProtectedBranch returns who may push or merge the given branch.
	// A nil rule with a nil error means the branch is not protected.
	// GitLab uses these access levels to decide who may create pipelines
	// for the ref. GitHub returns ErrNotSupported.
	GetProtectedBranch(ctx context.Context, owner, repo, branch string) (*ProtectedBranchRule, error)

	// GrantProtectedBranchMergeUser grants userID merge access on a
	// protected branch. Idempotent if the user already has merge or push
	// access. Used on GitLab so a Developer-level poller can create
	// pipelines without widening Developer-class merge policy. GitHub
	// returns ErrNotSupported.
	GrantProtectedBranchMergeUser(ctx context.Context, owner, repo, branch string, userID int) error

	// CreatePipeline creates a new pipeline on the given ref with the
	// given variables. Returns the pipeline metadata (ID, web URL).
	// Used by the cron-poller to dispatch agent stages directly via
	// the API instead of bridge jobs and child pipelines.
	CreatePipeline(ctx context.Context, owner, repo, ref string, variables map[string]string) (*Pipeline, error)

	// CreatePipelineWithInputs creates a new pipeline on the given ref using
	// GitLab CI/CD Inputs (spec:inputs) instead of user-defined pipeline
	// variables. It is additive to CreatePipeline, not a replacement:
	// callers that still need the variables-map path keep using
	// CreatePipeline unchanged. Unlike CreatePipeline, this never sends a
	// "variables" value on the wire, so it remains usable when a project's
	// ci_pipeline_variables_minimum_override_role is
	// PipelineVarOverrideNoOneAllowed — GitLab's variable-override gate does
	// not govern pipeline inputs. See PipelineInputValue for the supported
	// value shapes. Returns ErrNotSupported on forges with no equivalent
	// concept (e.g. GitHub Actions).
	CreatePipelineWithInputs(ctx context.Context, owner, repo, ref string, inputs map[string]PipelineInputValue) (*Pipeline, error)

	CreatePipelineSchedule(ctx context.Context, owner, repo, ref, description, cron string, variables map[string]string) (int64, error)
	DeletePipelineSchedule(ctx context.Context, owner, repo string, scheduleID int64) error
	ListPipelineSchedules(ctx context.Context, owner, repo string) ([]PipelineSchedule, error)
	// UpdatePipelineSchedule sets whether an existing pipeline schedule is
	// active. Used to reactivate required GitLab schedules that exist but
	// were disabled. GitHub returns ErrNotSupported.
	UpdatePipelineSchedule(ctx context.Context, owner, repo string, scheduleID int64, active bool) error

	// CI/CD branch-restricted variables (distinct from RepoVariable methods).
	// UpdateCIVariable upserts a CI/CD variable (update if exists, create if not).
	UpdateCIVariable(ctx context.Context, owner, repo, name, value string, protected bool) error
	// CreateProtectedCIVariable creates a branch-restricted, unmasked CI/CD variable.
	// Values are visible in pipeline logs; use CreateRepoSecret for credentials.
	CreateProtectedCIVariable(ctx context.Context, owner, repo, name, value string) error

	// CreatePipelineTriggerToken mints a pipeline trigger token on
	// owner/repo. The token value is only returned at creation time.
	CreatePipelineTriggerToken(ctx context.Context, owner, repo, description string) (*PipelineTriggerToken, error)
	// ListPipelineTriggerTokens lists pipeline trigger tokens.
	// Token values are omitted after creation.
	ListPipelineTriggerTokens(ctx context.Context, owner, repo string) ([]PipelineTriggerToken, error)
	// RevokePipelineTriggerToken deletes a trigger token by ID.
	// Returns ErrNotFound if the token does not exist.
	RevokePipelineTriggerToken(ctx context.Context, owner, repo string, tokenID int64) error

	// CreateProjectHook creates a project webhook with the given URL,
	// secret token, and event filters.
	CreateProjectHook(ctx context.Context, owner, repo string, hook ProjectHook) (*ProjectHook, error)
	// ListProjectHooks lists project webhooks. The secret token is
	// never returned.
	ListProjectHooks(ctx context.Context, owner, repo string) ([]ProjectHook, error)
	// UpdateProjectHook replaces an existing project webhook's full
	// configuration. It is not a partial update: every event-flag field
	// on hook is sent as given, including zero values, so any flag the
	// caller omits is cleared. Returns ErrNotFound if the hook does not
	// exist.
	UpdateProjectHook(ctx context.Context, owner, repo string, hookID int64, hook ProjectHook) (*ProjectHook, error)
	// DeleteProjectHook deletes a project webhook by ID.
	// Returns ErrNotFound if the hook does not exist.
	DeleteProjectHook(ctx context.Context, owner, repo string, hookID int64) error

	// GetPipelineVariablesMinimumOverrideRole returns the GitLab project
	// setting that gates who may pass user-defined variables when creating
	// or triggering a pipeline (ci_pipeline_variables_minimum_override_role).
	// Valid values are no_one_allowed, developer, maintainer, and owner.
	// Returns ("", nil) if the field is absent from GitLab's response
	// (e.g. an older GitLab instance or an edition that doesn't expose the
	// setting) — callers cannot distinguish that case from a project whose
	// role was explicitly read as empty, since GitLab never returns an
	// empty string for a populated field. Returns ErrNotFound if the
	// project does not exist. GitHub returns ErrNotSupported.
	GetPipelineVariablesMinimumOverrideRole(ctx context.Context, owner, repo string) (string, error)
	// SetPipelineVariablesMinimumOverrideRole updates that setting via
	// PUT /projects/:id. role must be one of the documented GitLab values
	// (see ValidatePipelineVarOverrideRole); implementations reject any
	// other value, including empty string, without making a request.
	// Returns ErrNotFound if the project does not exist. GitHub returns
	// ErrNotSupported.
	SetPipelineVariablesMinimumOverrideRole(ctx context.Context, owner, repo, role string) error

	// Commit comparison
	// CompareCommits compares two commits and returns their relationship
	// status: "ahead" (head is ahead of base), "behind" (head is behind
	// base), "identical" (same commit), or "diverged" (no linear
	// relationship). Used for SHA-based downgrade detection in upgrade.
	CompareCommits(ctx context.Context, owner, repo, base, head string) (status string, err error)
}

Client abstracts all git forge operations. Implementations exist for GitHub (and eventually GitLab, Forgejo).

type CommentReactionRecord added in v0.38.0

type CommentReactionRecord struct {
	Owner, Repo string
	CommentID   int
	Content     string
}

CommentReactionRecord records an AddIssueCommentReaction call.

type CommitFilesRecord added in v0.6.0

type CommitFilesRecord struct {
	Owner, Repo, Message string
	Files                []TreeFile
}

CommitFilesRecord records a CommitFiles call.

type CommitFilesToBranchRecord added in v0.18.0

type CommitFilesToBranchRecord struct {
	Owner, Repo, Branch, Message string
	Files                        []TreeFile
}

CommitFilesToBranchRecord records a CommitFilesToBranch call.

type CreatedIssueRecord added in v0.8.0

type CreatedIssueRecord struct {
	Owner, Repo string
	Title, Body string
	Labels      []string
	Number      int
}

CreatedIssueRecord records an issue creation call.

type DirectoryEntry added in v0.17.0

type DirectoryEntry struct {
	Path string // relative path within the listed directory
	Type string // "file" or "dir"
	Size int    // file size in bytes (0 for directories)
}

DirectoryEntry represents a file or subdirectory in a repository directory listing.

type DismissedReviewRecord added in v0.6.0

type DismissedReviewRecord struct {
	Owner, Repo string
	Number      int
	ReviewID    int
	Message     string
}

DismissedReviewRecord records a review dismissal call.

type FakeClient

type FakeClient struct {

	// Pre-populated data
	Repos                     []Repository
	OrgRepos                  map[string][]Repository  // per-org repos; when set, ListOrgRepos uses this instead of Repos
	FileContents              map[string][]byte        // key: "owner/repo/path"
	WorkflowRuns              map[string]*WorkflowRun  // key: "owner/repo/workflow"
	WorkflowRunsList          map[string][]WorkflowRun // key: "owner/repo/workflow" → multiple runs (takes precedence over WorkflowRuns)
	RecentWorkflowRuns        map[string][]WorkflowRun // key: "owner/repo"
	WorkflowRunArtifacts      map[int][]WorkflowArtifact
	WorkflowArtifactContents  map[int][]byte
	RepositoryArtifacts       map[string][]RepositoryArtifact // key: owner/repo
	Workflows                 map[string]*Workflow            // key: "owner/repo/workflow"
	AuthenticatedUser         string                          // login returned by GetAuthenticatedUser
	AuthenticatedUserIdentity *UserIdentity                   // identity returned by GetAuthenticatedUserIdentity
	OrgPlan                   string                          // plan name returned by GetOrgPlan (default: "free")
	Installations             []Installation
	Secrets                   map[string]bool             // key: "owner/repo/name"
	PullRequests              map[string][]ChangeProposal // key: "owner/repo"
	TokenScopes               []string                    // scopes returned by GetTokenScopes
	InstallationToken         bool                        // IsInstallationToken return value
	VariablesExist            map[string]bool             // key: "owner/repo/name"
	VariableValues            map[string]string           // key: "owner/repo/name"

	// ForkOwner controls the return value of CreateFork. When non-empty,
	// CreateFork returns this value as the fork owner login. When empty,
	// CreateFork uses AuthenticatedUser.
	ForkOwner string

	// ExistingForks maps "owner/repo" to the fork owner login returned
	// by FindExistingFork. Entries simulate an already-existing fork.
	ExistingForks map[string]string

	// ForkParents maps "owner/repo" to the parent "owner/repo" for repos
	// that have Fork=true in Repos. Used by CreateForkInOrg to verify
	// that an existing fork has the expected parent (non-fork collision
	// detection). Only consulted when a repo in Repos has Fork=true.
	ForkParents map[string]string

	// App client IDs for GetAppClientID
	AppClientIDs map[string]string // key: app slug → client ID

	// CollaboratorPermissions maps "owner/repo/username" → role_name for GetCollaboratorPermission.
	CollaboratorPermissions map[string]string
	// AddedCollaborators records AddCollaborator calls as "owner/repo/username" → permission.
	AddedCollaborators map[string]string
	// OrgMemberships maps "org/username" → membership for GetOrgMembership.
	OrgMemberships map[string]OrgMembership

	// Org-level secret state
	OrgSecrets       map[string]bool    // key: "org/name"
	OrgSecretRepoIDs map[string][]int64 // key: "org/name" → repo IDs

	// Org-level variable state
	OrgVariables       map[string]bool    // key: "org/name"
	OrgVariableValues  map[string]string  // key: "org/name" → value
	OrgVariableRepoIDs map[string][]int64 // key: "org/name" → repo IDs

	// Protected branches for IsProtectedBranch.
	ProtectedBranches map[string]bool // key: "owner/repo/branch"

	// ProtectedBranchRules stores push/merge access for GetProtectedBranch.
	// Key: "owner/repo/branch". When a key is present, the branch is
	// protected even if ProtectedBranches is false.
	ProtectedBranchRules map[string]*ProtectedBranchRule

	// GrantedProtectedBranchMergeUsers records GrantProtectedBranchMergeUser calls.
	GrantedProtectedBranchMergeUsers []ProtectedBranchMergeGrantRecord

	// Pipeline schedules for List/Create/Delete/UpdatePipelineSchedule.
	PipelineSchedules map[string][]PipelineSchedule // key: "owner/repo"

	// PipelineTriggerTokens stores trigger tokens keyed by "owner/repo".
	PipelineTriggerTokens map[string][]PipelineTriggerToken

	// ProjectHooks stores project webhooks keyed by "owner/repo".
	ProjectHooks map[string][]ProjectHook

	// PipelineVarOverrideRoles stores the GitLab
	// ci_pipeline_variables_minimum_override_role setting per project.
	// Key: "owner/repo". Missing keys round-trip as empty string.
	PipelineVarOverrideRoles map[string]string

	// Directory listings for ListDirectoryContents.
	DirContents map[string][]DirectoryEntry // key: "owner/repo/path@ref"

	// File contents at specific refs for GetFileContentAtRef.
	FileContentsRef map[string][]byte // key: "owner/repo/path@ref"

	// ForceReachableCommits maps "owner/repo/branch" to the number of
	// commits reachable on that branch after force-re-root writes.
	// Always 1 after a successful ForceCommitFileToBranch.
	ForceReachableCommits map[string]int

	// ExistingBranches, when set, makes CreateBranch and CreateBranchFromSHA
	// return ErrAlreadyExists for those keys ("owner/repo/branch").
	// DeleteBranch removes the matching key so a subsequent create succeeds.
	ExistingBranches map[string]bool

	// Branch refs for GetBranchRef.
	BranchRefs map[string]string // key: "owner/repo/branch" → commit SHA

	// Refs for GetRef.
	Refs map[string]string // key: "owner/repo/refPath" → commit SHA

	// Error injection: key is method name, value is error to return.
	Errors map[string]error

	// CreateBranchErrors injects per-repo errors for CreateBranch.
	// Key is "owner/repo", checked before the generic Errors map.
	CreateBranchErrors map[string]error

	// DeleteFilesErrors injects per-repo errors for DeleteFiles.
	// Key is "owner/repo", checked before the generic Errors map.
	DeleteFilesErrors map[string]error

	// GetFileContentErrors injects per-path errors for GetFileContent.
	// Key is "owner/repo/path", checked before the generic Errors map.
	GetFileContentErrors map[string]error

	// Issue comments for ListIssueComments / UpdateIssueComment.
	IssueComments map[string][]IssueComment // key: "owner/repo/number"
	OpenIssues    map[string][]Issue        // key: "owner/repo"

	// CommitFilesChanged controls the return value of both CommitFiles and
	// CommitFilesToBranch (default true). A single field suffices because
	// callers that test the fallback path inject an error on CommitFiles,
	// so only CommitFilesToBranch reads this value in practice.
	CommitFilesChanged *bool

	// CommitFilesErrSeq is an error queue for CommitFiles. Each call shifts
	// the first element; when empty, falls through to Errors["CommitFiles"].
	// A nil entry means no error for that call.
	CommitFilesErrSeq []error

	// CreateReviewErrSeq is an error queue for CreatePullRequestReview.
	// Each call shifts the first element; when empty, falls through to
	// Errors["CreatePullRequestReview"]. A nil entry means no error
	// for that call.
	CreateReviewErrSeq []error

	// CreatePipelineScheduleErrSeq is an error queue for CreatePipelineSchedule.
	// Each call shifts the first element; when empty, falls through to
	// Errors["CreatePipelineSchedule"]. A nil entry means no error for that call.
	CreatePipelineScheduleErrSeq []error

	// Pull request head SHA for GetPullRequestHeadSHA.
	PullRequestHeadSHA string

	// Pull request info for GetPullRequestInfo.
	PullRequestInfos map[string]PullRequestInfo // key: "owner/repo/number"

	// Pull request files for ListPullRequestFiles.
	PRFiles map[string][]string // key: "owner/repo/number"

	// Pull request file diffs for ListPullRequestFileDiffs.
	PRFileDiffs map[string][]PullRequestFileDiff // key: "owner/repo/number"

	// Pull request reviews for ListPullRequestReviews.
	PRReviews map[string][]PullRequestReview // key: "owner/repo/number"

	// WorkflowRunJobs for ListWorkflowRunJobs.
	WorkflowRunJobs map[int][]WorkflowJob // key: runID

	// Annotations for GetWorkflowRunAnnotations.
	Annotations []Annotation

	// Call recorders
	CreatedRepos            []Repository
	CreatedFiles            []FileRecord
	CreatedBranches         []string // "owner/repo/branch"
	CreatedBranchSHAs       []BranchSHARecord
	DeletedBranches         []string // "owner/repo/branch"
	DeletedRefs             []string // "owner/repo/refPath"
	CreatedProposals        []ChangeProposal
	DeletedRepos            []string // "owner/repo"
	DeletedFiles            []FileRecord
	CreatedSecrets          []SecretRecord
	DeletedSecrets          []SecretRecord
	Variables               []VariableRecord
	DeletedVariables        []VariableRecord
	DeletedOrgSecrets       []string // "org/name"
	CreatedOrgSecrets       []OrgSecretRecord
	CreatedOrgVariables     []OrgVariableRecord
	DeletedOrgVariables     []string // "org/name"
	CreatedIssues           []CreatedIssueRecord
	UpdatedComments         []UpdatedCommentRecord
	MinimizedComments       []MinimizedCommentRecord
	AddedReactions          []ReactionRecord
	DeletedReactions        []int64
	AddedCommentReactions   []CommentReactionRecord
	DeletedCommentReactions []int64
	CreatedReviews          []ReviewRecord
	DismissedReviews        []DismissedReviewRecord
	CommittedFiles          []CommitFilesRecord
	CommittedFilesToBranch  []CommitFilesToBranchRecord
	ForceCommittedFiles     []ForceCommitFileToBranchRecord
	CreatedForks            []string // "owner/repo"
	ClosedProposals         []int    // PR numbers
	DeletedComments         []int    // comment IDs
	CreatedPipelines        []Pipeline
	PipelineCalls           []PipelineCallRecord
	PipelineInputsCalls     []PipelineInputsCallRecord
	CreatedSchedules        []PipelineSchedule
	DeletedScheduleIDs      []int64
	UpdatedScheduleIDs      []int64
	UpdatedVariables        []VariableRecord
	CreatedProtectedVars    []VariableRecord
	CreatedTriggerTokens    []PipelineTriggerToken
	RevokedTriggerTokenIDs  []int64
	CreatedProjectHooks     []ProjectHook
	UpdatedProjectHooks     []ProjectHook
	DeletedProjectHookIDs   []int64

	// CommitAncestry maps "owner/repo/base/head" to a comparison status
	// string ("ahead", "behind", "identical", "diverged") for CompareCommits.
	CommitAncestry map[string]string
	// contains filtered or unexported fields
}

FakeClient is a thread-safe test double for forge.Client. Pre-populate its fields to control return values, and inspect recorder slices after the test to verify which calls were made.

func NewFakeClient

func NewFakeClient() *FakeClient

NewFakeClient returns a FakeClient with all maps initialised.

func (*FakeClient) AddCollaborator added in v0.44.0

func (f *FakeClient) AddCollaborator(_ context.Context, owner, repo, username, permission string) error

func (*FakeClient) AddIssueCommentReaction added in v0.38.0

func (f *FakeClient) AddIssueCommentReaction(_ context.Context, owner, repo string, commentID int, content string) (int64, error)

func (*FakeClient) AddIssueLabels added in v0.30.0

func (f *FakeClient) AddIssueLabels(_ context.Context, owner, repo string, number int, labels ...string) error

func (*FakeClient) AddIssueReaction added in v0.38.0

func (f *FakeClient) AddIssueReaction(_ context.Context, owner, repo string, number int, content string) (int64, error)

func (*FakeClient) CloseChangeProposal added in v0.33.0

func (f *FakeClient) CloseChangeProposal(_ context.Context, _, _ string, number int) error

func (*FakeClient) CloseIssue added in v0.0.3

func (f *FakeClient) CloseIssue(_ context.Context, _, _ string, _ int) error

func (*FakeClient) CommitFiles added in v0.6.0

func (f *FakeClient) CommitFiles(_ context.Context, owner, repo, message string, files []TreeFile) (bool, error)

func (*FakeClient) CommitFilesToBranch added in v0.18.0

func (f *FakeClient) CommitFilesToBranch(_ context.Context, owner, repo, branch, message string, files []TreeFile) (bool, error)

func (*FakeClient) CompareCommits added in v0.37.0

func (f *FakeClient) CompareCommits(_ context.Context, owner, repo, base, head string) (string, error)

func (*FakeClient) CreateBranch

func (f *FakeClient) CreateBranch(_ context.Context, owner, repo, branchName string) error

func (*FakeClient) CreateBranchFromSHA added in v0.34.0

func (f *FakeClient) CreateBranchFromSHA(_ context.Context, owner, repo, branchName, sha string) error

func (*FakeClient) CreateChangeProposal

func (f *FakeClient) CreateChangeProposal(_ context.Context, owner, repo, title, body, head, base string) (*ChangeProposal, error)

func (*FakeClient) CreateCrossRepoChangeProposal added in v0.33.0

func (f *FakeClient) CreateCrossRepoChangeProposal(_ context.Context, baseOwner, baseRepo, headOwner, headRepo, title, body, headBranch, baseBranch string) (*ChangeProposal, error)

func (*FakeClient) CreateFile

func (f *FakeClient) CreateFile(_ context.Context, owner, repo, path, message string, content []byte) error

func (*FakeClient) CreateFileOnBranch

func (f *FakeClient) CreateFileOnBranch(_ context.Context, owner, repo, branch, path, message string, content []byte) error

func (*FakeClient) CreateFork added in v0.24.0

func (f *FakeClient) CreateFork(_ context.Context, owner, repo string) (string, string, error)

func (*FakeClient) CreateForkInOrg added in v0.32.0

func (f *FakeClient) CreateForkInOrg(_ context.Context, owner, repo, org, forkName string) (string, error)

func (*FakeClient) CreateIssue added in v0.0.3

func (f *FakeClient) CreateIssue(_ context.Context, owner, repo, title, body string, labels ...string) (*Issue, error)

func (*FakeClient) CreateIssueComment added in v0.2.0

func (f *FakeClient) CreateIssueComment(_ context.Context, owner, repo string, number int, body string) (*IssueComment, error)

func (*FakeClient) CreateOrUpdateFile

func (f *FakeClient) CreateOrUpdateFile(_ context.Context, owner, repo, path, message string, content []byte) error

func (*FakeClient) CreateOrUpdateFileOnBranch

func (f *FakeClient) CreateOrUpdateFileOnBranch(_ context.Context, owner, repo, branch, path, message string, content []byte) error

func (*FakeClient) CreateOrUpdateOrgVariable added in v0.8.0

func (f *FakeClient) CreateOrUpdateOrgVariable(_ context.Context, org, name, value string, selectedRepoIDs []int64) error

func (*FakeClient) CreateOrUpdateOrgVariableAll added in v0.24.0

func (f *FakeClient) CreateOrUpdateOrgVariableAll(ctx context.Context, org, name, value string) error

func (*FakeClient) CreateOrUpdateRepoVariable

func (f *FakeClient) CreateOrUpdateRepoVariable(_ context.Context, owner, repo, name, value string) error

func (*FakeClient) CreateOrgSecret

func (f *FakeClient) CreateOrgSecret(_ context.Context, org, name, value string, selectedRepoIDs []int64) error

func (*FakeClient) CreatePipeline added in v0.33.0

func (f *FakeClient) CreatePipeline(_ context.Context, owner, repo, ref string, variables map[string]string) (*Pipeline, error)

func (*FakeClient) CreatePipelineSchedule added in v0.31.0

func (f *FakeClient) CreatePipelineSchedule(_ context.Context, owner, repo, ref, description, cron string, variables map[string]string) (int64, error)

func (*FakeClient) CreatePipelineTriggerToken added in v0.44.0

func (f *FakeClient) CreatePipelineTriggerToken(_ context.Context, owner, repo, description string) (*PipelineTriggerToken, error)

func (*FakeClient) CreatePipelineWithInputs added in v0.44.0

func (f *FakeClient) CreatePipelineWithInputs(_ context.Context, owner, repo, ref string, inputs map[string]PipelineInputValue) (*Pipeline, error)

CreatePipelineWithInputs records the call and returns a fake pipeline, mirroring CreatePipeline's behavior but without ever touching the variables-based call record — callers can use PipelineInputsCalls to assert that no user-defined variables were required for a dispatch.

func (*FakeClient) CreateProjectHook added in v0.44.0

func (f *FakeClient) CreateProjectHook(_ context.Context, owner, repo string, hook ProjectHook) (*ProjectHook, error)

func (*FakeClient) CreateProtectedCIVariable added in v0.31.0

func (f *FakeClient) CreateProtectedCIVariable(_ context.Context, owner, repo, name, value string) error

func (*FakeClient) CreatePullRequestReview added in v0.2.0

func (f *FakeClient) CreatePullRequestReview(_ context.Context, owner, repo string, number int, event, body, commitSHA string, comments []ReviewComment) error

func (*FakeClient) CreateRepo

func (f *FakeClient) CreateRepo(_ context.Context, org, name, description string, private bool) (*Repository, error)

func (*FakeClient) CreateRepoSecret

func (f *FakeClient) CreateRepoSecret(_ context.Context, owner, repo, name, value string) error

func (*FakeClient) DeleteBranch added in v0.44.0

func (f *FakeClient) DeleteBranch(_ context.Context, owner, repo, branchName string) error

func (*FakeClient) DeleteFile added in v0.1.0

func (f *FakeClient) DeleteFile(_ context.Context, owner, repo, path, message string) error

func (*FakeClient) DeleteFiles added in v0.19.0

func (f *FakeClient) DeleteFiles(_ context.Context, owner, repo, message string, paths []string) (int, error)

func (*FakeClient) DeleteIssueComment added in v0.15.0

func (f *FakeClient) DeleteIssueComment(_ context.Context, _, _ string, commentID int) error

func (*FakeClient) DeleteIssueCommentReaction added in v0.38.0

func (f *FakeClient) DeleteIssueCommentReaction(_ context.Context, _, _ string, _ int, reactionID int64) error

func (*FakeClient) DeleteIssueReaction added in v0.38.0

func (f *FakeClient) DeleteIssueReaction(_ context.Context, _, _ string, _ int, reactionID int64) error

func (*FakeClient) DeleteOrgSecret

func (f *FakeClient) DeleteOrgSecret(_ context.Context, org, name string) error

func (*FakeClient) DeleteOrgVariable added in v0.8.0

func (f *FakeClient) DeleteOrgVariable(_ context.Context, org, name string) error

func (*FakeClient) DeletePipelineSchedule added in v0.31.0

func (f *FakeClient) DeletePipelineSchedule(_ context.Context, owner, repo string, scheduleID int64) error

func (*FakeClient) DeleteProjectHook added in v0.44.0

func (f *FakeClient) DeleteProjectHook(_ context.Context, owner, repo string, hookID int64) error

func (*FakeClient) DeleteRef added in v0.33.0

func (f *FakeClient) DeleteRef(_ context.Context, owner, repo, refPath string) error

func (*FakeClient) DeleteRepo

func (f *FakeClient) DeleteRepo(_ context.Context, owner, repo string) error

func (*FakeClient) DeleteRepoSecret added in v0.28.0

func (f *FakeClient) DeleteRepoSecret(_ context.Context, owner, repo, name string) error

func (*FakeClient) DeleteRepoVariable added in v0.28.0

func (f *FakeClient) DeleteRepoVariable(_ context.Context, owner, repo, name string) error

func (*FakeClient) DismissPullRequestReview added in v0.6.0

func (f *FakeClient) DismissPullRequestReview(_ context.Context, owner, repo string, number, reviewID int, message string) error

func (*FakeClient) DispatchWorkflow

func (f *FakeClient) DispatchWorkflow(_ context.Context, _, _, _, _ string, _ map[string]string) error

func (*FakeClient) DownloadWorkflowRunArtifact added in v0.30.0

func (f *FakeClient) DownloadWorkflowRunArtifact(_ context.Context, _, _ string, artifactID int) ([]byte, error)

func (*FakeClient) FindExistingFork added in v0.24.0

func (f *FakeClient) FindExistingFork(_ context.Context, owner, repo string) (string, string, error)

func (*FakeClient) ForceCommitFileToBranch added in v0.44.0

func (f *FakeClient) ForceCommitFileToBranch(_ context.Context, owner, repo, branch, path, message string, content []byte) error

func (*FakeClient) GetAppClientID added in v0.1.0

func (f *FakeClient) GetAppClientID(_ context.Context, slug string) (string, error)

func (*FakeClient) GetAuthenticatedUser

func (f *FakeClient) GetAuthenticatedUser(_ context.Context) (string, error)

func (*FakeClient) GetAuthenticatedUserIdentity added in v0.19.0

func (f *FakeClient) GetAuthenticatedUserIdentity(_ context.Context) (*UserIdentity, error)

func (*FakeClient) GetBranchRef added in v0.25.0

func (f *FakeClient) GetBranchRef(_ context.Context, owner, repo, branch string) (string, error)

func (*FakeClient) GetCollaboratorPermission added in v0.31.0

func (f *FakeClient) GetCollaboratorPermission(_ context.Context, owner, repo, username string) (string, error)

func (*FakeClient) GetFileContent

func (f *FakeClient) GetFileContent(_ context.Context, owner, repo, path string) ([]byte, error)

func (*FakeClient) GetFileContentAtRef added in v0.17.0

func (f *FakeClient) GetFileContentAtRef(_ context.Context, owner, repo, path, ref string) ([]byte, error)

func (*FakeClient) GetIssue added in v0.30.0

func (f *FakeClient) GetIssue(_ context.Context, owner, repo string, number int) (*Issue, error)

func (*FakeClient) GetLatestWorkflowRun

func (f *FakeClient) GetLatestWorkflowRun(_ context.Context, owner, repo, workflowFile string) (*WorkflowRun, error)

func (*FakeClient) GetOrgMembership added in v0.44.0

func (f *FakeClient) GetOrgMembership(_ context.Context, org, username string) (OrgMembership, error)

func (*FakeClient) GetOrgPlan added in v0.8.0

func (f *FakeClient) GetOrgPlan(_ context.Context, _ string) (string, error)

func (*FakeClient) GetOrgSecretRepos added in v0.5.0

func (f *FakeClient) GetOrgSecretRepos(_ context.Context, org, name string) ([]int64, error)

func (*FakeClient) GetOrgVariable added in v0.24.0

func (f *FakeClient) GetOrgVariable(_ context.Context, org, name string) (string, bool, error)

func (*FakeClient) GetOrgVariableRepos added in v0.12.0

func (f *FakeClient) GetOrgVariableRepos(_ context.Context, org, name string) ([]int64, error)

func (*FakeClient) GetPipelineVariablesMinimumOverrideRole added in v0.44.0

func (f *FakeClient) GetPipelineVariablesMinimumOverrideRole(_ context.Context, owner, repo string) (string, error)

func (*FakeClient) GetProtectedBranch added in v0.44.0

func (f *FakeClient) GetProtectedBranch(_ context.Context, owner, repo, branch string) (*ProtectedBranchRule, error)

func (*FakeClient) GetPullRequestHeadSHA added in v0.2.0

func (f *FakeClient) GetPullRequestHeadSHA(_ context.Context, _, _ string, _ int) (string, error)

func (*FakeClient) GetPullRequestInfo added in v0.31.0

func (f *FakeClient) GetPullRequestInfo(_ context.Context, owner, repo string, number int) (*PullRequestInfo, error)

func (*FakeClient) GetRef added in v0.29.0

func (f *FakeClient) GetRef(_ context.Context, owner, repo, refPath string) (string, error)

func (*FakeClient) GetRepo

func (f *FakeClient) GetRepo(_ context.Context, owner, repo string) (*Repository, error)

func (*FakeClient) GetRepoVariable added in v0.8.0

func (f *FakeClient) GetRepoVariable(_ context.Context, owner, repo, name string) (string, bool, error)

func (*FakeClient) GetTokenScopes

func (f *FakeClient) GetTokenScopes(_ context.Context) ([]string, error)

func (*FakeClient) GetWorkflow added in v0.19.0

func (f *FakeClient) GetWorkflow(_ context.Context, owner, repo, workflowFile string) (*Workflow, error)

func (*FakeClient) GetWorkflowRun

func (f *FakeClient) GetWorkflowRun(_ context.Context, owner, repo string, runID int) (*WorkflowRun, error)

func (*FakeClient) GetWorkflowRunAnnotations added in v0.13.0

func (f *FakeClient) GetWorkflowRunAnnotations(_ context.Context, _, _ string, _ int) ([]Annotation, error)

func (*FakeClient) GetWorkflowRunLogs added in v0.0.3

func (f *FakeClient) GetWorkflowRunLogs(_ context.Context, _, _ string, _ int) (string, error)

func (*FakeClient) GrantProtectedBranchMergeUser added in v0.44.0

func (f *FakeClient) GrantProtectedBranchMergeUser(_ context.Context, owner, repo, branch string, userID int) error

func (*FakeClient) IsInstallationToken added in v0.24.0

func (f *FakeClient) IsInstallationToken(_ context.Context) (bool, error)

func (*FakeClient) IsProtectedBranch added in v0.31.0

func (f *FakeClient) IsProtectedBranch(_ context.Context, owner, repo, branch string) (bool, error)

func (*FakeClient) ListDirectoryContents added in v0.17.0

func (f *FakeClient) ListDirectoryContents(_ context.Context, owner, repo, path, ref string, _ bool) ([]DirectoryEntry, error)

func (*FakeClient) ListIssueComments added in v0.0.4

func (f *FakeClient) ListIssueComments(_ context.Context, owner, repo string, number int) ([]IssueComment, error)

func (*FakeClient) ListIssueReactions added in v0.38.0

func (f *FakeClient) ListIssueReactions(_ context.Context, owner, repo string, number int) ([]Reaction, error)

func (*FakeClient) ListOpenIssues added in v0.8.0

func (f *FakeClient) ListOpenIssues(_ context.Context, owner, repo string, labels ...string) ([]Issue, error)

func (*FakeClient) ListOrgInstallations

func (f *FakeClient) ListOrgInstallations(_ context.Context, _ string) ([]Installation, error)

func (*FakeClient) ListOrgRepos

func (f *FakeClient) ListOrgRepos(_ context.Context, org string, includePrivate bool) ([]Repository, error)

func (*FakeClient) ListOrgVariables added in v0.24.0

func (f *FakeClient) ListOrgVariables(_ context.Context, org string) ([]OrgVariable, error)

func (*FakeClient) ListPipelineSchedules added in v0.31.0

func (f *FakeClient) ListPipelineSchedules(_ context.Context, owner, repo string) ([]PipelineSchedule, error)

func (*FakeClient) ListPipelineTriggerTokens added in v0.44.0

func (f *FakeClient) ListPipelineTriggerTokens(_ context.Context, owner, repo string) ([]PipelineTriggerToken, error)

func (*FakeClient) ListProjectHooks added in v0.44.0

func (f *FakeClient) ListProjectHooks(_ context.Context, owner, repo string) ([]ProjectHook, error)

func (*FakeClient) ListPullRequestFileDiffs added in v0.11.0

func (f *FakeClient) ListPullRequestFileDiffs(_ context.Context, owner, repo string, number int) ([]PullRequestFileDiff, error)

func (*FakeClient) ListPullRequestFiles added in v0.8.5

func (f *FakeClient) ListPullRequestFiles(_ context.Context, owner, repo string, number int) ([]string, error)

func (*FakeClient) ListPullRequestReviews added in v0.2.0

func (f *FakeClient) ListPullRequestReviews(_ context.Context, owner, repo string, number int) ([]PullRequestReview, error)

func (*FakeClient) ListRecentWorkflowRuns added in v0.30.0

func (f *FakeClient) ListRecentWorkflowRuns(_ context.Context, owner, repo string, perPage int) ([]WorkflowRun, error)

func (*FakeClient) ListRepoPullRequests

func (f *FakeClient) ListRepoPullRequests(_ context.Context, owner, repo string) ([]ChangeProposal, error)

func (*FakeClient) ListRepoVariables added in v0.28.0

func (f *FakeClient) ListRepoVariables(_ context.Context, owner, repo string) (map[string]string, error)

func (*FakeClient) ListRepositoryArtifacts added in v0.30.0

func (f *FakeClient) ListRepositoryArtifacts(_ context.Context, owner, repo string, perPage int) ([]RepositoryArtifact, error)

func (*FakeClient) ListRepositoryFiles added in v0.30.0

func (f *FakeClient) ListRepositoryFiles(_ context.Context, owner, repo string) ([]string, error)

func (*FakeClient) ListWorkflowRunArtifacts added in v0.30.0

func (f *FakeClient) ListWorkflowRunArtifacts(_ context.Context, _, _ string, runID int) ([]WorkflowArtifact, error)

func (*FakeClient) ListWorkflowRunJobs added in v0.34.0

func (f *FakeClient) ListWorkflowRunJobs(_ context.Context, _, _ string, runID int) ([]WorkflowJob, error)

func (*FakeClient) ListWorkflowRuns added in v0.0.3

func (f *FakeClient) ListWorkflowRuns(_ context.Context, owner, repo, workflowFile string) ([]WorkflowRun, error)

func (*FakeClient) MergeChangeProposal added in v0.0.3

func (f *FakeClient) MergeChangeProposal(_ context.Context, _, _ string, _ int) error

func (*FakeClient) MinimizeComment added in v0.2.0

func (f *FakeClient) MinimizeComment(_ context.Context, nodeID, reason string) error

func (*FakeClient) OrgSecretExists

func (f *FakeClient) OrgSecretExists(_ context.Context, org, name string) (bool, error)

func (*FakeClient) OrgVariableExists added in v0.8.0

func (f *FakeClient) OrgVariableExists(ctx context.Context, org, name string) (bool, error)

func (*FakeClient) RepoSecretExists

func (f *FakeClient) RepoSecretExists(_ context.Context, owner, repo, name string) (bool, error)

func (*FakeClient) RepoVariableExists

func (f *FakeClient) RepoVariableExists(_ context.Context, owner, repo, name string) (bool, error)

func (*FakeClient) RevokePipelineTriggerToken added in v0.44.0

func (f *FakeClient) RevokePipelineTriggerToken(_ context.Context, owner, repo string, tokenID int64) error

func (*FakeClient) SetOrgSecretRepos

func (f *FakeClient) SetOrgSecretRepos(_ context.Context, org, name string, repoIDs []int64) error

func (*FakeClient) SetOrgVariableRepos added in v0.12.0

func (f *FakeClient) SetOrgVariableRepos(_ context.Context, org, name string, repoIDs []int64) error

func (*FakeClient) SetPipelineVariablesMinimumOverrideRole added in v0.44.0

func (f *FakeClient) SetPipelineVariablesMinimumOverrideRole(_ context.Context, owner, repo, role string) error

func (*FakeClient) UpdateCIVariable added in v0.31.0

func (f *FakeClient) UpdateCIVariable(_ context.Context, owner, repo, name, value string, protected bool) error

func (*FakeClient) UpdateIssueComment added in v0.2.0

func (f *FakeClient) UpdateIssueComment(_ context.Context, owner, repo string, commentID int, body string) error

func (*FakeClient) UpdatePipelineSchedule added in v0.44.0

func (f *FakeClient) UpdatePipelineSchedule(_ context.Context, owner, repo string, scheduleID int64, active bool) error

func (*FakeClient) UpdateProjectHook added in v0.44.0

func (f *FakeClient) UpdateProjectHook(_ context.Context, owner, repo string, hookID int64, hook ProjectHook) (*ProjectHook, error)

func (*FakeClient) UpdatePullRequestBranch added in v0.19.0

func (f *FakeClient) UpdatePullRequestBranch(_ context.Context, _, _ string, _ int) error

func (*FakeClient) UpdateRepoVisibility added in v0.33.0

func (f *FakeClient) UpdateRepoVisibility(_ context.Context, owner, repo string, private bool) error

type FileRecord

type FileRecord struct {
	Owner, Repo, Path, Branch, Message string
	Content                            []byte
}

FileRecord records a file creation/update call.

type ForceCommitFileToBranchRecord added in v0.44.0

type ForceCommitFileToBranchRecord struct {
	Owner, Repo, Branch, Path, Message string
	Content                            []byte
	StartSHA                           string
	Force                              bool
}

ForceCommitFileToBranchRecord records a ForceCommitFileToBranch call.

type ForgeURLInfo added in v0.17.0

type ForgeURLInfo struct {
	Forge    string // "github" (future: "gitlab")
	Owner    string
	Repo     string
	Path     string // path within the repo (e.g., "skills/pr-review")
	Ref      string // commit SHA, tag, or branch name
	PathType string // "tree" (directory), "blob" (file), or "" (raw content URLs)
}

ForgeURLInfo contains the parsed components of a forge URL.

func ParseForgeURL added in v0.17.0

func ParseForgeURL(rawURL string) (*ForgeURLInfo, error)

ParseForgeURL extracts forge, owner, repo, path, and ref from an HTTPS URL pointing to a supported git forge. Returns an error if the URL is not from a recognized forge or cannot be parsed.

Any #sha256=... fragment is stripped before parsing — handle integrity hashes separately via ParseIntegrityHash.

Accepted GitHub formats:

https://github.com/{owner}/{repo}/tree/{ref}/{path}   (directory)
https://github.com/{owner}/{repo}/blob/{ref}/{path}   (file)

Accepted GitLab formats (supports nested groups):

https://gitlab.com/{group}[/subgroup...]/{repo}/-/tree/{ref}/{path}
https://gitlab.com/{group}[/subgroup...]/{repo}/-/blob/{ref}/{path}

func ParseRawContentURL added in v0.22.1

func ParseRawContentURL(rawURL string) (*ForgeURLInfo, error)

ParseRawContentURL extracts forge, owner, repo, path, and ref from a raw.githubusercontent.com URL.

Accepted format:

https://raw.githubusercontent.com/{owner}/{repo}/{ref}/{path...}

The ref is a commit SHA, tag, or branch name. Everything after it is the file/directory path within the repo (may be empty).

func (*ForgeURLInfo) CloneURL added in v0.25.0

func (f *ForgeURLInfo) CloneURL() string

CloneURL returns the HTTPS clone URL for the repository.

type GitHubExtensions added in v0.31.0

type GitHubExtensions interface {
	// ListOrgInstallations returns all GitHub App installations for the org.
	ListOrgInstallations(ctx context.Context, org string) ([]Installation, error)
	// GetAppClientID returns the OAuth client ID for the named GitHub App.
	GetAppClientID(ctx context.Context, slug string) (string, error)

	// GetCollaboratorPermission returns the effective GitHub collaborator
	// permission role_name for username on owner/repo.
	// Returns forge.ErrNotFound when the user has no explicit permission.
	GetCollaboratorPermission(ctx context.Context, owner, repo, username string) (role string, err error)

	// AddCollaborator grants username a direct collaborator permission
	// (pull, triage, push, maintain, admin) on owner/repo. It returns an
	// error when GitHub only sends an invitation (the user is not an org
	// member), because access does not start until it is accepted.
	AddCollaborator(ctx context.Context, owner, repo, username, permission string) error

	// GetOrgMembership returns username's membership in org.
	// Returns forge.ErrNotFound when the user is not a member and has
	// no pending invitation.
	GetOrgMembership(ctx context.Context, org, username string) (OrgMembership, error)
}

GitHubExtensions provides GitHub-specific operations that are not part of the cross-forge Client interface. Callers should type-assert to this interface when they need GitHub App installation features.

type Installation

type Installation struct {
	ID            int
	AppID         int
	AppSlug       string
	AppOwnerLogin string // GitHub login of the app owner (org or user)
	Permissions   map[string]string
}

Installation represents an app installation on an org.

type Issue added in v0.0.3

type Issue struct {
	Number int
	Title  string
	Body   string
	URL    string
	Labels []string
}

Issue represents a forge issue.

type IssueComment added in v0.0.4

type IssueComment struct {
	ID        int
	NodeID    string
	HTMLURL   string
	Body      string
	Author    string
	CreatedAt string
}

IssueComment represents a comment on an issue.

type MinimizedCommentRecord added in v0.2.0

type MinimizedCommentRecord struct {
	NodeID string
	Reason string
}

MinimizedCommentRecord records a comment minimize call.

type OrgMembership added in v0.44.0

type OrgMembership struct {
	State string // "active" or "pending"
	Role  string // "admin" or "member"
}

OrgMembership is a user's membership in a GitHub organization.

type OrgSecretRecord

type OrgSecretRecord struct {
	Org, Name, Value string
	RepoIDs          []int64
}

OrgSecretRecord records an org-level secret creation call.

type OrgVariable added in v0.24.0

type OrgVariable struct {
	Name  string
	Value string
}

OrgVariable is an org-level GitHub Actions variable.

type OrgVariableRecord added in v0.8.0

type OrgVariableRecord struct {
	Org, Name, Value string
	RepoIDs          []int64
}

OrgVariableRecord records an org-level variable creation/update call.

type Pipeline added in v0.33.0

type Pipeline struct {
	ID     int64
	WebURL string
}

Pipeline represents a triggered pipeline.

type PipelineCallRecord added in v0.33.0

type PipelineCallRecord struct {
	Owner, Repo, Ref string
	Variables        map[string]string
}

PipelineCallRecord records a CreatePipeline invocation.

type PipelineInputValue added in v0.44.0

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

PipelineInputValue is a single typed value for a GitLab CI/CD pipeline input (spec:inputs in .gitlab-ci.yml). GitLab's pipeline-creation API accepts string, number, boolean, and array-of-string values for inputs; this type constrains callers to exactly those shapes rather than accepting an untyped any that could silently serialize something GitLab rejects (e.g. a nested object). Construct one with StringInput, NumberInput, BoolInput, or ArrayInput. See https://docs.gitlab.com/ee/ci/inputs/.

func ArrayInput added in v0.44.0

func ArrayInput(v []string) PipelineInputValue

ArrayInput constructs an array-typed pipeline input value from a slice of strings. The slice is copied so later mutation by the caller does not affect the constructed value.

func BoolInput added in v0.44.0

func BoolInput(v bool) PipelineInputValue

BoolInput constructs a boolean-typed pipeline input value.

func NumberInput added in v0.44.0

func NumberInput(v float64) PipelineInputValue

NumberInput constructs a number-typed pipeline input value.

func StringInput added in v0.44.0

func StringInput(v string) PipelineInputValue

StringInput constructs a string-typed pipeline input value.

func (PipelineInputValue) MarshalJSON added in v0.44.0

func (v PipelineInputValue) MarshalJSON() ([]byte, error)

MarshalJSON renders the value as the bare JSON primitive GitLab expects for a pipeline input: a JSON string, number, boolean, or array of strings — never an object wrapper.

type PipelineInputsCallRecord added in v0.44.0

type PipelineInputsCallRecord struct {
	Owner, Repo, Ref string
	Inputs           map[string]PipelineInputValue
}

PipelineInputsCallRecord records a CreatePipelineWithInputs invocation.

type PipelineSchedule added in v0.31.0

type PipelineSchedule struct {
	ID           int64
	Description  string
	Ref          string
	Cron         string
	CronTimezone string
	Active       bool
	Variables    map[string]string // schedule-level pipeline variables
}

PipelineSchedule represents a scheduled pipeline trigger.

type PipelineTriggerToken added in v0.44.0

type PipelineTriggerToken struct {
	ID          int64
	Description string
	Token       string
}

PipelineTriggerToken is a GitLab pipeline trigger token. Token is populated only in the CreatePipelineTriggerToken response; list responses omit it.

type ProjectHook added in v0.44.0

type ProjectHook struct {
	ID                       int64
	URL                      string
	Name                     string
	Description              string
	Token                    string
	PushEvents               bool
	IssuesEvents             bool
	ConfidentialIssuesEvents bool
	MergeRequestsEvents      bool
	TagPushEvents            bool
	NoteEvents               bool
	ConfidentialNoteEvents   bool
	JobEvents                bool
	PipelineEvents           bool
	WikiPageEvents           bool
	DeploymentEvents         bool
	ReleasesEvents           bool
	// EnableSSLVerification reflects GitLab's reported state on read.
	// On write, the GitLab client always enforces true regardless of
	// this field's value: Fullsend never disables TLS verification.
	EnableSSLVerification bool
}

ProjectHook is a GitLab project webhook. Token is write-only: GitLab never returns the secret on list or update responses. URL is the destination, typically a pipeline-trigger URL of the form /api/v4/projects/:id/ref/:ref/trigger/pipeline.

type ProtectedBranchAccess added in v0.44.0

type ProtectedBranchAccess struct {
	AccessLevel int
	UserID      int
	GroupID     int
}

ProtectedBranchAccess is one grant on a protected branch. A role-based grant has AccessLevel set and UserID/GroupID zero. A user or group grant has the corresponding ID set. GitLab access levels: 0 (No one), 30 (Developer), 40 (Maintainer), 60 (Admin). A role-based grant of N allows identities at N or above.

type ProtectedBranchMergeGrantRecord added in v0.44.0

type ProtectedBranchMergeGrantRecord struct {
	Owner, Repo, Branch string
	UserID              int
}

ProtectedBranchMergeGrantRecord records a GrantProtectedBranchMergeUser call.

type ProtectedBranchRule added in v0.44.0

type ProtectedBranchRule struct {
	Name              string
	PushAccessLevels  []ProtectedBranchAccess
	MergeAccessLevels []ProtectedBranchAccess
}

ProtectedBranchRule is the protection configuration for a branch. A nil value from GetProtectedBranch means the branch is not protected.

type PullRequestFileDiff added in v0.11.0

type PullRequestFileDiff struct {
	Path  string
	Patch string
}

PullRequestFileDiff represents a file changed in a pull request along with its unified diff patch. The patch may be empty for binary files, rename-only changes, or when GitHub truncates large diffs.

type PullRequestInfo added in v0.31.0

type PullRequestInfo struct {
	Number   int
	HTMLURL  string
	HeadRepo string
	BaseRepo string
	HeadRef  string
	BaseRef  string
	HeadSHA  string
	AuthorID string
	IsFork   bool
}

PullRequestInfo carries branch/repo context for dispatch enrichment.

type PullRequestReview added in v0.2.0

type PullRequestReview struct {
	ID          int
	NodeID      string
	User        string
	State       string // "APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED"
	Body        string
	SubmittedAt string
}

PullRequestReview represents a formal review on a pull request.

type RateLimit added in v0.38.0

type RateLimit struct {
	Limit     int
	Remaining int
	Reset     time.Time
	Resource  string
	Observed  time.Time
}

RateLimit is the most recent GitHub REST rate-limit state a client observed, taken from the X-RateLimit-* response headers.

func (RateLimit) String added in v0.38.0

func (r RateLimit) String() string

String renders the state for log lines and error messages. Fields the response did not carry are rendered as unknown rather than as plausible-looking zero values.

type RateLimitReporter added in v0.38.0

type RateLimitReporter interface {
	RateLimit() (state RateLimit, ok bool)
}

RateLimitReporter is implemented by clients that track RateLimit. ok is false until the client has seen a response carrying the headers.

type Reaction added in v0.38.0

type Reaction struct {
	ID      int64
	Content string // e.g. "+1", "-1", "laugh", "confused", "heart", "hooray", "rocket", "eyes"
	User    string // login of the user who added the reaction
}

Reaction represents an emoji reaction on an issue, pull request, or comment.

type ReactionRecord added in v0.38.0

type ReactionRecord struct {
	ID          int64
	Owner, Repo string
	Number      int
	Content     string
}

ReactionRecord records an AddIssueReaction call.

type Repository

type Repository struct {
	ID            int64
	Name          string
	FullName      string
	DefaultBranch string
	Private       bool
	Archived      bool
	Fork          bool
}

Repository represents a repository on a git forge.

type RepositoryArtifact added in v0.30.0

type RepositoryArtifact struct {
	ID            int
	Name          string
	CreatedAt     string
	WorkflowRunID int
}

RepositoryArtifact is an artifact stored for a repository, with metadata.

type ReviewComment added in v0.8.0

type ReviewComment struct {
	Path string // relative file path in the repository
	Line int    // line number in the diff (right side); 0 for file-level comments
	Body string // comment body (Markdown)
}

ReviewComment represents an inline comment on a specific line of a pull request diff. These are submitted as part of a formal PR review via the GitHub "Create a review" API.

When Line is 0, the comment is attached to the file as a whole rather than a specific line. This is used for findings that reference a file in the diff but a line outside any diff hunk. Forge implementations translate Line==0 into the appropriate API representation (e.g., GitHub's subject_type: "file").

type ReviewRecord added in v0.2.0

type ReviewRecord struct {
	Owner, Repo string
	Number      int
	Event, Body string
	CommitSHA   string
	Comments    []ReviewComment
}

ReviewRecord records a pull request review creation call.

type SecretRecord

type SecretRecord struct {
	Owner, Repo, Name, Value string
}

SecretRecord records a secret creation call.

type TreeFile added in v0.6.0

type TreeFile struct {
	Path    string
	Content []byte
	Mode    string // "100644" or "100755"
	Delete  bool   // remove file from tree instead of adding/updating
}

TreeFile represents a file to be committed via the Git Trees API. Mode controls file permissions: "100644" for regular files, "100755" for executable files (e.g., shell scripts). When Delete is true, the file is removed from the tree.

type UpdatedCommentRecord added in v0.2.0

type UpdatedCommentRecord struct {
	Owner, Repo string
	CommentID   int
	Body        string
}

UpdatedCommentRecord records an issue comment update call.

type UserIdentity added in v0.19.0

type UserIdentity struct {
	Name  string // display name (may equal login if no name is set)
	Email string // primary or noreply email
}

UserIdentity holds a forge user's display name and email, used for constructing Signed-off-by trailers in commit messages.

func (*UserIdentity) SignOffTrailer added in v0.37.0

func (id *UserIdentity) SignOffTrailer() (string, error)

SignOffTrailer returns a "Signed-off-by: Name <email>" string for this identity. Newline characters are stripped from both fields to prevent trailer injection via crafted profile names. Returns an error if name or email is empty after sanitization.

type VariableRecord

type VariableRecord struct {
	Owner, Repo, Name, Value string
	Protected                bool
}

VariableRecord records a variable creation/update call.

type Workflow added in v0.19.0

type Workflow struct {
	ID    int
	Name  string
	Path  string
	State string // "active", "disabled", etc.
}

Workflow represents a workflow definition registered with the forge.

type WorkflowArtifact added in v0.30.0

type WorkflowArtifact struct {
	ID   int
	Name string
}

WorkflowArtifact is a file bundle uploaded by a workflow run.

type WorkflowJob added in v0.34.0

type WorkflowJob struct {
	ID         int
	Name       string
	Status     string // "queued", "in_progress", "completed"
	Conclusion string // "success", "failure", "cancelled", etc.
}

WorkflowJob represents a job within a workflow run.

type WorkflowRun

type WorkflowRun struct {
	ID         int
	Name       string
	Event      string // GitHub trigger event, e.g. "issues", "issue_comment"
	Status     string // "queued", "in_progress", "completed"
	Conclusion string // "success", "failure", "cancelled", etc.
	HTMLURL    string
	CreatedAt  string
}

WorkflowRun represents a CI/CD workflow execution.

Directories

Path Synopsis
Package github implements forge.Client for the GitHub REST API.
Package github implements forge.Client for the GitHub REST API.
Package gitlab implements forge.Client for the GitLab REST API v4.
Package gitlab implements forge.Client for the GitLab REST API v4.
Package jira implements an HTTP client for the Jira Cloud REST API v3.
Package jira implements an HTTP client for the Jira Cloud REST API v3.

Jump to

Keyboard shortcuts

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