Help us shape the future of Go! Take the 2026 Go Developer Survey

gapi

package
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: Sep 28, 2026 License: Apache-2.0 Imports: 30 Imported by: 0

Documentation

Overview

Package gapi is the raw REST client for GitLab's API v4.

Raw, because CLAUDE.md rule 13 forbids a client library. Every request goes through Client.do, which owns the rules that must hold for every call: the token goes only to the configured instance and no redirect is followed (§11); a write never runs under a dry run; every call is charged to the per-instance rate model; only what cannot apply twice is retried, and a create never is (§4.5); and every failure comes back as a classified *Error whose text carries no URL, path or query.

Index

Constants

View Source 
const (
	DefaultHeaderTimeout = 60 * time.Second
	DefaultMaxAttempts   = 4
)

Defaults for Options.

View Source 
const (
	DefaultPerPage = 20
	MaxPerPage     = 100
)

DefaultPerPage and MaxPerPage are GitLab's own.

View Source 
const (
	DefaultRequestsPerMinute = 2000
	DefaultNotesPerMinute    = 60
	DefaultConcurrency       = 4
)

Defaults of the rate model (§11). gitlab.com allows 2,000 authenticated API requests a minute per user and 60 notes a minute.

View Source 
const MaxResponseBytes = 32 << 20

MaxResponseBytes bounds one response body (§11).

View Source 
const MaxTraceRange = 500 << 10

MaxTraceRange is the most bytes one ranged read of a job's log may ask for: GitLab refuses a larger byte_limit with 400 (Gitlab::Ci::Trace::Stream::LIMIT_SIZE; spike O).

View Source 
const PipelineVariablesRefused = "the project lets only roles above yours set pipeline variables (Settings, CI/CD, Variables: " +
	"the minimum role to use pipeline variables). Run it without variables, or ask a maintainer"

PipelineVariablesRefused says why GitLab refuses variables from an account and what to do, for every refusal of them.

Variables

View Source 
var Classes = []Class{
	ClassInvalid, ClassNotFound, ClassAuth, ClassForbidden,
	ClassConflict, ClassStale, ClassAmbiguous, ClassBlocked,
	ClassRateLimited, ClassUnavailable, ClassUnsupported,
	ClassAmbiguousOutcome, ClassUnexpected,
}

Classes is the vocabulary, in the order §6.5 tabulates it.

View Source 
var ErrDryRunWrite = errors.New("gapi: a write was attempted under a dry run")

ErrDryRunWrite is the cause of a write refused under WithDryRun. Reaching it is a bug in this server, never something a caller did.

Functions

func DecodeToken 

func DecodeToken(s, binding string, position any) error

DecodeToken reads a token EncodeToken made into position. It refuses [invalid] a token it cannot read, and one bound to another query.

func EncodeToken 

func EncodeToken(binding string, position any) string

EncodeToken makes an opaque page token carrying position, bound to the query binding names. A listing this server pages itself uses it too, so every page_token has one shape and one set of refusals.

func IsClass 

func IsClass(err error, c Class) bool

IsClass reports whether err carries class c.

func IsDryRun 

func IsDryRun(ctx context.Context) bool

IsDryRun reports whether ctx refuses writes.

func Requests 

func Requests(ctx context.Context) int

Requests is how many HTTP requests were made under ctx.

func WithCall 

func WithCall(ctx context.Context) context.Context

WithCall returns a context that counts the requests made under it, remembers project paths resolved to ids, and records moved projects. The server installs one per tool call, so the log line reports what GitLab was actually asked, retries included, and two calls in flight do not share state.

func WithDryRun 

func WithDryRun(ctx context.Context) context.Context

WithDryRun returns a context under which the client refuses every write, before anything reaches the network.

It is what dry_run is (CLAUDE.md rule 14). A tool still shapes its own preview, but the guarantee that a preview changes nothing is kept here, where every request passes, so a handler that forgets its preview branch fails loudly instead of writing.

func WithoutURL 

func WithoutURL(err error) error

WithoutURL strips the request URL, and the host names and addresses, from a transport error. net/http wraps every transport failure in a *url.Error whose text renders the whole URL, and a path or a search travels in it (§9.2); net and crypto/x509 name hosts. The result keeps the cause for errors.As and prints it with redact.NetError. nil stays nil.

Types

type Bucket 

type Bucket int

Bucket names a known application limit with a bucket of its own. 

const (
	// BucketGeneral is the instance-wide bucket every call is charged to.
	BucketGeneral Bucket = iota
	// BucketNotes is note creation: 60 a minute on gitlab.com (§2.13).
	BucketNotes
)

func (Bucket) String 

func (b Bucket) String() string

type Call 

type Call struct {
	// Method is the HTTP verb. It decides whether the call writes and
	// whether it may be repeated.
	Method string
	// Path is a template under the API root, written in this package and
	// never taken from a caller. Each {} is filled, in order, by one
	// element of Args, escaped as a single path segment exactly once.
	Path string
	// Args fill Path's placeholders. They are caller-supplied: ids, full
	// paths, file paths, refs.
	Args []string
	// Query is the query string. It may carry a search term, so it never
	// reaches a log or an error message.
	Query url.Values
	// Body is marshaled as JSON when not nil.
	Body any
	// Root is where Path starts. The zero value is the API root.
	Root Root
	// Repeatable is the reason a POST may be sent twice without applying
	// twice, such as "marking a todo done twice leaves it done". Empty
	// means the method decides: GET, PUT and DELETE repeat, POST does
	// not. A create is never declared repeatable (§4.5).
	Repeatable string
	// ReadOnly is the reason a POST changes nothing, such as "linting
	// creates nothing". Such a call may repeat and may run under a dry
	// run, and `scripts/gates outcomes` asks it for no outcome. Empty
	// means the method decides.
	ReadOnly string
	// Witness names the witness this write carries ("sha"). A 409 on a
	// call with a witness means the witness moved, so it is stale rather
	// than a conflict (§4.6).
	Witness string
	// UnmodifiedSince is sent as If-Unmodified-Since when set. GitLab's
	// conditional deletes answer 412 when the resource changed after it,
	// which is [stale] (§4.6).
	UnmodifiedSince time.Time
	// Bucket is the rate bucket the call is charged to, beyond the
	// instance's own. The zero value is the general bucket only.
	Bucket Bucket
	// Name is a short label for logs and messages, "get_issue". Never a
	// path.
	Name string
}

Call is one request to GitLab.

Every call site builds one as a composite literal whose Method and Path are literals: "GET", "projects/{}/issues/{}". `scripts/gates api-coverage` reads those pairs from this package's syntax tree and binds each to an operation of the OpenAPI snapshot, so a call nobody judged fails the build. Do not compute Method or Path.

type Class 

type Class string

Class is the closed error vocabulary of docs/architecture.md §6.5.

Closed means both directions, and `scripts/gates classes` asserts both: every class the code emits is in Classes, and every class in Classes is emitted somewhere. 

const (
	// ClassInvalid: malformed or under-specified arguments, or too large.
	ClassInvalid Class = "invalid"
	// ClassNotFound: no such resource, or the token cannot see it. GitLab
	// answers 404 for a private project, so the message always says both.
	ClassNotFound Class = "not_found"
	// ClassAuth: not signed in, the token expired or was revoked, or a
	// scope is missing. The caller runs login.
	ClassAuth Class = "auth"
	// ClassForbidden: signed in, but the role or a project rule refuses.
	ClassForbidden Class = "forbidden"
	// ClassConflict: the state refuses it — a branch exists, a merge
	// request is already open, not mergeable.
	ClassConflict Class = "conflict"
	// ClassStale: the witness moved since it was read (§4.6). Kept apart
	// from conflict because it asks for a re-read.
	ClassStale Class = "stale"
	// ClassAmbiguous: a name matched more than one thing.
	ClassAmbiguous Class = "ambiguous"
	// ClassBlocked: a guard refused what the API would have allowed.
	ClassBlocked Class = "blocked"
	// ClassRateLimited: an instance or application limit (§2.13).
	ClassRateLimited Class = "rate_limited"
	// ClassUnavailable: a transient upstream failure.
	ClassUnavailable Class = "unavailable"
	// ClassUnsupported: the account's tier or edition lacks the route, or
	// the API cannot do this.
	ClassUnsupported Class = "unsupported"
	// ClassAmbiguousOutcome: a create may or may not have happened (§4.5).
	// Never retried.
	ClassAmbiguousOutcome Class = "ambiguous_outcome"
	// ClassUnexpected: anything unclassified.
	ClassUnexpected Class = "unexpected"
)

The thirteen classes. The standard names six; the other seven are forced by this API and each is argued in §6.5.

func ClassOf 

func ClassOf(err error) (Class, bool)

ClassOf returns the class of err, and whether it carried one. An instance or URL error from package instance is invalid.

func (Class) Retryable 

func (c Class) Retryable() bool

Retryable reports whether a failure of this class may clear by trying again unchanged. stale needs a re-read and ambiguous_outcome needs a look, so neither is.

func (Class) Valid 

func (c Class) Valid() bool

Valid reports whether c is in the vocabulary.

type Client 

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

Client calls one GitLab instance.

func New 

func New(o Options) (*Client, error)

New builds a Client.

func (*Client) ApproveMergeRequest 

func (c *Client) ApproveMergeRequest(ctx context.Context, p Project, iid int64, sha string) (*gitlab.Approvals, error)

ApproveMergeRequest approves at the head sha. GitLab answers 409 when the head moved, and 401 when the account may not approve or already has.

func (*Client) Blame 

func (c *Client) Blame(ctx context.Context, p Project, path, ref string, start, end int) ([]gitlab.BlameRange, error)

Blame reads who last changed each line of a file at a ref, from line start to line end when both are set.

func (*Client) CancelPipeline 

func (c *Client) CancelPipeline(ctx context.Context, p Project, id int64) (*gitlab.PipelineDetail, error)

CancelPipeline cancels a pipeline's jobs. GitLab answers with the pipeline whether or not anything could be canceled.

func (*Client) CherryPick 

func (c *Client) CherryPick(ctx context.Context, p Project, sha, branch, message string, dryRun bool) (*gitlab.Commit, error)

CherryPick applies a commit to a branch as a new commit. With dryRun GitLab commits nothing and only says whether it would apply.

func (*Client) Compare 

func (c *Client) Compare(ctx context.Context, p Project, from, to string, straight bool) (*gitlab.Compare, error)

Compare compares two refs. Without straight, GitLab compares from the merge base, as a merge request would.

func (*Client) CreateBranch 

func (c *Client) CreateBranch(ctx context.Context, p Project, branch, ref string) (*gitlab.Branch, error)

CreateBranch creates a branch at ref. GitLab refuses a name that exists, which guards this create itself (§2.11), but a retry after a lost answer would still read as that refusal, so it is not repeated.

func (*Client) CreateCommit 

func (c *Client) CreateCommit(ctx context.Context, p Project, in CommitCreate) (*gitlab.Commit, error)

CreateCommit commits the actions to a branch.

func (*Client) CreateDraftNote 

func (c *Client) CreateDraftNote(ctx context.Context, p Project, iid int64, in DraftCreate) (*gitlab.DraftNote, error)

CreateDraftNote adds an unpublished review comment.

func (*Client) CreateIssue 

func (c *Client) CreateIssue(ctx context.Context, p Project, in IssueCreate) (*gitlab.Issue, error)

CreateIssue creates an issue.

func (*Client) CreateIssueDiscussion 

func (c *Client) CreateIssueDiscussion(ctx context.Context, p Project, iid int64, body string) (*gitlab.Discussion, error)

CreateIssueDiscussion starts a resolvable thread on an issue. 

func (c *Client) CreateIssueLink(ctx context.Context, p Project, iid int64, in IssueLinkCreate) (*gitlab.IssueLink, error)

CreateIssueLink links two issues. It is never repeated.

func (*Client) CreateIssueNote 

func (c *Client) CreateIssueNote(ctx context.Context, p Project, iid int64, body string) (*gitlab.Note, error)

CreateIssueNote comments on an issue.

func (*Client) CreateLabel 

func (c *Client) CreateLabel(ctx context.Context, p Project, in LabelCreate) (*gitlab.Label, error)

CreateLabel creates a project label. It is never repeated.

func (*Client) CreateMergeRequest 

func (c *Client) CreateMergeRequest(ctx context.Context, p Project, in MergeRequestCreate) (*gitlab.MergeRequest, error)

CreateMergeRequest opens a merge request. GitLab refuses a second open one for the same branches with 409, which guards this create itself.

func (*Client) CreateMergeRequestDiscussion 

func (c *Client) CreateMergeRequestDiscussion(ctx context.Context, p Project, iid int64, body string, pos *diffpos.Position) (*gitlab.Discussion, error)

CreateMergeRequestDiscussion starts a thread on a merge request, on a line of its diff when pos is not nil.

func (*Client) CreateMergeRequestNote 

func (c *Client) CreateMergeRequestNote(ctx context.Context, p Project, iid int64, body string) (*gitlab.Note, error)

CreateMergeRequestNote comments on a merge request.

func (*Client) CreateMilestone 

func (c *Client) CreateMilestone(ctx context.Context, p Project, in MilestoneCreate) (*gitlab.ProjectMilestone, error)

CreateMilestone creates a project milestone. It is never repeated.

func (*Client) CreatePipeline 

func (c *Client) CreatePipeline(ctx context.Context, p Project, in PipelineCreate) (*gitlab.PipelineDetail, error)

CreatePipeline runs a pipeline for a ref. It creates one, so it is not repeated (§4.5).

func (*Client) CreateProjectSnippet 

func (c *Client) CreateProjectSnippet(ctx context.Context, p Project, in SnippetCreate) (*gitlab.Snippet, error)

CreateProjectSnippet creates a snippet in a project. It is not repeated.

func (*Client) CreateRelease 

func (c *Client) CreateRelease(ctx context.Context, p Project, in ReleaseCreate) (*gitlab.Release, error)

CreateRelease creates a release, and its tag at ref when the tag does not exist. GitLab refuses a second release of a tag with 409. It is not repeated.

func (*Client) CreateSnippet 

func (c *Client) CreateSnippet(ctx context.Context, in SnippetCreate) (*gitlab.Snippet, error)

CreateSnippet creates a personal snippet. It is not repeated.

func (*Client) CreateTag 

func (c *Client) CreateTag(ctx context.Context, p Project, name, ref, message string) (*gitlab.Tag, error)

CreateTag creates a tag at a ref. It is never repeated.

func (*Client) CreateWikiPage 

func (c *Client) CreateWikiPage(ctx context.Context, p Project, in WikiPageCreate) (*gitlab.WikiPage, error)

CreateWikiPage creates a page. GitLab refuses a title that exists.

func (*Client) DeleteBranch 

func (c *Client) DeleteBranch(ctx context.Context, p Project, branch string) error

DeleteBranch deletes a branch. GitLab deletes it at the head it reads itself; the service holds the caller's head before sending.

func (*Client) DeleteDraftNote 

func (c *Client) DeleteDraftNote(ctx context.Context, p Project, iid, draft int64) error

DeleteDraftNote deletes one of the signed-in account's drafts. 

func (c *Client) DeleteIssueLink(ctx context.Context, p Project, iid, linkID int64) error

DeleteIssueLink removes a link between two issues.

func (*Client) DeleteIssueNote 

func (c *Client) DeleteIssueNote(ctx context.Context, p Project, iid, note int64, updatedAt time.Time) error

DeleteIssueNote deletes a comment on an issue unless it changed after updatedAt, the time a read showed, which GitLab answers with 412.

func (*Client) DeleteLabel 

func (c *Client) DeleteLabel(ctx context.Context, p Project, id int64) error

DeleteLabel deletes a project label, addressed by id.

func (*Client) DeleteMergeRequestNote 

func (c *Client) DeleteMergeRequestNote(ctx context.Context, p Project, iid, note int64, updatedAt time.Time) error

DeleteMergeRequestNote deletes a comment on a merge request unless it changed after updatedAt, the time a read showed, which GitLab answers with 412.

func (*Client) DeleteMilestone 

func (c *Client) DeleteMilestone(ctx context.Context, p Project, id int64) error

DeleteMilestone deletes a project milestone.

func (*Client) DeleteTag 

func (c *Client) DeleteTag(ctx context.Context, p Project, name string) error

DeleteTag deletes a tag.

func (*Client) DeleteWikiPage 

func (c *Client) DeleteWikiPage(ctx context.Context, p Project, slug string) error

DeleteWikiPage deletes a page.

func (*Client) Do 

func (c *Client) Do(ctx context.Context, call Call, out any) error

Do sends one call and decodes a JSON response into out, which may be nil.

func (*Client) GetArtifact 

func (c *Client) GetArtifact(ctx context.Context, p Project, job int64, path string) ([]byte, error)

GetArtifact reads one file of a job's artifacts, as GitLab extracts it from the archive.

func (*Client) GetBranch 

func (c *Client) GetBranch(ctx context.Context, p Project, branch string) (*gitlab.Branch, error)

GetBranch reads one branch and its head commit.

func (*Client) GetCommit 

func (c *Client) GetCommit(ctx context.Context, p Project, sha string) (*gitlab.Commit, error)

GetCommit reads one commit with its line counts.

func (*Client) GetCommitDiff 

func (c *Client) GetCommitDiff(ctx context.Context, p Project, sha string, opts ListOptions) ([]gitlab.Diff, Page, error)

GetCommitDiff lists a commit's per-file diffs.

func (*Client) GetCurrentUser 

func (c *Client) GetCurrentUser(ctx context.Context) (*gitlab.User, error)

GetCurrentUser reads the signed-in account.

func (*Client) GetFile 

func (c *Client) GetFile(ctx context.Context, p Project, path, ref string) (*gitlab.File, error)

GetFile reads a file at a ref. An empty ref reads HEAD, the default branch. The path is escaped once, slashes included, as GitLab expects.

func (*Client) GetIssue 

func (c *Client) GetIssue(ctx context.Context, p Project, iid int64) (*gitlab.Issue, error)

GetIssue reads one issue by project and iid.

func (*Client) GetIssueDiscussion 

func (c *Client) GetIssueDiscussion(ctx context.Context, p Project, iid int64, discussion string) (*gitlab.Discussion, error)

GetIssueDiscussion reads one thread of an issue.

func (*Client) GetIssueNote 

func (c *Client) GetIssueNote(ctx context.Context, p Project, iid, note int64) (*gitlab.Note, error)

GetIssueNote reads one comment on an issue.

func (*Client) GetJob 

func (c *Client) GetJob(ctx context.Context, p Project, id int64) (*gitlab.Job, error)

GetJob reads one job.

func (*Client) GetJobTrace 

func (c *Client) GetJobTrace(ctx context.Context, p Project, id int64, offset, limit int) ([]byte, error)

GetJobTrace reads a job's log as GitLab stored it, bytes, ANSI escapes and section markers included: from offset, and limit bytes of it, or to the end when limit is 0. An offset past the end reads nothing (spike J).

func (*Client) GetLabel 

func (c *Client) GetLabel(ctx context.Context, p Project, id int64) (*gitlab.Label, error)

GetLabel reads one label by id, a group's included, so a write can refuse a group's label by name rather than not find it.

func (*Client) GetMergeRequest 

func (c *Client) GetMergeRequest(ctx context.Context, p Project, iid int64) (*gitlab.MergeRequest, error)

GetMergeRequest reads one merge request by project and iid.

func (*Client) GetMergeRequestApprovals 

func (c *Client) GetMergeRequestApprovals(ctx context.Context, p Project, iid int64) (*gitlab.Approvals, error)

GetMergeRequestApprovals reads a merge request's approval state.

func (*Client) GetMergeRequestDiscussion 

func (c *Client) GetMergeRequestDiscussion(ctx context.Context, p Project, iid int64, discussion string) (*gitlab.Discussion, error)

GetMergeRequestDiscussion reads one thread of a merge request.

func (*Client) GetMergeRequestNote 

func (c *Client) GetMergeRequestNote(ctx context.Context, p Project, iid, note int64) (*gitlab.Note, error)

GetMergeRequestNote reads one comment on a merge request.

func (*Client) GetMergeRequestRebase 

func (c *Client) GetMergeRequestRebase(ctx context.Context, p Project, iid int64) (*gitlab.MergeRequestRebase, error)

GetMergeRequestRebase reads a merge request with whether a rebase is in progress.

func (*Client) GetMetadata 

func (c *Client) GetMetadata(ctx context.Context) (*gitlab.Metadata, error)

GetMetadata reads the instance's version and edition. It needs authentication.

func (*Client) GetMilestone 

func (c *Client) GetMilestone(ctx context.Context, p Project, id int64) (*gitlab.ProjectMilestone, error)

GetMilestone reads one project milestone by id.

func (*Client) GetPipeline 

func (c *Client) GetPipeline(ctx context.Context, p Project, id int64) (*gitlab.PipelineDetail, error)

GetPipeline reads one pipeline.

func (*Client) GetProject 

func (c *Client) GetProject(ctx context.Context, p Project) (*gitlab.Project, error)

GetProject reads one project, and remembers its id and path.

func (*Client) GetProjectSnippet 

func (c *Client) GetProjectSnippet(ctx context.Context, p Project, id int64) (*gitlab.Snippet, error)

GetProjectSnippet reads a project's snippet.

func (*Client) GetRelease 

func (c *Client) GetRelease(ctx context.Context, p Project, tag string) (*gitlab.Release, error)

GetRelease reads the release of a tag.

func (*Client) GetSnippet 

func (c *Client) GetSnippet(ctx context.Context, id int64) (*gitlab.Snippet, error)

GetSnippet reads a personal snippet.

func (*Client) GetTag 

func (c *Client) GetTag(ctx context.Context, p Project, name string) (*gitlab.Tag, error)

GetTag reads one tag; a tag that does not exist is [not_found].

func (*Client) GetWikiPage 

func (c *Client) GetWikiPage(ctx context.Context, p Project, slug string) (*gitlab.WikiPage, error)

GetWikiPage reads a wiki page's raw content. The slug may hold slashes, which the path escapes as one segment.

func (*Client) Instance 

func (c *Client) Instance() instance.Instance

Instance is the instance this client talks to.

func (*Client) LintCI 

func (c *Client) LintCI(ctx context.Context, p Project, q LintQuery) (*gitlab.Lint, error)

LintCI checks a project's CI configuration at a ref.

func (*Client) LintCIContent 

func (c *Client) LintCIContent(ctx context.Context, p Project, content string, q LintQuery) (*gitlab.Lint, error)

LintCIContent validates supplied configuration in the project's context. It is a POST that changes nothing, so it may repeat and may run under a dry run; a read-only token still cannot send it, because read_api is enforced by method (§2.6).

func (*Client) ListArtifacts 

func (c *Client) ListArtifacts(ctx context.Context, p Project, job int64, dir string, recursive bool, opts ListOptions) ([]gitlab.ArtifactEntry, Page, error)

ListArtifacts lists the files and directories of a job's artifacts under a directory, or every entry below it when recursive.

func (*Client) ListBranches 

func (c *Client) ListBranches(ctx context.Context, p Project, search string, opts ListOptions) ([]gitlab.Branch, Page, error)

ListBranches lists branches, optionally those matching search.

func (*Client) ListCommits 

func (c *Client) ListCommits(ctx context.Context, p Project, q CommitQuery, opts ListOptions) ([]gitlab.Commit, Page, error)

ListCommits lists commits reachable from a ref.

func (*Client) ListDeployments 

func (c *Client) ListDeployments(ctx context.Context, p Project, q DeploymentQuery, opts ListOptions) ([]gitlab.Deployment, Page, error)

ListDeployments lists a project's deployments.

func (*Client) ListDraftNotes 

func (c *Client) ListDraftNotes(ctx context.Context, p Project, iid int64) ([]gitlab.DraftNote, error)

ListDraftNotes lists the signed-in account's unpublished review comments on a merge request. GitLab returns them all, unpaged.

func (*Client) ListEnvironments 

func (c *Client) ListEnvironments(ctx context.Context, p Project, q EnvironmentQuery, opts ListOptions) ([]gitlab.Environment, Page, error)

ListEnvironments lists a project's environments.

func (*Client) ListEvents 

func (c *Client) ListEvents(ctx context.Context, q EventQuery, opts ListOptions) ([]gitlab.Event, Page, error)

ListEvents lists the signed-in account's own activity.

func (*Client) ListIssueDiscussions 

func (c *Client) ListIssueDiscussions(ctx context.Context, p Project, iid int64, opts ListOptions) ([]gitlab.Discussion, Page, error)

ListIssueDiscussions lists an issue's threads, oldest first as GitLab returns them. 

func (c *Client) ListIssueLinks(ctx context.Context, p Project, iid int64) ([]gitlab.RelatedIssue, error)

ListIssueLinks lists the issues an issue is linked to, with each link.

func (*Client) ListLabels 

func (c *Client) ListLabels(ctx context.Context, p Project, q LabelQuery, opts ListOptions) ([]gitlab.Label, Page, error)

ListLabels lists the labels a project's issues and merge requests can carry.

func (*Client) ListMergeRequestCommits 

func (c *Client) ListMergeRequestCommits(ctx context.Context, p Project, iid int64, opts ListOptions) ([]gitlab.Commit, Page, error)

ListMergeRequestCommits lists a merge request's commits, newest first.

func (*Client) ListMergeRequestDiffs 

func (c *Client) ListMergeRequestDiffs(ctx context.Context, p Project, iid int64, opts ListOptions) ([]gitlab.Diff, Page, error)

ListMergeRequestDiffs lists a merge request's per-file diffs.

func (*Client) ListMergeRequestDiscussions 

func (c *Client) ListMergeRequestDiscussions(ctx context.Context, p Project, iid int64, opts ListOptions) ([]gitlab.Discussion, Page, error)

ListMergeRequestDiscussions lists a merge request's threads.

func (*Client) ListMilestones 

func (c *Client) ListMilestones(ctx context.Context, q MilestoneQuery, opts ListOptions) ([]gitlab.ProjectMilestone, Page, error)

ListMilestones lists a project's or a group's milestones.

func (*Client) ListPipelineJobs 

func (c *Client) ListPipelineJobs(ctx context.Context, p Project, pipeline int64, q JobQuery, opts ListOptions) ([]gitlab.Job, Page, error)

ListPipelineJobs lists a pipeline's jobs.

func (*Client) ListPipelineTriggerJobs 

func (c *Client) ListPipelineTriggerJobs(ctx context.Context, p Project, pipeline int64, q JobQuery, opts ListOptions) ([]gitlab.Bridge, Page, error)

ListPipelineTriggerJobs lists a pipeline's trigger jobs, which the job listing leaves out.

func (*Client) ListPipelines 

func (c *Client) ListPipelines(ctx context.Context, p Project, q PipelineQuery, opts ListOptions) ([]gitlab.Pipeline, Page, error)

ListPipelines lists a project's pipelines.

func (*Client) ListProjectEvents 

func (c *Client) ListProjectEvents(ctx context.Context, p Project, q EventQuery, opts ListOptions) ([]gitlab.Event, Page, error)

ListProjectEvents lists a project's activity.

func (*Client) ListProjectMembers 

func (c *Client) ListProjectMembers(ctx context.Context, p Project, query string, opts ListOptions) ([]gitlab.Member, Page, error)

ListProjectMembers lists everyone with access to a project, those who have it through a group included. query matches names and usernames.

func (*Client) ListProjectSnippets 

func (c *Client) ListProjectSnippets(ctx context.Context, p Project, opts ListOptions) ([]gitlab.Snippet, Page, error)

ListProjectSnippets lists a project's snippets.

func (*Client) ListProtectedBranches 

func (c *Client) ListProtectedBranches(ctx context.Context, p Project, opts ListOptions) ([]gitlab.ProtectedBranch, Page, error)

ListProtectedBranches lists a project's protected branch rules. A rule name may be a wildcard.

func (*Client) ListProtectedTags 

func (c *Client) ListProtectedTags(ctx context.Context, p Project, opts ListOptions) ([]gitlab.ProtectedTag, Page, error)

ListProtectedTags lists a project's protected tag rules. A rule name may be a wildcard.

func (*Client) ListReleases 

func (c *Client) ListReleases(ctx context.Context, p Project, q ReleaseQuery, opts ListOptions) ([]gitlab.Release, Page, error)

ListReleases lists a project's releases.

func (*Client) ListSnippets 

func (c *Client) ListSnippets(ctx context.Context, createdAfter time.Time, opts ListOptions) ([]gitlab.Snippet, Page, error)

ListSnippets lists the signed-in account's own snippets.

func (*Client) ListTags 

func (c *Client) ListTags(ctx context.Context, p Project, q TagQuery, opts ListOptions) ([]gitlab.Tag, Page, error)

ListTags lists a project's tags.

func (*Client) ListTodos 

func (c *Client) ListTodos(ctx context.Context, q TodoQuery, opts ListOptions) ([]gitlab.Todo, Page, error)

ListTodos lists the signed-in account's to-do items.

func (*Client) ListTree 

func (c *Client) ListTree(ctx context.Context, p Project, q TreeQuery, opts ListOptions) ([]gitlab.TreeEntry, Page, error)

ListTree lists a directory, paged by keyset.

func (*Client) ListUsers 

func (c *Client) ListUsers(ctx context.Context, q UserQuery, opts ListOptions) ([]gitlab.UserBasic, Page, error)

ListUsers finds accounts.

func (*Client) ListWikiPages 

func (c *Client) ListWikiPages(ctx context.Context, p Project) ([]gitlab.WikiPageBasic, error)

ListWikiPages lists a project wiki's pages, without their content. GitLab answers with every page at once; the listing is not paged.

func (*Client) MarkTodoDone 

func (c *Client) MarkTodoDone(ctx context.Context, id int64) (*gitlab.Todo, error)

MarkTodoDone marks one of the signed-in account's to-do items done.

func (*Client) MergeMergeRequest 

func (c *Client) MergeMergeRequest(ctx context.Context, p Project, iid int64, in MergeBody) (*gitlab.MergeRequest, error)

MergeMergeRequest merges a merge request, or sets it to merge when its pipeline succeeds. A PUT repeats; with the head fixed by the witness, a repeat can only merge the same commits, and GitLab refuses a merge request that is already merged.

func (*Client) MoveIssue 

func (c *Client) MoveIssue(ctx context.Context, p Project, iid, toProjectID int64) (*gitlab.Issue, error)

MoveIssue moves an issue to another project: GitLab makes a copy there and closes the original, so the move is never repeated.

func (*Client) PlayJob 

func (c *Client) PlayJob(ctx context.Context, p Project, id int64, vars []JobVariable, inputs map[string]any) (*gitlab.Job, error)

PlayJob starts a manual job. It runs the job, so it is not repeated.

func (*Client) ProjectSnippetFileRaw 

func (c *Client) ProjectSnippetFileRaw(ctx context.Context, p Project, id int64, ref, path string) ([]byte, error)

ProjectSnippetFileRaw reads one file of a project snippet at a ref.

func (*Client) ProjectSnippetRaw 

func (c *Client) ProjectSnippetRaw(ctx context.Context, p Project, id int64) ([]byte, error)

ProjectSnippetRaw reads a project snippet's first file as bytes.

func (*Client) PublishDraftNotes 

func (c *Client) PublishDraftNotes(ctx context.Context, p Project, iid int64, summary, reviewerState string) error

PublishDraftNotes publishes every draft of the signed-in account on a merge request at once, with an optional summary comment and reviewer state. It creates comments, so it is not repeated.

func (*Client) RateReading 

func (c *Client) RateReading() Reading

RateReading is the last rate-limit reading GitLab reported.

func (*Client) RebaseMergeRequest 

func (c *Client) RebaseMergeRequest(ctx context.Context, p Project, iid int64, skipCI bool) (*gitlab.RebaseState, error)

RebaseMergeRequest asks GitLab to rebase a merge request's source branch onto its target. GitLab answers 202 and rebases in the background.

func (*Client) ReplyToIssueDiscussion 

func (c *Client) ReplyToIssueDiscussion(ctx context.Context, p Project, iid int64, discussion, body string) (*gitlab.Note, error)

ReplyToIssueDiscussion adds a note to an issue's thread.

func (*Client) ReplyToMergeRequestDiscussion 

func (c *Client) ReplyToMergeRequestDiscussion(ctx context.Context, p Project, iid int64, discussion, body string) (*gitlab.Note, error)

ReplyToMergeRequestDiscussion adds a note to a merge request's thread.

func (*Client) ResolveIssueDiscussion 

func (c *Client) ResolveIssueDiscussion(ctx context.Context, p Project, iid int64, discussion string, resolved bool) (*gitlab.Discussion, error)

ResolveIssueDiscussion resolves or reopens an issue's thread.

func (*Client) ResolveMergeRequestDiscussion 

func (c *Client) ResolveMergeRequestDiscussion(ctx context.Context, p Project, iid int64, discussion string, resolved bool) (*gitlab.Discussion, error)

ResolveMergeRequestDiscussion resolves or reopens a thread. Setting a state twice leaves it set, which PUT already says.

func (*Client) ResolveProject 

func (c *Client) ResolveProject(ctx context.Context, p Project) (Project, error)

ResolveProject returns p addressed by numeric id, with its full path. A path is read at most once per call context (WithCall), and then not again for a few minutes in this process; a move GitLab reports forgets what the process remembered. A proxy that decodes %2F then breaks at most this one request (§6.1).

An id is returned as given, with its path when the process knows it, and is never read for it.

func (*Client) RetryJob 

func (c *Client) RetryJob(ctx context.Context, p Project, id int64, inputs map[string]any) (*gitlab.Job, error)

RetryJob runs a job again as a new job, which it returns.

func (*Client) RetryPipeline 

func (c *Client) RetryPipeline(ctx context.Context, p Project, id int64) (*gitlab.PipelineDetail, error)

RetryPipeline retries a pipeline's failed and canceled jobs; with none, GitLab changes nothing. Each retry creates jobs, so it is not repeated.

func (*Client) Revert 

func (c *Client) Revert(ctx context.Context, p Project, sha, branch string, dryRun bool) (*gitlab.Commit, error)

Revert applies a commit's inverse to a branch as a new commit. With dryRun GitLab commits nothing and only says whether it would apply.

func (*Client) Search 

func (c *Client) Search(ctx context.Context, q SearchQuery, opts ListOptions) ([]gitlab.SearchHit, Page, error)

Search runs a search of any scope but commits, whose rows have another shape (SearchCommits). The two stay separate methods, each with its own Call literals and decoded type, so the API gates can read both.

func (*Client) SearchCommits 

func (c *Client) SearchCommits(ctx context.Context, q SearchQuery, opts ListOptions) ([]gitlab.SearchCommit, Page, error)

SearchCommits runs a search of the commits scope.

func (*Client) SearchIssues 

func (c *Client) SearchIssues(ctx context.Context, q ItemQuery, opts ListOptions) ([]gitlab.Issue, Page, error)

SearchIssues lists issues in a project, a group, or across the instance.

func (*Client) SearchMergeRequests 

func (c *Client) SearchMergeRequests(ctx context.Context, q ItemQuery, opts ListOptions) ([]gitlab.MergeRequest, Page, error)

SearchMergeRequests lists merge requests in a project, a group, or across the instance.

func (*Client) SearchProjects 

func (c *Client) SearchProjects(ctx context.Context, q ProjectQuery, opts ListOptions) ([]gitlab.Project, Page, error)

SearchProjects lists projects, across the instance or in one group.

func (*Client) SnippetFileRaw 

func (c *Client) SnippetFileRaw(ctx context.Context, id int64, ref, path string) ([]byte, error)

SnippetFileRaw reads one file of a personal snippet at a ref.

func (*Client) SnippetRaw 

func (c *Client) SnippetRaw(ctx context.Context, id int64) ([]byte, error)

SnippetRaw reads a personal snippet's first file as bytes.

func (*Client) TokenInfo 

func (c *Client) TokenInfo(ctx context.Context) (*gitlab.TokenInfo, error)

TokenInfo introspects the bearer token: scopes, expiry, application. Doorkeeper serves it under the web base, not the API root.

func (*Client) UnapproveMergeRequest 

func (c *Client) UnapproveMergeRequest(ctx context.Context, p Project, iid int64) (*gitlab.Approvals, error)

UnapproveMergeRequest withdraws the account's approval. GitLab answers 404 when there is none.

func (*Client) UpdateIssue 

func (c *Client) UpdateIssue(ctx context.Context, p Project, iid int64, in IssueUpdate) (*gitlab.Issue, error)

UpdateIssue changes the fields given.

func (*Client) UpdateLabel 

func (c *Client) UpdateLabel(ctx context.Context, p Project, id int64, in LabelUpdate) (*gitlab.Label, error)

UpdateLabel changes a project label, addressed by id.

func (*Client) UpdateMergeRequest 

func (c *Client) UpdateMergeRequest(ctx context.Context, p Project, iid int64, in MergeRequestUpdate) (*gitlab.MergeRequest, error)

UpdateMergeRequest changes the fields given.

func (*Client) UpdateMilestone 

func (c *Client) UpdateMilestone(ctx context.Context, p Project, id int64, in MilestoneUpdate) (*gitlab.ProjectMilestone, error)

UpdateMilestone changes a project milestone.

func (*Client) UpdateWikiPage 

func (c *Client) UpdateWikiPage(ctx context.Context, p Project, slug string, in WikiPageUpdate) (*gitlab.WikiPage, error)

UpdateWikiPage changes the fields given.

type CommitAction 

type CommitAction struct {
	Action       string `json:"action"`
	FilePath     string `json:"file_path"`
	PreviousPath string `json:"previous_path,omitempty"`
	// Content is the file's new content. nil leaves it out: a move then
	// keeps the file's content, where "" would empty it
	// (app/services/files/multi_service.rb), and a delete takes none. An
	// update needs the key even for an empty file.
	Content  *string `json:"content,omitempty"`
	Encoding string  `json:"encoding,omitempty"`
	// LastCommitID is the witness: GitLab refuses the action with 400
	// when the file's last commit is another (§2.10).
	LastCommitID string `json:"last_commit_id,omitempty"`
}

CommitAction is one file change of a commit.

type CommitCreate 

type CommitCreate struct {
	Branch        string         `json:"branch"`
	StartBranch   string         `json:"start_branch,omitempty"`
	CommitMessage string         `json:"commit_message"`
	Actions       []CommitAction `json:"actions"`
}

CommitCreate is POST /projects/:id/repository/commits.

type CommitQuery 

type CommitQuery struct {
	Ref         string
	Path        string
	Author      string
	Since       time.Time
	Until       time.Time
	FirstParent bool
}

CommitQuery filters ListCommits.

type DeploymentQuery 

type DeploymentQuery struct {
	Environment   string
	Status        string
	OrderBy       string // id, iid, created_at, updated_at, finished_at or ref
	Sort          string
	UpdatedAfter  time.Time
	UpdatedBefore time.Time
}

DeploymentQuery filters ListDeployments.

type DraftCreate 

type DraftCreate struct {
	Note                  string            `json:"note"`
	Position              *diffpos.Position `json:"position,omitempty"`
	InReplyToDiscussionID string            `json:"in_reply_to_discussion_id,omitempty"`
	ResolveDiscussion     bool              `json:"resolve_discussion,omitempty"`
}

DraftCreate is POST …/draft_notes.

type EnvironmentQuery 

type EnvironmentQuery struct {
	Name   string
	Search string
	States string // available, stopping or stopped
}

EnvironmentQuery filters ListEnvironments.

type Error 

type Error struct {
	Class Class
	// Status is the HTTP status, 0 for a failure that never got one.
	Status int
	// Message says what happened and what to do. It never carries a
	// request URL, a path or a query.
	Message string
	// contains filtered or unexported fields
}

Error is a classified failure. It reaches the model as a tool result, never as a protocol error.

func AsError 

func AsError(err error) *Error

AsError returns err as a classified *Error, classing anything that carries no class as unexpected. nil stays nil.

func Errf 

func Errf(c Class, format string, args ...any) *Error

Errf builds a classified error.

func Wrap 

func Wrap(c Class, err error, format string, args ...any) *Error

Wrap builds a classified error carrying a cause. The cause's text is not added to the message; say it in format if it is safe to show.

func (*Error) Error 

func (e *Error) Error() string

Error renders "[class] message".

func (*Error) Unwrap 

func (e *Error) Unwrap() error

Unwrap exposes the cause.

type EventQuery 

type EventQuery struct {
	Action     string
	TargetType string
	Before     string
	After      string
	Sort       string
}

EventQuery filters ListEvents. Before and After are days, YYYY-MM-DD, and exclusive.

type Group 

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

Group addresses a group by numeric id or full path.

func ParseGroup 

func ParseGroup(s string) (Group, error)

ParseGroup reads a numeric id or a full path.

func (Group) ID 

func (l Group) ID() int64

ID is the numeric id, 0 when addressed by path.

func (Group) IsZero 

func (l Group) IsZero() bool

IsZero reports an unset locator.

func (Group) Path 

func (l Group) Path() string

Path is the full path, "" when addressed by id only.

func (Group) String 

func (l Group) String() string

String is the id when known, else the path.

type IssueCreate 

type IssueCreate struct {
	Title        string   `json:"title"`
	Description  string   `json:"description,omitempty"`
	Labels       []string `json:"labels,omitempty"`
	AssigneeIDs  []int64  `json:"assignee_ids,omitempty"`
	MilestoneID  int64    `json:"milestone_id,omitempty"`
	DueDate      string   `json:"due_date,omitempty"`
	Confidential bool     `json:"confidential,omitempty"`
}

IssueCreate is POST /projects/:id/issues.

type IssueLinkCreate 

type IssueLinkCreate struct {
	TargetProjectID string `json:"target_project_id"`
	TargetIssueIID  string `json:"target_issue_iid"`
	LinkType        string `json:"link_type,omitempty"`
}

IssueLinkCreate is POST …/issues/:iid/links' request.

type IssueUpdate 

type IssueUpdate struct {
	Title        *string  `json:"title,omitempty"`
	Description  *string  `json:"description,omitempty"`
	AddLabels    []string `json:"add_labels,omitempty"`
	RemoveLabels []string `json:"remove_labels,omitempty"`
	// AssigneeIDs is the whole set, computed from a fresh read: GitLab
	// takes no add or remove for assignees.
	AssigneeIDs *[]int64 `json:"assignee_ids,omitempty"`
	// MilestoneID 0 clears the milestone.
	MilestoneID  *int64  `json:"milestone_id,omitempty"`
	StateEvent   string  `json:"state_event,omitempty"`
	DueDate      *string `json:"due_date,omitempty"`
	Confidential *bool   `json:"confidential,omitempty"`
}

IssueUpdate is PUT /projects/:id/issues/:iid. A nil field is not sent.

type ItemQuery 

type ItemQuery struct {
	Project          Project
	Group            Group
	State            string // opened, closed, merged, all
	Labels           []string
	AuthorUsername   string
	AssigneeUsername string
	ReviewerUsername string // merge requests only
	Milestone        string
	Search           string
	// Scope is created_by_me, assigned_to_me or all. GitLab's default
	// differs by endpoint, so it is sent only when set.
	Scope         string
	CreatedAfter  time.Time
	CreatedBefore time.Time
	UpdatedAfter  time.Time
	UpdatedBefore time.Time
	OrderBy, Sort string
	SourceBranch  string // merge requests only
	TargetBranch  string // merge requests only
	Draft         *bool  // merge requests only
}

ItemQuery filters SearchIssues and SearchMergeRequests. At most one of Project and Group is set; neither searches across the instance.

type JobQuery 

type JobQuery struct {
	// Scope is one job status, such as failed; empty lists every job.
	Scope          string
	IncludeRetried bool
}

JobQuery filters ListPipelineJobs.

type JobVariable 

type JobVariable struct {
	Key   string `json:"key"`
	Value string `json:"value"`
}

JobVariable is one variable a manual job is played with.

type LabelCreate 

type LabelCreate struct {
	Name        string  `json:"name"`
	Color       string  `json:"color"`
	Description *string `json:"description,omitempty"`
	Priority    *int    `json:"priority,omitempty"`
}

LabelCreate is POST …/labels' request.

type LabelQuery 

type LabelQuery struct {
	Search string
	// IncludeAncestorGroups adds the labels of the groups above the
	// project, which its issues can carry too.
	IncludeAncestorGroups bool
	WithCounts            bool
}

LabelQuery filters ListLabels.

type LabelUpdate 

type LabelUpdate struct {
	NewName     string  `json:"new_name,omitempty"`
	Color       string  `json:"color,omitempty"`
	Description *string `json:"description,omitempty"`
	Priority    *int    `json:"priority,omitempty"`
	// ClearPriority sends priority as null, which GitLab reads as
	// removing it (lib/api/helpers/label_helpers.rb at v19.4.1-ee).
	ClearPriority bool `json:"-"`
}

LabelUpdate is PUT …/labels/:id's request. Only the fields set are sent.

func (LabelUpdate) MarshalJSON added in v1.1.0 

func (u LabelUpdate) MarshalJSON() ([]byte, error)

MarshalJSON sends priority as null when ClearPriority is set.

type LintQuery 

type LintQuery struct {
	// Ref is the branch or tag whose configuration is linted; the
	// default branch when empty.
	Ref string
	// Simulate asks GitLab to simulate creating a pipeline for Ref,
	// which finds what a static check cannot, such as rules that match
	// no job.
	Simulate    bool
	IncludeJobs bool
}

LintQuery selects what LintCI checks.

type ListOptions 

type ListOptions struct {
	// PerPage is the page size, 1 to 100; zero takes 20.
	PerPage int
	// PageToken is the NextToken of the previous page, or empty for the
	// first.
	PageToken string
	// Page asks for one offset page by number, 1 first, for a caller
	// that jumps rather than walks: the newest thread is on the last
	// page. It is not used with PageToken, and only on an endpoint that
	// pages by offset.
	Page int
}

ListOptions select one page of a listing.

type MergeBody 

type MergeBody struct {
	SHA                      string `json:"sha"`
	Squash                   *bool  `json:"squash,omitempty"`
	ShouldRemoveSourceBranch *bool  `json:"should_remove_source_branch,omitempty"`
	MergeCommitMessage       string `json:"merge_commit_message,omitempty"`
	SquashCommitMessage      string `json:"squash_commit_message,omitempty"`
	AutoMerge                bool   `json:"auto_merge,omitempty"`
}

MergeBody is PUT …/merge_requests/:iid/merge. SHA is the witness: GitLab refuses with 409 when the source branch's head is another.

type MergeRequestCreate 

type MergeRequestCreate struct {
	SourceBranch       string   `json:"source_branch"`
	TargetBranch       string   `json:"target_branch"`
	Title              string   `json:"title"`
	Description        string   `json:"description,omitempty"`
	Labels             []string `json:"labels,omitempty"`
	AssigneeIDs        []int64  `json:"assignee_ids,omitempty"`
	ReviewerIDs        []int64  `json:"reviewer_ids,omitempty"`
	MilestoneID        int64    `json:"milestone_id,omitempty"`
	RemoveSourceBranch bool     `json:"remove_source_branch,omitempty"`
	Squash             bool     `json:"squash,omitempty"`
}

MergeRequestCreate is POST /projects/:id/merge_requests.

type MergeRequestUpdate 

type MergeRequestUpdate struct {
	Title              *string  `json:"title,omitempty"`
	Description        *string  `json:"description,omitempty"`
	AddLabels          []string `json:"add_labels,omitempty"`
	RemoveLabels       []string `json:"remove_labels,omitempty"`
	AssigneeIDs        *[]int64 `json:"assignee_ids,omitempty"`
	ReviewerIDs        *[]int64 `json:"reviewer_ids,omitempty"`
	MilestoneID        *int64   `json:"milestone_id,omitempty"`
	StateEvent         string   `json:"state_event,omitempty"`
	TargetBranch       *string  `json:"target_branch,omitempty"`
	RemoveSourceBranch *bool    `json:"remove_source_branch,omitempty"`
	Squash             *bool    `json:"squash,omitempty"`
}

MergeRequestUpdate is PUT /projects/:id/merge_requests/:iid. A nil field is not sent. GitLab takes no draft field: the title's "Draft:" prefix is the draft state.

type MilestoneCreate 

type MilestoneCreate struct {
	Title       string  `json:"title"`
	Description *string `json:"description,omitempty"`
	DueDate     *string `json:"due_date,omitempty"`
	StartDate   *string `json:"start_date,omitempty"`
}

MilestoneCreate is POST …/milestones' request.

type MilestoneQuery 

type MilestoneQuery struct {
	Project Project
	Group   Group
	State   string // active or closed
	Search  string
	Title   string
	// IncludeAncestors adds the milestones of the groups above.
	IncludeAncestors bool
}

MilestoneQuery filters ListMilestones. Exactly one of Project and Group is set.

type MilestoneUpdate 

type MilestoneUpdate struct {
	Title       string  `json:"title,omitempty"`
	Description *string `json:"description,omitempty"`
	DueDate     *string `json:"due_date,omitempty"`
	StartDate   *string `json:"start_date,omitempty"`
	StateEvent  string  `json:"state_event,omitempty"`
}

MilestoneUpdate is PUT …/milestones/:id's request. Only the fields set are sent.

type Move 

type Move struct {
	From, To string
}

Move is a project GitLab reported as renamed or transferred: a GET to From answered with a redirect to To, which the client followed once.

func Moves 

func Moves(ctx context.Context) []Move

Moves lists the moved projects met under ctx, for the result to report.

type Options 

type Options struct {
	// Instance is the normalized GitLab the client talks to. The token
	// is sent nowhere else.
	Instance instance.Instance
	// HTTPClient carries the transport and its proxy. It is
	// copied; its redirect policy is replaced and its Timeout cleared,
	// because the client bounds each attempt itself.
	HTTPClient *http.Client
	// Tokens supplies the access token. nil answers every call [auth].
	Tokens TokenSource
	// Logger receives one debug line per attempt and drift reports.
	// Never the payload.
	Logger *slog.Logger
	// Version is this build's version, sent as "gitlab-mcp/<version>".
	Version string
	// HeaderTimeout bounds the wait for response headers per attempt.
	HeaderTimeout time.Duration
	// StallTimeout bounds each read of a response body. Zero takes
	// HeaderTimeout: a body that stops arriving is cut, a slow one is not.
	StallTimeout time.Duration
	// MaxAttempts is the most attempts a call gets, the first included.
	MaxAttempts int
	// RequestsPerMinute, NotesPerMinute and Concurrency set the rate
	// model; zero takes the defaults.
	RequestsPerMinute int
	NotesPerMinute    int
	Concurrency       int
	// Sleep waits between attempts; tests stub it.
	Sleep func(ctx context.Context, d time.Duration) error
	// Now is the clock; tests stub it.
	Now func() time.Time
}

Options configure a Client. Only Instance is required.

type Page 

type Page struct {
	// NextToken continues the listing; empty means it is complete.
	NextToken string
	// Total is X-Total, or -1 when GitLab did not say. It stops saying
	// once a count passes 10,000, and never says on keyset endpoints.
	Total int
	// Pages is X-Total-Pages, or -1 when GitLab did not say, which it
	// stops saying with Total.
	Pages int
}

Page describes one page of a listing.

func (Page) Complete 

func (p Page) Complete() bool

Complete reports whether there is no further page.

func (Page) TotalKnown 

func (p Page) TotalKnown() bool

TotalKnown reports whether Total is GitLab's count.

type PipelineCreate 

type PipelineCreate struct {
	Ref       string             `json:"ref"`
	Variables []PipelineVariable `json:"variables,omitempty"`
	Inputs    map[string]any     `json:"inputs,omitempty"`
}

PipelineCreate is POST /projects/:id/pipeline.

type PipelineQuery 

type PipelineQuery struct {
	Ref           string
	SHA           string
	Status        string
	Source        string
	Username      string
	UpdatedAfter  time.Time
	UpdatedBefore time.Time
	// CreatedAfter is how a lost run_pipeline is settled (§4.5).
	CreatedAfter time.Time
	OrderBy      string // id, status, ref, updated_at or user_id
	Sort         string // asc or desc
}

PipelineQuery filters ListPipelines.

type PipelineVariable 

type PipelineVariable struct {
	Key          string `json:"key"`
	Value        string `json:"value"`
	VariableType string `json:"variable_type,omitempty"`
}

PipelineVariable is one variable of a new pipeline.

type Project 

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

Project addresses a project by numeric id or full path ("group/sub/project"). The zero value is unset.

func ParseProject 

func ParseProject(s string) (Project, error)

ParseProject reads a numeric id or a full path. A path is kept unescaped; the client escapes it once when it builds a request.

func ProjectByID 

func ProjectByID(id int64) Project

ProjectByID addresses a project by numeric id.

func (Project) ID 

func (l Project) ID() int64

ID is the numeric id, 0 when addressed by path.

func (Project) IsZero 

func (l Project) IsZero() bool

IsZero reports an unset locator.

func (Project) Path 

func (l Project) Path() string

Path is the full path, "" when addressed by id only.

func (Project) String 

func (l Project) String() string

String is the id when known, else the path.

type ProjectQuery 

type ProjectQuery struct {
	// Group limits the search to one group; zero searches everything the
	// token can see.
	Group            Group
	IncludeSubgroups bool
	Search           string
	Membership       bool
	Owned            bool
	Starred          bool
	Archived         *bool
	Visibility       string
	OrderBy, Sort    string
	// Keyset asks for keyset pagination, which GitLab offers on project
	// lists ordered by id and which has no 50,000-row edge.
	Keyset bool
}

ProjectQuery filters SearchProjects.

type Reading 

type Reading struct {
	// Known is false until a response carried RateLimit-Remaining.
	Known     bool
	Limit     int
	Remaining int
	Reset     time.Time
	Observed  time.Time
}

Reading is the last rate-limit state GitLab reported. get_me shows it. The headers describe only the instance throttles, never an application limit, and are often absent (§2.13).

type ReleaseCreate 

type ReleaseCreate struct {
	TagName     string        `json:"tag_name"`
	Ref         string        `json:"ref,omitempty"`
	TagMessage  string        `json:"tag_message,omitempty"`
	Name        string        `json:"name,omitempty"`
	Description string        `json:"description,omitempty"`
	Milestones  []string      `json:"milestones,omitempty"`
	ReleasedAt  *time.Time    `json:"released_at,omitempty"`
	Assets      *ReleaseLinks `json:"assets,omitempty"`
}

ReleaseCreate is POST /projects/:id/releases. 

type ReleaseLink struct {
	Name            string `json:"name"`
	URL             string `json:"url"`
	LinkType        string `json:"link_type,omitempty"`
	DirectAssetPath string `json:"direct_asset_path,omitempty"`
}

ReleaseLink is one asset link: a name and a URL, and optionally its kind and the path GitLab serves it at under the release. 

type ReleaseLinks struct {
	Links []ReleaseLink `json:"links"`
}

ReleaseLinks are the asset links a new release is created with.

type ReleaseQuery 

type ReleaseQuery struct {
	OrderBy string // released_at or created_at
	Sort    string // asc or desc
}

ReleaseQuery orders ListReleases.

type Root 

type Root int

Root is the base a Call's Path is resolved against. 

const (
	// RootAPI is <instance>/api/v4/.
	RootAPI Root = iota
	// RootWeb is the instance's web base, for the OAuth endpoints
	// Doorkeeper serves outside the API, such as /oauth/token/info.
	RootWeb
)

type SearchQuery 

type SearchQuery struct {
	Project Project
	Group   Group
	Scope   string
	Search  string
	State   string // issues and merge requests
	Ref     string // a project's blobs and commits
}

SearchQuery is one search. At most one of Project and Group is set; neither searches the whole instance.

type SnippetCreate 

type SnippetCreate struct {
	Title       string              `json:"title"`
	Description string              `json:"description,omitempty"`
	Visibility  string              `json:"visibility"`
	Files       []SnippetFileCreate `json:"files"`
}

SnippetCreate is POST /snippets and /projects/:id/snippets. Visibility is always private: the service never sends another (§7.8).

type SnippetFileCreate 

type SnippetFileCreate struct {
	FilePath string `json:"file_path"`
	Content  string `json:"content"`
}

SnippetFileCreate is one file of a new snippet.

type StaticToken 

type StaticToken string

StaticToken is a TokenSource that always hands out the same token, for a token that was just issued and a test. Nothing replaces it, so Invalidate does nothing.

func (StaticToken) Invalidate 

func (StaticToken) Invalidate(string)

Invalidate does nothing: there is no other token to move to.

func (StaticToken) Token 

func (t StaticToken) Token(context.Context) (string, error)

Token returns the token.

type TagQuery 

type TagQuery struct {
	Search  string
	OrderBy string // name, updated or version
	Sort    string // asc or desc
}

TagQuery filters ListTags.

type TodoQuery 

type TodoQuery struct {
	// ProjectID limits the list to one project; GitLab takes only the
	// numeric id here.
	ProjectID int64
	State     string // pending or done
	Action    string
	Type      string
}

TodoQuery filters ListTodos.

type TokenSource 

type TokenSource interface {
	Token(ctx context.Context) (string, error)
	// Invalidate drops an access token GitLab refused as invalid_token,
	// so the next Token reads the store again or refreshes. A logout and
	// a login in another process revoke the token held here long before
	// its expiry says so. A source with nothing to drop does nothing.
	Invalidate(rejected string)
}

TokenSource supplies the bearer token. It refreshes as it needs to; the client asks once per call.

type TreeQuery 

type TreeQuery struct {
	Path      string
	Ref       string
	Recursive bool
}

TreeQuery selects a directory listing.

type UserQuery 

type UserQuery struct {
	Search   string
	Username string
}

UserQuery filters ListUsers. Username is an exact match; Search matches names and usernames.

type WikiPageCreate 

type WikiPageCreate struct {
	Title   string `json:"title"`
	Content string `json:"content"`
	Format  string `json:"format,omitempty"`
}

WikiPageCreate is POST /projects/:id/wikis.

type WikiPageUpdate 

type WikiPageUpdate struct {
	Title   *string `json:"title,omitempty"`
	Content *string `json:"content,omitempty"`
	Format  *string `json:"format,omitempty"`
}

WikiPageUpdate is PUT /projects/:id/wikis/:slug. A nil field is not sent.

Source Files

View all Source files

Directories

Path Synopsis
Package gitlabtest is an in-memory GitLab behind httptest, for tests.
 Package gitlabtest is an in-memory GitLab behind httptest, for tests.

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.