@moeed/nx-jira-compass

An Nx plugin for sending events to Atlassian Jira Compass from your Nx workspace and CI/CD pipelines.

Installation

npm install --save-dev @moeed/nx-jira-compass

Features

• ✅ Send build, deployment, and custom events to Jira Compass
• ✅ CI/CD integration (GitHub Actions, GitLab CI, Jenkins, CircleCI)
• ✅ Easy setup with a generator
• ✅ Nx workspace integration
• ✅ TypeScript support

Setup

To set up Jira Compass integration in your project, run:

nx generate @moeed/nx-jira-compass:setup \
  --project=your-project \
  --atlassianSite=your-site.atlassian.net \
  --cloudId=00000000-0000-0000-0000-000000000000 \
  --componentId=ari:cloud:compass:00000000-0000-0000-0000-000000000000:component/1111-1111-1111-1111-111111111111/22222222-2222-2222-2222-2222

Required Parameters

• --project - Your Nx project name
• --atlassianSite - Your Atlassian site URL (e.g., example.atlassian.net)
• --cloudId - Your Compass Cloud ID (from your component ID)
• --componentId - The full component ID in Compass

Optional Parameters

• --userEmail - Your Atlassian account email (if not provided, will use COMPASS_USER_EMAIL environment variable)
• --apiToken - Your Atlassian API token (if not provided, will use COMPASS_API_TOKEN environment variable)

The setup command will:

1. Create a compass.json configuration file in your project
2. Add a compass target to your project.json

Authentication

You'll need an Atlassian API token to authenticate with the Compass API:

1. Visit https://id.atlassian.com/manage/api-tokens
2. Click "Create API token"
3. Give it a descriptive name (e.g., "Nx Jira Compass Integration")
4. Save the token securely - you'll need it for your local development and CI environments

Usage

Environment Variables

If you didn't provide userEmail or apiToken during setup, set them as environment variables:

export [email protected]
export COMPASS_API_TOKEN=your-atlassian-api-token

Sending Events

You can send events to Jira Compass with:

nx run your-project:compass \
  --eventType=build \
  --displayName="Build #123" \
  --description="Successfully built the application" \
  --url="https://your-ci-system.example.com/builds/123" \
  --externalEventSourceId="your-repo-name" \
  --customProperties='{"status":"successful","buildNumber":"123"}'

Common Parameters

• --eventType - Type of event (deployment, build, custom, etc.)
• --displayName - Name to display for the event
• --description - Description of the event
• --url - URL related to the event
• --externalEventSourceId - ID of the external source (e.g., repo URL, CI job name)
• --updateSequenceNumber - Sequence number for the event (must be incremented for updates)
• --customProperties - JSON string with additional properties based on event type

Event Types

The plugin supports the following event types:

1. build - For CI/CD build events

   nx run your-project:compass \
     --eventType=build \
     --displayName="Build #123" \
     --externalEventSourceId="your-repo-name" \
     --customProperties='{"status":"successful","pipelineId":"pipeline-123","buildNumber":"123"}'

2. deployment - For deployment events

   nx run your-project:compass \
     --eventType=deployment \
     --displayName="Deploy to Production" \
     --externalEventSourceId="your-repo-name" \
     --customProperties='{"status":"successful","pipelineId":"pipeline-123","environmentId":"prod-1","environmentName":"Production","environmentType":"production","sequenceNumber":1}'

3. custom - For custom events

   nx run your-project:compass \
     --eventType=custom \
     --displayName="Custom Event" \
     --externalEventSourceId="your-system" \
     --customProperties='{"id":"event-123","icon":"INFO"}'

CI/CD Integration

Helper Script

The plugin includes a helper script for CI integration:

# Using the CI helper script
npx ts-node node_modules/@moeed/nx-jira-compass/scripts/ci-helper.ts \
  --project=your-project \
  --type=build \
  --status=successful

The helper script automatically detects:

• CI environment (GitHub Actions, GitLab CI, CircleCI, Jenkins)
• Build/deployment information (numbers, URLs)
• Git repository details

Example CI Configurations

The plugin includes examples for popular CI platforms in the examples/ci directory:

• GitHub Actions
• GitLab CI
• Jenkins Pipeline
• CircleCI

Example for GitHub Actions

name: Build and Deploy

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v4
    - name: Use Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '20.x'
    
    - name: Install dependencies
      run: npm ci
      
    - name: Build
      run: npx nx build your-project
      
    - name: Send build event to Compass
      env:
        COMPASS_USER_EMAIL: ${{ secrets.COMPASS_USER_EMAIL }}
        COMPASS_API_TOKEN: ${{ secrets.COMPASS_API_TOKEN }}
      run: |
        npx ts-node node_modules/@moeed/nx-jira-compass/scripts/ci-helper.ts \
          --project=your-project \
          --type=build \
          --status=successful

Rate Limiting

The Compass API has a rate limit of 100 requests per user per minute. The plugin includes built-in handling for rate limits, but be aware of this limitation when designing your CI/CD pipelines.

Finding Your Component ID

To find your component ID in Compass:

1. Navigate to your component in Compass
2. Look at the URL, which should contain a pattern like: ari:cloud:compass:{cloudId}:component/{someId}/{componentId}
3. Extract the cloudId and full componentId for use with this plugin

Troubleshooting

If events aren't appearing in Compass:

1. Check that your credentials are correct
2. Verify the cloudId and componentId match your Compass component
3. Ensure the plugin executed successfully (check logs)
4. Check for rate limiting issues (100 requests per user per minute)

License

MIT