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

environments

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: 11 Imported by: 0

Documentation

Overview

Package environments implements MCP tools for GitLab environment operations.

The package wraps the GitLab Environments 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 environment actions.

func Delete 

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

Delete deletes an environment from a project.

func FormatListMarkdown 

func FormatListMarkdown(out ListOutput) string

FormatListMarkdown renders a page of a project's environments as a Markdown table.

func FormatOutputMarkdown 

func FormatOutputMarkdown(e Output) string

FormatOutputMarkdown renders one environment as the card of a single object: its own fields, the project and cluster agent as nested objects, and the deployment that put the code there as a section of its own.

Types

type ClusterAgentOutput 

type ClusterAgentOutput struct {
	ID              int64                `json:"id"`
	Name            string               `json:"name"`
	ConfigProject   *ConfigProjectOutput `json:"config_project,omitempty"`
	CreatedAt       string               `json:"created_at,omitempty"`
	CreatedByUserID int64                `json:"created_by_user_id,omitempty"`
}

ClusterAgentOutput mirrors the environment `cluster_agent` object documented in the "Retrieve an environment" response (doc/api/environments.md): id, name, config_project, created_at, created_by_user_id.

Documented reference subset per doc/api/environments.md

type ConfigProjectOutput 

type ConfigProjectOutput struct {
	ID                int64  `json:"id"`
	Description       string `json:"description"`
	Name              string `json:"name"`
	NameWithNamespace string `json:"name_with_namespace,omitempty"`
	Path              string `json:"path,omitempty"`
	PathWithNamespace string `json:"path_with_namespace,omitempty"`
	CreatedAt         string `json:"created_at,omitempty"`
}

ConfigProjectOutput mirrors the `cluster_agent.config_project` object documented in the "Retrieve an environment" response (doc/api/environments.md): id, description, name, name_with_namespace, path, path_with_namespace, created_at.

Documented reference subset per doc/api/environments.md

type CreateInput 

type CreateInput struct {
	ProjectID           toolutil.StringOrInt `json:"project_id"             jsonschema:"Project ID or URL-encoded path,required"`
	Name                string               `json:"name"                   jsonschema:"Environment name (e.g. production, staging),required"`
	Description         string               `json:"description,omitempty"  jsonschema:"Description of the environment"`
	ExternalURL         string               `json:"external_url,omitempty" jsonschema:"URL of the environment's external deployment"`
	Tier                string               `json:"tier,omitempty"         jsonschema:"Deployment tier: production, staging, testing, development, other"`
	ClusterAgentID      *int64               `json:"cluster_agent_id,omitempty"      jsonschema:"ID of the cluster agent to associate with this environment"`
	KubernetesNamespace string               `json:"kubernetes_namespace,omitempty"  jsonschema:"Kubernetes namespace for the cluster agent"`
	FluxResourcePath    string               `json:"flux_resource_path,omitempty"    jsonschema:"Flux resource path used to track the environment's deployment status"`
	AutoStopSetting     string               `json:"auto_stop_setting,omitempty"     jsonschema:"Auto-stop behavior: always or with_action"`
}

CreateInput defines parameters for creating an environment.

type DeleteInput 

type DeleteInput struct {
	ProjectID     toolutil.StringOrInt `json:"project_id"      jsonschema:"Project ID or URL-encoded path,required"`
	EnvironmentID int64                `json:"environment_id"  jsonschema:"Environment ID,required"`
}

DeleteInput defines parameters for deleting an environment.

type DeployableCommitOutput 

type DeployableCommitOutput struct {
	ID             string   `json:"id"`
	ShortID        string   `json:"short_id,omitempty"`
	CreatedAt      string   `json:"created_at,omitempty"`
	ParentIDs      []string `json:"parent_ids,omitempty"`
	Title          string   `json:"title,omitempty"`
	Message        string   `json:"message,omitempty"`
	AuthorName     string   `json:"author_name,omitempty"`
	AuthorEmail    string   `json:"author_email,omitempty"`
	AuthoredDate   string   `json:"authored_date,omitempty"`
	CommitterName  string   `json:"committer_name,omitempty"`
	CommitterEmail string   `json:"committer_email,omitempty"`
	CommittedDate  string   `json:"committed_date,omitempty"`
}

DeployableCommitOutput mirrors the `deployable.commit` object documented in the "Retrieve an environment" response (doc/api/environments.md): id, short_id, created_at, parent_ids, title, message, author_name, author_email, authored_date, committer_name, committer_email, committed_date.

Documented reference subset per doc/api/environments.md

type DeployableOutput 

type DeployableOutput struct {
	ID         int64                     `json:"id"`
	Status     string                    `json:"status,omitempty"`
	Stage      string                    `json:"stage,omitempty"`
	Name       string                    `json:"name,omitempty"`
	Ref        string                    `json:"ref,omitempty"`
	Tag        bool                      `json:"tag,omitempty"`
	Coverage   float64                   `json:"coverage,omitempty"`
	CreatedAt  string                    `json:"created_at,omitempty"`
	StartedAt  string                    `json:"started_at,omitempty"`
	FinishedAt string                    `json:"finished_at,omitempty"`
	Duration   float64                   `json:"duration,omitempty"`
	User       *DeployableUserOutput     `json:"user,omitempty"`
	Commit     *DeployableCommitOutput   `json:"commit,omitempty"`
	Pipeline   *DeployablePipelineOutput `json:"pipeline,omitempty"`
	Runner     *DeployableRunnerOutput   `json:"runner,omitempty"`
}

DeployableOutput mirrors the `last_deployment.deployable` job object documented in the "Retrieve an environment" response (doc/api/environments.md): id, status, stage, name, ref, tag, coverage, created_at, started_at, finished_at, duration, user, commit, pipeline, runner. The documented `project` (ci_job_token_scope_enabled), `web_url`, `artifacts`, and `artifacts_expire_at` fields are not present on the client-go DeploymentDeployable struct (v2.42.0) and therefore cannot be surfaced.

Documented reference subset per doc/api/environments.md

type DeployablePipelineOutput 

type DeployablePipelineOutput struct {
	ID     int64  `json:"id"`
	SHA    string `json:"sha,omitempty"`
	Ref    string `json:"ref,omitempty"`
	Status string `json:"status,omitempty"`
	WebURL string `json:"web_url,omitempty"`
}

DeployablePipelineOutput mirrors the `deployable.pipeline` object documented in the "Retrieve an environment" response (doc/api/environments.md): id, sha, ref, status, web_url.

Documented reference subset per doc/api/environments.md

type DeployableRunnerOutput 

type DeployableRunnerOutput struct {
	ID          int64  `json:"id"`
	Description string `json:"description,omitempty"`
	Name        string `json:"name,omitempty"`
	IsShared    bool   `json:"is_shared,omitempty"`
	RunnerType  string `json:"runner_type,omitempty"`
	Online      bool   `json:"online,omitempty"`
	Status      string `json:"status,omitempty"`
}

DeployableRunnerOutput mirrors the `deployable.runner` object documented in the "Retrieve an environment" response (doc/api/environments.md). The documented example shows `runner` as null, so its shape is reduced to the canonical runner identity fields exposed by the client-go Runner struct.

Documented reference subset per doc/api/environments.md

type DeployableUserOutput 

type DeployableUserOutput struct {
	ID           int64  `json:"id"`
	Name         string `json:"name"`
	Username     string `json:"username,omitempty"`
	State        string `json:"state,omitempty"`
	AvatarURL    string `json:"avatar_url,omitempty"`
	WebURL       string `json:"web_url,omitempty"`
	CreatedAt    string `json:"created_at,omitempty"`
	Bio          string `json:"bio,omitempty"`
	Location     string `json:"location,omitempty"`
	PublicEmail  string `json:"public_email,omitempty"`
	Linkedin     string `json:"linkedin,omitempty"`
	Twitter      string `json:"twitter,omitempty"`
	WebsiteURL   string `json:"website_url,omitempty"`
	Organization string `json:"organization,omitempty"`
}

DeployableUserOutput mirrors the `deployable.user` object documented in the "Retrieve an environment" response (doc/api/environments.md): id, name, username, state, avatar_url, web_url, created_at, bio, location, public_email, linkedin, twitter, website_url, organization.

Documented reference subset per doc/api/environments.md

type DeploymentOutput 

type DeploymentOutput struct {
	ID         int64                 `json:"id"`
	IID        int64                 `json:"iid,omitempty"`
	Ref        string                `json:"ref,omitempty"`
	SHA        string                `json:"sha,omitempty"`
	CreatedAt  string                `json:"created_at,omitempty"`
	Status     string                `json:"status,omitempty"`
	User       *DeploymentUserOutput `json:"user,omitempty"`
	Deployable *DeployableOutput     `json:"deployable,omitempty"`
}

DeploymentOutput mirrors the environment `last_deployment` object documented in the "Retrieve an environment" response (doc/api/environments.md): id, iid, ref, sha, created_at, status, user, deployable. The deployment's back-reference to its environment is intentionally omitted to avoid the recursive Environment -> last_deployment -> environment cycle, and `updated_at` is omitted because the documented last_deployment object does not include it.

Documented reference subset per doc/api/environments.md

type DeploymentUserOutput 

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

DeploymentUserOutput mirrors the `last_deployment.user` object documented in the "Retrieve an environment" response (doc/api/environments.md): id, name, state, username, avatar_url, web_url.

Documented reference subset per doc/api/environments.md

type GetInput 

type GetInput struct {
	ProjectID     toolutil.StringOrInt `json:"project_id"      jsonschema:"Project ID or URL-encoded path,required"`
	EnvironmentID int64                `json:"environment_id"  jsonschema:"Environment ID,required"`
}

GetInput defines parameters for getting a single environment.

type ListInput 

type ListInput struct {
	ProjectID toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
	Name      string               `json:"name,omitempty"   jsonschema:"Filter by exact environment name"`
	Search    string               `json:"search,omitempty" jsonschema:"Search environments by name (fuzzy)"`
	States    string               `json:"states,omitempty" jsonschema:"Filter by state: available, stopping, stopped"`
	OrderBy   string               `json:"order_by,omitempty" jsonschema:"Column to order results by (e.g. id, name)"`
	Sort      string               `json:"sort,omitempty"     jsonschema:"Sort order: asc or desc"`
	toolutil.PaginationInput
	toolutil.KeysetPaginationInput
}

ListInput defines parameters for listing project environments.

type ListOutput 

type ListOutput struct {
	toolutil.HintableOutput
	Environments []Output                  `json:"environments"`
	Pagination   toolutil.PaginationOutput `json:"pagination"`
}

ListOutput holds a paginated list of environments.

func List 

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

List retrieves all environments for a project.

type Output 

type Output struct {
	toolutil.HintableOutput
	ID                  int64  `json:"id"`
	Name                string `json:"name"`
	Slug                string `json:"slug"`
	Description         string `json:"description,omitempty"`
	State               string `json:"state"`
	Tier                string `json:"tier,omitempty"`
	ExternalURL         string `json:"external_url,omitempty"`
	CreatedAt           string `json:"created_at,omitempty"`
	UpdatedAt           string `json:"updated_at,omitempty"`
	AutoStopAt          string `json:"auto_stop_at,omitempty"`
	AutoStopSetting     string `json:"auto_stop_setting,omitempty"`
	KubernetesNamespace string `json:"kubernetes_namespace,omitempty"`
	FluxResourcePath    string `json:"flux_resource_path,omitempty"`

	// Project is the project the environment belongs to, as the basic project
	// details GitLab renders under it.
	Project *ProjectOutput `json:"project,omitempty"`
	// ClusterAgent is the cluster agent associated with the environment, when set.
	ClusterAgent *ClusterAgentOutput `json:"cluster_agent,omitempty"`
	// LastDeployment is the most recent deployment to this environment, when present.
	LastDeployment *DeploymentOutput `json:"last_deployment,omitempty"`
}

Output represents a single GitLab environment.

func Create 

func Create(ctx context.Context, client *gitlabclient.Client, input CreateInput) (Output, error)

Create creates a new environment in a project.

func Get 

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

Get retrieves a single environment by ID.

func Stop 

func Stop(ctx context.Context, client *gitlabclient.Client, input StopInput) (Output, error)

Stop stops an active environment.

func Update 

func Update(ctx context.Context, client *gitlabclient.Client, input UpdateInput) (Output, error)

Update updates an existing environment.

type ProjectLicenseOutput 

type ProjectLicenseOutput struct {
	Key       string `json:"key"`
	Name      string `json:"name"`
	Nickname  string `json:"nickname,omitempty"`
	HTMLURL   string `json:"html_url,omitempty"`
	SourceURL string `json:"source_url,omitempty"`
}

ProjectLicenseOutput mirrors the license object under that project.

type ProjectNamespaceOutput 

type ProjectNamespaceOutput struct {
	ID        int64  `json:"id"`
	Name      string `json:"name"`
	Path      string `json:"path,omitempty"`
	Kind      string `json:"kind,omitempty"`
	FullPath  string `json:"full_path,omitempty"`
	ParentID  int64  `json:"parent_id,omitempty"`
	AvatarURL string `json:"avatar_url,omitempty"`
	WebURL    string `json:"web_url,omitempty"`
}

ProjectNamespaceOutput mirrors the namespace object under that project.

type ProjectOutput 

type ProjectOutput struct {
	ID                int64                            `json:"id"`
	Description       string                           `json:"description,omitempty"`
	Name              string                           `json:"name"`
	NameWithNamespace string                           `json:"name_with_namespace,omitempty"`
	Path              string                           `json:"path,omitempty"`
	PathWithNamespace string                           `json:"path_with_namespace,omitempty"`
	CreatedAt         string                           `json:"created_at,omitempty"`
	DefaultBranch     string                           `json:"default_branch,omitempty"`
	TagList           []string                         `json:"tag_list,omitempty"`
	Topics            []string                         `json:"topics,omitempty"`
	SSHURLToRepo      string                           `json:"ssh_url_to_repo,omitempty"`
	HTTPURLToRepo     string                           `json:"http_url_to_repo,omitempty"`
	WebURL            string                           `json:"web_url,omitempty"`
	ReadmeURL         string                           `json:"readme_url,omitempty"`
	ForksCount        int64                            `json:"forks_count"`
	LicenseURL        string                           `json:"license_url,omitempty"`
	License           *ProjectLicenseOutput            `json:"license,omitempty"`
	AvatarURL         string                           `json:"avatar_url,omitempty"`
	StarCount         int64                            `json:"star_count"`
	LastActivityAt    string                           `json:"last_activity_at,omitempty"`
	Visibility        string                           `json:"visibility,omitempty"`
	Namespace         *ProjectNamespaceOutput          `json:"namespace,omitempty"`
	CustomAttributes  []toolutil.CustomAttributeOutput `json:"custom_attributes,omitempty"`
	RepositoryStorage string                           `json:"repository_storage,omitempty"`
}

ProjectOutput mirrors the project object GitLab renders on an environment, which is lib/api/entities/basic_project_details.rb and not a whole project: twenty-four keys, every one of them carried by the SDK's own Project.

type StopInput 

type StopInput struct {
	ProjectID     toolutil.StringOrInt `json:"project_id"          jsonschema:"Project ID or URL-encoded path,required"`
	EnvironmentID int64                `json:"environment_id"      jsonschema:"Environment ID,required"`
	Force         *bool                `json:"force,omitempty"     jsonschema:"Force stop even if environment has active deployments"`
}

StopInput defines parameters for stopping an environment.

type UpdateInput 

type UpdateInput struct {
	ProjectID           toolutil.StringOrInt `json:"project_id"             jsonschema:"Project ID or URL-encoded path,required"`
	EnvironmentID       int64                `json:"environment_id"         jsonschema:"Environment ID,required"`
	Name                string               `json:"name,omitempty"         jsonschema:"New environment name"`
	Description         *string              `` /* 135-byte string literal not displayed */
	ExternalURL         *string              `` /* 136-byte string literal not displayed */
	Tier                string               `json:"tier,omitempty"         jsonschema:"Updated tier: production, staging, testing, development, other"`
	ClusterAgentID      *int64               `json:"cluster_agent_id,omitempty"      jsonschema:"ID of the cluster agent to associate with this environment"`
	KubernetesNamespace string               `json:"kubernetes_namespace,omitempty"  jsonschema:"Kubernetes namespace for the cluster agent"`
	FluxResourcePath    string               `json:"flux_resource_path,omitempty"    jsonschema:"Flux resource path used to track the environment's deployment status"`
	AutoStopSetting     string               `json:"auto_stop_setting,omitempty"     jsonschema:"Auto-stop behavior: always or with_action"`
}

UpdateInput defines parameters for updating an environment.

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.