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

packages

package
v3.4.0 Latest Latest
Warning

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

 Go to latest Published: Oct 30, 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, group list, get, 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 the card of one object.

func FormatFileListMarkdown 

func FormatFileListMarkdown(out FileListOutput) string

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

func FormatGetMarkdown added in v3.1.0 

func FormatGetMarkdown(out GetOutput) string

FormatGetMarkdown renders one package as the card of one object: its own fields, the pipeline that last built it, and the package's other versions as a nested table, which only this read is sent. It offers package.download only for a generic package, the one type whose files that action can fetch.

func FormatGroupListMarkdown 

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 one card with a section per object: the package file and the release link it now has.

func FormatPublishDirMarkdown 

func FormatPublishDirMarkdown(out PublishDirOutput) string

FormatPublishDirMarkdown renders a directory publish result as the card of one object.

The heading names the outcome rather than always claiming success: a run where every file failed used to be headed "Directory Published" with an errors section under it, which is the opposite of what happened. The count is published out of the two lists too, because TotalFiles is the number of files that succeeded and reads as the number attempted.

func FormatPublishMarkdown 

func FormatPublishMarkdown(out PublishOutput) string

FormatPublishMarkdown renders a published package file as the card of one object.

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 DetailItem added in v3.1.0 

type DetailItem struct {
	ListItem
	Versions []toolutil.PackageVersionOutput `json:"versions,omitempty"`
}

DetailItem is one package as a request for it publishes: every field the project's listing publishes for it, and the package's other versions, which GitLab sends only to this read and never on a page of packages.

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               `` /* 149-byte string literal not displayed */
	OutputPath     string               `` /* 305-byte string literal not displayed */
}

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: id (default), file_name, or created_at"`
	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:"id"`
	PackageID     int64  `json:"package_id"`
	FileName      string `json:"file_name"`
	Size          int64  `json:"size"`
	SHA256        string `json:"file_sha256"`
	FileMD5       string `json:"file_md5,omitempty"`
	FileSHA1      string `json:"file_sha1,omitempty"`
	CreatedAt     string `json:"created_at,omitempty"`
	// Pipelines are the pipelines that built the file, which
	// lib/api/entities/package_file.rb sends when there is one and the caller
	// may read the project's pipelines. client-go decodes each into its
	// Pipeline, which carries every key but the two its BasicUser leaves out of
	// the user who ran it; those are read off the captured response.
	Pipelines []toolutil.PackagePipelineOutput `json:"pipelines,omitempty"`
}

FileListItem represents a single file within a package, under the keys Entities::PackageFile sends it with: the file's own id as id, which is the package_file_id package.file_delete takes, and its digest as file_sha256.

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 GetInput added in v3.1.0 

type GetInput struct {
	ProjectID toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
	PackageID toolutil.StringOrInt `json:"package_id" jsonschema:"Package ID, as package.list or package.group_list returns it,required"`
}

GetInput defines input for retrieving one package of a project.

type GetOutput added in v3.1.0 

type GetOutput struct {
	toolutil.HintableOutput
	Package DetailItem `json:"package"`
}

GetOutput is one package: every field package.list publishes, and the package's other versions, which only this read is sent.

func Get added in v3.1.0 

func Get(ctx context.Context, client *gitlabclient.Client, input GetInput) (GetOutput, error)

Get retrieves one package of a project via the GitLab Packages API (GET /projects/:id/packages/:package_id), the only endpoint that sends the package's other versions.

client-go decodes every field package.list publishes, and the other versions with their tags; the three keys of each pipeline that its PackagePipeline leaves out, and two of the user who ran it, are read from the captured response beside that decode (ADR-0021), on the package's own pipeline and on those of its other versions alike.

type GroupListInput 

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"`
	PackageVersion     string               `` /* 177-byte string literal not displayed */
	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 

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 

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

GroupListOutput contains the paginated list of group packages.

func GroupList 

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, and the pipeline's five keys client-go does not decode are read from the captured response as List reads them.

type LinksItem 

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"`
	// ConanPackageName is the recipe's own name, sent for a Conan package.
	ConanPackageName string     `json:"conan_package_name,omitempty"`
	Links            *LinksItem `json:"_links,omitempty"`
	// Pipeline is the pipeline that last built the package, with every key
	// GitLab's pipeline entity sends, five of them read from the captured
	// response because client-go's PackagePipeline and BasicUser leave them
	// out.
	Pipeline         *toolutil.PackagePipelineOutput `json:"pipeline,omitempty"`
	CreatedAt        string                          `json:"created_at,omitempty"`
	LastDownloadedAt string                          `json:"last_downloaded_at,omitempty"`
	CreatorID        int64                           `json:"creator_id,omitempty"`
	Tags             []toolutil.PackageTagOutput     `json:"tags,omitempty"`
}

ListItem represents a single package as the project listing publishes it, and as the group listing and a request for one package publish it beside what each of them adds. It mirrors the GitLab Packages API gl.Package object, surfacing the full nested _links, pipeline and tags sub-objects.

Three keys of GitLab's entity are deliberately not here. The owning project's id and path are exposed only when it renders a group's listing, where GroupListItem publishes them, and the package's other versions only when it renders one package rather than a page, where DetailItem publishes them; on this item each was a key the schema offered and no answer filled. The entity's pipelines key is not published anywhere: lib/api/entities/ package.rb renders it as the constant EMPTY_PIPELINES whatever the package, which is how GitLab deprecated it in 16.1, and the pipeline that last built the package is under pipeline.

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.

The five keys of each package's pipeline that client-go does not decode are read from the captured response beside that decode (ADR-0021).

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               `` /* 167-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               `` /* 163-byte string literal not displayed */
	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.

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.