Documenso CI Integration

Documenso CI Integration

Output

• A credential-free pull-request lane for schema/template/unit checks and a trusted, scoped development integration lane.
• A redacted CI receipt with validation outcome and a safe failure/retry procedure.

Examples

Run template/schema/unit checks on every pull request using synthetic documents and signers, then execute one protected-branch development integration check with a scoped secret. If it fails, retain redacted correlation/status evidence; never expose signing credentials, document payloads, or production workspace access to forked CI code.

Overview

Configure CI/CD pipelines for Documenso integrations with GitHub Actions. Covers unit testing with mocks, integration testing against staging, and deployment workflows with secret management.

Prerequisites

• GitHub repository with Actions enabled
• Documenso staging API key
• Test environment configured (see documenso-local-dev-loop)

Instructions

Step 1: GitHub Actions Workflow

# .github/workflows/documenso-ci.yml
name: Documenso CI

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

env:
  NODE_ENV: test

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test
        # Unit tests use mocks — no API key needed

  integration-tests:
    runs-on: ubuntu-latest
    if: github.event_name == 'push'  # Only on push to main/develop
    needs: unit-tests
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run test:integration
        env:
          DOCUMENSO_API_KEY: ${{ secrets.DOCUMENSO_STAGING_API_KEY }}
      - run: npm run test:cleanup  # Remove test documents
        env:
          DOCUMENSO_API_KEY: ${{ secrets.DOCUMENSO_STAGING_API_KEY }}
        if: always()

Step 2: Unit Tests with Mocked SDK

// tests/unit/document-service.test.ts
import { describe, it, expect, vi, beforeEach } from "vitest";
import { createMockClient } from "../mocks/documenso";
import { DocumentService } from "../../src/services/document-service";

describe("DocumentService", () => {
  let service: DocumentService;
  let mockClient: ReturnType<typeof createMockClient>;

  beforeEach(() => {
    mockClient = createMockClient();
    service = new DocumentService(mockClient as any);
  });

  it("creates document with recipients and sends", async () => {
    const result = await service.createAndSend({
      title: "Test Contract",
      pdfPath: "./fixtures/test.pdf",
      signers: [{ email: "test@example.com", name: "Test User" }],
    });

    expect(mockClient.documents.createV0).toHaveBeenCalledWith({ title: "Test Contract" });
    expect(mockClient.documentsRecipients.createV0).toHaveBeenCalled();
    expect(mockClient.documents.sendV0).toHaveBeenCalled();
    expect(result.documentId).toBe(1);
  });

  it("handles API errors gracefully", async () => {
    mockClient.documents.createV0.mockRejectedValue(
      Object.assign(new Error("Unauthorized"), { statusCode: 401 })
    );

    await expect(service.createAndSend({
      title: "Test",
      pdfPath: "./fixtures/test.pdf",
      signers: [],
    })).rejects.toThrow("Unauthorized");
  });
});

Step 3: Integration Tests Against Staging

// tests/integration/document-lifecycle.test.ts
import { describe, it, expect, afterAll } from "vitest";
import { Documenso } from "@documenso/sdk-typescript";

const client = new Documenso({ apiKey: process.env.DOCUMENSO_API_KEY! });
const testDocIds: number[] = [];

describe("Document Lifecycle (Integration)", () => {
  it("creates a document", async () => {
    const doc = await client.documents.createV0({
      title: "[CI-TEST] Integration Test",
    });
    testDocIds.push(doc.documentId);
    expect(doc.documentId).toBeGreaterThan(0);
  }, 30000);

  it("lists documents", async () => {
    const { documents } = await client.documents.findV0({ page: 1, perPage: 5 });
    expect(documents.length).toBeGreaterThan(0);
  }, 15000);

  afterAll(async () => {
    // Cleanup: delete test documents
    for (const id of testDocIds) {
      try {
        await client.documents.deleteV0(id);
      } catch {
        console.warn(`Cleanup: could not delete document ${id}`);
      }
    }
  });
});

Step 4: Add Secrets to GitHub

# Using GitHub CLI
gh secret set DOCUMENSO_STAGING_API_KEY --body "api_stg_xxxxxxxxxxxx"
gh secret set DOCUMENSO_WEBHOOK_SECRET --body "whsec_xxxxxxxxxxxx"

# Verify secrets exist
gh secret list

Step 5: Package.json Scripts

{
  "scripts": {
    "test": "vitest run tests/unit/",
    "test:integration": "vitest run tests/integration/ --timeout 60000",
    "test:cleanup": "tsx scripts/cleanup-test-docs.ts",
    "test:all": "npm test && npm run test:integration"
  }
}

Step 6: Pre-commit Hook (Optional)

# .husky/pre-commit
npm test -- --run

This runs unit tests (with mocks) before every commit, catching issues early without needing API access.

CI Strategy Summary

Error Handling

Resources

• GitHub Actions Documentation
• Vitest Documentation
• Documenso SDK Testing

Next Steps

For deployment strategies, see documenso-deploy-integration.