runners

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Apr 21, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package runners implements GitLab Runners API operations as MCP tools. It supports listing, getting, updating, removing runners, managing project/group runner assignments, listing runner jobs, registering/verifying runners, and resetting runner authentication tokens.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

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 RegisterMeta 

func RegisterMeta(server *mcp.Server, client *gitlabclient.Client)

RegisterMeta registers the gitlab_runner meta-tool with all runner actions.

func RegisterTools 

func RegisterTools(server *mcp.Server, client *gitlabclient.Client)

RegisterTools registers all runner management MCP tools.

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"`
	ProjectCount    int      `json:"project_count,omitempty"`
	GroupCount      int      `json:"group_count,omitempty"`
}

DetailsOutput represents detailed runner information.

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:"Comma-separated list of tags to filter by"`
	toolutil.PaginationInput
}

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:"Comma-separated list of tags to filter by"`
	toolutil.PaginationInput
}

ListGroupInput defines parameters for listing group runners.

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:"Comma-separated list of tags to filter by"`
	toolutil.PaginationInput
}

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
}

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"`
	TagList   string               `json:"tag_list,omitempty"   jsonschema:"Comma-separated list of tags to filter by"`
	toolutil.PaginationInput
}

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"`
}

Output represents a GitLab CI Runner in responses.

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 RegisterInput 

type RegisterInput struct {
	Token           string   `json:"token"                        jsonschema:"Registration token,required"`
	Description     string   `json:"description,omitempty"        jsonschema:"Runner description"`
	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"`
}

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 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"`
}

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.