gitlab

package
v0.32.0 Latest Latest
Warning

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

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

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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

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

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

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) 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) 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).
  • REQUEST_CHANGES or COMMENT: POST a note with the review body, plus individual notes for each inline comment. GitLab's Notes API has no commit-pinning parameter, so commitSHA cannot be enforced for these events.

Inline comments are posted as plain MR notes with file:line in the body text, not as positioned diff comments. GitLab's Discussions API supports positioned comments but requires base/head/start SHAs that are not available through the forge.Client interface.

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) 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) 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) 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 supported on GitLab (GitHub Actions concept).

func (*LiveClient) DownloadWorkflowRunArtifact 

func (c *LiveClient) DownloadWorkflowRunArtifact(_ context.Context, _, _ string, _ int) ([]byte, error)

DownloadWorkflowRunArtifact is not supported on GitLab (GitHub Actions concept).

func (*LiveClient) FindExistingFork 

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

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

func (c *LiveClient) GetLatestWorkflowRun(_ context.Context, _, _, _ string) (*forge.WorkflowRun, error)

GetLatestWorkflowRun is not supported on GitLab (GitHub Actions concept).

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. Returns "free" if the plan field is empty.

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) 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 (GitHub Actions concept).

func (*LiveClient) GetWorkflowRun 

func (c *LiveClient) GetWorkflowRun(_ context.Context, _, _ string, _ int) (*forge.WorkflowRun, error)

GetWorkflowRun is not supported on GitLab (GitHub Actions concept).

func (*LiveClient) GetWorkflowRunAnnotations 

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

GetWorkflowRunAnnotations is not supported on GitLab (GitHub Actions concept).

func (*LiveClient) GetWorkflowRunLogs 

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

GetWorkflowRunLogs is not supported on GitLab (GitHub Actions concept).

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, sorted ascending. GitLab calls issue comments "notes".

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) ([]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) 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(_ context.Context, _, _ string, _ int) ([]forge.WorkflowRun, error)

ListRecentWorkflowRuns is not supported on GitLab (GitHub Actions concept).

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(_ context.Context, _, _ string, _ int) ([]forge.RepositoryArtifact, error)

ListRepositoryArtifacts is not supported on GitLab (GitHub Actions concept).

func (*LiveClient) ListRepositoryFiles 

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

func (*LiveClient) ListWorkflowRunArtifacts 

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

ListWorkflowRunArtifacts is not supported on GitLab (GitHub Actions concept).

func (*LiveClient) ListWorkflowRuns 

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

ListWorkflowRuns is not supported on GitLab (GitHub Actions concept).

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

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

UpdateCIVariable updates an existing CI/CD variable's value and protected flag.

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

type Option 

type Option func(*LiveClient)

Option configures the GitLab client.

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

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