packages

package
v2.3.0 Latest Latest
Warning

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

 Go to latest Published: Jun 28, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package packages implements MCP tools for GitLab Generic Packages registry operations.

The package supports publishing, downloading, streaming downloads to disk, listing packages and package files, deleting package records and files, and higher-level helpers such as publishing a release asset link or publishing all matching files in a directory. Markdown formatters render package outputs for individual tools and meta-tool dispatchers.

Large Payloads

Download helpers stream package files through bounded file utilities rather than forcing large artifacts into MCP text content. Metadata-oriented tools keep structured output compact and use Markdown tables for human review.

GitLab API References

The package wraps the GitLab Packages API:

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ActionSpecs 

func ActionSpecs(client *gitlabclient.Client) []toolutil.ActionSpec

ActionSpecs returns canonical specs for Generic Package Registry actions exposed as MCP tools. The publish, download, list, file list, delete, file delete, publish-and-link, and publish-directory routes are projected into the dynamic, meta, individual, and audit surfaces by the action catalog (ADR-0004).

func Delete 

func Delete(ctx context.Context, _ *mcp.CallToolRequest, client *gitlabclient.Client, input DeleteInput) error

Delete deletes a single Generic Package Registry package via the GitLab Packages API (DELETE /projects/:id/packages/:package_id). Requires Maintainer or Owner role on the project.

func FileDelete 

func FileDelete(ctx context.Context, _ *mcp.CallToolRequest, client *gitlabclient.Client, input FileDeleteInput) error

FileDelete deletes a single file from a Generic Package Registry package via the GitLab Packages API (DELETE /projects/:id/packages/:package_id/package_files/:file_id).

func FormatDownloadMarkdown 

func FormatDownloadMarkdown(out DownloadOutput) string

FormatDownloadMarkdown renders a downloaded package file as Markdown.

func FormatFileListMarkdown 

func FormatFileListMarkdown(out FileListOutput) string

FormatFileListMarkdown renders a paginated list of package files as a Markdown table.

func FormatGroupListMarkdown added in v2.3.0 

func FormatGroupListMarkdown(out GroupListOutput) string

FormatGroupListMarkdown renders a paginated list of group packages as a Markdown table.

func FormatListMarkdown 

func FormatListMarkdown(out ListOutput) string

FormatListMarkdown renders a paginated list of packages as a Markdown table.

func FormatPublishAndLinkMarkdown 

func FormatPublishAndLinkMarkdown(out PublishAndLinkOutput) string

FormatPublishAndLinkMarkdown renders a publish-and-link result as Markdown.

func FormatPublishDirMarkdown 

func FormatPublishDirMarkdown(out PublishDirOutput) string

FormatPublishDirMarkdown renders a directory publish result as Markdown.

func FormatPublishMarkdown 

func FormatPublishMarkdown(out PublishOutput) string

FormatPublishMarkdown renders a published package file as Markdown.

Types

type DeleteInput 

type DeleteInput struct {
	ProjectID toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
	PackageID toolutil.StringOrInt `json:"package_id" jsonschema:"Package ID to delete,required"`
}

DeleteInput defines input for deleting a package.

type DownloadInput 

type DownloadInput struct {
	ProjectID      toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
	PackageName    string               `json:"package_name" jsonschema:"Package name,required"`
	PackageVersion string               `json:"package_version" jsonschema:"Package version,required"`
	FileName       string               `json:"file_name" jsonschema:"File name to download,required"`
	OutputPath     string               `json:"output_path" jsonschema:"Absolute path where the file will be saved on the local filesystem,required"`
}

DownloadInput defines input for downloading a package file.

type DownloadOutput 

type DownloadOutput struct {
	toolutil.HintableOutput
	OutputPath string `json:"output_path"`
	Size       int64  `json:"size"`
	SHA256     string `json:"sha256"`
}

DownloadOutput contains the result of a package file download.

func Download 

func Download(ctx context.Context, req *mcp.CallToolRequest, client *gitlabclient.Client, input DownloadInput) (DownloadOutput, error)

Download downloads a single file from the GitLab Generic Package Registry via the GitLab Packages download API (GET /projects/:id/packages/generic/:package_name/:package_version/:file_name). The file is streamed to the local OutputPath, with the resulting size and SHA256 surfaced in the response.

type FileDeleteInput 

type FileDeleteInput struct {
	ProjectID     toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
	PackageID     toolutil.StringOrInt `json:"package_id" jsonschema:"Package ID,required"`
	PackageFileID toolutil.StringOrInt `json:"package_file_id" jsonschema:"Package file ID to delete,required"`
}

FileDeleteInput defines input for deleting a single file from a package.

type FileListInput 

type FileListInput struct {
	ProjectID toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
	PackageID toolutil.StringOrInt `json:"package_id" jsonschema:"Package ID,required"`
	OrderBy   string               `json:"order_by,omitempty" jsonschema:"Order package files by: created_at, file_name, or id"`
	Sort      string               `json:"sort,omitempty" jsonschema:"Sort direction: asc or desc"`
	toolutil.PaginationInput
	toolutil.KeysetPaginationInput
}

FileListInput defines input for listing files within a package.

type FileListItem 

type FileListItem struct {
	PackageFileID int64  `json:"package_file_id"`
	PackageID     int64  `json:"package_id"`
	FileName      string `json:"file_name"`
	Size          int64  `json:"size"`
	SHA256        string `json:"sha256"`
	FileMD5       string `json:"file_md5,omitempty"`
	FileSHA1      string `json:"file_sha1,omitempty"`
	CreatedAt     string `json:"created_at,omitempty"`
}

FileListItem represents a single file within a package.

type FileListOutput 

type FileListOutput struct {
	toolutil.HintableOutput
	Files      []FileListItem            `json:"files"`
	Pagination toolutil.PaginationOutput `json:"pagination"`
}

FileListOutput contains the paginated list of package files.

func FileList 

func FileList(ctx context.Context, client *gitlabclient.Client, input FileListInput) (FileListOutput, error)

FileList lists the files within a single Generic Package Registry package via the GitLab Packages file list API (GET /projects/:id/packages/:package_id/package_files).

type GroupListInput added in v2.3.0 

type GroupListInput struct {
	GroupID            toolutil.StringOrInt `json:"group_id" jsonschema:"Group ID or URL-encoded path,required"`
	ExcludeSubgroups   bool                 `` /* 135-byte string literal not displayed */
	PackageName        string               `json:"package_name,omitempty" jsonschema:"Filter by package name"`
	PackageType        string               `json:"package_type,omitempty" jsonschema:"Filter by type (generic, npm, maven, etc.)"`
	OrderBy            string               `json:"order_by,omitempty" jsonschema:"Order by: name, created_at, version, type, project_path"`
	Sort               string               `json:"sort,omitempty" jsonschema:"Sort direction: asc or desc"`
	IncludeVersionless bool                 `json:"include_versionless,omitempty" jsonschema:"Include versionless packages"`
	Status             string               `json:"status,omitempty" jsonschema:"Filter by status: default, hidden, processing, error"`
	toolutil.PaginationInput
	toolutil.KeysetPaginationInput
}

GroupListInput defines input for listing packages across a group and its descendant projects.

type GroupListItem added in v2.3.0 

type GroupListItem struct {
	ListItem
	ProjectID   int64  `json:"project_id"`
	ProjectPath string `json:"project_path,omitempty"`
}

GroupListItem represents a single package in the group list output. It mirrors the GitLab Packages API gl.GroupPackage object, which embeds the project-scoped gl.Package fields and adds the owning project's ID and path.

type GroupListOutput added in v2.3.0 

type GroupListOutput struct {
	toolutil.HintableOutput
	Packages   []GroupListItem           `json:"packages"`
	Pagination toolutil.PaginationOutput `json:"pagination"`
}

GroupListOutput contains the paginated list of group packages.

func GroupList added in v2.3.0 

func GroupList(ctx context.Context, client *gitlabclient.Client, input GroupListInput) (GroupListOutput, error)

GroupList retrieves a paginated list of packages across a group and its descendant projects via the GitLab group Packages list API (GET /groups/:id/packages). Each item carries the owning project's ID and path in addition to the project-scoped package fields.

type LinksItem added in v2.3.0 

type LinksItem struct {
	WebPath       string `json:"web_path,omitempty"`
	DeleteAPIPath string `json:"delete_api_path,omitempty"`
}

LinksItem mirrors the GitLab Packages API gl.PackageLinks object, holding the package's web path and delete API path.

type ListInput 

type ListInput struct {
	ProjectID          toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
	PackageName        string               `json:"package_name,omitempty" jsonschema:"Filter by package name"`
	PackageVersion     string               `json:"package_version,omitempty" jsonschema:"Filter by package version"`
	PackageType        string               `json:"package_type,omitempty" jsonschema:"Filter by type (generic, npm, maven, etc.)"`
	OrderBy            string               `json:"order_by,omitempty" jsonschema:"Order by: name, created_at, version, type"`
	Sort               string               `json:"sort,omitempty" jsonschema:"Sort direction: asc or desc"`
	IncludeVersionless bool                 `json:"include_versionless,omitempty" jsonschema:"Include versionless packages"`
	Status             string               `json:"status,omitempty" jsonschema:"Filter by status: default, hidden, processing, error"`
	toolutil.PaginationInput
	toolutil.KeysetPaginationInput
}

ListInput defines input for listing project packages.

type ListItem 

type ListItem struct {
	ID               int64          `json:"id"`
	Name             string         `json:"name"`
	Version          string         `json:"version"`
	PackageType      string         `json:"package_type"`
	Status           string         `json:"status"`
	Links            *LinksItem     `json:"_links,omitempty"`
	Pipeline         *PipelineItem  `json:"pipeline,omitempty"`
	Pipelines        []PipelineItem `json:"pipelines,omitempty"`
	CreatedAt        string         `json:"created_at,omitempty"`
	LastDownloadedAt string         `json:"last_downloaded_at,omitempty"`
	Tags             []TagItem      `json:"tags,omitempty"`
}

ListItem represents a single package in the list output. It mirrors the GitLab Packages API gl.Package object, surfacing the full nested _links, pipeline, pipelines, and tags sub-objects.

type ListOutput 

type ListOutput struct {
	toolutil.HintableOutput
	Packages   []ListItem                `json:"packages"`
	Pagination toolutil.PaginationOutput `json:"pagination"`
}

ListOutput contains the paginated list of packages.

func List 

func List(ctx context.Context, client *gitlabclient.Client, input ListInput) (ListOutput, error)

List retrieves a paginated list of Generic Package Registry packages in a project via the GitLab Packages list API (GET /projects/:id/packages). Optional filters narrow by package name, version, status, and the [buildListOptions] sort field.

type PipelineItem 

type PipelineItem struct {
	ID        int64         `json:"id"`
	Status    string        `json:"status"`
	Ref       string        `json:"ref"`
	SHA       string        `json:"sha"`
	WebURL    string        `json:"web_url"`
	CreatedAt string        `json:"created_at,omitempty"`
	UpdatedAt string        `json:"updated_at,omitempty"`
	User      *PipelineUser `json:"user,omitempty"`
}

PipelineItem represents CI pipeline metadata attached to a package.

type PipelineUser 

type PipelineUser struct {
	ID        int64  `json:"id"`
	Username  string `json:"username"`
	Name      string `json:"name"`
	State     string `json:"state,omitempty"`
	AvatarURL string `json:"avatar_url,omitempty"`
	WebURL    string `json:"web_url"`
	CreatedAt string `json:"created_at,omitempty"`
}

PipelineUser mirrors the GitLab gl.BasicUser object attached to package pipeline metadata.

type PublishAndLinkInput 

type PublishAndLinkInput struct {
	ProjectID      toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
	PackageName    string               `json:"package_name" jsonschema:"Package name (alphanumeric, dots, dashes, underscores),required"`
	PackageVersion string               `json:"package_version" jsonschema:"Package version (e.g. 1.0.0),required"`
	FileName       string               `json:"file_name" jsonschema:"Name of the file within the package,required"`
	FilePath       string               `json:"file_path,omitempty" jsonschema:"Absolute path to a local file. Alternative to content_base64."`
	ContentBase64  string               `json:"content_base64,omitempty" jsonschema:"Base64-encoded file content. Alternative to file_path."`
	Status         string               `json:"status,omitempty" jsonschema:"Package status: default or hidden"`
	TagName        string               `json:"tag_name" jsonschema:"Tag name of the release to link the package file to,required"`
	LinkName       string               `` /* 170-byte string literal not displayed */
	LinkType       string               `json:"link_type,omitempty" jsonschema:"Type of the release link: package, runbook, image, or other. Defaults to package."`
}

PublishAndLinkInput defines input for publishing a file to the Generic Package Registry and creating a release asset link in one step.

type PublishAndLinkOutput 

type PublishAndLinkOutput struct {
	toolutil.HintableOutput
	Package     PublishOutput       `json:"package"`
	ReleaseLink releaselinks.Output `json:"release_link"`
}

PublishAndLinkOutput contains the results of both the publish and release link creation operations. 

func PublishAndLink(ctx context.Context, req *mcp.CallToolRequest, client *gitlabclient.Client, input PublishAndLinkInput) (PublishAndLinkOutput, error)

PublishAndLink publishes a file to the Generic Package Registry and then creates a release asset link pointing to it. If the publish succeeds but the link creation fails, the package file remains published and the error includes the package details so the caller can retry the link.

type PublishDirInput 

type PublishDirInput struct {
	ProjectID      toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
	PackageName    string               `json:"package_name" jsonschema:"Package name (alphanumeric, dots, dashes, underscores),required"`
	PackageVersion string               `json:"package_version" jsonschema:"Package version (e.g. 1.0.0),required"`
	DirectoryPath  string               `json:"directory_path" jsonschema:"Absolute path to a local directory whose files will be published,required"`
	IncludePattern string               `` /* 211-byte string literal not displayed */
	Status         string               `json:"status,omitempty" jsonschema:"Package status: default or hidden"`
}

PublishDirInput defines input for publishing all matching files in a directory to the Generic Package Registry.

type PublishDirItem 

type PublishDirItem struct {
	FileName      string `json:"file_name"`
	PackageFileID int64  `json:"package_file_id"`
	Size          int64  `json:"size"`
	SHA256        string `json:"sha256"`
	URL           string `json:"url"`
}

PublishDirItem represents a single file published from a directory.

type PublishDirOutput 

type PublishDirOutput struct {
	toolutil.HintableOutput
	Published  []PublishDirItem `json:"published"`
	TotalFiles int              `json:"total_files"`
	TotalBytes int64            `json:"total_bytes"`
	Errors     []string         `json:"errors,omitempty"`
}

PublishDirOutput contains the aggregated results of publishing all matching files from a directory.

func PublishDirectory 

func PublishDirectory(ctx context.Context, req *mcp.CallToolRequest, client *gitlabclient.Client, input PublishDirInput) (PublishDirOutput, error)

PublishDirectory walks a directory, filters files by an optional glob pattern, and publishes each matching regular file to the Generic Package Registry. It continues on individual file errors and reports them in output.

type PublishInput 

type PublishInput struct {
	ProjectID      toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
	PackageName    string               `json:"package_name" jsonschema:"Package name (alphanumeric, dots, dashes, underscores),required"`
	PackageVersion string               `json:"package_version" jsonschema:"Package version (e.g. 1.0.0),required"`
	FileName       string               `json:"file_name" jsonschema:"Name of the file within the package,required"`
	FilePath       string               `` /* 161-byte string literal not displayed */
	ContentBase64  string               `json:"content_base64,omitempty" jsonschema:"Base64-encoded file content. Only one should be provided."`
	Status         string               `json:"status,omitempty" jsonschema:"Package status: default or hidden"`
	Select         string               `` /* 174-byte string literal not displayed */
}

PublishInput defines input for publishing a file to the Generic Package Registry.

type PublishOutput 

type PublishOutput struct {
	toolutil.HintableOutput
	PackageFileID int64  `json:"package_file_id"`
	PackageID     int64  `json:"package_id"`
	FileName      string `json:"file_name"`
	Size          int64  `json:"size"`
	SHA256        string `json:"sha256"`
	FileMD5       string `json:"file_md5,omitempty"`
	FileSHA1      string `json:"file_sha1,omitempty"`
	FileStore     int64  `json:"file_store"`
	CreatedAt     string `json:"created_at,omitempty"`
	UpdatedAt     string `json:"updated_at,omitempty"`
	URL           string `json:"url"`
}

PublishOutput contains the result of a package file publish operation.

func Publish 

func Publish(ctx context.Context, req *mcp.CallToolRequest, client *gitlabclient.Client, input PublishInput) (PublishOutput, error)

Publish publishes a file to the GitLab Generic Package Registry.

type TagItem added in v2.3.0 

type TagItem struct {
	ID        int64  `json:"id"`
	PackageID int64  `json:"package_id"`
	Name      string `json:"name"`
	CreatedAt string `json:"created_at,omitempty"`
	UpdatedAt string `json:"updated_at,omitempty"`
}

TagItem mirrors the GitLab Packages API gl.PackageTag object.

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.