Set the default runner

If your company's security policies require running jobs locally instead of in the cloud, you can use a self-hosted runner to meet that requirement. With Liquibase, you can set the default runner to be either self-hosted or Liquibase-hosted at the Workspace, Project, or Workflow level. In this article, you'll learn three places where you can set the default runner: the Workspace, the Project, and the Workflow. The runner setting inherits down the hierarchy (Workspace → Project → Workflow), so you typically only need to configure it at one level. Depending on your use case, you'll only need to edit the Workspace, Project, or workflow settings.

This inheritance gives you flexibility: you can set a workspace-wide default and then override it for specific projects or workflows as needed. For example, you might set your workspace to use self-hosted runners by default, but configure one workflow to use a Liquibase-hosted runner for testing purposes.

Workspace level: Set organization-wide security policies and standards that apply to all teams and projects by default

Project level: Override Workspace defaults for specific applications that have different security, compliance, or infrastructure requirements than the rest of your organization
Workflow level: Test and validate changes using a different runner type before deploying to production with your standard runner configuration 

Procedure

Setting the default runner at the Workspace level  

1. To set the default for all projects and workflows in a workspace:
   Navigate to the Workspaces tab and select the edit button next to the workspace you want to configure. 

The Edit Workspace dialog will appear.

2. In the Edit Workspace dialog, locate the Job Runner section.

 Here you will set the default job runner type for Workflows in this Workspace. This is initially set up so you can override the default at runtime.

Select either the Liquibase-hosted runner or the Self-hosted runner radio button and press the Save button.

• Liquibase-hosted runner: Cloud-based and hosted by Liquibase (recommended option)

• Self-hosted runner: Managed internally by your organization (requires setup in your environment)

3. Select Save.

Overriding at the Project level (optional)  

1. To use a different runner for a specific project:
Navigate back to the Projects tab and select the edit button next to the Project.

2. In the Edit Project dialog, scroll to the Job Runner section and choose: 

• Inherit from Workspace: Uses the job runner setting currently configured at the Workspace level. (default behavior)

• Liquibase-hosted runner:  Overrides the default to use the cloud-based runner

• Self-hosted runner: Overrides the default to use a self-hosted runner

3. Select Save.

2. Scroll to the Job Runner section and choose between the three options:

• Inherit from Project: Uses the Project setting or the Workspace setting if it is set.

• Liquibase-hosted runner:  Overrides the default to use the cloud-based runner

• Self-hosted runner: Overrides the default to use a self-hosted runner

3. Select Save.

Next steps

Once your default runners are configured, you can use these settings as runtime variables to dynamically choose runners during execution. Learn how to create a runtime variable here.