gitlab

package
v1.16.3 Latest Latest
Warning

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

 Go to latest Published: Feb 22, 2026 License: GPL-3.0 Imports: 13 Imported by: 0

Documentation

Overview

Package gitlab provides GitLab API client functionality with rate limiting.

The package implements a Service layer that wraps the official GitLab Go client with additional features:

  • Per-endpoint rate limiting (download: 5/min, export: 6/min, import: 6/min)
  • Project and group operations (list, get, create)
  • Export/import workflow with polling and status tracking
  • Project emptiness validation for safe restore

Rate Limiting: The Service enforces GitLab API rate limits per endpoint using token buckets:

  • Download API: 5 requests/minute (repository files)
  • Export API: 6 requests/minute (project export)
  • Import API: 6 requests/minute (project import)

See "Rate Limiting" documentation block (around line 60) for comprehensive details on enforcement mechanisms, consequences, tuning guidance, and recovery procedures.

Key Interfaces:

  • Client: GitLab API operations (implemented by Service)
  • RateLimiter: Token bucket rate limiter

Architecture: 

Service
    ├─> gitlab.Client (official client)
    ├─> downloadLimiter (5 req/min)
    ├─> exportLimiter (6 req/min)
    └─> importLimiter (6 req/min)

Example usage: 

service := gitlab.NewService(baseURL, token, logger)

// Export project
exportID, err := service.ExportProject(ctx, projectID)
status, err := service.WaitForExportCompletion(ctx, projectID, exportID, timeout)

// Import project
importID, err := service.ImportProject(ctx, namespace, projectPath, archivePath)
status, err := service.WaitForImportCompletion(ctx, projectID, timeout)

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrUnmarshalJSON is returned when JSON unmarshalling fails.
	ErrUnmarshalJSON = errors.New("error unmarshalling json")
	// ErrGitlabAPI is returned when GitLab API returns an error.
	ErrGitlabAPI = errors.New("error message from Gitlab API")
)
View Source 
var (
	// ErrExportTimeout is returned when timeout occurs waiting for GitLab to start project export.
	ErrExportTimeout = errors.New("timeout waiting for gitlab to start the export project")
	// ErrRateLimit is returned when rate limit is exceeded.
	ErrRateLimit = errors.New("rate limit error")
)
View Source 
var (
	// ErrImportFailed is returned when GitLab import fails.
	ErrImportFailed = errors.New("import failed")
	// ErrUnexpectedImportStatus is returned when import reaches an unexpected status.
	ErrUnexpectedImportStatus = errors.New("unexpected import status")
)
View Source 
var (
	// ErrHTTPStatusCode is returned when an unexpected HTTP status code is received.
	ErrHTTPStatusCode = errors.New("unexpected HTTP status code")
)

Functions

func SetLogger 

func SetLogger(l Logger)

SetLogger sets the logger.

func UnmarshalErrorMessage added in v1.10.0 

func UnmarshalErrorMessage(body []byte) error

UnmarshalErrorMessage unmarshals the error message from the Gitlab API.

Types

type CommitsService added in v1.16.0 

type CommitsService interface {
	//nolint:lll // GitLab API method signatures are inherently long
	ListCommits(pid any, opt *gitlab.ListCommitsOptions, options ...gitlab.RequestOptionFunc) ([]*gitlab.Commit, *gitlab.Response, error)
}

CommitsService defines the interface for GitLab Commits API operations.

type ErrorMessage added in v1.5.0 

type ErrorMessage struct {
	Message string `json:"message"`
}

ErrorMessage is a struct that contains an error message. It is returned by the Gitlab API when an error occurs.

type GitLabClient added in v1.13.0 

type GitLabClient interface {
	Groups() GroupsService
	Projects() ProjectsService
	ProjectImportExport() ProjectImportExportService
	Labels() LabelsService
	Issues() IssuesService
	Notes() NotesService
	Commits() CommitsService
}

GitLabClient defines the interface for GitLab client operations.

func NewGitLabClientWrapper added in v1.13.0 

func NewGitLabClientWrapper(client *gitlab.Client) GitLabClient

NewGitLabClientWrapper creates a new wrapper around the official GitLab client.

type GitLabService added in v1.16.2 

type GitLabService interface {
	// Client returns the underlying GitLab client for API operations.
	// The client provides access to all GitLab API services (Projects, Commits,
	// Issues, Labels, ProjectImportExport, etc.) through their respective
	// service interfaces.
	Client() GitLabClient

	// RateLimitImportAPI returns the import API rate limiter.
	// This limiter enforces GitLab's 6 requests/minute limit for import operations
	// to prevent API throttling and potential account restrictions.
	RateLimitImportAPI() *rate.Limiter
}

GitLabService defines the GitLab service operations needed for restore workflows. This interface enables testing of the restore orchestrator without requiring a real GitLab API connection.

The interface exposes only the minimal surface area required by the restore orchestrator, following the Interface Segregation Principle.

type Group added in v1.11.0 

type Group struct {
	ID   int64  `json:"id"`
	Name string `json:"name"`
}

Group represents a Gitlab group https://docs.gitlab.com/ee/api/groups.html struct fields are not exhaustive - most of them won't be used.

type GroupsService added in v1.13.0 

type GroupsService interface {
	//nolint:lll // GitLab API method signatures are inherently long
	GetGroup(gid any, opt *gitlab.GetGroupOptions, options ...gitlab.RequestOptionFunc) (*gitlab.Group, *gitlab.Response, error)
	//nolint:lll // GitLab API method signatures are inherently long
	ListSubGroups(gid any, opt *gitlab.ListSubGroupsOptions, options ...gitlab.RequestOptionFunc) ([]*gitlab.Group, *gitlab.Response, error)
	//nolint:lll // GitLab API method signatures are inherently long
	ListGroupProjects(gid any, opt *gitlab.ListGroupProjectsOptions, options ...gitlab.RequestOptionFunc) ([]*gitlab.Project, *gitlab.Response, error)
}

GroupsService defines the interface for GitLab Groups API operations.

type ImportService added in v1.16.0 

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

ImportService provides GitLab project import functionality.

func NewImportService added in v1.16.0 

func NewImportService(importExportService ProjectImportExportService) *ImportService

NewImportService creates a new import service instance.

func NewImportServiceWithRateLimiters added in v1.16.0 

func NewImportServiceWithRateLimiters(
	importExportService ProjectImportExportService,
	rateLimiterImport *rate.Limiter,
) *ImportService

NewImportServiceWithRateLimiters creates an import service with custom rate limiters.

func (*ImportService) ImportProject added in v1.16.0 

func (s *ImportService) ImportProject(
	ctx context.Context,
	archive io.Reader,
	namespace string,
	projectPath string,
) (*gitlabapi.ImportStatus, error)

ImportProject initiates a GitLab project import and waits for completion. It respects rate limiting and polls the import status until finished or failed.

Returns the final ImportStatus on success. Returns error if import initiation fails, import status becomes "failed", or timeout occurs.

func (*ImportService) WaitForImport added in v1.16.0 

func (s *ImportService) WaitForImport(
	ctx context.Context,
	projectID int64,
	timeout time.Duration,
) (*gitlabapi.ImportStatus, error)

WaitForImport polls the import status until it reaches a terminal state (finished or failed). It respects the context deadline and rate limiting.

Returns the final ImportStatus when import reaches "finished" state. Returns error if import fails, times out, or API errors occur.

type IssuesService added in v1.16.0 

type IssuesService interface {
	//nolint:lll // GitLab API method signatures are inherently long
	ListProjectIssues(pid any, opt *gitlab.ListProjectIssuesOptions, options ...gitlab.RequestOptionFunc) ([]*gitlab.Issue, *gitlab.Response, error)
	//nolint:lll // GitLab API method signatures are inherently long
	CreateIssue(pid any, opt *gitlab.CreateIssueOptions, options ...gitlab.RequestOptionFunc) (*gitlab.Issue, *gitlab.Response, error)
	//nolint:lll // GitLab API method signatures are inherently long
	UpdateIssue(pid any, issue int64, opt *gitlab.UpdateIssueOptions, options ...gitlab.RequestOptionFunc) (*gitlab.Issue, *gitlab.Response, error)
}

IssuesService defines the interface for GitLab Issues API operations.

type LabelsService added in v1.16.0 

type LabelsService interface {
	//nolint:lll // GitLab API method signatures are inherently long
	ListLabels(pid any, opt *gitlab.ListLabelsOptions, options ...gitlab.RequestOptionFunc) ([]*gitlab.Label, *gitlab.Response, error)
	//nolint:lll // GitLab API method signatures are inherently long
	CreateLabel(pid any, opt *gitlab.CreateLabelOptions, options ...gitlab.RequestOptionFunc) (*gitlab.Label, *gitlab.Response, error)
}

LabelsService defines the interface for GitLab Labels API operations.

type Logger 

type Logger interface {
	Debug(msg string, args ...any)
	Warn(msg string, args ...any)
	Error(msg string, args ...any)
	Info(msg string, args ...any)
}

Logger interface defines the logging methods used by GitLab service.

type NotesService added in v1.16.0 

type NotesService interface {
	//nolint:lll // GitLab API method signatures are inherently long
	CreateIssueNote(pid any, issue int64, opt *gitlab.CreateIssueNoteOptions, options ...gitlab.RequestOptionFunc) (*gitlab.Note, *gitlab.Response, error)
}

NotesService defines the interface for GitLab Notes API operations.

type Project added in v1.11.0 

type Project struct {
	ID           int64  `json:"id"`
	Name         string `json:"name"`
	Archived     bool   `json:"archived"`
	ExportStatus string `json:"export_status"`
}

Project represents a Gitlab project https://docs.gitlab.com/ee/api/projects.html struct fields are not exhaustive - most of them won't be used.

type ProjectImportExportService added in v1.13.0 

type ProjectImportExportService interface {
	//nolint:lll // GitLab API method signatures are inherently long
	ScheduleExport(pid any, opt *gitlab.ScheduleExportOptions, options ...gitlab.RequestOptionFunc) (*gitlab.Response, error)
	ExportStatus(pid any, options ...gitlab.RequestOptionFunc) (*gitlab.ExportStatus, *gitlab.Response, error)
	ExportDownloadStream(pid any, w io.Writer, options ...gitlab.RequestOptionFunc) (*gitlab.Response, error)
	//nolint:lll // GitLab API method signatures are inherently long
	ImportFromFile(archive io.Reader, opt *gitlab.ImportFileOptions, options ...gitlab.RequestOptionFunc) (*gitlab.ImportStatus, *gitlab.Response, error)
	ImportStatus(pid any, options ...gitlab.RequestOptionFunc) (*gitlab.ImportStatus, *gitlab.Response, error)
}

ProjectImportExportService defines the interface for GitLab Project Import/Export API operations.

type ProjectsService added in v1.13.0 

type ProjectsService interface {
	//nolint:lll // GitLab API method signatures are inherently long
	GetProject(pid any, opt *gitlab.GetProjectOptions, options ...gitlab.RequestOptionFunc) (*gitlab.Project, *gitlab.Response, error)
}

ProjectsService defines the interface for GitLab Projects API operations.

type Service added in v1.11.0 

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

Service provides methods to interact with GitLab API.

func NewGitlabService 

func NewGitlabService() *Service

NewGitlabService returns a new Service with default timeout.

func NewGitlabServiceWithTimeout added in v1.14.0 

func NewGitlabServiceWithTimeout(timeoutMins int) *Service

NewGitlabServiceWithTimeout returns a new Service with configurable timeout.

func (*Service) Client added in v1.16.0 

func (r *Service) Client() GitLabClient

Client returns the underlying GitLab client for advanced operations.

func (*Service) ExportProject added in v1.11.0 

func (s *Service) ExportProject(ctx context.Context, project *Project, archiveFilePath string) error

ExportProject exports the project to the given archive file path.

func (*Service) GetGroup added in v1.11.0 

func (r *Service) GetGroup(ctx context.Context, groupID int64) (Group, error)

GetGroup returns the gitlab group from the given ID.

func (*Service) GetProject added in v1.11.0 

func (r *Service) GetProject(ctx context.Context, projectID int64) (Project, error)

GetProject returns informations of the project that matches the given ID.

func (*Service) GetProjectsLst added in v1.11.0 

func (s *Service) GetProjectsLst(ctx context.Context, groupID int64) ([]Project, error)

GetProjectsLst returns the list of projects of the group.

func (*Service) GetProjectsOfGroup added in v1.11.0 

func (s *Service) GetProjectsOfGroup(ctx context.Context, groupID int64) ([]Project, error)

GetProjectsOfGroup returns the list of every projects of the group and subgroups.

func (*Service) GetSubgroups added in v1.11.0 

func (s *Service) GetSubgroups(ctx context.Context, groupID int64) ([]Group, error)

GetSubgroups returns the list of subgroups of the group. It's a recursive function that will return all subgroups of the group.

func (*Service) RateLimitImportAPI added in v1.16.0 

func (r *Service) RateLimitImportAPI() *rate.Limiter

RateLimitImportAPI returns the import API rate limiter.

func (*Service) SetGitlabEndpoint added in v1.11.0 

func (r *Service) SetGitlabEndpoint(gitlabAPIEndpoint string)

SetGitlabEndpoint sets the Gitlab API endpoint default: https://gitlab.com/v4/api/

func (*Service) SetToken added in v1.11.0 

func (r *Service) SetToken(token string)

SetToken sets the Gitlab API token default: GITLAB_TOKEN env variable

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.