Runners

Runners are external processes used to run CI jobs. They are deployed by the administrator and registered to the GitLab instance.

Shared runners are available for all projects. Specific runners are enabled for a list of projects.

Global runners (admin)

Reference

Examples

Use the runners.list() and runners_all.list() methods to list runners. runners.list() - Get a list of specific runners available to the user runners_all.list() - Get a list of all runners in the GitLab instance (specific and shared). Access is restricted to users with administrator access.

Both methods accept a scope parameter to filter the list. Allowed values for this parameter are:

  • active

  • paused

  • online

  • specific (runners_all.list() only)

  • shared (runners_all.list() only)

Note

The returned objects hold minimal information about the runners. Use the get() method to retrieve detail about a runner.

Runners returned via runners_all.list() also cannot be manipulated directly. You will need to use the get() method to create an editable object.

# List owned runners
runners = gl.runners.list()

# List owned runners with a filter
runners = gl.runners.list(scope='active')

# List all runners in the GitLab instance (specific and shared), using a filter
runners = gl.runners_all.list(scope='paused')

Get a runner’s detail:

runner = gl.runners.get(runner_id)

Register a new runner:

runner = gl.runners.create({'token': secret_token})

Note

A new runner registration workflow has been introduced since GitLab 16.0. This new workflow comes with a new API endpoint to create runners, which does not use registration tokens.

The new endpoint can be called using gl.user.runners.create() after authenticating with gl.auth().

Update a runner:

runner = gl.runners.get(runner_id)
runner.tag_list.append('new_tag')
runner.save()

Remove a runner:

gl.runners.delete(runner_id)
# or
runner.delete()

Remove a runner by its authentication token:

gl.runners.delete(token="runner-auth-token")

Verify a registered runner token:

try:
    gl.runners.verify(runner_token)
    print("Valid token")
except GitlabVerifyError:
    print("Invalid token")

Project/Group runners

Reference

Examples

List the runners for a project:

runners = project.runners.list()

Enable a specific runner for a project:

p_runner = project.runners.create({'runner_id': runner.id})

Disable a specific runner for a project:

project.runners.delete(runner.id)

Runner jobs

Reference

Examples

List for jobs for a runner:

jobs = runner.jobs.list()

Filter the list using the jobs status:

# status can be 'running', 'success', 'failed' or 'canceled'
active_jobs = runner.jobs.list(status='running')