forge

package
v0.51.0-rc.1 Latest Latest
Warning

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

Go to latest
Published: Oct 27, 2026 License: Apache-2.0 Imports: 16 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"

	// VarGCPServiceAccount is the GitLab CI/CD variable naming the
	// service account the agent job impersonates for Vertex inference
	// (config.inference.service_account). Written only when configured;
	// unset keeps direct federated identity.
	VarGCPServiceAccount = "FULLSEND_GCP_SERVICE_ACCOUNT"

	// User-managed OpenAI Workload Identity identifier variables.
	VarOpenAIAudience           = "FULLSEND_OPENAI_AUDIENCE"
	VarOpenAIIdentityProviderID = "FULLSEND_OPENAI_IDENTITY_PROVIDER_ID"
	VarOpenAIServiceAccountID   = "FULLSEND_OPENAI_SERVICE_ACCOUNT_ID"

	// Retired GitLab poller state variables. Superseded by HMAC-signed
	// state.json on fullsend-poll-state-slash / fullsend-poll-state-events.
	// Install and converge neither seed nor migrate them; uninstall
	// deletes any leftovers.
	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"

	// OpenAI static-key secret (ADR 0092). `fullsend repos install`
	// writes it on GitHub and GitLab for repositories whose inference.auth
	// is openai-api-key, and probe/converge require it for those repos
	// only — it is never part of requiredSecrets/requiredSecretsForForge.
	// GitHub uninstall deletes it if present so a torn-down repo doesn't
	// keep a long-lived key around. GitLab CI maps it to OPENAI_API_KEY
	// for the job. GitLab uninstall deletes this prefixed key too;
	// GitLab's unprefixed, potentially-shared OPENAI_API_KEY CI/CD
	// variable is no longer read by the job and is never deleted — see
	// gitlabUninstallSecrets in internal/repos/uninstall.go.
	SecretOpenAIAPIKey = "FULLSEND_OPENAI_API_KEY"
	// SecretInferenceGatewayAPIKey is the inference gateway's API key for
	// inference.gateway.auth api-key (ADR 0138): a forge secret (GitHub) or
	// masked CI/CD variable (GitLab) the runner reads under this name.
	// Setup does not write it; the repository admin sets it.
	SecretInferenceGatewayAPIKey = "FULLSEND_INFERENCE_GATEWAY_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"

	// VarGitLabDispatchRoute is the job-local selector the GitLab poll and
	// dispatcher job scripts export for `fullsend poll` (#8438). It is never
	// a CI/CD variable: the scripts derive it from the pinned pipeline's
	// creator. "child-pipeline" starts agent pipelines with CI_JOB_TOKEN
	// through the pipeline trigger API (source "pipeline"); unset or "api"
	// keeps the Poller credential and the pipelines API (source "api").
	VarGitLabDispatchRoute = "FULLSEND_GITLAB_DISPATCH_ROUTE"
	// GitLabDispatchRouteChildPipeline is the VarGitLabDispatchRoute value
	// that selects the CI_JOB_TOKEN child-pipeline dispatch route.
	GitLabDispatchRouteChildPipeline = "child-pipeline"
	// GitLabDispatchRouteAPI is the VarGitLabDispatchRoute value that keeps
	// the Poller-credential pipelines API dispatch route.
	GitLabDispatchRouteAPI = "api"
	// VarGitLabAnalystUserID is the job-local numeric GitLab user ID of the
	// registered Analyst identity, which the GitLab poll and dispatcher job
	// scripts resolve with the Analyst credential before blanking it and
	// export for `fullsend poll` (#8807). It is never a CI/CD variable.
	// Unset means unknown: no changes-requested marker reaches the fix
	// stage.
	VarGitLabAnalystUserID = "FULLSEND_GITLAB_ANALYST_USER_ID"

	// 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"

	// VarGitLabPollerGenerations is the protected, unmasked Poller
	// identity-generation document (current, pending, and retiring Poller
	// account IDs and the pending generation's handoff phase). It never
	// stores token values. Not yet written by any command. See #8210.
	VarGitLabPollerGenerations = "FULLSEND_GITLAB_POLLER_GENERATIONS"

	// VarGitLabTriggerAccount is the protected, unmasked ledger for the
	// trigger-only GitLab service account (account, bootstrap PAT,
	// deploy-key and branch-grant, and pipeline trigger token IDs, plus
	// the lifecycle phase). It never stores token values or private keys.
	// Written by repos install and removed by repos uninstall only after
	// every resource it records is gone; see #8437 and #8438.
	VarGitLabTriggerAccount = "FULLSEND_GITLAB_TRIGGER_ACCOUNT"

	// VarGitLabDispatchActivation is the protected, unmasked activation record
	// for the trigger-account dispatch route (#8438). It is a separate variable
	// rather than a ledger field because every released decoder of
	// FULLSEND_GITLAB_TRIGGER_ACCOUNT rejects unknown fields before it reads the
	// ledger version, so a new ledger field would make an older CLI fail on an
	// activated project. The record binds to the exact ledger generation (nonce
	// and resource IDs) it was written for, so any lifecycle change, including
	// one made by an older CLI that does not know this variable, leaves it
	// stale and the scaffold falls back to the Poller route. It never stores
	// token values.
	VarGitLabDispatchActivation = "FULLSEND_GITLAB_DISPATCH_ACTIVATION"

	// SecretGitLabTriggerAccountToken is the pipeline trigger token owned by
	// the trigger-only service account. It is stored as a masked, protected
	// CI/CD variable. While the dispatch route of #8438 is activated, the
	// managed webhook embeds it in its trigger URL in place of
	// FULLSEND_TRIGGER_TOKEN (#8509). Never logged and never written to the
	// ledger.
	SecretGitLabTriggerAccountToken = "FULLSEND_GITLAB_TRIGGER_ACCOUNT_TOKEN"
)

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 (
	GitLabAccessLevelDeveloper  = 30
	GitLabAccessLevelMaintainer = 40
	GitLabAccessLevelOwner      = 50
)

GitLab project access levels (members API access_level).

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 mark the repository as installed.

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 ErrConflict = errors.New("conflict")

ErrConflict indicates that a conditional write was rejected because the target changed since the caller read it (see UpdateFileIfMatch).

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 ErrSignedCommitsRequired = errors.New("signed commits required")

ErrSignedCommitsRequired indicates that a commit was rejected because the repository's rules require verified signatures and the commit is not signed. Implementations wrap it together with ErrBranchProtected so existing protection handling still applies, while callers can name the actual rule instead of a generic protection message.

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 AmbiguousRetryDisabled added in v0.50.0

func AmbiguousRetryDisabled(ctx context.Context) bool

AmbiguousRetryDisabled reports whether ctx came from WithoutAmbiguousRetry.

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 GitBlobSHA added in v0.49.0

func GitBlobSHA(content []byte) string

GitBlobSHA returns the Git blob object ID (SHA-1) of content: the expectedSHA UpdateFileIfMatch compares against the stored file.

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 IsConflict added in v0.49.0

func IsConflict(err error) bool

IsConflict reports whether err indicates a rejected conditional write.

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 IsSignedCommitsRequired added in v0.48.1

func IsSignedCommitsRequired(err error) bool

IsSignedCommitsRequired reports whether err indicates a rejection by a rule that requires signed commits.

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 RetryGuard added in v0.50.0

func RetryGuard(ctx context.Context) func(context.Context) error

RetryGuard returns the guard installed by WithRetryGuard, or nil.

func UnverifiedScopes added in v0.46.0

func UnverifiedScopes(err error) []string

UnverifiedScopes returns the scopes named by an UnverifiedScopesError in err's chain, or nil when there is none.

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.

func WithRetryGuard added in v0.50.0

func WithRetryGuard(ctx context.Context, guard func(context.Context) error) context.Context

WithRetryGuard returns a context under which the client calls guard after every retry wait (including rate-limit waits, repository-race waits and commit-retry delays) and before resending the request or rerunning the operation. It also calls guard immediately before the mutating request of a multi-step commit (after the preparatory reads), including on the first attempt. A non-nil error from guard stops the operation: nothing is sent and that error is returned, wrapped. Use it for requests whose target may change while the client waits or reads, such as writing to or deleting a repository by name that another party may have deleted and recreated. guard receives the request context; requests it makes on that context are subject to the same guard, so it should use its own context.

func WithoutAmbiguousRetry added in v0.50.0

func WithoutAmbiguousRetry(ctx context.Context) context.Context

WithoutAmbiguousRetry returns a context that stops the client from retrying a request after an ambiguous failure: a transport timeout or a 5xx response, where the server may already have applied the request. Rate-limit rejections are still retried because the server did not process those. Use it for requests that must not be replayed blindly, such as deleting a repository by name that another party may have recreated; the caller re-checks state after the error.

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.
	//
	// When includePrivate is true, private repos are included in the
	// result. This is appropriate for per-repo installs 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)

	// DeleteProjectServiceAccount deletes a project-owned service account,
	// preserving its contributions. The caller must verify Fullsend ownership.
	// This destructive uninstall operation stays on Client so all forge writes
	// use the shared abstraction; the other GitLab service-account methods
	// (creation, personal access tokens, project members) are concrete
	// gitlab.LiveClient methods and are not part of Client.
	DeleteProjectServiceAccount(ctx context.Context, owner, repo string, userID int) 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)

	// UpdateFileIfMatch writes content to path on the default branch only
	// if the file's current Git blob SHA equals expectedSHA (GitBlobSHA of
	// the content the caller read). An empty expectedSHA creates the file
	// only if it does not exist yet. When the file changed, was deleted,
	// or (for an empty expectedSHA) already exists, it returns an error
	// wrapping ErrConflict. The write is attempted once: implementations
	// must not retry it after a conflict or an ambiguous failure. The
	// caller decides whether to reread and try again. GitLab returns
	// ErrNotSupported.
	UpdateFileIfMatch(ctx context.Context, owner, repo, path, message string, content []byte, expectedSHA string) error

	DeleteFile(ctx context.Context, owner, repo, path, message string) error

	// DeleteFiles atomically removes multiple paths in a single commit.
	// Missing paths are skipped. Returns the number of paths removed, or
	// (0, nil) when none of the paths exist. On GitHub the commit is
	// created with the createCommitOnBranch mutation and is therefore
	// signed by GitHub (see CommitFiles).
	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).
	//
	// On GitHub, a commit whose changed files are all regular inline files
	// (mode 100644, no LocalPath) is created with createCommitOnBranch and
	// signed by GitHub for any credential; it cannot change an existing
	// file's mode, so a mode-only difference counts as unchanged. Other
	// commits (the vendored bundle) use the Git Data REST API, signed only
	// for App installation tokens. GitLab commits count as web-based
	// commits and are signed only where web-based commit signing is set
	// up: the group or project setting on GitLab.com, the instance's
	// signing key on Self-Managed and Dedicated.
	//
	// Returns ErrBranchProtected when a rule rejects the commit, also
	// wrapping ErrSignedCommitsRequired for a signature rule.
	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. The signing rules
	// documented on CommitFiles apply.
	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
	//
	// On GitLab, RepoSecretExists, GetRepoSecretProtection, and
	// DeleteRepoSecret and all individual repository-variable operations address
	// only the wildcard-scoped (environment_scope
	// "*") variable; an environment-specific variable with the same key is
	// ignored and left untouched. ListRepoVariables returns the
	// wildcard-scoped value when a key exists for several scopes. Listing
	// inventories all scopes: a name defined only for a named environment is
	// included in the list but is absent from the individual wildcard lookups.
	// Its listed value must not be treated as evidence of a wildcard definition.
	CreateRepoSecret(ctx context.Context, owner, repo, name, value string) error
	RepoSecretExists(ctx context.Context, owner, repo, name string) (bool, error)
	// GetRepoSecretProtection reports whether a repo secret exists and the
	// masking/protection controls applied to it. It never returns the value.
	GetRepoSecretProtection(ctx context.Context, owner, repo, name string) (SecretProtection, error)
	DeleteRepoSecret(ctx context.Context, owner, repo, name string) error
	// CreateOrUpdateRepoVariable writes an ordinary repository variable. On
	// GitLab it creates or updates only the wildcard-scoped definition, leaving
	// same-named variables in named environments untouched.
	CreateOrUpdateRepoVariable(ctx context.Context, owner, repo, name, value string) error
	// RepoVariableExists checks the wildcard definition on GitLab; a variable
	// present only in a named environment is reported absent.
	RepoVariableExists(ctx context.Context, owner, repo, name string) (bool, error)
	// GetRepoVariable reads the wildcard definition on GitLab; a variable
	// present only in a named environment is reported absent.
	GetRepoVariable(ctx context.Context, owner, repo, name string) (string, bool, error)
	// GetRepoVariableInfo returns stored contents and file-type metadata.
	// On GitLab it uses the same wildcard lookup as GetRepoVariable.
	GetRepoVariableInfo(ctx context.Context, owner, repo, name string) (RepoVariable, bool, error)
	// ListRepoVariables inventories all repository-variable scopes on GitLab.
	// Wildcard values win duplicate names, but a listed name alone does not
	// establish that a wildcard definition exists.
	ListRepoVariables(ctx context.Context, owner, repo string) (map[string]string, error)
	// DeleteRepoVariable removes only the wildcard definition on GitLab,
	// preserving same-named variables in named environments.
	DeleteRepoVariable(ctx context.Context, owner, repo, name string) error

	// Org-level secrets (cleanup of legacy dispatch tokens)
	OrgSecretExists(ctx context.Context, org, name string) (bool, error)
	DeleteOrgSecret(ctx context.Context, org, name string) error

	// Org-level variables (foreign-mint authorization and mint discovery)
	// 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
	GetOrgVariable(ctx context.Context, org, name string) (value string, exists bool, err error)
	ListOrgVariables(ctx context.Context, org string) ([]OrgVariable, error)
	// ListInheritedRepoVariables lists the organization (GitHub) or group
	// (GitLab) variables a repository inherits. GitHub returns only the
	// variables whose visibility includes the repository, with values;
	// GitLab returns group variable names and NonBlank metadata without values.
	// A repository variable takes precedence over an inherited one.
	// When some scopes cannot be inspected, the variables that could be read
	// are returned together with an *UnverifiedScopesError.
	ListInheritedRepoVariables(ctx context.Context, owner, repo string) ([]OrgVariable, error)
	// ListInstanceVariables lists the names of instance-level CI/CD variables
	// (self-managed GitLab). Forges without instance-level variables, or
	// where the caller cannot inspect them, return an error; ErrForbidden
	// means the caller lacks the access to inspect them.
	ListInstanceVariables(ctx context.Context) ([]OrgVariable, error)
	DeleteOrgVariable(ctx context.Context, org, name string) 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)
	// GetIssueComment fetches a single comment by ID. Returns ErrNotFound if
	// the comment does not exist (or, on GitLab, if it could not be located
	// by the ID-scan lookup UpdateIssueComment/DeleteIssueComment also use).
	GetIssueComment(ctx context.Context, owner, repo string, commentID int) (*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)
	// ListPullRequestCommits returns the commit SHAs on a pull request,
	// oldest first. The result is the pull request's current commit list,
	// not a historical record: force-pushing or rebasing the head branch
	// can replace it, and the first entry is the commit the PR was opened
	// with only while the PR has not been rewritten (and, for a
	// multi-commit PR, the PR opens at its last commit). On GitHub the
	// API caps results at 250 commits.
	ListPullRequestCommits(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)
	// ListPullRequestReviewThreads returns review threads, including their
	// resolution state and comments. It returns ErrNotSupported when the forge
	// has no equivalent review-thread API.
	ListPullRequestReviewThreads(ctx context.Context, owner, repo string, number int) (ReviewThreadPage, 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)
	// ListWorkflowRunsSince returns workflow runs for workflowFile created at
	// or after since, paginating as needed rather than returning only the
	// newest page. Use this instead of ListWorkflowRuns when the caller must
	// not miss an older-but-still-eligible run that newer runs (including
	// ones for other agents) could otherwise push off the first page (#7996
	// review).
	ListWorkflowRunsSince(ctx context.Context, owner, repo, workflowFile string, since time.Time) ([]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)

	// ListProtectedBranches returns every protected-branch rule on the
	// project, including wildcard patterns (Name is the rule's pattern).
	// GitLab webhook readiness uses it to see which refs a project-wide
	// pipeline trigger token could start pipelines on. GitHub returns
	// ErrNotSupported.
	ListProtectedBranches(ctx context.Context, owner, repo string) ([]ProtectedBranchRule, error)

	// ListProtectedTags returns the name or wildcard pattern of every
	// protected-tag rule on the project. GitLab pipeline trigger tokens can
	// target tag refs as well as branches, so webhook readiness uses it to
	// see which tag refs the token could start pipelines on. GitHub returns
	// ErrNotSupported.
	ListProtectedTags(ctx context.Context, owner, repo string) ([]string, 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

	// RevokeProtectedBranchMergeUserEntry removes the single user merge-access
	// entry identified by entryID from the exact-name protected-branch rule for
	// branch. It exists so a caller that added a grant (and learned its entry ID
	// from a ProtectedBranchAccess it read back) can undo exactly that grant
	// without touching any other entry for the same user. It refuses an entry
	// that is not a grant for userID, never touches wildcard rules, and is a
	// no-op when the entry or rule is already gone. Used on GitLab; GitHub
	// returns ErrNotSupported.
	RevokeProtectedBranchMergeUserEntry(ctx context.Context, owner, repo, branch string, entryID, 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)
	// CreatePipelineScheduleWithActive is CreatePipelineSchedule with the
	// schedule's initial active state sent in the create request. With
	// active false the schedule is never active, so it cannot fire between
	// a create and a separate disable. GitHub returns ErrNotSupported.
	CreatePipelineScheduleWithActive(ctx context.Context, owner, repo, ref, description, cron string, variables map[string]string, active bool) (int64, error)
	DeletePipelineSchedule(ctx context.Context, owner, repo string, scheduleID int64) error
	// GetPipelineSchedule includes variables omitted by GitLab's list endpoint.
	GetPipelineSchedule(ctx context.Context, owner, repo string, scheduleID int64) (*PipelineSchedule, 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
	// GetProjectMemberAccessLevel returns userID's effective access level
	// on owner/repo, including membership inherited from groups (GitLab
	// /projects/:id/members/all/:user_id). Returns ErrNotFound when the
	// user has no access. Used to verify a trigger token owner's runtime
	// privilege; see the GitLabAccessLevel constants.
	GetProjectMemberAccessLevel(ctx context.Context, owner, repo string, userID int64) (int, 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
	// GetJobTokenRepositoryPushAllowed returns the GitLab project setting
	// ci_push_repository_for_job_token_allowed, which lets a job's
	// CI_JOB_TOKEN push to the project repository. Returns ErrNotSupported
	// if the field is absent from GitLab's response (an instance or edition
	// that does not report the setting), so callers can fail closed rather
	// than treat an unreported setting as disabled. Returns ErrNotFound if
	// the project does not exist. GitHub returns ErrNotSupported.
	GetJobTokenRepositoryPushAllowed(ctx context.Context, owner, repo string) (bool, error)
	// GetPushRuleBranchNameRegex returns the branch_name_regex of the
	// GitLab project's push rule (GET /projects/:id/push_rule), which
	// every pushed or API-created branch name must match. Returns
	// ("", nil) when the project has no push rule or the rule sets no
	// branch name regex. Returns ErrNotFound when the endpoint or project
	// is unavailable (push rules are not offered on every GitLab edition)
	// and ErrForbidden when the caller may not read push rules. GitHub
	// returns ErrNotSupported.
	GetPushRuleBranchNameRegex(ctx context.Context, owner, repo string) (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"
	SecretProtections         map[string]SecretProtection // key: "owner/repo/name"; overrides the default fully-protected report for existing secrets
	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"
	VariableFileTypes         map[string]bool             // key: "owner/repo/name"; file-type metadata for repository variables

	// 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"

	// Org-level variable state
	OrgVariables      map[string]bool   // key: "org/name"
	InstanceVariables []string          // instance-level CI/CD variable names
	OrgVariableValues map[string]string // key: "org/name" → value

	// 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

	// ProtectedTags lists protected-tag rules for ListProtectedTags.
	ProtectedTags map[string]bool // key: "owner/repo/tag-pattern"

	// GrantedProtectedBranchMergeUsers records GrantProtectedBranchMergeUser calls.
	GrantedProtectedBranchMergeUsers []ProtectedBranchMergeGrantRecord
	// RevokedProtectedBranchMergeEntries records RevokeProtectedBranchMergeUserEntry calls.
	RevokedProtectedBranchMergeEntries []ProtectedBranchMergeRevokeRecord

	// 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
	// TriggerTokenOwnerID is the owner recorded on tokens minted by
	// CreatePipelineTriggerToken (GitLab binds a token to its creator).
	TriggerTokenOwnerID int64
	// ProjectMemberAccess maps a user ID to its effective project access
	// level for GetProjectMemberAccessLevel; absent users are not members.
	ProjectMemberAccess map[int64]int

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

	// ProjectLeases holds the leases taken through AcquireProjectLease; see
	// the method for the key format.
	ProjectLeases map[string]string

	// 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

	// JobTokenRepositoryPushAllowed stores the GitLab
	// ci_push_repository_for_job_token_allowed setting per project.
	// Key: "owner/repo". Missing keys read as false (push disabled).
	JobTokenRepositoryPushAllowed map[string]bool

	// PushRuleBranchNameRegexes stores the GitLab push rule
	// branch_name_regex per project. Key: "owner/repo". Missing keys read
	// as "" (no push rule).
	PushRuleBranchNameRegexes 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 commit SHAs (oldest first) for ListPullRequestCommits.
	PRCommits 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"

	// Pull request review threads for ListPullRequestReviewThreads.
	PRReviewThreads map[string]ReviewThreadPage // key: "owner/repo/number"

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

	// Annotations for GetWorkflowRunAnnotations.
	Annotations []Annotation

	// Call recorders
	DeletedProjectServiceAccounts []int

	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"
	CreatedOrgVariables     []OrgVariableRecord
	DeletedOrgVariables     []string // "org/name"
	CreatedIssues           []CreatedIssueRecord
	UpdatedComments         []UpdatedCommentRecord
	GetNoteOnParentCalls    []NoteOnParentRecord
	UpdateNoteOnParentCalls []NoteOnParentRecord
	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) AcquireProjectLease added in v0.46.0

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

AcquireProjectLease implements ProjectLeaser. Leases are keyed "owner/repo/name" in ProjectLeases with the holder as value; a test seeds an entry to model another installer process holding the lease.

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) CreateOrUpdateOrgVariableAll added in v0.24.0

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

func (*FakeClient) CreateOrUpdateRepoVariable

func (f *FakeClient) CreateOrUpdateRepoVariable(_ context.Context, owner, repo, name, value string) 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(ctx context.Context, owner, repo, ref, description, cron string, variables map[string]string) (int64, error)

func (*FakeClient) CreatePipelineScheduleWithActive added in v0.49.0

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

CreatePipelineScheduleWithActive shares CreatePipelineSchedule's error injection ("CreatePipelineSchedule", CreatePipelineScheduleErrSeq), also honors its own "CreatePipelineScheduleWithActive" error key, and records the schedule with the requested active state.

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) DeleteProjectServiceAccount added in v0.46.0

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

DeleteProjectServiceAccount records a project service-account deletion.

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) GetIssueComment added in v0.45.0

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

func (*FakeClient) GetJobTokenRepositoryPushAllowed added in v0.48.0

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

func (*FakeClient) GetLatestWorkflowRun

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

func (*FakeClient) GetNoteOnParent added in v0.45.0

func (f *FakeClient) GetNoteOnParent(_ context.Context, owner, repo, parentType string, parentIID, noteID int) (*IssueComment, error)

GetNoteOnParent implements GitLabExtensions. Unlike the real GitLab client, FakeClient has no notion of noteTarget-vs-parentType mismatch; it records the call (so tests can assert the direct-addressing path was taken) and otherwise looks the note up the same way GetIssueComment does.

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) GetOrgVariable added in v0.24.0

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

func (*FakeClient) GetPipelineSchedule added in v0.46.0

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

func (*FakeClient) GetPipelineVariablesMinimumOverrideRole added in v0.44.0

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

func (*FakeClient) GetProjectMemberAccessLevel added in v0.46.0

func (f *FakeClient) GetProjectMemberAccessLevel(_ context.Context, _, _ string, userID int64) (int, 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) GetPushRuleBranchNameRegex added in v0.49.0

func (f *FakeClient) GetPushRuleBranchNameRegex(_ context.Context, owner, repo string) (string, 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) GetRepoSecretProtection added in v0.46.0

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

func (*FakeClient) GetRepoVariable added in v0.8.0

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

func (*FakeClient) GetRepoVariableInfo added in v0.46.0

func (f *FakeClient) GetRepoVariableInfo(_ context.Context, owner, repo, name string) (RepoVariable, 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) ListInheritedRepoVariables added in v0.46.0

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

ListInheritedRepoVariables returns the organization variables of owner, which the fake treats as visible to every repository in the organization.

func (*FakeClient) ListInstanceVariables added in v0.46.0

func (f *FakeClient) ListInstanceVariables(_ context.Context) ([]OrgVariable, error)

ListInstanceVariables returns the instance-level CI/CD variable names configured in InstanceVariables.

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) ListProtectedBranches added in v0.46.0

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

func (*FakeClient) ListProtectedTags added in v0.46.0

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

func (*FakeClient) ListPullRequestCommits added in v0.46.0

func (f *FakeClient) ListPullRequestCommits(_ context.Context, owner, repo string, number int) ([]string, 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) ListPullRequestReviewThreads added in v0.46.0

func (f *FakeClient) ListPullRequestReviewThreads(_ context.Context, owner, repo string, number int) (ReviewThreadPage, 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) ListWorkflowRunsSince added in v0.45.0

func (f *FakeClient) ListWorkflowRunsSince(ctx context.Context, owner, repo, workflowFile string, since time.Time) ([]WorkflowRun, error)

ListWorkflowRunsSince returns the same configured runs as ListWorkflowRuns, filtered to those created at or after since. Unlike the live GitHub client's ListWorkflowRuns (capped at per_page=10), FakeClient never truncates its configured list, so this filters rather than paginates — tests configure WorkflowRunsList directly with as many runs as a scenario needs, including more than a single live-API page, to exercise since-bounded selection (#7996 review).

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) ReleaseProjectLease added in v0.46.0

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

ReleaseProjectLease implements ProjectLeaser.

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) RevokeProtectedBranchMergeUserEntry added in v0.48.0

func (f *FakeClient) RevokeProtectedBranchMergeUserEntry(ctx context.Context, owner, repo, branch string, entryID, userID int) 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) UpdateFileIfMatch added in v0.49.0

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

UpdateFileIfMatch writes content only when the stored file's blob SHA equals expectedSHA (or, for an empty expectedSHA, when no file exists). Otherwise it returns ErrConflict and leaves the file unchanged.

func (*FakeClient) UpdateIssueComment added in v0.2.0

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

func (*FakeClient) UpdateNoteOnParent added in v0.45.0

func (f *FakeClient) UpdateNoteOnParent(_ context.Context, owner, repo, parentType string, parentIID, noteID int, body string) error

UpdateNoteOnParent implements GitLabExtensions. See GetNoteOnParent.

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 base role
	// (admin, maintain, write, triage, read or none) for username on
	// owner/repo, resolving custom role names from effective permissions.
	// 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 GitLabExtensions added in v0.45.0

type GitLabExtensions interface {
	// GetNoteOnParent fetches a note by its parent noteable's IID and the
	// note's own ID, addressing the GitLab Notes API path directly.
	// parentType must be "issues" or "merge_requests".
	GetNoteOnParent(ctx context.Context, owner, repo, parentType string, parentIID, noteID int) (*IssueComment, error)

	// UpdateNoteOnParent updates a note's body by its parent noteable's
	// IID and the note's own ID, addressing the GitLab Notes API path
	// directly. parentType must be "issues" or "merge_requests".
	UpdateNoteOnParent(ctx context.Context, owner, repo, parentType string, parentIID, noteID int, body string) error
}

GitLabExtensions provides GitLab-specific operations that are not part of the cross-forge Client interface. Callers type-assert to this interface when they already know a note's parent noteable (issue or merge request) type and IID, and want to address it directly instead of through GetIssueComment/UpdateIssueComment's ID-only scan — the scan is bounded and, because it is driven by the client's own fixed noteTarget, cannot find a note whose actual parent type differs from how the client was constructed.

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
	// State is "open" or "closed". It is only populated by GetIssue;
	// other issue reads leave it empty.
	State string
	// StateReason is GitHub's state_reason: "completed", "not_planned"
	// or "duplicate" for a closed issue, "reopened" or empty otherwise.
	// GitLab does not report one. Only populated by GetIssue.
	StateReason 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 NoteOnParentRecord added in v0.45.0

type NoteOnParentRecord struct {
	Owner, Repo, ParentType string
	ParentIID, NoteID       int
	Body                    string // empty for GetNoteOnParent calls
}

NoteOnParentRecord records a GetNoteOnParent/UpdateNoteOnParent call, letting tests assert that a caller addressed a note directly by its parent's type and IID instead of going through the ID-only scan that GetIssueComment/UpdateIssueComment use.

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 OrgVariable added in v0.24.0

type OrgVariable struct {
	Name  string
	Value string
	// NonBlank reports effective value presence without disclosing a GitLab
	// group/instance variable's potentially sensitive value. Nil means that
	// metadata was unavailable; Value remains the source on other forges.
	NonBlank *bool
}

OrgVariable is a GitHub organization variable or an inherited GitLab group variable.

type OrgVariableRecord added in v0.8.0

type OrgVariableRecord struct {
	Org, Name, Value string
}

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
	OwnerID      int64 // zero when GitLab did not report an owner
	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
	OwnerID     int64
}

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

OwnerID is the numeric ID of the user the token acts as (GitLab runs trigger pipelines with the owner's permissions); 0 means the owner is unknown, which callers must treat as unverifiable.

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
	// AlertStatus is GitLab's reported delivery state on read ("executable",
	// "temporarily_disabled", or "disabled"); "" when the server does not
	// report it. It is never sent on write.
	AlertStatus string
	// DisabledUntil is the RFC 3339 time a temporarily disabled hook is
	// retried, or "" when the hook is not temporarily disabled. Read only.
	DisabledUntil string
}

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.

func (ProjectHook) HookDeliveryDisabled added in v0.46.0

func (h ProjectHook) HookDeliveryDisabled() bool

HookDeliveryDisabled reports whether GitLab has permanently disabled delivery for the hook after repeated failures. Such a hook stays configured but never fires until it is re-enabled or recreated.

type ProjectLeaser added in v0.46.0

type ProjectLeaser interface {
	// AcquireProjectLease creates the lease named name with the given holder
	// value. It reports false, without error, when the lease already exists.
	AcquireProjectLease(ctx context.Context, owner, repo, name, holder string) (bool, error)
	// ReleaseProjectLease removes the lease only while it still carries
	// holder. A lease that is gone or held by someone else is left alone.
	// The holder check and the removal are not guaranteed to be atomic: a
	// backend without a conditional delete (GitLab CI variables) can remove a
	// newer holder's lease if the lease is replaced and re-acquired between
	// the check and the removal. Callers must therefore never take over a
	// lease while a previous holder may still release it.
	ReleaseProjectLease(ctx context.Context, owner, repo, name, holder string) error
}

ProjectLeaser is implemented by clients that can take a project-scoped lease shared by every installer process, whatever host it runs on. A lease is a named record the forge creates atomically only when it is absent, so two holders can never both succeed. Callers use it to serialize multi-request transactions that a process-local mutex cannot protect.

type ProtectedBranchAccess added in v0.44.0

type ProtectedBranchAccess struct {
	ID          int
	AccessLevel int
	UserID      int
	GroupID     int
	DeployKeyID int
}

ProtectedBranchAccess is one grant on a protected branch. A role-based grant has AccessLevel set and UserID/GroupID/DeployKeyID zero. A user, group, or deploy-key grant has the corresponding ID set. GitLab reports a deploy-key grant with a Maintainer AccessLevel, but it admits only the key, not every Maintainer, so callers must not read it as a role grant. ID is the forge's identifier of this individual entry (zero when the forge does not report one); it lets a caller remove exactly this entry later. 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 ProtectedBranchMergeRevokeRecord added in v0.48.0

type ProtectedBranchMergeRevokeRecord struct {
	Owner, Repo, Branch string
	EntryID, UserID     int
	// CtxErr is the context's error when the call arrived, so tests can
	// assert that cleanup ran on a context detached from cancellation.
	CtxErr error
	// HasDeadline reports whether the call's context was bounded.
	HasDeadline bool
}

ProtectedBranchMergeRevokeRecord records a RevokeProtectedBranchMergeUserEntry 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 RepoVariable added in v0.46.0

type RepoVariable struct {
	Value    string
	FileType bool
}

RepoVariable describes stored contents and the runtime delivery type.

type Repository

type Repository struct {
	ID            int64
	Name          string
	FullName      string
	DefaultBranch string
	Private       bool
	Archived      bool
	Fork          bool
	// Description is the repository description. Populated by CreateRepo
	// and GetRepo; list operations may leave it empty.
	Description string
	// CIConfigPath is the project's configured CI configuration path, as
	// reported by GitLab (ci_config_path). Empty means the default
	// .gitlab-ci.yml at the repository root. Other forges leave it empty.
	CIConfigPath string
	// CreatedAt is when the repository was created. Populated by the
	// GitHub CreateRepo and GetRepo; zero when the forge did not report it.
	CreatedAt time.Time
}

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 ReviewThread added in v0.46.0

type ReviewThread struct {
	ID                     string                `json:"id"`
	IsResolved             bool                  `json:"is_resolved"`
	Path                   string                `json:"path"`
	Line                   *int                  `json:"line"`
	OriginalLine           *int                  `json:"original_line"`
	ResolvedBy             string                `json:"resolved_by"`
	ResolvedByType         string                `json:"resolved_by_type"`
	ResolvedByRole         normevent.ActorRole   `json:"resolved_by_role"`
	ResolvedByRoleVerified bool                  `json:"resolved_by_role_verified"`
	Comments               []ReviewThreadComment `json:"comments"`
	CommentsTruncated      bool                  `json:"comments_truncated"`
}

ReviewThread represents the resolution state and comments of a pull-request review thread. Forges that do not expose review threads return ErrNotSupported.

type ReviewThreadComment added in v0.46.0

type ReviewThreadComment struct {
	Author             string              `json:"author"`
	AuthorType         string              `json:"author_type"`
	AuthorRole         normevent.ActorRole `json:"author_role"`
	AuthorRoleVerified bool                `json:"author_role_verified"`
	Body               string              `json:"body"`
	CreatedAt          string              `json:"created_at"`
}

ReviewThreadComment is a comment belonging to a pull-request review thread. AuthorType is the forge's actor type (for example, "Bot" or "User").

type ReviewThreadPage added in v0.46.0

type ReviewThreadPage struct {
	Threads   []ReviewThread `json:"threads"`
	Truncated bool           `json:"truncated"`
}

ReviewThreadPage contains a complete fetch of a pull request's review threads. Truncated is true when the implementation hit its safety cap.

type SecretProtection added in v0.46.0

type SecretProtection struct {
	// Exists reports whether the secret is present.
	Exists bool
	// Masked reports that the forge redacts the value in job logs.
	Masked bool
	// Protected reports that the value is only exposed to jobs on
	// protected branches and tags.
	Protected bool
	// FileType reports that the secret is a file-type variable, whose
	// value jobs receive as a temporary file path rather than the value.
	// Forges without variable types always report false.
	FileType bool
	// EnvironmentScoped reports that the secret is limited to specific
	// environments, so jobs that declare no environment do not receive
	// it. Forges without environment scopes always report false.
	EnvironmentScoped bool
}

SecretProtection describes the exposure controls on an existing repo secret. Forges that always encrypt and mask secrets report both true.

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
	LocalPath string // stream from this filesystem path instead of Content
	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.

Large binaries (e.g. a vendored CLI) should set LocalPath instead of Content so callers do not hold the full payload in memory between collection and CommitFiles. Forge clients stream or read LocalPath at commit time. When LocalPath is set, Content is ignored.

func (TreeFile) Bytes added in v0.46.0

func (f TreeFile) Bytes() ([]byte, error)

Bytes returns the file payload. LocalPath, when set, is read from disk so callers can keep large binaries out of TreeFile.Content. Delete entries have no payload.

type UnverifiedScopesError added in v0.46.0

type UnverifiedScopesError struct {
	// Scopes names each scope that could not be inspected.
	Scopes []string
}

UnverifiedScopesError is returned by ListInheritedRepoVariables together with the variables that could be read when some inherited scopes (ancestor groups, the instance) could not be inspected. Those scopes are unknown, not verified empty: a caller that needs the effective variable set must not treat their variables as absent.

func (*UnverifiedScopesError) Error added in v0.46.0

func (e *UnverifiedScopesError) Error() string

Error implements error.

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