gitlab

package
v0.45.0 Latest Latest
Warning

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

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

Documentation

Overview

Package gitlab implements forge.Client for the GitLab REST API v4.

Index

Constants

This section is empty.

Variables

View Source
var URLEnvVars = []string{"FULLSEND_GITLAB_URL", "GITLAB_API_URL", "CI_SERVER_URL"}

URLEnvVars is the ordered list of environment variables consulted to resolve the GitLab instance URL. Precedence matches forge_client.go.

Functions

func ResolveForgeHostPort added in v0.38.0

func ResolveForgeHostPort() (host, port string)

ResolveForgeHostPort returns the GitLab forge hostname and port from environment variables. URL precedence matches forge_client.go: FULLSEND_GITLAB_URL > GITLAB_API_URL > CI_SERVER_URL. When the URL does not include an explicit port, the default is derived from the scheme ("80" for http, "443" otherwise). Returns ("", "") when no URL can be resolved.

Types

type APIError

type APIError struct {
	StatusCode int
	Message    string
}

APIError represents an error response from the GitLab API.

func (*APIError) Error

func (e *APIError) Error() string

func (*APIError) IsTransient added in v0.37.0

func (e *APIError) IsTransient() bool

IsTransient reports whether the API error represents a transient failure that may succeed on retry: server errors (500–504) and rate limits (429). This method satisfies the transientReporter interface used by forge.IsTransient.

func (*APIError) Unwrap

func (e *APIError) Unwrap() error

type LiveClient

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

LiveClient implements forge.Client for the GitLab REST API v4.

func New

func New(token string, opts ...Option) (*LiveClient, error)

New creates a new GitLab client with the given project access token. Returns an error if the configured base URL uses an insecure scheme for a non-loopback host.

func (*LiveClient) AddIssueCommentReaction added in v0.38.0

func (c *LiveClient) AddIssueCommentReaction(_ context.Context, _, _ string, _ int, _ string) (int64, error)

AddIssueCommentReaction is not yet implemented for GitLab. See AddIssueReaction.

func (*LiveClient) AddIssueLabels

func (c *LiveClient) AddIssueLabels(ctx context.Context, owner, repo string, number int, newLabels ...string) error

AddIssueLabels atomically appends labels to an existing issue using GitLab's add_labels parameter, avoiding the read-modify-write race of replacing the full label set.

func (*LiveClient) AddIssueReaction added in v0.38.0

func (c *LiveClient) AddIssueReaction(_ context.Context, _, _ string, _ int, _ string) (int64, error)

AddIssueReaction is not yet implemented for GitLab. GitLab has an equivalent "award emoji" API, but no caller currently exercises this path on GitLab, so it is left unimplemented rather than guessed at.

func (*LiveClient) BaseURL added in v0.37.0

func (c *LiveClient) BaseURL() string

BaseURL returns the configured base URL for the GitLab instance.

func (*LiveClient) CloseChangeProposal added in v0.33.0

func (c *LiveClient) CloseChangeProposal(ctx context.Context, owner, repo string, number int) error

CloseChangeProposal closes an open merge request without merging it.

func (*LiveClient) CloseIssue

func (c *LiveClient) CloseIssue(ctx context.Context, owner, repo string, number int) error

CloseIssue closes an issue by setting its state_event to "close".

func (*LiveClient) CommitFileToBranch added in v0.44.0

func (c *LiveClient) CommitFileToBranch(ctx context.Context, owner, repo, branch, path, message string, content []byte, expectedSHA string) error

CommitFileToBranch commits a single file to branch without force-re-root. expectedSHA is the branch tip observed at load time and is sent as start_sha so a concurrent writer surfaces forge.ErrNonFastForward instead of last-writer-wins. An empty expectedSHA means no branch was observed at load time (first write, or the branch was missing): the commit is still parented at the repository root via start_sha, but force is left unset so GitLab creates the branch rather than force-resetting it. If a concurrent writer created the branch first, GitLab reports it as already-exists, which is mapped to forge.ErrNonFastForward below so persistWithCAS reloads the new tip and retries instead of overwriting it. A non-empty expectedSHA means the branch is already known to exist; some GitLab editions (observed on self-hosted EE v19.2.7, see issue #7892) unconditionally reject start_sha for an already-existing branch even when it matches the current tip, so commitFilesImpl retries that case once without start_sha after confirming the live tip has not moved. The commit message is suffixed with [skip ci] when not already present.

func (*LiveClient) CommitFiles

func (c *LiveClient) CommitFiles(ctx context.Context, owner, repo, message string, files []forge.TreeFile) (bool, error)

CommitFiles atomically commits multiple files to the default branch via GitLab's Commits API. Returns (false, nil) when all files already match the current tree (idempotent).

func (*LiveClient) CommitFilesToBranch

func (c *LiveClient) CommitFilesToBranch(ctx context.Context, owner, repo, branch, message string, files []forge.TreeFile) (bool, error)

func (*LiveClient) CompareCommits added in v0.37.0

func (c *LiveClient) CompareCommits(ctx context.Context, owner, repo, base, head string) (string, error)

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

GitLab's compare endpoint is not symmetric — it only reports commits reachable from "to" but not from "from". A single forward call cannot distinguish "ahead" from "diverged" because both cases return non-empty commits. To resolve the ambiguity, a reverse comparison (from=head, to=base) is always made when the forward call returns any diffs or commits. When both directions have commits, the history has diverged.

func (*LiveClient) CreateBranch

func (c *LiveClient) CreateBranch(ctx context.Context, owner, repo, branchName string) error

func (*LiveClient) CreateBranchFromSHA added in v0.34.0

func (c *LiveClient) CreateBranchFromSHA(ctx context.Context, owner, repo, branchName, sha string) error

CreateBranchFromSHA creates a new branch pointing at the given commit SHA. GitLab's branch creation API accepts a commit SHA as the ref parameter. Returns forge.ErrAlreadyExists if the branch already exists.

func (*LiveClient) CreateChangeProposal

func (c *LiveClient) CreateChangeProposal(ctx context.Context, owner, repo, title, body, head, base string) (*forge.ChangeProposal, error)

CreateChangeProposal creates a merge request on GitLab.

func (*LiveClient) CreateCrossRepoChangeProposal added in v0.33.0

func (c *LiveClient) CreateCrossRepoChangeProposal(_ context.Context, _, _, _, _, _, _, _, _ string) (*forge.ChangeProposal, error)

CreateCrossRepoChangeProposal is not supported on GitLab. GitLab merge requests between forks use the same source_branch / target_branch API as same-repo MRs (the fork relationship is implicit in the project), so the cross-repo variant is unnecessary. Returns forge.ErrNotSupported.

func (*LiveClient) CreateFile

func (c *LiveClient) CreateFile(ctx context.Context, owner, repo, path, message string, content []byte) error

func (*LiveClient) CreateFileOnBranch

func (c *LiveClient) CreateFileOnBranch(ctx context.Context, owner, repo, branch, path, message string, content []byte) error

func (*LiveClient) CreateFork

func (c *LiveClient) CreateFork(ctx context.Context, owner, repo string) (string, string, error)

CreateFork is idempotent: if a fork already exists (409 Conflict), it returns the existing fork's metadata.

func (*LiveClient) CreateForkInOrg

func (c *LiveClient) CreateForkInOrg(ctx context.Context, owner, repo, org, forkName string) (string, error)

CreateForkInOrg creates a fork of the given repository under the specified GitLab group (namespace) with the given name.

func (*LiveClient) CreateIssue

func (c *LiveClient) CreateIssue(ctx context.Context, owner, repo, title, body string, labels ...string) (*forge.Issue, error)

CreateIssue creates a new issue on a GitLab project. Labels are sent as a comma-separated string per the GitLab API convention.

func (*LiveClient) CreateIssueComment

func (c *LiveClient) CreateIssueComment(ctx context.Context, owner, repo string, number int, body string) (*forge.IssueComment, error)

CreateIssueComment creates a new note on an issue or merge request.

func (*LiveClient) CreateOrUpdateFile

func (c *LiveClient) CreateOrUpdateFile(ctx context.Context, owner, repo, path, message string, content []byte) error

CreateOrUpdateFile tries a POST (create); on 400 "already exists" it falls back to PUT (update). GitLab's file API does not require a SHA for updates, unlike GitHub.

func (*LiveClient) CreateOrUpdateFileOnBranch

func (c *LiveClient) CreateOrUpdateFileOnBranch(ctx context.Context, owner, repo, branch, path, message string, content []byte) error

func (*LiveClient) CreateOrUpdateOrgVariable

func (c *LiveClient) CreateOrUpdateOrgVariable(_ context.Context, _, _, _ string, _ []int64) error

CreateOrUpdateOrgVariable is not supported on GitLab (per-repo mode).

func (*LiveClient) CreateOrUpdateOrgVariableAll

func (c *LiveClient) CreateOrUpdateOrgVariableAll(_ context.Context, _, _, _ string) error

CreateOrUpdateOrgVariableAll is not supported on GitLab (per-repo mode).

func (*LiveClient) CreateOrUpdateRepoVariable

func (c *LiveClient) CreateOrUpdateRepoVariable(ctx context.Context, owner, repo, name, value string) error

CreateOrUpdateRepoVariable creates a CI/CD variable, or updates it if it already exists. GitLab returns either 409 Conflict or 400 Bad Request with "has already been taken" for duplicate keys.

func (*LiveClient) CreateOrgSecret

func (c *LiveClient) CreateOrgSecret(_ context.Context, _, _, _ string, _ []int64) error

CreateOrgSecret is not supported on GitLab (per-repo mode).

func (*LiveClient) CreatePipeline added in v0.33.0

func (c *LiveClient) CreatePipeline(ctx context.Context, owner, repo, ref string, variables map[string]string) (*forge.Pipeline, error)

CreatePipeline creates a new pipeline on the given ref with the given variables via POST /projects/:id/pipeline. Returns the pipeline ID and web URL. Used by the cron-poller to dispatch agent stages directly.

func (*LiveClient) CreatePipelineSchedule

func (c *LiveClient) CreatePipelineSchedule(ctx context.Context, owner, repo, ref, description, cron string, variables map[string]string) (int64, error)

CreatePipelineSchedule creates a pipeline schedule and attaches variables. Returns the schedule ID.

func (*LiveClient) CreatePipelineTriggerToken added in v0.44.0

func (c *LiveClient) CreatePipelineTriggerToken(ctx context.Context, owner, repo, description string) (*forge.PipelineTriggerToken, error)

CreatePipelineTriggerToken mints a pipeline trigger token via POST /projects/:id/triggers. The token value is only returned here.

func (*LiveClient) CreatePipelineWithInputs added in v0.44.0

func (c *LiveClient) CreatePipelineWithInputs(ctx context.Context, owner, repo, ref string, inputs map[string]forge.PipelineInputValue) (*forge.Pipeline, error)

CreatePipelineWithInputs creates a new pipeline on the given ref using GitLab CI/CD Inputs (POST /projects/:id/pipeline with an "inputs" object) instead of the user-defined "variables" array CreatePipeline sends. This request never includes a "variables" field, so it remains usable when a project's ci_pipeline_variables_minimum_override_role is set to forge.PipelineVarOverrideNoOneAllowed — GitLab's variable-override gate does not govern pipeline inputs. See forge.PipelineInputValue for the supported value shapes.

func (*LiveClient) CreateProjectAccessToken added in v0.34.0

func (c *LiveClient) CreateProjectAccessToken(ctx context.Context, owner, repo, name string, scopes []string, accessLevel int, expiresAt string) (*ProjectAccessToken, error)

CreateProjectAccessToken creates a project access token with the given name, scopes, and access level. Returns the token (only available at creation time) and the token ID. accessLevel 30 = Developer, 40 = Maintainer.

func (*LiveClient) CreateProjectHook added in v0.44.0

func (c *LiveClient) CreateProjectHook(ctx context.Context, owner, repo string, hook forge.ProjectHook) (*forge.ProjectHook, error)

CreateProjectHook creates a project webhook via POST /projects/:id/hooks.

func (*LiveClient) CreateProtectedCIVariable

func (c *LiveClient) CreateProtectedCIVariable(ctx context.Context, owner, repo, name, value string) error

CreateProtectedCIVariable creates a branch-restricted, unmasked CI/CD variable. Values are visible in pipeline logs; use CreateRepoSecret for credentials.

func (*LiveClient) CreatePullRequestReview

func (c *LiveClient) CreatePullRequestReview(ctx context.Context, owner, repo string, number int, event, body, commitSHA string, comments []forge.ReviewComment) error

CreatePullRequestReview creates a review on a merge request.

GitLab has no native review object. This method synthesizes reviews:

  • APPROVE: POST /projects/:id/merge_requests/:iid/approve When commitSHA is non-empty, it is passed as the "sha" parameter so GitLab rejects the approval if HEAD has advanced (409 Conflict). GitLab rejects the approval outright when the authenticated user is the MR author (self-approval is blocked by default: merge_requests_author_approval=false), and fullsend's code and review agents share one bot PAT on GitLab, so that rejection is a certainty on bot-authored MRs, not a possible-but-rare outcome. The identity is checked before the call, and the call is skipped entirely in favor of posting a note that records the approve verdict. A post-hoc 401 handler remains as a safety net for edge cases (e.g., a future per-role PAT where the pre-call identity check doesn't apply but project settings still block approval). The sticky review comment remains the authoritative record either way.
  • REQUEST_CHANGES or COMMENT: POST a note with the review body, plus inline comments (see below). GitLab's Notes API has no commit-pinning parameter, so commitSHA cannot be enforced for the review-body note.

Inline comments with a line number are posted as positioned diff discussions (POST .../discussions) using the MR's current diff_refs. When commitSHA is non-empty, the discussion is only positioned if diff_refs.head_sha matches, so findings from an older revision are not attached to a newer diff. File-level comments (Line == 0), comments whose position cannot be resolved, and comments rejected by the Discussions API fall back to general MR notes with a `path:line` prefix — the same non-inline path used previously.

func (*LiveClient) CreateRepo

func (c *LiveClient) CreateRepo(ctx context.Context, org, name, description string, private bool) (*forge.Repository, error)

func (*LiveClient) CreateRepoSecret

func (c *LiveClient) CreateRepoSecret(ctx context.Context, owner, repo, name, value string) error

CreateRepoSecret creates or updates a protected, masked CI/CD variable (secret). If the value doesn't meet GitLab's masking requirements (min 8 chars, single line, restricted charset), the variable is stored unmasked. If the variable already exists, it is updated in place.

func (*LiveClient) DeleteBranch added in v0.44.0

func (c *LiveClient) DeleteBranch(ctx context.Context, owner, repo, branchName string) error

DeleteBranch deletes a git branch. Returns forge.ErrNotFound (wrapped) if the branch does not exist.

func (*LiveClient) DeleteFile

func (c *LiveClient) DeleteFile(ctx context.Context, owner, repo, path, message string) error

func (*LiveClient) DeleteFiles

func (c *LiveClient) DeleteFiles(ctx context.Context, owner, repo, message string, paths []string) (int, error)

func (*LiveClient) DeleteIssueComment

func (c *LiveClient) DeleteIssueComment(ctx context.Context, owner, repo string, commentID int) error

DeleteIssueComment deletes a note on an issue. See UpdateIssueComment for the note-lookup strategy.

func (*LiveClient) DeleteIssueCommentReaction added in v0.38.0

func (c *LiveClient) DeleteIssueCommentReaction(_ context.Context, _, _ string, _ int, _ int64) error

DeleteIssueCommentReaction is not yet implemented for GitLab. See AddIssueReaction.

func (*LiveClient) DeleteIssueReaction added in v0.38.0

func (c *LiveClient) DeleteIssueReaction(_ context.Context, _, _ string, _ int, _ int64) error

DeleteIssueReaction is not yet implemented for GitLab. See AddIssueReaction.

func (*LiveClient) DeleteOrgSecret

func (c *LiveClient) DeleteOrgSecret(_ context.Context, _, _ string) error

DeleteOrgSecret is not supported on GitLab (per-repo mode).

func (*LiveClient) DeleteOrgVariable

func (c *LiveClient) DeleteOrgVariable(_ context.Context, _, _ string) error

DeleteOrgVariable is not supported on GitLab (per-repo mode).

func (*LiveClient) DeletePipelineSchedule

func (c *LiveClient) DeletePipelineSchedule(ctx context.Context, owner, repo string, scheduleID int64) error

DeletePipelineSchedule deletes a pipeline schedule.

func (*LiveClient) DeleteProjectHook added in v0.44.0

func (c *LiveClient) DeleteProjectHook(ctx context.Context, owner, repo string, hookID int64) error

DeleteProjectHook deletes a project webhook via DELETE /projects/:id/hooks/:hook_id. Returns forge.ErrNotFound (wrapped) if the hook does not exist.

func (*LiveClient) DeleteRef added in v0.33.0

func (c *LiveClient) DeleteRef(ctx context.Context, owner, repo, refPath string) error

DeleteRef deletes a git ref via the GitLab Branches or Tags API. refPath must be in the form "heads/<branch>" or "tags/<tag>". Returns forge.ErrNotFound (wrapped) if the ref does not exist.

func (*LiveClient) DeleteRepo

func (c *LiveClient) DeleteRepo(ctx context.Context, owner, repo string) error

func (*LiveClient) DeleteRepoSecret

func (c *LiveClient) DeleteRepoSecret(ctx context.Context, owner, repo, name string) error

DeleteRepoSecret deletes a CI/CD variable (secret). It is idempotent: a 404 (variable already gone) is not treated as an error.

func (*LiveClient) DeleteRepoVariable

func (c *LiveClient) DeleteRepoVariable(ctx context.Context, owner, repo, name string) error

DeleteRepoVariable deletes a CI/CD variable. It is idempotent: a 404 (variable already gone) is not treated as an error.

func (*LiveClient) DismissPullRequestReview

func (c *LiveClient) DismissPullRequestReview(ctx context.Context, owner, repo string, number, reviewID int, message string) error

DismissPullRequestReview dismisses a review on a merge request.

On GitLab, if the review was an approval, this unapproves the MR. For non-approval reviews backed by a request-changes note, this edits the note to replace the request-changes marker with a dismissed marker so ListPullRequestReviews stops reporting it as CHANGES_REQUESTED.

func (*LiveClient) DispatchWorkflow

func (c *LiveClient) DispatchWorkflow(_ context.Context, _, _, _, _ string, _ map[string]string) error

DispatchWorkflow is not directly supported on GitLab — use CreatePipeline with variables instead (already implemented above).

func (*LiveClient) DownloadWorkflowRunArtifact

func (c *LiveClient) DownloadWorkflowRunArtifact(ctx context.Context, owner, repo string, artifactID int) ([]byte, error)

DownloadWorkflowRunArtifact downloads the artifact archive for a GitLab job (the artifactID is the job ID).

func (*LiveClient) FindExistingFork

func (c *LiveClient) FindExistingFork(ctx context.Context, owner, repo string) (string, string, error)

func (*LiveClient) ForceCommitFileToBranch added in v0.44.0

func (c *LiveClient) ForceCommitFileToBranch(ctx context.Context, owner, repo, branch, path, message string, content []byte) error

ForceCommitFileToBranch force-updates branch to a single-file commit re-rooted on the repository's root commit. The branch is created if it does not exist. Each call leaves the branch at base+1 commit (prior force-commits become unreachable). The commit message is suffixed with [skip ci] when not already present.

func (*LiveClient) GetAuthenticatedUser

func (c *LiveClient) GetAuthenticatedUser(ctx context.Context) (string, error)

GetAuthenticatedUser returns the username of the authenticated GitLab user.

func (*LiveClient) GetAuthenticatedUserIdentity

func (c *LiveClient) GetAuthenticatedUserIdentity(ctx context.Context) (*forge.UserIdentity, error)

GetAuthenticatedUserIdentity returns the display name and email of the authenticated GitLab user for Signed-off-by trailers.

When name is empty, the username is used as a fallback. When email is empty, a noreply address is constructed from the user's ID and username to avoid producing malformed Signed-off-by trailers.

func (*LiveClient) GetBranchRef

func (c *LiveClient) GetBranchRef(ctx context.Context, owner, repo, branch string) (string, error)

func (*LiveClient) GetFileContent

func (c *LiveClient) GetFileContent(ctx context.Context, owner, repo, path string) ([]byte, error)

func (*LiveClient) GetFileContentAtRef

func (c *LiveClient) GetFileContentAtRef(ctx context.Context, owner, repo, path, ref string) ([]byte, error)

func (*LiveClient) GetIssue

func (c *LiveClient) GetIssue(ctx context.Context, owner, repo string, number int) (*forge.Issue, error)

GetIssue returns an issue by its project-scoped IID.

func (*LiveClient) GetIssueComment added in v0.45.0

func (c *LiveClient) GetIssueComment(ctx context.Context, owner, repo string, commentID int) (*forge.IssueComment, error)

GetIssueComment fetches a single note by its numeric ID. See UpdateIssueComment for why this requires scanning: GitLab's Notes API requires the noteable IID in the URL, but forge.Client only provides a bare commentID. Returns forge.ErrNotFound (wrapped) if the note cannot be located within the same open+500/closed(+merged) scan bound documented on updateOrDeleteNote.

func (*LiveClient) GetLatestWorkflowRun

func (c *LiveClient) GetLatestWorkflowRun(ctx context.Context, owner, repo, workflowFile string) (*forge.WorkflowRun, error)

GetLatestWorkflowRun returns the newest pipeline for the project, optionally filtered by ref (workflowFile is treated as the ref name).

func (*LiveClient) GetNoteOnParent added in v0.45.0

func (c *LiveClient) GetNoteOnParent(ctx context.Context, owner, repo, parentType string, parentIID, noteID int) (*forge.IssueComment, error)

GetNoteOnParent fetches a note directly by its parent noteable's IID and the note's own ID (forge.GitLabExtensions). Unlike GetIssueComment, this never scans: the caller already knows the parent, so GitLab's Notes API can be addressed directly. parentType must be "issues" or "merge_requests".

func (*LiveClient) GetOrgPlan

func (c *LiveClient) GetOrgPlan(ctx context.Context, org string) (string, error)

GetOrgPlan returns the billing plan name for a GitLab namespace. Uses the Namespaces API where the plan field is documented, rather than the Groups API where it is undocumented and may be absent. Self-hosted instances typically return "default"; gitlab.com returns the SaaS tier name ("free", "premium", "ultimate", etc.).

func (*LiveClient) GetOrgSecretRepos

func (c *LiveClient) GetOrgSecretRepos(_ context.Context, _, _ string) ([]int64, error)

GetOrgSecretRepos is not supported on GitLab (per-repo mode).

func (*LiveClient) GetOrgVariable

func (c *LiveClient) GetOrgVariable(_ context.Context, _, _ string) (string, bool, error)

GetOrgVariable is not supported on GitLab (per-repo mode).

func (*LiveClient) GetOrgVariableRepos

func (c *LiveClient) GetOrgVariableRepos(_ context.Context, _, _ string) ([]int64, error)

GetOrgVariableRepos is not supported on GitLab (per-repo mode).

func (*LiveClient) GetPipelineVariablesMinimumOverrideRole added in v0.44.0

func (c *LiveClient) GetPipelineVariablesMinimumOverrideRole(ctx context.Context, owner, repo string) (string, error)

GetPipelineVariablesMinimumOverrideRole reads the GitLab project setting that gates who may pass user-defined pipeline variables. If GitLab's response omits ci_pipeline_variables_minimum_override_role (e.g. an older GitLab instance or an edition that doesn't expose the field), this returns ("", nil); callers cannot distinguish that from an explicitly empty role, since GitLab never populates the field with an empty string.

func (*LiveClient) GetProtectedBranch added in v0.44.0

func (c *LiveClient) GetProtectedBranch(ctx context.Context, owner, repo, branch string) (*forge.ProtectedBranchRule, error)

GetProtectedBranch returns push/merge access levels for a protected branch. A nil rule means the branch is not protected.

GitLab protects branches either by an exact-name rule or by one or more wildcard rules (e.g. "*", "main*") that match many branches at once, and CreatePipeline access is the most-permissive union across every rule matching the branch — not just the first one found. So this always checks both: the exact-name rule (if any) and every protected-branch rule whose wildcard pattern matches, then merges their access levels into a single synthetic rule. Merging keeps downstream checks (PollerCanCreatePipeline) correct when, for example, a Maintainer-only exact rule for the default branch coexists with a Developer-allowed wildcard rule, or multiple overlapping wildcards match the same branch.

func (*LiveClient) GetPullRequestHeadSHA

func (c *LiveClient) GetPullRequestHeadSHA(ctx context.Context, owner, repo string, number int) (string, error)

GetPullRequestHeadSHA returns the current HEAD commit SHA of a merge request.

func (*LiveClient) GetPullRequestInfo

func (c *LiveClient) GetPullRequestInfo(ctx context.Context, owner, repo string, number int) (*forge.PullRequestInfo, error)

GetPullRequestInfo returns branch and repo context for a merge request.

func (*LiveClient) GetRef

func (c *LiveClient) GetRef(ctx context.Context, owner, repo, refPath string) (string, error)

GetRef maps forge-style ref paths ("heads/main", "tags/v1") to GitLab commit lookups. GitLab's commits endpoint accepts branch names, tag names, and SHAs directly.

func (*LiveClient) GetRepo

func (c *LiveClient) GetRepo(ctx context.Context, owner, repo string) (*forge.Repository, error)

func (*LiveClient) GetRepoVariable

func (c *LiveClient) GetRepoVariable(ctx context.Context, owner, repo, name string) (string, bool, error)

GetRepoVariable returns the value of a CI/CD variable. Returns ("", false, nil) if the variable does not exist.

func (*LiveClient) GetTokenScopes

func (c *LiveClient) GetTokenScopes(_ context.Context) ([]string, error)

GetTokenScopes returns nil because GitLab does not expose token scopes via an API response header the way GitHub does.

func (*LiveClient) GetWorkflow

func (c *LiveClient) GetWorkflow(_ context.Context, _, _, _ string) (*forge.Workflow, error)

GetWorkflow is not supported on GitLab — GitLab CI configuration lives in .gitlab-ci.yml, not in individually addressable workflow objects.

func (*LiveClient) GetWorkflowRun

func (c *LiveClient) GetWorkflowRun(ctx context.Context, owner, repo string, runID int) (*forge.WorkflowRun, error)

GetWorkflowRun returns a single pipeline by ID, mapped to a WorkflowRun.

func (*LiveClient) GetWorkflowRunAnnotations

func (c *LiveClient) GetWorkflowRunAnnotations(_ context.Context, _, _ string, _ int) ([]forge.Annotation, error)

GetWorkflowRunAnnotations returns an empty slice — GitLab CI has no annotations concept equivalent to GitHub Actions check-run annotations.

func (*LiveClient) GetWorkflowRunLogs

func (c *LiveClient) GetWorkflowRunLogs(ctx context.Context, owner, repo string, runID int) (string, error)

GetWorkflowRunLogs concatenates the trace (log output) of all jobs in a pipeline, separated by headers.

func (*LiveClient) GrantProtectedBranchMergeUser added in v0.44.0

func (c *LiveClient) GrantProtectedBranchMergeUser(ctx context.Context, owner, repo, branch string, userID int) error

GrantProtectedBranchMergeUser adds userID to allowed_to_merge on the branch's exact-name protected-branch rule. No-op if the user already has merge or push access. Fails closed, without PATCHing anything, when the branch is only protected via a wildcard rule (e.g. "*", "main*") and has no exact-name rule of its own: a wildcard rule's access-level settings apply to every branch it matches, so PATCHing it to add the poller would grant merge access far beyond the single default branch this call is scoped to.

func (*LiveClient) IsEnterprise added in v0.34.0

func (c *LiveClient) IsEnterprise(ctx context.Context) bool

IsEnterprise checks the /metadata endpoint to determine if the GitLab instance is running Enterprise Edition. Self-hosted EE instances always have this set to true. Returns false on error or CE instances.

func (*LiveClient) IsInstallationToken

func (c *LiveClient) IsInstallationToken(_ context.Context) (bool, error)

IsInstallationToken returns false because GitLab has no App installation token concept.

func (*LiveClient) IsProtectedBranch

func (c *LiveClient) IsProtectedBranch(ctx context.Context, owner, repo, branch string) (bool, error)

IsProtectedBranch checks whether the given branch has protection rules. GitLab returns 200 if the branch is protected, 404 if not.

func (*LiveClient) ListDirectoryContents

func (c *LiveClient) ListDirectoryContents(ctx context.Context, owner, repo, path, ref string, recursive bool) ([]forge.DirectoryEntry, error)

func (*LiveClient) ListIssueComments

func (c *LiveClient) ListIssueComments(ctx context.Context, owner, repo string, number int) ([]forge.IssueComment, error)

ListIssueComments returns all notes on an issue or merge request, sorted ascending. GitLab calls comments "notes". The target type (issue vs MR) is controlled by WithNoteTarget.

func (*LiveClient) ListIssueReactions added in v0.38.0

func (c *LiveClient) ListIssueReactions(_ context.Context, _, _ string, _ int) ([]forge.Reaction, error)

ListIssueReactions is not yet implemented for GitLab. See AddIssueReaction.

func (*LiveClient) ListOpenIssues

func (c *LiveClient) ListOpenIssues(ctx context.Context, owner, repo string, labelFilter ...string) ([]forge.Issue, error)

ListOpenIssues returns open issues for a project, optionally filtered by labels. Paginates automatically until all matching issues are retrieved.

func (*LiveClient) ListOrgRepos

func (c *LiveClient) ListOrgRepos(ctx context.Context, org string, includePrivate bool) ([]forge.Repository, error)

func (*LiveClient) ListOrgVariables

func (c *LiveClient) ListOrgVariables(_ context.Context, _ string) ([]forge.OrgVariable, error)

ListOrgVariables is not supported on GitLab (per-repo mode).

func (*LiveClient) ListPipelineSchedules

func (c *LiveClient) ListPipelineSchedules(ctx context.Context, owner, repo string) ([]forge.PipelineSchedule, error)

ListPipelineSchedules returns all pipeline schedules for the project.

func (*LiveClient) ListPipelineTriggerTokens added in v0.44.0

func (c *LiveClient) ListPipelineTriggerTokens(ctx context.Context, owner, repo string) ([]forge.PipelineTriggerToken, error)

ListPipelineTriggerTokens lists pipeline trigger tokens via GET /projects/:id/triggers. Token values are omitted after creation.

func (*LiveClient) ListProjectAccessTokens added in v0.34.0

func (c *LiveClient) ListProjectAccessTokens(ctx context.Context, owner, repo string) ([]ProjectAccessToken, error)

ListProjectAccessTokens lists all project access tokens.

func (*LiveClient) ListProjectHooks added in v0.44.0

func (c *LiveClient) ListProjectHooks(ctx context.Context, owner, repo string) ([]forge.ProjectHook, error)

ListProjectHooks lists project webhooks via GET /projects/:id/hooks. The webhook secret token is never returned.

func (*LiveClient) ListPullRequestFileDiffs

func (c *LiveClient) ListPullRequestFileDiffs(ctx context.Context, owner, repo string, number int) ([]forge.PullRequestFileDiff, error)

ListPullRequestFileDiffs returns the files changed by a merge request along with their unified diff patches.

func (*LiveClient) ListPullRequestFiles

func (c *LiveClient) ListPullRequestFiles(ctx context.Context, owner, repo string, number int) ([]string, error)

ListPullRequestFiles returns the file paths changed by a merge request. GitLab returns diffs with old_path and new_path; we use new_path as the canonical path (matching rename destinations).

func (*LiveClient) ListPullRequestReviews

func (c *LiveClient) ListPullRequestReviews(ctx context.Context, owner, repo string, number int) ([]forge.PullRequestReview, error)

ListPullRequestReviews synthesizes reviews from GitLab's approval state and MR notes.

GitLab has no native review object. Approvals are mapped to APPROVED reviews (ID = approver's user ID), and MR notes are mapped to COMMENTED reviews (ID = note ID). DismissPullRequestReview relies on this convention to distinguish approvals from comments.

func (*LiveClient) ListRecentWorkflowRuns

func (c *LiveClient) ListRecentWorkflowRuns(ctx context.Context, owner, repo string, perPage int) ([]forge.WorkflowRun, error)

ListRecentWorkflowRuns lists the most recent pipelines regardless of ref.

func (*LiveClient) ListRepoPullRequests

func (c *LiveClient) ListRepoPullRequests(ctx context.Context, owner, repo string) ([]forge.ChangeProposal, error)

ListRepoPullRequests lists open merge requests for a project with pagination.

func (*LiveClient) ListRepoVariables

func (c *LiveClient) ListRepoVariables(ctx context.Context, owner, repo string) (map[string]string, error)

ListRepoVariables returns all CI/CD variables for a project as a key-to-value map. Results are paginated; the method follows pagination until all variables are fetched.

func (*LiveClient) ListRepositoryArtifacts

func (c *LiveClient) ListRepositoryArtifacts(ctx context.Context, owner, repo string, perPage int) ([]forge.RepositoryArtifact, error)

ListRepositoryArtifacts lists recent jobs that have artifacts across the project. Each job with artifacts is returned as a RepositoryArtifact with the job ID, name, creation time, and parent pipeline ID.

func (*LiveClient) ListRepositoryFiles

func (c *LiveClient) ListRepositoryFiles(ctx context.Context, owner, repo string) ([]string, error)

func (*LiveClient) ListResourceGroups added in v0.35.0

func (c *LiveClient) ListResourceGroups(ctx context.Context, owner, repo string) ([]ResourceGroup, error)

ListResourceGroups returns all resource groups for the project. Results are paginated; the method follows pagination until all groups are fetched.

func (*LiveClient) ListWorkflowRunArtifacts

func (c *LiveClient) ListWorkflowRunArtifacts(ctx context.Context, owner, repo string, runID int) ([]forge.WorkflowArtifact, error)

ListWorkflowRunArtifacts lists the artifacts produced by a pipeline's jobs. GitLab artifacts are per-job; this method enumerates all jobs and returns one WorkflowArtifact per job that has artifacts.

func (*LiveClient) ListWorkflowRunJobs added in v0.34.0

func (c *LiveClient) ListWorkflowRunJobs(ctx context.Context, owner, repo string, runID int) ([]forge.WorkflowJob, error)

ListWorkflowRunJobs lists the jobs for a given pipeline, mapped to WorkflowJob.

func (*LiveClient) ListWorkflowRuns

func (c *LiveClient) ListWorkflowRuns(ctx context.Context, owner, repo, workflowFile string) ([]forge.WorkflowRun, error)

ListWorkflowRuns lists recent pipelines, optionally filtered by ref (workflowFile is treated as the ref name). Returns up to 100 pipelines.

func (*LiveClient) ListWorkflowRunsSince added in v0.45.0

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

ListWorkflowRunsSince lists pipelines for workflowFile (treated as the ref name, as in ListWorkflowRuns), paginating through as many 100-per-page requests as needed to reach pipelines created at or after since instead of ListWorkflowRuns's single page. Pipelines are requested newest-first, so once a page's pipeline was created before since (or a short page signals the end of the listing), earlier pages cannot contain anything newer and pagination stops (#7996 review — mirrors the GitHub driver's fix for earliest-round selection truncation). It also stops once GitLab's X-Next-Page response header is empty, the same signal ListWorkflowRunJobs already honors, so a final page containing exactly perPage pipelines does not trigger one more, empty, page request (#7996 review).

func (*LiveClient) MergeChangeProposal

func (c *LiveClient) MergeChangeProposal(ctx context.Context, owner, repo string, number int) error

MergeChangeProposal merges a merge request by its IID.

func (*LiveClient) MinimizeComment

func (c *LiveClient) MinimizeComment(_ context.Context, _, _ string) error

MinimizeComment is not supported on GitLab -- there is no equivalent concept of hiding/minimizing individual comments.

func (*LiveClient) OrgSecretExists

func (c *LiveClient) OrgSecretExists(_ context.Context, _, _ string) (bool, error)

OrgSecretExists is not supported on GitLab (per-repo mode).

func (*LiveClient) OrgVariableExists

func (c *LiveClient) OrgVariableExists(_ context.Context, _, _ string) (bool, error)

OrgVariableExists is not supported on GitLab (per-repo mode).

func (*LiveClient) RepoSecretExists

func (c *LiveClient) RepoSecretExists(ctx context.Context, owner, repo, name string) (bool, error)

RepoSecretExists checks whether a CI/CD variable (secret) exists.

func (*LiveClient) RepoVariableExists

func (c *LiveClient) RepoVariableExists(ctx context.Context, owner, repo, name string) (bool, error)

RepoVariableExists checks whether a CI/CD variable exists.

func (*LiveClient) RevokePipelineTriggerToken added in v0.44.0

func (c *LiveClient) RevokePipelineTriggerToken(ctx context.Context, owner, repo string, tokenID int64) error

RevokePipelineTriggerToken deletes a pipeline trigger token by ID via DELETE /projects/:id/triggers/:trigger_id. Returns forge.ErrNotFound (wrapped) if the token does not exist.

func (*LiveClient) RevokeProjectAccessToken added in v0.34.0

func (c *LiveClient) RevokeProjectAccessToken(ctx context.Context, owner, repo string, tokenID int) error

RevokeProjectAccessToken revokes (deletes) a project access token by ID.

func (*LiveClient) SetOrgSecretRepos

func (c *LiveClient) SetOrgSecretRepos(_ context.Context, _, _ string, _ []int64) error

SetOrgSecretRepos is not supported on GitLab (per-repo mode).

func (*LiveClient) SetOrgVariableRepos

func (c *LiveClient) SetOrgVariableRepos(_ context.Context, _, _ string, _ []int64) error

SetOrgVariableRepos is not supported on GitLab (per-repo mode).

func (*LiveClient) SetPipelineVariablesMinimumOverrideRole added in v0.44.0

func (c *LiveClient) SetPipelineVariablesMinimumOverrideRole(ctx context.Context, owner, repo, role string) error

SetPipelineVariablesMinimumOverrideRole updates the GitLab project setting that gates who may pass user-defined pipeline variables. role must be one of the documented forge.PipelineVarOverride* constants; anything else is rejected before issuing the request.

func (*LiveClient) UpdateCIVariable

func (c *LiveClient) UpdateCIVariable(ctx context.Context, owner, repo, name, value string, protected bool) error

UpdateCIVariable upserts a CI/CD variable (update if exists, create if not).

func (*LiveClient) UpdateIssueComment

func (c *LiveClient) UpdateIssueComment(ctx context.Context, owner, repo string, commentID int, body string) error

UpdateIssueComment updates the body of an existing note on an issue. GitLab's note API requires the issue IID in the URL path, but the forge.Client interface only provides the note ID. Since GitLab has no endpoint to look up a note by ID alone, we scan recent issues (open then closed) to locate the note. In practice, this is always called shortly after ListIssueComments or CreateIssueComment on the same issue.

func (*LiveClient) UpdateNoteOnParent added in v0.45.0

func (c *LiveClient) UpdateNoteOnParent(ctx context.Context, owner, repo, parentType string, parentIID, noteID int, body string) error

UpdateNoteOnParent updates a note's body directly by its parent noteable's IID and the note's own ID (forge.GitLabExtensions). Unlike UpdateIssueComment, this never scans: the caller already knows the parent, so GitLab's Notes API can be addressed directly. parentType must be "issues" or "merge_requests".

func (*LiveClient) UpdatePipelineSchedule added in v0.44.0

func (c *LiveClient) UpdatePipelineSchedule(ctx context.Context, owner, repo string, scheduleID int64, active bool) error

UpdatePipelineSchedule sets whether a pipeline schedule is active.

func (*LiveClient) UpdateProjectHook added in v0.44.0

func (c *LiveClient) UpdateProjectHook(ctx context.Context, owner, repo string, hookID int64, hook forge.ProjectHook) (*forge.ProjectHook, error)

UpdateProjectHook updates a project webhook via PUT /projects/:id/hooks/:hook_id. This is a full replace: hookToGitLabBody serializes every field on hook, including zero-value event flags, so any flag the caller omits from hook is cleared on GitLab rather than left unchanged. Returns forge.ErrNotFound (wrapped) if the hook does not exist.

func (*LiveClient) UpdatePullRequestBranch

func (c *LiveClient) UpdatePullRequestBranch(ctx context.Context, owner, repo string, number int) error

UpdatePullRequestBranch rebases a merge request's source branch onto the target branch. GitLab uses rebase rather than merge-base-into-head. The rebase may be asynchronous; we fire the request and return without waiting for completion.

func (*LiveClient) UpdateRepoVisibility added in v0.33.0

func (c *LiveClient) UpdateRepoVisibility(ctx context.Context, owner, repo string, private bool) error

func (*LiveClient) UpdateResourceGroupProcessMode added in v0.35.0

func (c *LiveClient) UpdateResourceGroupProcessMode(ctx context.Context, owner, repo, key, processMode string) error

UpdateResourceGroupProcessMode sets the process_mode for a resource group. Valid modes are "unordered", "oldest_first", and "newest_first".

type Option

type Option func(*LiveClient)

Option configures the GitLab client.

func WithAfterFunc added in v0.37.0

func WithAfterFunc(f func(time.Duration) <-chan time.Time) Option

WithAfterFunc replaces the default time.After used for retry delays. Tests can inject an immediate-return function to avoid real sleeps.

func WithBaseURL

func WithBaseURL(rawURL string) Option

WithBaseURL sets a custom base URL for self-hosted GitLab instances. Non-https schemes are only allowed for loopback addresses (localhost, 127.0.0.1) to support test servers; other http:// URLs are rejected to prevent sending the PRIVATE-TOKEN header in cleartext.

func WithNoteTarget added in v0.34.0

func WithNoteTarget(target string) Option

WithNoteTarget configures which GitLab noteable type the comment methods (CreateIssueComment, ListIssueComments, UpdateIssueComment, DeleteIssueComment) operate on. Valid values are "issues" (default) and "merge_requests". GitLab uses separate API endpoints for issue notes vs MR notes; this option selects the correct one.

type PollClient added in v0.33.0

type PollClient struct {
	*LiveClient
}

PollClient wraps a LiveClient to satisfy poll.GitLabClient.

A separate type is needed because poll.GitLabClient.GetIssue returns *poll.Issue while forge.Client.GetIssue returns *forge.Issue. Go does not allow two methods with the same name and different return types on a single struct, so PollClient shadows GetIssue with the poll-specific version and inherits the remaining methods (ForceCommitFileToBranch, CommitFileToBranch, GetBranchRef, GetFileContentAtRef, DeleteRef, GetAuthenticatedUser) from the embedded LiveClient.

func NewPollClient added in v0.33.0

func NewPollClient(c *LiveClient) *PollClient

NewPollClient wraps a LiveClient for use with the cron poller.

func (*PollClient) CreateNoteAwardEmoji added in v0.33.0

func (pc *PollClient) CreateNoteAwardEmoji(ctx context.Context, owner, repo string, noteableType string, noteableIID, noteID int, emoji string) error

CreateNoteAwardEmoji adds an emoji reaction to a note. noteableType must be "Issue" or "MergeRequest" to select the correct API path.

func (*PollClient) CreatePipeline added in v0.33.0

func (pc *PollClient) CreatePipeline(ctx context.Context, owner, repo, ref string, variables map[string]string) (int64, string, error)

CreatePipeline creates a new pipeline on the given ref with the given variables. Returns the pipeline ID and web URL.

func (*PollClient) GetAuthenticatedUserID added in v0.33.0

func (pc *PollClient) GetAuthenticatedUserID(ctx context.Context) (int, error)

GetAuthenticatedUserID returns the numeric user ID of the authenticated GitLab user. Used by the CLI to set the bot user ID for event filtering.

func (*PollClient) GetCIVariable added in v0.33.0

func (pc *PollClient) GetCIVariable(ctx context.Context, owner, repo, name string) (string, error)

GetCIVariable returns the value of a CI/CD variable by key.

func (*PollClient) GetIssue added in v0.33.0

func (pc *PollClient) GetIssue(ctx context.Context, owner, repo string, issueIID int) (*poll.Issue, error)

GetIssue returns a single issue by its project-scoped IID. This method shadows LiveClient.GetIssue to return *poll.Issue instead of *forge.Issue.

func (*PollClient) GetMemberAccessLevel added in v0.33.0

func (pc *PollClient) GetMemberAccessLevel(ctx context.Context, owner, repo string, userID int) (int, error)

GetMemberAccessLevel returns the access level for a project member. Uses the /members/all/:user_id endpoint to include inherited group-level membership.

func (*PollClient) GetMergeRequest added in v0.33.0

func (pc *PollClient) GetMergeRequest(ctx context.Context, owner, repo string, mrIID int) (*poll.MergeRequest, error)

GetMergeRequest returns a single merge request by its project-scoped IID.

func (*PollClient) GetProjectPath added in v0.33.0

func (pc *PollClient) GetProjectPath(ctx context.Context, projectID int) (string, error)

GetProjectPath returns the path_with_namespace for a project by its numeric ID.

func (*PollClient) ListIssueNotes added in v0.33.0

func (pc *PollClient) ListIssueNotes(ctx context.Context, owner, repo string, issueIID int) ([]poll.Note, error)

ListIssueNotes returns all notes on the given issue in ascending created_at order.

func (*PollClient) ListIssuesUpdatedSince added in v0.33.0

func (pc *PollClient) ListIssuesUpdatedSince(ctx context.Context, owner, repo string, since time.Time) ([]poll.Issue, error)

ListIssuesUpdatedSince returns all project issues updated after the given timestamp. Results are paginated; all pages are fetched.

func (*PollClient) ListMergeRequestNotes added in v0.33.0

func (pc *PollClient) ListMergeRequestNotes(ctx context.Context, owner, repo string, mrIID int) ([]poll.Note, error)

ListMergeRequestNotes returns all notes on the given merge request in ascending created_at order.

func (*PollClient) ListMergeRequestsUpdatedSince added in v0.33.0

func (pc *PollClient) ListMergeRequestsUpdatedSince(ctx context.Context, owner, repo string, since time.Time) ([]poll.MergeRequest, error)

ListMergeRequestsUpdatedSince returns all project merge requests updated after the given timestamp. Results are paginated.

func (*PollClient) ListProjectEvents added in v0.33.0

func (pc *PollClient) ListProjectEvents(ctx context.Context, owner, repo string, targetType string, after time.Time) ([]poll.ProjectEvent, error)

ListProjectEvents returns project events matching the given target type (e.g. "note") created after the given timestamp. The GitLab Events API "after" parameter is date-only (ISO 8601, exclusive), so we widen the window by one day and filter client-side.

func (*PollClient) ListResourceLabelEvents added in v0.33.0

func (pc *PollClient) ListResourceLabelEvents(ctx context.Context, owner, repo string, issueIID int) ([]poll.ResourceLabelEvent, error)

ListResourceLabelEvents returns all resource label events for the given issue in ascending ID order.

type ProjectAccessToken added in v0.34.0

type ProjectAccessToken struct {
	ID        int    `json:"id"`
	Name      string `json:"name"`
	Active    bool   `json:"active"`
	Token     string `json:"token"`
	ExpiresAt string `json:"expires_at,omitempty"`
	Revoked   bool   `json:"revoked,omitempty"`
	UserID    int    `json:"user_id,omitempty"`
}

ProjectAccessToken represents a GitLab project access token.

type ResourceGroup added in v0.35.0

type ResourceGroup struct {
	Key         string `json:"key"`
	ProcessMode string `json:"process_mode"`
}

ResourceGroup represents a GitLab project resource group.

Jump to

Keyboard shortcuts

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