CI/CD Workflows

Integrate the dcupl CLI into your CI/CD pipelines for automated deployments.

Prerequisites

  • dcupl CLI (npm install -g @dcupl/cli)
  • A CLI API key from Console → Settings → API Keys
  • Your project ID from Console → Settings

GitHub Actions

Basic Push on Merge

Push to dcupl when changes are merged to main:

.github/workflows/dcupl-deploy.yml
name: Deploy to dcupl

on:
  push:
    branches: [main]
    paths:
      - 'dcupl/**'  # Only run when dcupl files change

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

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dcupl CLI
        run: npm install -g @dcupl/cli

      - name: Push to dcupl
        working-directory: ./dcupl
        env:
          DCUPL_PROJECT_ID: ${{ secrets.DCUPL_PROJECT_ID }}
          DCUPL_API_KEY: ${{ secrets.DCUPL_API_KEY }}
        run: dcupl push --message "Deploy from GitHub Actions"

Validate Before Push

Run validation before deploying:

.github/workflows/dcupl-validate-deploy.yml
name: Validate and Deploy

on:
  push:
    branches: [main]

jobs:
  validate-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: |
          npm install -g @dcupl/cli
          npm ci

      - name: Validate models
        run: npm run validate  # Your validation script

      - name: Run tests
        run: npm test

      - name: Push to dcupl
        if: success()
        env:
          DCUPL_PROJECT_ID: ${{ secrets.DCUPL_PROJECT_ID }}
          DCUPL_API_KEY: ${{ secrets.DCUPL_API_KEY }}
        run: dcupl push

Multi-Environment Deployment

Deploy to different environments based on branch:

.github/workflows/dcupl-multi-env.yml
name: Multi-Environment Deploy

on:
  push:
    branches:
      - develop
      - main

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

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dcupl CLI
        run: npm install -g @dcupl/cli

      - name: Deploy to Development
        if: github.ref == 'refs/heads/develop'
        env:
          DCUPL_PROJECT_ID: ${{ secrets.DCUPL_PROJECT_ID_DEV }}
          DCUPL_API_KEY: ${{ secrets.DCUPL_API_KEY_DEV }}
          DCUPL_VERSION: draft
        run: dcupl push

      - name: Deploy to Production
        if: github.ref == 'refs/heads/main'
        env:
          DCUPL_PROJECT_ID: ${{ secrets.DCUPL_PROJECT_ID_PROD }}
          DCUPL_API_KEY: ${{ secrets.DCUPL_API_KEY_PROD }}
          DCUPL_VERSION: draft
        run: dcupl push

GitLab CI

Basic Pipeline

.gitlab-ci.yml
stages:
  - deploy

deploy-dcupl:
  stage: deploy
  image: node:20
  only:
    - main
  script:
    - npm install -g @dcupl/cli
    - dcupl push
  variables:
    DCUPL_PROJECT_ID: $DCUPL_PROJECT_ID
    DCUPL_API_KEY: $DCUPL_API_KEY

With Validation

.gitlab-ci.yml
stages:
  - validate
  - deploy

validate:
  stage: validate
  image: node:20
  script:
    - npm ci
    - npm run validate
    - npm test

deploy:
  stage: deploy
  image: node:20
  only:
    - main
  needs:
    - validate
  script:
    - npm install -g @dcupl/cli
    - dcupl push --message "GitLab CI deploy $CI_COMMIT_SHORT_SHA"
  variables:
    DCUPL_PROJECT_ID: $DCUPL_PROJECT_ID
    DCUPL_API_KEY: $DCUPL_API_KEY

Azure DevOps

azure-pipelines.yml
trigger:
  branches:
    include:
      - main

pool:
  vmImage: 'ubuntu-latest'

steps:
  - task: NodeTool@0
    inputs:
      versionSpec: '20.x'

  - script: npm install -g @dcupl/cli
    displayName: 'Install dcupl CLI'

  - script: dcupl push
    displayName: 'Push to dcupl'
    env:
      DCUPL_PROJECT_ID: $(DCUPL_PROJECT_ID)
      DCUPL_API_KEY: $(DCUPL_API_KEY)

CircleCI

.circleci/config.yml
version: 2.1

jobs:
  deploy:
    docker:
      - image: cimg/node:20
    steps:
      - checkout
      - run:
          name: Install dcupl CLI
          command: npm install -g @dcupl/cli
      - run:
          name: Push to dcupl
          command: dcupl push

workflows:
  deploy-workflow:
    jobs:
      - deploy:
          filters:
            branches:
              only: main

Best Practices

1. Use Secrets for Credentials

Never hardcode API keys. Use your CI/CD platform's secrets management:

Platform Secret Setup
GitHub Actions Settings → Secrets → Actions
GitLab CI Settings → CI/CD → Variables
Azure DevOps Pipelines → Library → Variable groups
CircleCI Project Settings → Environment Variables

2. Limit Trigger Paths

Only run the pipeline when dcupl files change:

# GitHub Actions
on:
  push:
    paths:
      - 'dcupl/**'
      - 'models/**'
      - 'data/**'

3. Add Commit Messages

Include context in your pushes:

dcupl push --message "Deploy $COMMIT_SHA: $COMMIT_MESSAGE"

4. Handle Failures

Exit with appropriate codes for CI feedback:

dcupl push || exit 1

5. Cache Dependencies

Speed up pipelines by caching:

# GitHub Actions
- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-${{ hashFiles('**/package-lock.json') }}

Troubleshooting CI/CD

Authentication Errors

Error: Authentication failed

Solution: Verify your API key is correctly set and has CLI permissions.

# Debug: Check if variable is set
echo "API Key set: ${DCUPL_API_KEY:+yes}"

Push Conflicts

Error: Remote has changes not in local

Solution: Pull before push or use --force:

dcupl pull
dcupl push
# Or if you're sure:
dcupl push --force

Network Timeouts

Error: Request timed out

Solution: Retry with longer timeout or check network:

dcupl push --verbose  # See detailed output

See Also