Deploy Pipelines Using the Coalesce CLI

This guide walks you through promoting a pipeline you built locally with coa so it runs as a managed Environment in the Coalesce App. You push metadata to your repository, configure deploy-time mappings, sync the Coalesce App, and use cloud commands for plan, deploy, and refresh.

coa local development commands create and run execute SQL directly against your warehouse. They don't go through Coalesce Cloud. To see your pipeline in the Coalesce App and run it as a managed environment, push your code to your repository and deploy it.

Prerequisites

• A Coalesce Project linked to a version control repository, created in the Coalesce App.
• An Environment for that Project, created in the Coalesce App.
• Cloud credentials in ~/.coa/config, including domain, token, and environmentID.

Step 1: Push Your Code to Your Repository

From your project root, initialize version control if you need to, ignore local-only files, and push your first commit:

git init
echo "workspaces.yml" >> .gitignore
echo "coa-plan.json" >> .gitignore
git add .
git commit -m "Initial pipeline"
git remote add origin <your-project-git-repo-url>
git push -u origin main

Step 2: Configure Environment Storage Mappings

Your Environment needs storage location mappings, meaning the database and schema pairs for each location at deploy time. Add a YAML file under environments/ using a name like environments/<ENVIRONMENT_NAME>-<ID>.yml, then use the following structure:

fileVersion: 1
id: "<your-environment-id>"
mappingDefinitions:
  SRC:
    database: <MY_DATABASE>
    schema: <MY_SOURCE_SCHEMA>
  TARGET:
    database: <MY_DATABASE>
    schema: <MY_TARGET_SCHEMA>
name: <My Environment>
type: Environment

Get your Environment ID with coa environments list. Commit and push this file.

Configure storage in the App and in YAML

You also need to configure Workspace storage locations in the Coalesce App separately. The Environment YAML configures deploy-time mappings. Workspace mappings are configured in the Coalesce App for the build-time experience.

Step 3: Pull Into the Coalesce App

In the Coalesce App:

1. Open your Project's Workspace.
2. Set the branch to match what you pushed.
3. Click Force Checkout to load the pipeline from your repository.

Step 4: Plan and Deploy

Generate a plan, then apply it from your machine:

# Generate a deployment plan
coa plan --environmentID <id>

# Apply the plan
coa deploy --environmentID <id> --plan ./coa-plan.json

After a successful deploy, your Nodes appear in the DAG view in the Coalesce App, and you can run them from the Environment.

Refresh a Deployed Environment

To run DML on already-deployed Nodes without re-deploying, use:

coa refresh --environmentID <id> --include '{ name: "STG_CUSTOMER" }'

What's Next?

• Read CLI Commands for flags and options on plan, deploy, and refresh.
• Return to Build Pipelines With the Coalesce CLI for the local authoring loop.
• See Troubleshoot the Coalesce CLI when commands or validation behave unexpectedly.

---