Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mage.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Introduction

Mage Pro supports two CI/CD approaches to fit different organizational needs. Both follow the same core workflow: develop → staging → deploy to production using the Git terminal and the Mage Pro deployment application. This document clarifies the two primary CI/CD approaches available in Mage Pro:
  1. CI/CD by cluster - Separate clusters for development, staging, and production
  2. CI/CD by workspace - Multiple workspaces within a single cluster
Both approaches follow the same core principles: develop in isolation, test thoroughly, and deploy safely to production. The choice between cluster based and workspace based workflows depends on your infrastructure requirements, security policies, and team structure.

​
1. CI/CD by cluster

Setup: Separate clusters for each environment
  • Development cluster - Active development
  • Staging cluster (optional) - Pre-production validation
  • Production cluster - Live pipelines

​
2. CI/CD by workspace

Setup: Single cluster with multiple workspaces (see our workspaces guide for more details on configuring workspaces)
  • Development workspace - Active development
  • Staging workspace (optional) - Pre-production validation
  • Production workspace - Live pipelines

​
Git Branch Strategy & Environment Mapping

main/master     → Production environment
staging         → Staging environment  
development     → Development environment
feature/*       → Development environment (feature branches)

​
Workflow Best Practices

Development:
  • Create feature branches from development: feature/new-pipeline
  • Develop pipelines in feature branch and push changes to Github using the Git terminal (for more details on pushing code to Github see Mage Pro’s Git terminal doc)
Staging:
  • Merge development → staging when ready for testing
  • Staging environment deploys from staging branch
  • Run full validation and integration tests
Production:
  • Merge staging → main after successful testing
  • Production environment deploys from main branch only
  • Use deployment application for controlled production releases (for more on Mage Pro’s deployment application see the version control guide)

​
Environment-Specific Configurations

Same Code, Different Targets: The same codebase connects to different systems using environment-specific configurations: Environment Variables & Secrets:
  • Each cluster/workspace maintains its own connection settings
  • DATABASE_URL points to dev/staging/prod databases
  • API_KEYS use environment-appropriate credentials
Configuration Examples: 
Development:   DATABASE_URL = dev-warehouse.company.com
Staging:          DATABASE_URL = staging-warehouse.company.com  
Production:    DATABASE_URL = prod-warehouse.company.com
In Mage Pro:
  • Configure different data source connections per environment
  • Use environment variables in pipeline io_config.yaml file: {{ env_var('DATABASE_URL') }}
    • or python interpolation in a block os.environ.get('DB_USERNAME')
Using these strategies will allow you to develop the same pipeline code, but select different source and targets for each cluster / workspace environment.

​
Conclusion

Both approaches use the same tools and follow identical workflows. The choice depends on your infrastructure and security requirements. Use Git terminal for code management and the deployment application for production deployments in either setup. Use our version control guide to implement this in your Mage Pro environment.