MaintainX Production Checklist

Overview

Comprehensive pre-deployment and post-deployment checklist for MaintainX integrations covering security, reliability, observability, and data integrity.

Prerequisites

MaintainX integration developed and tested
Production MaintainX account with API access
Deployment infrastructure ready (Cloud Run, K8s, or similar)

Instructions

Step 1: Authentication & Security

# Verify production API key works
curl -s -o /dev/null -w "HTTP %{http_code}" \
  https://api.getmaintainx.com/v1/users?limit=1 \
  -H "Authorization: Bearer $MAINTAINX_API_KEY_PROD"

# Verify no secrets in codebase
npx gitleaks detect --source . --no-git

API key stored in secret manager (not env file or code)
```
.env
```
and
```
*.key
```
files in
```
.gitignore
```
Pre-commit hook blocking secret commits
API key rotation schedule set (every 90 days)
Input validation on all user-provided data (Zod or similar)

Step 2: Error Handling & Resilience

Retry logic with exponential backoff for 429 and 5xx errors
```
Retry-After
```
header honored on 429 responses
Circuit breaker for cascading failure prevention
Graceful degradation when MaintainX API is down
Request timeout set (30 seconds recommended)

// Verify retry logic is configured
const client = axios.create({
  baseURL: 'https://api.getmaintainx.com/v1',
  timeout: 30_000,  // 30 second timeout
  headers: { Authorization: `Bearer ${apiKey}` },
});

Step 3: Data Integrity

Cursor-based pagination handles all list endpoints
Idempotency keys on webhook handlers (prevent duplicate processing)
Data sync state persisted (survives restarts)
Reconciliation job runs daily to detect drift
Work order status transitions follow valid paths only

Step 4: Observability

Structured JSON logging (not console.log in production)
API request metrics (count, latency, error rate)
Health check endpoint (
```
/health
```
) returning API connectivity status
Readiness probe (
```
/ready
```
) for container orchestration
Alerting configured for error rate > 5%, latency > 5s, sync lag > 15min

Step 5: Performance

Connection pooling with keep-alive enabled
Response caching for static resources (users, locations, teams)
Max page size (100) used for pagination
Webhook-driven updates instead of polling where possible
Rate limiting to stay within API quotas

Step 6: Deployment

Multi-stage Docker build (small production image)
Non-root user in container
Resource limits set (CPU, memory)
Auto-scaling configured (min 1 instance for webhooks)
Rollback procedure documented and tested

Post-Deployment Verification

#!/bin/bash
echo "=== Post-Deployment Verification ==="

# 1. Health check
echo -n "Health check: "
curl -s http://YOUR_SERVICE_URL/health | jq -r '.status'

# 2. API connectivity
echo -n "MaintainX API: "
curl -s -o /dev/null -w "%{http_code}" \
  https://api.getmaintainx.com/v1/users?limit=1 \
  -H "Authorization: Bearer $MAINTAINX_API_KEY_PROD"
echo ""

# 3. Create test work order
echo "Creating test work order..."
WO=$(curl -s -X POST https://api.getmaintainx.com/v1/workorders \
  -H "Authorization: Bearer $MAINTAINX_API_KEY_PROD" \
  -H "Content-Type: application/json" \
  -d '{"title":"Post-deploy verification test","priority":"LOW"}')
WO_ID=$(echo $WO | jq -r '.id')
echo "  Created: #$WO_ID"

# 4. Verify retrieval
echo -n "Retrieve test: "
curl -s "https://api.getmaintainx.com/v1/workorders/$WO_ID" \
  -H "Authorization: Bearer $MAINTAINX_API_KEY_PROD" | jq -r '.status'

# 5. Clean up
curl -s -X PATCH "https://api.getmaintainx.com/v1/workorders/$WO_ID" \
  -H "Authorization: Bearer $MAINTAINX_API_KEY_PROD" \
  -H "Content-Type: application/json" \
  -d '{"status":"CLOSED"}' > /dev/null
echo "  Cleaned up test work order #$WO_ID"

# 6. Check metrics endpoint
echo -n "Metrics endpoint: "
curl -s -o /dev/null -w "%{http_code}" http://YOUR_SERVICE_URL/metrics
echo ""

echo "=== Verification complete ==="

Go-Live Readiness Summary

Category	Requirement	Priority
Auth	Secret manager, no hardcoded keys	P0
Errors	Retry + backoff for 429/5xx	P0
Data	Pagination, idempotency, sync state	P0
Observability	Logging, metrics, health check	P0
Performance	Connection pooling, caching	P1
Security	Input validation, audit logging	P1
Deployment	Docker, non-root, resource limits	P1
Recovery	Rollback procedure, reconciliation	P2

Output

All P0 checklist items verified before go-live
Post-deployment verification script run successfully
Test work order created and cleaned up in production
Health check and metrics endpoints responding
Go-live readiness documented

Error Handling

Issue	Check	Solution
Health check fails post-deploy	`curl /health`	Check API key is mounted, restart pod
Test work order creation fails	Check HTTP status	Verify API key permissions and plan tier
Metrics endpoint 404	Check route config	Ensure metrics server started on correct port
High error rate after deploy	Check logs	Roll back, investigate, fix, redeploy

Resources

Next Steps

For API version migrations, see

maintainx-upgrade-migration

Examples

Automated pre-deploy gate in CI:

# .github/workflows/deploy.yml
jobs:
  pre-deploy-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx gitleaks detect --source . --no-git
      - run: npm run test -- --coverage --coverageThreshold='{"global":{"branches":80}}'
      - run: npm run lint
      - run: npm run typecheck

Claude-code-plugins maintainx-prod-checklist