# Git Workflow

_If you are looking to use a coding agents such as Claude Code, Codex or Gemini CLI checkout the [Agent Docs](https://taleshape.com/shaper/docs/ai-agent-workflow/) to learn how to setup Skills for Shaper._

Dashboards are just SQL. And instead of using Shaper's built-in editor you can also manage dashboards as files directly.

This allows you to:
- Use your favorite editor and AI agent
- Use Git for version control
- Collaborate with your team using pull requests
- Integrate with CI/CD workflows

A dashboard is a file ending with `.dashboard.sql` and a task is a file ending with `.task.sql`.
The file name before the extension is shown as the name in Shaper.

You can organize dashboards into folders. The folder structure will be synchronized with Shaper.

See the file-based workflow in action:

<YouTube id="https://www.youtube.com/watch?v=HHYvx_MsQHc" />

---

## Setup

Let's look at the workflow for interactively developing dashboards and deploying them to production.

To develop dashboards, you need the `shaper` binary [installed](https://taleshape.com/shaper/docs/installing-shaper) locally on your machine.

This allows you to run `shaper dev` which watches for file changes and automatically shows you a preview dashboard in your browser.

Each Shaper project needs a `shaper.json` file.
When you run `shaper dev` in a folder without a `shaper.json` file,
it prompts you for the URL of your Shaper instance and the folder to store dashboards in.
Then it creates the `shaper.json` file for you.

`shaper dev` also prompts you to login to your Shaper account when running it initially.
Your session token is stored in the `.shaper-auth` file. Make sure you add this file to your `.gitignore` file.

### Existing Dashboards

If you have existing dashboards, you can download them by running:
```bash
shaper pull
```

## Developing Dashboards

The only command you normally need to develop dashboards is:
```bash
shaper dev
```
The `dev` command watches files for changes and automatically opens a preview of the dashboard in your browser and new changes are automatically shown in the browser.

### Creating a dashboard

Create a new file with the `.dashboard.sql` extension in your dashboards folder.

In addition to showing a preview, Shaper will also generate a `shaperid:` comment at the top of the file if it doesn't exist yet.

The ID identifies the dashboard in Shaper. As long as you don't change the ID, you can rename and move the file freely and Shaper will keep the dashboard in sync.

## Deploying Dashboards

The `dev` and `pull` commands do not modify the live dashboards in your Shaper instance.

Shaper encourages you to follow a Git-based workflow to deploy dashboards to production.

Instead of deploying dashboards from your local machine, commit changes to a Git repository and use a CI/CD pipeline to deploy to production.

### Github Action

Use the [Shaper Deploy Action](https://github.com/taleshape-com/shaper-deploy-action) to deploy dashboards from a GitHub repository to your Shaper instance as follows:

```yaml
name: Deploy and Validate Shaper Dashboards

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  validate:
    name: Validate on PRs
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate Shaper Dashboards
        uses: taleshape-com/shaper-deploy-action@v1
        with:
          validate-only: true
          api-key: ${{ secrets.SHAPER_DEPLOY_API_KEY }}

  deploy:
    name: Deploy on main
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy Shaper Dashboards
        uses: taleshape-com/shaper-deploy-action@v1
        with:
          api-key: ${{ secrets.SHAPER_DEPLOY_API_KEY }}
```

Make sure to create an API key with "Deploy" permissions in Shaper's Admin section. Then add it as `SHAPER_DEPLOY_API_KEY` secret to your GitHub repository settings.

Note that the Github action also runs `shaper validate` which executes each dashboard and fails if the SQL returns any errors.

### Deploy via CLI

Use the following command to deploy dashboards with the `shaper` CLI instead of using the GitHub Action:
```bash
shaper deploy
```

You need to set the `SHAPER_DEPLOY_API_KEY` environment variable to authenticate.

_Note that you need to authenticate with an API key instead of a user account since we encourage using CI/CD pipelines for deployments instead of deploying manually._

To validate changes without deploying them, run:
```bash
shaper deploy --validate-only
```

Validation ensures that IDs are set and there are no conflicts.

Additionally you can run `shaper validate` before deploying which actually runs the SQL for each dashboard and fails if there are any errors.

## Resolving conflicts

We recommend using the file-based workflow for everything, instead of editing dashboards through the Shaper web interface.
If you edit dashboards in the web interface, your local files will be out of sync. You then need to run:
```yml
shaper pull
```
The `pull` command downloads any changes from the Shaper instance and updates your local files, including a `-- shapersync:` timestamp comment in the file.

If you try to deploy and there are changes in Shaper that were made after your last pull, the deployment will fail.
You then need to manually review and resolve any conflicts.

## Tasks as Files
**Work in Progress:** Currently only dashboards can be managed as files.
Tasks will follow soon.