Environment:TobikoData Sqlmesh GitHub CICD Runner

Knowledge Sources	TobikoData/sqlmesh
Domains	CI/CD, GitHub Actions, DevOps
Last Updated	2026-02-07 21:00 GMT

Overview

GitHub Actions CI/CD runner environment for automating SQLMesh data transformation workflows through the integrated bot.

Description

The GitHub CI/CD runner environment enables automated SQLMesh workflows within GitHub Actions using the sqlmesh_cicd CLI tool. It orchestrates test execution, PR environment management, production plan generation, and deployment operations through GitHubCICDController. The bot leverages PyGithub for API interactions, creates GitHub Check Runs for detailed reporting, and manages PR comments for user feedback. Configuration is handled through YAML files or environment variables with Pydantic validation.

Usage

This environment is required when implementing automated SQLMesh workflows in GitHub Actions including running unit tests on PRs, creating isolated PR environments, generating production deployment plans, and executing production deployments. The bot auto-detects GitHub Actions context and integrates with SQLMesh's plan/apply workflow.

System Requirements

Category	Requirement	Notes
Runtime	GitHub Actions runner	Ubuntu, macOS, or Windows runner
Python	>= 3.9	SQLMesh Python runtime required
Network	GitHub API access	api.github.com and graphql.github.com
Authentication	GitHub token with repo permissions	GITHUB_TOKEN or PAT

Dependencies

System Packages

Git (for repository operations)
All SQLMesh Python runtime dependencies

Python Packages

PyGithub>=2.6.0 - GitHub API client library
All core SQLMesh dependencies (sqlglot, duckdb, pydantic, etc.)

Credentials

GitHub Actions automatically provides:

GITHUB_TOKEN - Automatic token with repository permissions
GITHUB_EVENT_PATH - Path to event payload JSON
GITHUB_API_URL - GitHub API base URL (default: https://api.github.com)
GITHUB_GRAPHQL_URL - GitHub GraphQL endpoint
GITHUB_OUTPUT - Path for setting action outputs
GITHUB_ACTIONS - Set to "true" when running in GitHub Actions

Bot configuration (via YAML or environment variables):

SQLMESH_GITHUB_BOT_TOKEN - Custom GitHub token (if not using GITHUB_TOKEN)
SQLMESH_GITHUB_BOT_CONFIG - Path to bot configuration YAML
SQLMESH_CICD_COMMAND - Command to execute (test, update-pr-environment, gen-prod-plan, deploy-production)

Additional configuration variables (see config.py):

Approval workflow settings
Required approvers list
Deployment triggers
Test execution parameters

Quick Install

# Install SQLMesh with GitHub CI/CD support
pip install "sqlmesh[github]"

# Create GitHub Actions workflow
cat > .github/workflows/sqlmesh.yml << 'EOF'
name: SQLMesh CI/CD

on:
  pull_request:
    types: [opened, synchronize, reopened]
  push:
    branches: [main]

jobs:
  sqlmesh-bot:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install SQLMesh
        run: pip install "sqlmesh[github]"

      - name: Run SQLMesh CI/CD Bot
        run: sqlmesh_cicd
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
EOF

# Create bot configuration file
cat > .sqlmesh_cicd.yml << 'EOF'
bot:
  auto_deploy_on_approval: true
  required_approvers:
    - user1
    - user2
  run_tests_on_pr: true
  create_pr_environments: true
EOF

Code Evidence

# File: pyproject.toml:113
github = ["PyGithub>=2.6.0"]

# File: pyproject.toml:151
[project.scripts]
sqlmesh_cicd = "sqlmesh.cicd.bot:cli"

# File: sqlmesh/integrations/github/cicd/controller.py:230
def _load_event_payload(self) -> t.Dict[str, t.Any]:
    """Load GitHub event payload from GITHUB_EVENT_PATH."""
    event_path = os.environ.get("GITHUB_EVENT_PATH")
    if not event_path:
        raise ValueError("GITHUB_EVENT_PATH not set")
    with open(event_path) as f:
        return json.load(f)

# File: sqlmesh/integrations/github/cicd/controller.py:317
@property
def github_api_url(self) -> str:
    """Get GitHub API URL from environment."""
    return os.environ.get("GITHUB_API_URL", "https://api.github.com")

# File: sqlmesh/integrations/github/cicd/controller.py:495
def _set_github_output(self, name: str, value: str) -> None:
    """Set GitHub Actions output variable."""
    output_file = os.environ.get("GITHUB_OUTPUT")
    if output_file:
        with open(output_file, "a") as f:
            f.write(f"{name}={value}\n")

# File: sqlmesh/integrations/github/cicd/controller.py:1193
@property
def is_github_actions(self) -> bool:
    """Check if running in GitHub Actions environment."""
    return os.environ.get("GITHUB_ACTIONS", "").lower() == "true"

Common Errors

Error Message	Cause	Solution
GITHUB_EVENT_PATH not set	Not running in GitHub Actions	Ensure workflow runs in GitHub Actions context
401 Unauthorized	Invalid or missing GitHub token	Verify GITHUB_TOKEN has correct permissions
403 Resource not accessible by integration	Insufficient token permissions	Grant token read/write access to contents, pull requests, checks
PyGithub not found	Missing dependency	Install with pip install "sqlmesh[github]"
Configuration file not found	Missing .sqlmesh_cicd.yml	Create bot configuration file or use environment variables
Check run creation failed	Token lacks checks write permission	Grant checks: write permission in workflow

Compatibility Notes

Requires PyGithub >= 2.6.0 for latest GitHub API features
Auto-detects GitHub Actions context via GITHUB_ACTIONS environment variable
Works with both GitHub-hosted and self-hosted runners
Supports GitHub Enterprise Server (configure GITHUB_API_URL)
GraphQL API used for efficient data fetching (GITHUB_GRAPHQL_URL)
Check Runs require repository checks write permission
PR comments require pull requests write permission
Bot configuration supports both YAML files and environment variables
Pydantic models ensure type-safe configuration validation
Integrates with SQLMesh's virtual environments for PR isolation
Deployment workflows support approval requirements before production

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment