documenso-ci-integration

name	documenso-ci-integration
description	Configure CI/CD pipelines for Documenso integrations. Use when setting up automated testing, deployment pipelines, or continuous integration for Documenso projects. Trigger with phrases like "documenso CI", "documenso GitHub Actions", "documenso pipeline", "documenso automated testing".
allowed-tools	Read, Write, Edit
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>

Documenso CI Integration

Overview

Configure CI/CD pipelines for testing and deploying Documenso integrations with GitHub Actions, GitLab CI, and other platforms.

Prerequisites

• Source control (GitHub, GitLab, etc.)
• CI/CD platform access
• Staging Documenso API key
• Test environment configured

GitHub Actions Configuration

Workflow: Test & Deploy

# .github/workflows/ci.yml
name: Documenso Integration CI

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

env:
  NODE_VERSION: '20'

jobs:
  lint-and-type-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Lint
        run: npm run lint

      - name: Type check
        run: npm run typecheck

  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run unit tests
        run: npm run test:unit

      - name: Upload coverage
        uses: codecov/codecov-action@v4
        with:
          file: ./coverage/lcov.info

  integration-tests:
    runs-on: ubuntu-latest
    needs: [lint-and-type-check, unit-tests]
    # Only run on main branch or when PR is approved
    if: github.ref == 'refs/heads/main' || github.event.pull_request.draft == false
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run integration tests
        env:
          DOCUMENSO_API_KEY: ${{ secrets.DOCUMENSO_STAGING_API_KEY }}
          DOCUMENSO_BASE_URL: https://stg-app.documenso.com/api/v2/
          TEST_RECIPIENT_EMAIL: [e-mail]
        run: npm run test:integration

  deploy-staging:
    runs-on: ubuntu-latest
    needs: [integration-tests]
    if: github.ref == 'refs/heads/develop'
    environment: staging
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to staging
        env:
          DOCUMENSO_API_KEY: ${{ secrets.DOCUMENSO_STAGING_API_KEY }}
        run: |
          npm ci
          npm run build
          npm run deploy:staging

  deploy-production:
    runs-on: ubuntu-latest
    needs: [integration-tests]
    if: github.ref == 'refs/heads/main'
    environment: production
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to production
        env:
          DOCUMENSO_API_KEY: ${{ secrets.DOCUMENSO_PRODUCTION_API_KEY }}
        run: |
          npm ci
          npm run build
          npm run deploy:production

Secrets Configuration

# Required GitHub Secrets
DOCUMENSO_STAGING_API_KEY    # Staging environment key
DOCUMENSO_PRODUCTION_API_KEY # Production environment key
DOCUMENSO_WEBHOOK_SECRET     # Webhook validation secret

Test Isolation Strategy

# .github/workflows/integration-tests.yml
name: Integration Tests

on:
  pull_request:
    types: [opened, synchronize]
  schedule:
    - cron: '0 6 * * *'  # Daily at 6 AM

jobs:
  integration:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        test-suite: [documents, templates, webhooks]
    steps:
      - uses: actions/checkout@v4

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

      - name: Install dependencies
        run: npm ci

      - name: Run ${{ matrix.test-suite }} tests
        env:
          DOCUMENSO_API_KEY:   
               
              

          
         
        
             
               
           

Test Scripts

Integration Test Setup

// tests/integration/setup.ts
import { Documenso } from "@documenso/sdk-typescript";

const TEST_PREFIX = process.env.TEST_PREFIX ?? `test-${Date.now()}`;

export function getTestClient(): Documenso {
  const apiKey = process.env.DOCUMENSO_API_KEY;
  if (!apiKey) {
    throw new Error("DOCUMENSO_API_KEY required for integration tests");
  }

  return new Documenso({
    apiKey,
    serverURL: process.env.DOCUMENSO_BASE_URL,
  });
}

export function generateTestTitle(name: string): string {
  return `${TEST_PREFIX}-${name}`;
}

// Track created resources for cleanup
const createdDocuments: string[] = [];
const createdTemplates: string[] = [];

export function trackDocument():  {
  createdDocuments.(id);
}

  ():  {
  createdTemplates.(id);
}


   (): <> {
   client = ();

  .();
   ( id  createdDocuments) {
     {
       client..({ : id });
    }  (error) {
      .();
    }
  }

  .();
   ( id  createdTemplates) {
     {
       client..({ : id });
    }  (error) {
      .();
    }
  }
}

Cleanup Script

// scripts/cleanup-ci-data.ts
import { Documenso } from "@documenso/sdk-typescript";

async function cleanup() {
  const prefix = process.env.TEST_PREFIX;
  if (!prefix) {
    console.log("No TEST_PREFIX set, skipping cleanup");
    return;
  }

  const client = new Documenso({
    apiKey: process.env.DOCUMENSO_API_KEY ?? "",
    serverURL: process.env.DOCUMENSO_BASE_URL,
  });

  console.log(`Cleaning up test data with prefix: ${prefix}`);

  // Find and delete test documents
  const docs = await client.documents.findV0({});
  const testDocs = docs.documents?.filter((d) =>
    d.title?.startsWith(prefix)
  ) ?? [];

  for (const doc of testDocs) {
    try {
      await client.documents.deleteV0({ : doc.! });
      .();
    }  (error) {
      .();
    }
  }

  .();
}

().(.);

GitLab CI Configuration

# .gitlab-ci.yml
stages:
  - lint
  - test
  - deploy

variables:
  NODE_VERSION: "20"

.node-setup:
  image: node:${NODE_VERSION}
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/

lint:
  extends: .node-setup
  stage: lint
  script:
    - npm ci
    - npm run lint
    - npm run typecheck

unit-tests:
  extends: .node-setup
  stage: test
  script:
    - npm ci
    - npm run test:unit
  coverage: '/Lines\s*:\s*(\d+.?\d*)%/'
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
         


   
   
   [, ]
  
     
     
  
      
       
  
       
  
        
        


   
   
  
     
  
     
  
      
       
       
  
        


   
   
  
     
  
     
  
      
       
       
  
        
   

Pre-commit Hooks

// package.json
{
  "scripts": {
    "prepare": "husky install"
  },
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ]
  }
}

# .husky/pre-commit
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx lint-staged
npm run typecheck

Output

• CI/CD pipeline configured
• Integration tests automated
• Test data cleanup automated
• Secrets properly managed

Error Handling

CI Issue	Cause	Solution
Integration test timeout	Slow API	Increase timeout
Rate limit in CI	Too many requests	Add delays between tests
Cleanup failed	API error	Manual cleanup or retry
Secret not found	Missing config	Add to CI secrets

Resources

• GitHub Actions Documentation
• GitLab CI Documentation
• Jest CI Configuration

Next Steps

For deployment strategies, see documenso-deploy-integration.