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".
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: "[email protected]", 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");
});
});
