npm package: @moeed/nx-jira-compass
Description: Nx plugin for integrating with Atlassian Jira Compass
Author: Moeed HY
Latest version: 1.0.0

# @moeed/nx-jira-compass

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

## Installation

```bash
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:

```bash
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:

```bash
export COMPASS_USER_EMAIL=your-email@example.com
export COMPASS_API_TOKEN=your-atlassian-api-token
```

### Sending Events

You can send events to Jira Compass with:

```bash
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
   ```bash
   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
   ```bash
   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
   ```bash
   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:

```bash
# 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

```yaml
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