go-gitlab

go-gitlab is a Go client library that wraps nearly all of the GitLab REST API v4, giving Go programs typed access to projects, merge requests, pipelines, groups, packages, and dozens of other GitLab services through service structs hung off a single Client object. It supports both GitLab.com and self-managed GitLab instances via a configurable base URL, offers pluggable authentication (private tokens, OAuth2, job tokens), and layers automatic rate-limiting and retry handling on top of GitLab’s API responses.

The project was originally maintained under github.com/xanzy/go-gitlab and grew over nearly a decade into one of the most complete unofficial GitLab clients in the Go ecosystem. In late 2024, GitLab took over stewardship and migrated the module to gitlab.com/gitlab-org/api/client-go; this repository is now archived and frozen, kept only for backward compatibility. New consumers should import the GitLab-hosted module directly — the code itself is unchanged and remains a drop-in replacement.

What You Get

• A Client covering nearly every GitLab v4 REST endpoint, organized into per-resource services
• Support for both gitlab.com and self-managed GitLab instances via a configurable base URL
• Multiple authentication modes: private token, OAuth2 token, and CI job token
• Automatic request retries and rate-limit handling built on hashicorp/go-retryablehttp
• Typed structs for parsing GitLab webhook and system-hook event payloads
• A runnable examples/ directory covering pagination, impersonation, webhooks, and more

Common Use Cases

• Writing CI/CD automation that creates pipeline schedules or reads pipeline/job status from Go
• Scripting GitLab instance administration — projects, groups, members, protected branches — for self-managed installs
• Building ChatOps bots or internal CLIs that open merge requests, post notes, or query issue boards
• Ingesting and unmarshaling GitLab webhook events in a Go service

Under The Hood

Architecture The package centers on a single Client (gitlab.go) that owns an HTTP transport, base URL, auth configuration, and rate limiter, and exposes dozens of *Service structs (ProjectsService, MergeRequestsService, PipelinesService, etc.) as fields — each service implements the request-building and response-decoding for one GitLab API resource area. Requests flow through a shared NewRequest/Do path in gitlab.go that attaches auth headers, retries via retryablehttp, and rate-limits before handing off to the caller, so adding a new endpoint is a matter of adding a new file with a service struct and methods rather than touching shared plumbing. The per-resource file layout (projects.go, merge_requests.go, pipelines.go, …) each paired with its own _test.go keeps the surface area of any single change small despite the library’s size.

Tech Stack Written in plain Go (module targets Go 1.19) with a deliberately small dependency set: google/go-querystring for encoding list options into query strings, hashicorp/go-cleanhttp and hashicorp/go-retryablehttp for transport and retry behavior, golang.org/x/oauth2 for OAuth2 token support, golang.org/x/time/rate for client-side rate limiting, and stretchr/testify for assertions in tests. There is no code generation step and no external service dependency at build time — it’s a pure client library.

Code Quality Test coverage is extensive and consistent: essentially every source file (projects.go, merge_requests.go, pipelines.go, and so on) has a matching _test.go exercising its methods against fixture-backed HTTP responses, and a .golangci.yml plus CONTRIBUTING.md formatting rules (gofumpt, line-width conventions) indicate an enforced lint/format standard. Error handling follows Go convention (explicit error returns, a shared ErrNotFound sentinel), and naming is consistent across the service files, which made the codebase straightforward for hundreds of contributors to extend without deep coordination.

API Design The API favors a resource-oriented, chainable style — client.Projects.ListProjects(opts) — with functional options (With... constructors) for client configuration and typed *Options structs with pointer fields for optional API parameters, mirroring common Go SDK conventions. Documentation is thorough: nearly every exported type and method carries a GoDoc comment linking to the relevant GitLab API docs page, and the examples/ directory demonstrates realistic end-to-end usage, keeping the boilerplate needed to get started low despite the library’s breadth.