salesforce-ci-integration

# Salesforce CI Integration

## Overview
Set up CI/CD pipelines for Salesforce using GitHub Actions with JWT-based authentication, automated Apex testing, and metadata deployment.

## Prerequisites
- GitHub repository with Actions enabled
- Salesforce Connected App with JWT Bearer flow configured
- RSA key pair (private key stored as GitHub Secret)
- Scratch org or sandbox for test execution

## Instructions

### Step 1: Create GitHub Actions Workflow
Create `.github/workflows/salesforce-ci.yml`:

```yaml
name: Salesforce CI

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

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install Salesforce CLI
        run: npm install -g @salesforce/cli

      - name: Authenticate to Salesforce (JWT)
        run: |
          echo "${{ secrets.SF_JWT_KEY }}" > server.key
          sf org login jwt \
            --client-id ${{ secrets.SF_CLIENT_ID }} \
            --jwt-key-file server.key \
            --username ${{ secrets.SF_USERNAME }} \
            --set-default \
            --alias ci-org
          rm server.key

      - name: Validate Metadata Deployment (dry run)
        run: |
          sf project deploy start \
            --target-org ci-org \
            --dry-run \
            --wait 30

      - name: Run Apex Tests
        run: |
          sf apex run test \
            --target-org ci-org \
            --result-format human \
            --code-coverage \
            --wait 20

      - name: Check API Limits
        run: |
          sf limits api display --target-org ci-org --json | \
            jq '.result[] | select(.name == "DailyApiRequests") | "\(.name): \(.remaining)/\(.max)"'

  integration-tests:
    runs-on: ubuntu-latest
    needs: validate
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci

      - name: Run jsforce Integration Tests
        env:
          SF_LOGIN_URL: https://test.salesforce.com
          SF_USERNAME: ${{ secrets.SF_USERNAME }}
          SF_PASSWORD: ${{ secrets.SF_PASSWORD }}
          SF_SECURITY_TOKEN: ${{ secrets.SF_SECURITY_TOKEN }}
        run: npm run test:integration
```

### Step 2: Configure GitHub Secrets
```bash
# JWT private key (from your RSA key pair)
gh secret set SF_JWT_KEY < server.key

# Connected App consumer key
gh secret set SF_CLIENT_ID --body "3MVG9..."

# Integration user credentials
gh secret set SF_USERNAME --body "ci-user@yourcompany.com"
gh secret set SF_PASSWORD --body "password"
gh secret set SF_SECURITY_TOKEN --body "token"
```

### Step 3: Generate JWT Key Pair
```bash
# Generate RSA key pair for JWT Bearer flow
openssl genrsa -out server.key 2048
openssl req -new -x509 -key server.key -out server.crt -days 365 \
  -subj "/CN=Salesforce CI/O=YourCompany"

# Upload server.crt to Connected App in Salesforce Setup:
# Setup > App Manager > Your App > Edit > Use Digital Signatures > Choose File
```

### Step 4: Write Integration Tests
```typescript
import { describe, it, expect } from 'vitest';
import jsforce from 'jsforce';

describe('Salesforce Integration', () => {
  const conn = new jsforce.Connection({
    loginUrl: process.env.SF_LOGIN_URL || 'https://test.salesforce.com',
  });

  beforeAll(async () => {
    await conn.login(
      process.env.SF_USERNAME!,
      process.env.SF_PASSWORD! + process.env.SF_SECURITY_TOKEN!
    );
  });

  it('should query Accounts via SOQL', async () => {
    const result = await conn.query('SELECT Id, Name FROM Account LIMIT 1');
    expect(result.totalSize).toBeGreaterThanOrEqual(0);
    expect(result.done).toBe(true);
  });

  it('should check API limits are not exhausted', async () => {
    const limits = await conn.request('/services/data/v59.0/limits/');
    const remaining = limits.DailyApiRequests.Remaining;
    const max = limits.DailyApiRequests.Max;
    expect(remaining / max).toBeGreaterThan(0.1); // At least 10% remaining
  });

  it('should describe Account sObject', async () => {
    const meta = await conn.sobject('Account').describe();
    expect(meta.name).toBe('Account');
    expect(meta.fields.length).toBeGreaterThan(0);
    expect(meta.fields.find(f => f.name === 'Name')).toBeDefined();
  });
});
```

### Step 5: Metadata Deployment Pipeline
```yaml
# Deploy on merge to main
deploy:
  runs-on: ubuntu-latest
  if: github.ref == 'refs/heads/main' && github.event_name == 'push'
  needs: [validate, integration-tests]
  steps:
    - uses: actions/checkout@v4
    - name: Install Salesforce CLI
      run: npm install -g @salesforce/cli
    - name: Authenticate
      run: |
        echo "${{ secrets.SF_JWT_KEY_PROD }}" > server.key
        sf org login jwt \
          --client-id ${{ secrets.SF_CLIENT_ID_PROD }} \
          --jwt-key-file server.key \
          --username ${{ secrets.SF_USERNAME_PROD }} \
          --set-default
        rm server.key
    - name: Deploy to Production
      run: |
        sf project deploy start \
          --target-org ${{ secrets.SF_USERNAME_PROD }} \
          --test-level RunLocalTests \
          --wait 30
```

## Output
- JWT-authenticated CI pipeline
- Automated Apex test execution on PR
- Integration tests validating jsforce operations
- Metadata deployment on merge to main
- API limit monitoring in CI

## Error Handling
| Issue | Cause | Solution |
|-------|-------|----------|
| `INVALID_GRANT` | JWT cert not uploaded or user not pre-authorized | Upload cert to Connected App; add user to pre-authorized profiles |
| Apex test failures | Test data dependencies | Use `@testSetup` methods for test isolation |
| Deploy validation errors | Missing dependencies | Check component dependencies with `sf project deploy report` |
| API limit in CI | Too many test runs/day | Use sandbox instead of production for CI |

## Resources
- [Salesforce CLI JWT Auth](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_auth_jwt_flow.htm)
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
- [Apex Testing Best Practices](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_testing.htm)

## Next Steps
For deployment patterns, see `salesforce-deploy-integration`.