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

runners

package
v3.2.0 Latest Latest
Warning

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

 Go to latest Published: Oct 9, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package runners implements MCP tools for GitLab runner operations.

The package wraps the GitLab Runners 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 runner and runner controller actions.

func DeleteByID 

func DeleteByID(ctx context.Context, client *gitlabclient.Client, input DeleteByIDInput) error

DeleteByID deletes a registered runner by its ID.

func DeleteByToken 

func DeleteByToken(ctx context.Context, client *gitlabclient.Client, input DeleteByTokenInput) error

DeleteByToken deletes a registered runner using its authentication token.

func DisableProject 

func DisableProject(ctx context.Context, client *gitlabclient.Client, input DisableProjectInput) error

DisableProject removes a runner from a project.

func FormatAuthTokenMarkdown 

func FormatAuthTokenMarkdown(out AuthTokenOutput) string

FormatAuthTokenMarkdown renders the authentication token a runner reset answered with: the secret GitLab shows once, and when it expires.

func FormatDetailsMarkdown 

func FormatDetailsMarkdown(out DetailsOutput) string

FormatDetailsMarkdown renders one runner in full: its configuration, then the projects and groups it serves as nested collections.

func FormatJobListMarkdown 

func FormatJobListMarkdown(out JobListOutput) string

FormatJobListMarkdown renders the jobs a runner has processed as a Markdown table.

func FormatListMarkdown 

func FormatListMarkdown(out ListOutput) string

FormatListMarkdown renders a page of runners as a Markdown table.

func FormatManagerListMarkdown 

func FormatManagerListMarkdown(out ManagerListOutput) string

FormatManagerListMarkdown renders the managers of one runner as a Markdown table.

func FormatOutputMarkdown 

func FormatOutputMarkdown(out Output) string

FormatOutputMarkdown renders one runner as the card of a single object.

A runner GitLab has just created or registered answers with the authentication token it minted, once and nowhere else, so the card shows it as a secret and toolutil.Card.End adds the sentence saying it cannot be read back. The table this replaced published every other field and dropped the token on the floor, which made the register action unusable: the value it exists to return was not in its answer.

func FormatRegTokenMarkdown 

func FormatRegTokenMarkdown(out RegTokenOutput) string

FormatRegTokenMarkdown renders a registration token reset. It is a formatter of its own because the two tokens are different secrets used in different places: a registration token registers new runners, an authentication token is what one runner authenticates with.

func Remove 

func Remove(ctx context.Context, client *gitlabclient.Client, input RemoveInput) error

Remove deletes a runner by its ID.

func Verify 

func Verify(ctx context.Context, client *gitlabclient.Client, input VerifyInput) error

Verify checks whether a runner authentication token is valid.

Types

type AuthTokenOutput 

type AuthTokenOutput struct {
	toolutil.HintableOutput
	Token     string `json:"token"`
	ExpiresAt string `json:"token_expires_at,omitempty"`
}

AuthTokenOutput represents a runner authentication token.

func ResetAuthToken 

func ResetAuthToken(ctx context.Context, client *gitlabclient.Client, input ResetAuthTokenInput) (AuthTokenOutput, error)

ResetAuthToken resets the authentication token for a runner.

type DeleteByIDInput 

type DeleteByIDInput struct {
	RunnerID int64 `json:"runner_id" jsonschema:"Runner ID to delete,required"`
}

DeleteByIDInput defines parameters for deleting a registered runner by ID.

type DeleteByTokenInput 

type DeleteByTokenInput struct {
	Token string `json:"token" jsonschema:"Runner authentication token,required"`
}

DeleteByTokenInput defines parameters for deleting a runner by its token.

type DetailsOutput 

type DetailsOutput struct {
	toolutil.HintableOutput
	ID              int64                        `json:"id"`
	Description     string                       `json:"description"`
	Name            string                       `json:"name"`
	Paused          bool                         `json:"paused"`
	IsShared        bool                         `json:"is_shared"`
	RunnerType      string                       `json:"runner_type"`
	Online          bool                         `json:"online"`
	Status          string                       `json:"status"`
	ContactedAt     string                       `json:"contacted_at,omitempty"`
	MaintenanceNote string                       `json:"maintenance_note,omitempty"`
	TagList         []string                     `json:"tag_list,omitempty"`
	RunUntagged     bool                         `json:"run_untagged"`
	Locked          bool                         `json:"locked"`
	AccessLevel     string                       `json:"access_level"`
	MaximumTimeout  int64                        `json:"maximum_timeout,omitempty"`
	Groups          []RunnerDetailsGroupOutput   `json:"groups,omitempty"`
	Projects        []RunnerDetailsProjectOutput `json:"projects,omitempty"`
	// CreatedAt, CreatedBy and JobExecutionStatus are what
	// lib/api/entities/ci/runner.rb sends on every runner and
	// gl.RunnerDetails does not carry, read from the captured response
	// (ADR-0021); created_by is sent to a caller allowed to read the user.
	CreatedAt          string                    `json:"created_at,omitempty"`
	CreatedBy          *toolutil.UserBasicOutput `json:"created_by,omitempty"`
	JobExecutionStatus string                    `json:"job_execution_status,omitempty"`
	// Active mirrors the deprecated gl.RunnerDetails.Active flag.
	Active bool `json:"active"`
	// Architecture mirrors the deprecated gl.RunnerDetails.Architecture.
	Architecture string `json:"architecture,omitempty"`
	// Platform mirrors the deprecated gl.RunnerDetails.Platform.
	Platform string `json:"platform,omitempty"`
	// Revision mirrors the deprecated gl.RunnerDetails.Revision.
	Revision string `json:"revision,omitempty"`
	// Version mirrors the deprecated gl.RunnerDetails.Version.
	Version string `json:"version,omitempty"`
	// IPAddress mirrors the deprecated gl.RunnerDetails.IPAddress.
	IPAddress string `json:"ip_address,omitempty"`
}

DetailsOutput represents detailed runner information. Field set mirrors gl.RunnerDetails one-to-one, including the deprecated Active/Architecture/Platform/Revision/Version/IPAddress fields and the full Groups/Projects sub-object arrays.

The one field of gl.RunnerDetails it does not carry is Token. GitLab mints a runner's authentication token once, at registration, and answers with it there and nowhere else: the responses of GET /runners/:id and PUT /runners/:id name every field below and no token (GitLab's own generated OpenAPI document), while POST /runners answers with id, token and token_expires_at, which is what Output carries. Publishing it here promised a secret the endpoint never sends, so a model was told to read a value that is always empty.

func Get 

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

Get returns detailed information about a specific runner.

func Update 

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

Update modifies a runner's configuration and returns updated details.

type DisableProjectInput 

type DisableProjectInput struct {
	ProjectID toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
	RunnerID  int64                `json:"runner_id"  jsonschema:"Runner ID to remove from project,required"`
}

DisableProjectInput defines parameters for removing a runner from a project.

type EnableProjectInput 

type EnableProjectInput struct {
	ProjectID toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
	RunnerID  int64                `json:"runner_id"  jsonschema:"Runner ID to assign,required"`
}

EnableProjectInput defines parameters for assigning a runner to a project.

type GetInput 

type GetInput struct {
	RunnerID int64 `json:"runner_id" jsonschema:"Runner ID,required"`
}

GetInput defines parameters for getting runner details.

type JobListOutput 

type JobListOutput struct {
	toolutil.HintableOutput
	Jobs       []jobs.Output             `json:"jobs"`
	Pagination toolutil.PaginationOutput `json:"pagination"`
}

JobListOutput holds a paginated list of runner jobs.

func ListJobs 

func ListJobs(ctx context.Context, client *gitlabclient.Client, input ListJobsInput) (JobListOutput, error)

ListJobs returns jobs processed by a specific runner.

type ListAllInput 

type ListAllInput struct {
	Type    string   `json:"type,omitempty"     jsonschema:"Runner type filter: instance_type, group_type, project_type"`
	Status  string   `json:"status,omitempty"   jsonschema:"Runner status filter: online, offline, stale, never_contacted"`
	Paused  *bool    `json:"paused,omitempty"   jsonschema:"Filter by paused state"`
	TagList []string `json:"tag_list,omitempty" jsonschema:"List of tags to filter by"`
	Scope   string   `` /* 155-byte string literal not displayed */
	OrderBy string   `json:"order_by,omitempty" jsonschema:"Field to order keyset-paginated results by, e.g. id"`
	Sort    string   `json:"sort,omitempty"     jsonschema:"Sort direction: asc or desc"`
	toolutil.PaginationInput
	toolutil.KeysetPaginationInput
}

ListAllInput defines parameters for listing all runners (admin).

type ListGroupInput 

type ListGroupInput struct {
	GroupID toolutil.StringOrInt `json:"group_id"           jsonschema:"Group ID or URL-encoded path,required"`
	Type    string               `json:"type,omitempty"     jsonschema:"Runner type filter: instance_type, group_type, project_type"`
	Status  string               `json:"status,omitempty"   jsonschema:"Runner status filter: online, offline, stale, never_contacted"`
	TagList []string             `json:"tag_list,omitempty" jsonschema:"List of tags to filter by"`
	OrderBy string               `json:"order_by,omitempty" jsonschema:"Field to order keyset-paginated results by, e.g. id"`
	Sort    string               `json:"sort,omitempty"     jsonschema:"Sort direction: asc or desc"`
	toolutil.PaginationInput
	toolutil.KeysetPaginationInput
}

ListGroupInput defines parameters for listing group runners. The group runners endpoint (gl.ListGroupsRunnersOptions) does not accept paused or scope filters, so they are intentionally omitted here.

type ListInput 

type ListInput struct {
	Type    string   `json:"type,omitempty"     jsonschema:"Runner type filter: instance_type, group_type, project_type"`
	Status  string   `json:"status,omitempty"   jsonschema:"Runner status filter: online, offline, stale, never_contacted"`
	Paused  *bool    `json:"paused,omitempty"   jsonschema:"Filter by paused state"`
	TagList []string `json:"tag_list,omitempty" jsonschema:"List of tags to filter by"`
	Scope   string   `` /* 137-byte string literal not displayed */
	OrderBy string   `json:"order_by,omitempty" jsonschema:"Field to order keyset-paginated results by, e.g. id"`
	Sort    string   `json:"sort,omitempty"     jsonschema:"Sort direction: asc or desc"`
	toolutil.PaginationInput
	toolutil.KeysetPaginationInput
}

ListInput defines parameters for listing owned runners.

type ListJobsInput 

type ListJobsInput struct {
	RunnerID int64  `json:"runner_id"           jsonschema:"Runner ID,required"`
	Status   string `` /* 208-byte string literal not displayed */
	OrderBy  string `json:"order_by,omitempty"  jsonschema:"Order by field: id (default)"`
	Sort     string `json:"sort,omitempty"      jsonschema:"Sort direction: asc, desc"`
	toolutil.PaginationInput
	toolutil.KeysetPaginationInput
}

ListJobsInput defines parameters for listing jobs processed by a runner.

type ListManagersInput 

type ListManagersInput struct {
	RunnerID int64 `json:"runner_id" jsonschema:"Runner ID,required"`
}

ListManagersInput defines parameters for listing runner managers.

type ListOutput 

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

ListOutput holds a paginated list of runners.

func List 

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

List returns owned runners with optional filters.

func ListAll 

func ListAll(ctx context.Context, client *gitlabclient.Client, input ListAllInput) (ListOutput, error)

ListAll returns all runners across the GitLab instance (admin endpoint).

func ListGroup 

func ListGroup(ctx context.Context, client *gitlabclient.Client, input ListGroupInput) (ListOutput, error)

ListGroup returns runners available in a specific group.

func ListProject 

func ListProject(ctx context.Context, client *gitlabclient.Client, input ListProjectInput) (ListOutput, error)

ListProject returns runners assigned to a specific project.

type ListProjectInput 

type ListProjectInput struct {
	ProjectID toolutil.StringOrInt `json:"project_id"         jsonschema:"Project ID or URL-encoded path,required"`
	Type      string               `json:"type,omitempty"     jsonschema:"Runner type filter: instance_type, group_type, project_type"`
	Status    string               `json:"status,omitempty"   jsonschema:"Runner status filter: online, offline, stale, never_contacted"`
	Paused    *bool                `json:"paused,omitempty"   jsonschema:"Filter by paused state"`
	TagList   []string             `json:"tag_list,omitempty" jsonschema:"List of tags to filter by"`
	Scope     string               `` /* 137-byte string literal not displayed */
	OrderBy   string               `json:"order_by,omitempty" jsonschema:"Field to order keyset-paginated results by, e.g. id"`
	Sort      string               `json:"sort,omitempty"     jsonschema:"Sort direction: asc or desc"`
	toolutil.PaginationInput
	toolutil.KeysetPaginationInput
}

ListProjectInput defines parameters for listing project runners.

type ManagerListOutput 

type ManagerListOutput struct {
	toolutil.HintableOutput
	Managers []ManagerOutput `json:"managers"`
}

ManagerListOutput holds a list of runner managers.

func ListManagers 

func ListManagers(ctx context.Context, client *gitlabclient.Client, input ListManagersInput) (ManagerListOutput, error)

ListManagers retrieves all managers for a specific runner.

type ManagerOutput 

type ManagerOutput struct {
	ID           int64  `json:"id"`
	SystemID     string `json:"system_id"`
	Version      string `json:"version"`
	Revision     string `json:"revision"`
	Platform     string `json:"platform"`
	Architecture string `json:"architecture"`
	CreatedAt    string `json:"created_at,omitempty"`
	ContactedAt  string `json:"contacted_at,omitempty"`
	IPAddress    string `json:"ip_address"`
	Status       string `json:"status"`
	// JobExecutionStatus is what the manager is doing now. A runner's own
	// status is the aggregate of its managers'.
	JobExecutionStatus string `json:"job_execution_status,omitempty"`
}

ManagerOutput represents a runner manager in responses.

type Output 

type Output struct {
	toolutil.HintableOutput
	ID                 int64                     `json:"id"`
	Description        string                    `json:"description"`
	Name               string                    `json:"name"`
	Paused             bool                      `json:"paused"`
	IsShared           bool                      `json:"is_shared"`
	RunnerType         string                    `json:"runner_type"`
	Online             bool                      `json:"online"`
	Status             string                    `json:"status"`
	CreatedAt          string                    `json:"created_at,omitempty"`
	CreatedBy          *toolutil.UserBasicOutput `json:"created_by,omitempty"`
	JobExecutionStatus string                    `json:"job_execution_status,omitempty"`
	// Active mirrors the deprecated gl.Runner.Active flag (use Paused instead).
	Active bool `json:"active"`
	// IPAddress mirrors the deprecated gl.Runner.IPAddress (empty from 17.0 on).
	IPAddress string `json:"ip_address,omitempty"`
	// Token is the authentication token returned by register/create responses.
	Token string `json:"token,omitempty"`
	// TokenExpiresAt is the registration token expiry returned by register.
	TokenExpiresAt string `json:"token_expires_at,omitempty"`
}

Output represents a GitLab CI Runner in responses. Field set mirrors gl.Runner one-to-one, including the deprecated Active/IPAddress fields and the registration Token/TokenExpiresAt returned by create/register endpoints, plus what lib/api/entities/ci/runner.rb sends on every runner and the SDK does not carry, read from the captured response (ADR-0021): when it was created, who created it when the caller may read that user, and the job execution status.

func EnableProject 

func EnableProject(ctx context.Context, client *gitlabclient.Client, input EnableProjectInput) (Output, error)

EnableProject assigns a runner to a project.

func Register 

func Register(ctx context.Context, client *gitlabclient.Client, input RegisterInput) (Output, error)

Register creates a new runner with the given registration token.

type RegTokenOutput added in v3.1.0 

type RegTokenOutput struct {
	toolutil.HintableOutput
	Token     string `json:"token"`
	ExpiresAt string `json:"token_expires_at,omitempty"`
}

RegTokenOutput represents a runner *registration* token, carrying exactly the fields AuthTokenOutput carries and published under the same JSON keys, so the actions' schemas are unchanged.

It is a type of its own because the Markdown registry is keyed by type: the two tokens are different secrets used in different places, and while the three registration resets answered with AuthTokenOutput the registry could hold one formatter for the pair. The first registration won, so every registration-token reset rendered under the heading "Runner Authentication Token" and the auth-token reset was the one that never reached its own formatter at all.

func ResetGroupRegToken deprecated 

func ResetGroupRegToken(ctx context.Context, client *gitlabclient.Client, input ResetGroupRegTokenInput) (RegTokenOutput, error)

ResetGroupRegToken resets a group's runner registration token.

Deprecated: Scheduled for removal in GitLab 20.0.

func ResetInstanceRegToken deprecated 

func ResetInstanceRegToken(ctx context.Context, client *gitlabclient.Client, _ ResetInstanceRegTokenInput) (RegTokenOutput, error)

ResetInstanceRegToken resets the instance-level runner registration token.

Deprecated: Scheduled for removal in GitLab 20.0.

func ResetProjectRegToken deprecated 

func ResetProjectRegToken(ctx context.Context, client *gitlabclient.Client, input ResetProjectRegTokenInput) (RegTokenOutput, error)

ResetProjectRegToken resets a project's runner registration token.

Deprecated: Scheduled for removal in GitLab 20.0.

type RegisterInfoInput 

type RegisterInfoInput struct {
	Name         string `json:"name,omitempty"         jsonschema:"Runner manager name"`
	Version      string `json:"version,omitempty"      jsonschema:"Runner version"`
	Revision     string `json:"revision,omitempty"     jsonschema:"Runner revision"`
	Platform     string `json:"platform,omitempty"     jsonschema:"Runner platform (e.g. linux)"`
	Architecture string `json:"architecture,omitempty" jsonschema:"Runner architecture (e.g. amd64)"`
}

RegisterInfoInput mirrors gl.RegisterNewRunnerInfoOptions: the optional "info" hashmap describing the runner manager registering.

type RegisterInput 

type RegisterInput struct {
	Token           string             `json:"token"                      jsonschema:"Registration token,required"`
	Description     string             `json:"description,omitempty"      jsonschema:"Runner description"`
	Info            *RegisterInfoInput `json:"info,omitempty"             jsonschema:"Runner manager info hashmap (name, version, revision, platform, architecture)"`
	Paused          *bool              `json:"paused,omitempty"           jsonschema:"Register in paused state"`
	Locked          *bool              `json:"locked,omitempty"           jsonschema:"Lock runner to current project"`
	RunUntagged     *bool              `json:"run_untagged,omitempty"     jsonschema:"Whether to run untagged jobs"`
	TagList         []string           `json:"tag_list,omitempty"         jsonschema:"List of runner tags"`
	AccessLevel     string             `json:"access_level,omitempty"     jsonschema:"Access level: not_protected, ref_protected"`
	MaximumTimeout  *int64             `json:"maximum_timeout,omitempty"  jsonschema:"Maximum job timeout in seconds"`
	MaintenanceNote string             `json:"maintenance_note,omitempty" jsonschema:"Maintenance note"`
	Active          *bool              `json:"active,omitempty"           jsonschema:"Deprecated: registration active state. Prefer paused instead"`
}

RegisterInput defines parameters for registering a new runner.

type RemoveInput 

type RemoveInput struct {
	RunnerID int64 `json:"runner_id" jsonschema:"Runner ID to remove,required"`
}

RemoveInput defines parameters for removing a runner.

type ResetAuthTokenInput 

type ResetAuthTokenInput struct {
	RunnerID int64 `json:"runner_id" jsonschema:"Runner ID,required"`
}

ResetAuthTokenInput defines parameters for resetting a runner's auth token.

type ResetGroupRegTokenInput 

type ResetGroupRegTokenInput struct {
	GroupID toolutil.StringOrInt `json:"group_id" jsonschema:"Group ID or URL-encoded path,required"`
}

ResetGroupRegTokenInput defines parameters for resetting group runner reg token.

type ResetInstanceRegTokenInput 

type ResetInstanceRegTokenInput struct{}

ResetInstanceRegTokenInput is an empty struct for the instance reg token reset (no parameters needed).

type ResetProjectRegTokenInput 

type ResetProjectRegTokenInput struct {
	ProjectID toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
}

ResetProjectRegTokenInput defines parameters for resetting project runner reg token.

type RunnerDetailsGroupOutput 

type RunnerDetailsGroupOutput struct {
	ID     int64  `json:"id"`
	Name   string `json:"name"`
	WebURL string `json:"web_url"`
}

RunnerDetailsGroupOutput mirrors gl.RunnerDetailsGroup one-to-one.

type RunnerDetailsProjectOutput 

type RunnerDetailsProjectOutput struct {
	ID                int64  `json:"id"`
	Name              string `json:"name"`
	NameWithNamespace string `json:"name_with_namespace"`
	Path              string `json:"path"`
	PathWithNamespace string `json:"path_with_namespace"`
}

RunnerDetailsProjectOutput mirrors gl.RunnerDetailsProject one-to-one.

type UpdateInput 

type UpdateInput struct {
	RunnerID        int64    `json:"runner_id"                    jsonschema:"Runner ID,required"`
	Description     string   `json:"description,omitempty"        jsonschema:"Runner description"`
	Paused          *bool    `json:"paused,omitempty"             jsonschema:"Pause/unpause the runner"`
	TagList         []string `json:"tag_list,omitempty"           jsonschema:"List of runner tags"`
	RunUntagged     *bool    `json:"run_untagged,omitempty"       jsonschema:"Whether to run untagged jobs"`
	Locked          *bool    `json:"locked,omitempty"             jsonschema:"Whether runner is locked to current project"`
	AccessLevel     string   `json:"access_level,omitempty"       jsonschema:"Access level: not_protected, ref_protected"`
	MaximumTimeout  *int64   `json:"maximum_timeout,omitempty"    jsonschema:"Maximum job timeout in seconds"`
	MaintenanceNote string   `json:"maintenance_note,omitempty"   jsonschema:"Maintenance note for the runner"`
	Active          *bool    `json:"active,omitempty"             jsonschema:"Deprecated: runner active state. Prefer paused instead"`
}

UpdateInput defines parameters for updating a runner.

type VerifyInput 

type VerifyInput struct {
	Token string `json:"token" jsonschema:"Runner authentication token to verify,required"`
}

VerifyInput defines parameters for verifying a runner token.

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.