File-based Workflow

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 - including AI features
Use Git for version control
Collaborate with your team using pull requests
Integrate with CI/CD workflows

A dashboard is a file ending in .dashboard.sql. The file name before the extension is used as the dashboard name in Shaper.

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

Let’s look at the workflow for interactively developing dashboards and deploying them to production:

Setup

To develop dashboards, you need the shaper binary installed 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:

shaper pull

Developing Dashboards

The only command you normally need to develop dashboards is:

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 to deploy dashboards from a GitHub repository to your Shaper instance as follows:

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 in Shaper’s Admin section. Then add it as SHAPER_DEPLOY_API_KEY secret to your GitHub repository settings.

Deploy via CLI

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

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:

shaper deploy --validate-only

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

The above Github Action uses the --validate-only flag to validate changes on pull requests before deploying them on merge to the main branch.

Resolving conflicts

We recommend using the file-based workflow for everything and 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:

shaper pull

The pull command downloads any changes from the Shaper instance and updates your local files. It also updates the lastPull timestamp in the shaper.json file. This timestamp is used to detect conflicts during deployment. Make sure to also commit the updated shaper.json file to your Git repository.

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.