runners

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: 13 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 an auth token as Markdown.

func FormatDetailsMarkdown 

func FormatDetailsMarkdown(out DetailsOutput) string

FormatDetailsMarkdown renders detailed runner information as Markdown.

func FormatJobListMarkdown 

func FormatJobListMarkdown(out JobListOutput) string

FormatJobListMarkdown renders a list of runner jobs as Markdown.

func FormatListMarkdown 

func FormatListMarkdown(out ListOutput) string

FormatListMarkdown renders a list of runners as Markdown.

func FormatManagerListMarkdown 

func FormatManagerListMarkdown(out ManagerListOutput) string

FormatManagerListMarkdown renders a list of runner managers as Markdown.

func FormatOutputMarkdown 

func FormatOutputMarkdown(out Output) string

FormatOutputMarkdown renders a runner output as Markdown.

func FormatRegTokenMarkdown 

func FormatRegTokenMarkdown(out AuthTokenOutput) string

FormatRegTokenMarkdown renders a registration token as Markdown.

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.

func ResetGroupRegToken deprecated 

func ResetGroupRegToken(ctx context.Context, client *gitlabclient.Client, input ResetGroupRegTokenInput) (AuthTokenOutput, 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) (AuthTokenOutput, 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) (AuthTokenOutput, error)

ResetProjectRegToken resets a project's runner registration token.

Deprecated: Scheduled for removal in GitLab 20.0.

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"`
	Token           string                       `json:"token,omitempty"`
	Groups          []RunnerDetailsGroupOutput   `json:"groups,omitempty"`
	Projects        []RunnerDetailsProjectOutput `json:"projects,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.

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   `` /* 143-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   `` /* 143-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 `json:"status,omitempty"    jsonschema:"Job status filter: running, success, failed, canceled"`
	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               `` /* 143-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"`
}

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"`
	// 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.

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 RegisterInfoInput added in v2.3.0 

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 added in v2.3.0 

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 added in v2.3.0 

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.