Implementation:TobikoData Sqlmesh CICD Run Tests

Knowledge Sources	SQLMesh SQLMesh Docs
Domains	Data_Engineering, CICD
Last Updated	2026-02-07 00:00 GMT

Overview

Concrete implementation for executing SQLMesh unit tests in CI/CD pipelines and reporting results via GitHub Check Runs provided by SQLMesh.

Description

The run_tests command and its underlying controller method automate the execution of data model unit tests within GitHub Actions workflows. It creates a GitHub Check Run to track test execution status, runs all discovered unit tests through the SQLMesh Context, formats test results with detailed pass/fail information, updates the Check Run with formatted results, and sets appropriate success/failure conclusions. This implementation provides immediate feedback on test status directly in the GitHub PR interface.

Usage

Use run_tests as a GitHub Actions workflow step to validate data transformations before creating PR environments or deploying to production. The command is typically invoked early in the workflow to fail fast if tests don't pass.

Code Reference

Source Location

• Repository: sqlmesh
• File: sqlmesh/integrations/github/cicd/command.py:L116-119 (CLI), sqlmesh/integrations/github/cicd/controller.py:L665-669 (controller method)

Signature

# CLI Command
@github.command()
@click.pass_context
@cli_analytics
def run_tests(ctx: click.Context) -> None:
    """Runs the unit tests"""
    if not _run_tests(ctx.obj["github"]):
        raise CICDBotError("Failed to run tests. See Pull Requests Checks for more information.")

# Controller Method
def run_tests(self) -> t.Tuple[ModelTextTestResult, str]:
    """
    Run tests for the PR
    """
    return self._context._run_tests(verbosity=Verbosity.VERBOSE)

Import

from sqlmesh.integrations.github.cicd.command import run_tests
from sqlmesh.integrations.github.cicd.controller import GithubController

I/O Contract

Inputs

Name	Type	Required	Description
ctx	click.Context	Yes	Click context containing initialized GithubController in ctx.obj["github"]

Outputs

Name	Type	Description
None	None	Command creates GitHub Check Run with test results; raises CICDBotError if tests fail

Usage Examples

Basic Usage

# In GitHub Actions workflow:
# - name: Run SQLMesh Tests
#   env:
#     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
#   run: sqlmesh_cicd bot github run-tests

# Programmatic usage:
from click.testing import CliRunner
from sqlmesh.integrations.github.cicd.command import github
from sqlmesh.integrations.github.cicd.controller import GithubController

runner = CliRunner()

# Setup context with controller
controller = GithubController(
    paths=["path/to/project"],
    token="github_token"
)

result = runner.invoke(
    github,
    ['run-tests'],
    obj={"github": controller}
)

# Direct controller usage:
controller = GithubController(
    paths=["path/to/project"],
    token="github_token"
)

# Update check status to in-progress
controller.update_test_check(status=GithubCheckStatus.IN_PROGRESS)

# Run tests
test_result, output = controller.run_tests()

# Update check with results
if test_result.wasSuccessful():
    controller.update_test_check(
        status=GithubCheckStatus.COMPLETED,
        conclusion=GithubCheckConclusion.SUCCESS,
        result=test_result
    )
else:
    controller.update_test_check(
        status=GithubCheckStatus.COMPLETED,
        conclusion=GithubCheckConclusion.FAILURE,
        result=test_result
    )

# Example test result output in GitHub Check Run:
# Tests Passed
#
# Running test: test_customers_model
# ✓ test_customers_model passed
#
# Running test: test_orders_aggregation
# ✓ test_orders_aggregation passed
#
# Ran 2 tests in 1.23s
# OK

Related Pages

Implements Principle

• Principle:TobikoData_Sqlmesh_CICD_Automated_Test_Execution

• Environment:TobikoData_Sqlmesh_GitHub_CICD_Runner