Agent Skills: MaintainX CI Integration

MaintainX CI Integration

Overview

Configure CI/CD pipelines for MaintainX integrations with unit tests (mocked), integration tests (live API), and automated quality gates.

Prerequisites

• Git repository with MaintainX integration
• GitHub Actions (or GitLab CI)
• Test environment MaintainX API key stored as CI secret

Instructions

Step 1: GitHub Actions Workflow

# .github/workflows/maintainx-ci.yml
name: MaintainX Integration CI

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

env:
  NODE_VERSION: '20'

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: npm
      - run: npm ci
      - run: npm run test -- --coverage
      - uses: actions/upload-artifact@v4
        with:
          name: coverage
          path: coverage/

  integration-tests:
    runs-on: ubuntu-latest
    needs: unit-tests
    environment: staging
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: npm
      - run: npm ci
      - run: npm run test:integration
        env:
          MAINTAINX_API_KEY: ${{ secrets.MAINTAINX_API_KEY_STAGING }}
          MAINTAINX_ENV: staging
      - run: npm run lint
      - run: npm run typecheck

  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Scan for secrets
        run: npx gitleaks detect --source . --no-git --verbose
      - name: Audit dependencies
        run: npm audit --production --audit-level=high

Step 2: Unit Tests with Mocked API

// tests/work-orders.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest';
import axios from 'axios';

vi.mock('axios');

describe('Work Order Service', () => {
  beforeEach(() => {
    process.env.MAINTAINX_API_KEY = 'test-key';
    vi.resetAllMocks();
  });

  it('creates a work order with required fields', async () => {
    const mockWO = { id: 1, title: 'Test WO', status: 'OPEN', priority: 'LOW' };
    vi.mocked(axios.create).mockReturnValue({
      post: vi.fn().mockResolvedValue({ data: mockWO }),
      interceptors: { response: { use: vi.fn() } },
    } as any);

    const { MaintainXClient } = await import('../src/client');
    const client = new MaintainXClient();
    const result = await client.createWorkOrder({ title: 'Test WO' });

    expect(result.data.id).toBe(1);
    expect(result.data.status).toBe('OPEN');
  });

  it('handles 429 rate limit with retry', async () => {
    const rateLimitErr = {
      response: { status: 429, headers: { 'retry-after': '1' } },
      isAxiosError: true,
    };
    const successResponse = { data: { id: 2, title: 'Retried' } };
    const postMock = vi.fn()
      .mockRejectedValueOnce(rateLimitErr)
      .mockResolvedValueOnce(successResponse);

    vi.mocked(axios.create).mockReturnValue({
      post: postMock,
      interceptors: { response: { use: vi.fn() } },
    } as any);

    // Test that retry logic eventually succeeds
    const { MaintainXClient } = await import('../src/client');
    const client = new MaintainXClient();
    // Wrap with retry logic from sdk-patterns
    const result = await withRetry(() => client.createWorkOrder({ title: 'Retried' }));
    expect(result.data.id).toBe(2);
  });

  it('validates work order status transitions', () => {
    const validTransitions: Record<string, string[]> = {
      OPEN: ['IN_PROGRESS', 'CLOSED'],
      IN_PROGRESS: ['ON_HOLD', 'COMPLETED', 'CLOSED'],
      ON_HOLD: ['IN_PROGRESS', 'CLOSED'],
      COMPLETED: ['CLOSED'],
      CLOSED: [],
    };

    expect(validTransitions['OPEN']).toContain('IN_PROGRESS');
    expect(validTransitions['CLOSED']).not.toContain('OPEN');
    expect(validTransitions['IN_PROGRESS']).toContain('ON_HOLD');
  });
});

Step 3: Integration Tests (Live API)

// tests/integration.test.ts
import { describe, it, expect, beforeAll, afterAll } from 'vitest';

const INTEGRATION = process.env.INTEGRATION === 'true';

describe.skipIf(!INTEGRATION)('MaintainX Integration', () => {
  let client: any;
  let testWorkOrderId: number;

  beforeAll(async () => {
    const { MaintainXClient } = await import('../src/client');
    client = new MaintainXClient();
  });

  it('authenticates successfully', async () => {
    const { data } = await client.getUsers({ limit: 1 });
    expect(data.users).toBeDefined();
  });

  it('creates and retrieves a work order', async () => {
    const { data: created } = await client.createWorkOrder({
      title: `CI Test - ${new Date().toISOString()}`,
      description: 'Automated CI test. Safe to delete.',
      priority: 'LOW',
    });
    testWorkOrderId = created.id;
    expect(created.id).toBeGreaterThan(0);

    const { data: fetched } = await client.getWorkOrder(created.id);
    expect(fetched.title).toContain('CI Test');
  });

  afterAll(async () => {
    // Clean up test work order
    if (testWorkOrderId) {
      try {
        await client.updateWorkOrder(testWorkOrderId, { status: 'CLOSED' });
      } catch { /* ignore cleanup errors */ }
    }
  });
});

Step 4: Quality Gates

{
  "scripts": {
    "test": "vitest run",
    "test:integration": "INTEGRATION=true vitest run tests/integration.test.ts",
    "lint": "eslint src/ tests/",
    "typecheck": "tsc --noEmit",
    "ci": "npm run lint && npm run typecheck && npm run test -- --coverage"
  }
}

Output

• GitHub Actions workflow with unit tests, integration tests, and security scanning
• Unit tests using vitest with mocked axios responses
• Integration tests that run against a live staging MaintainX API
• Security scanning for leaked secrets and vulnerable dependencies
• Quality gate script combining lint, typecheck, and test coverage

Error Handling

| Issue | Cause | Solution | |-------|-------|----------| | Integration tests fail in CI | Missing MAINTAINX_API_KEY_STAGING secret | Add secret in GitHub repo Settings > Secrets | | Rate limits during test runs | Too many concurrent CI runs | Use staging environment with higher limits | | Flaky integration tests | Network timeouts | Add retry logic, increase timeout to 30s | | Secret scan false positives | Test fixtures with key-like strings | Add .gitleaksignore for known false positives |

Resources

• MaintainX API Reference
• GitHub Actions Docs
• Vitest Documentation

Next Steps

For deployment automation, see maintainx-deploy-integration.

Examples

GitLab CI equivalent:

# .gitlab-ci.yml
stages: [test, integration]

unit-tests:
  stage: test
  image: node:20
  script:
    - npm ci
    - npm run test -- --coverage

integration-tests:
  stage: integration
  image: node:20
  only: [main, develop]
  script:
    - npm ci
    - INTEGRATION=true npm run test:integration
  variables:
    MAINTAINX_API_KEY: $MAINTAINX_API_KEY_STAGING