fix(jira-integration): Complete GitHub <> JIRA integration fixes

.env.example

@@ -0,0 +1,68 @@
+# ==============================================================================
+# Jira Integration Environment Variables
+# ==============================================================================
+# Copy this file to .env and fill in your actual values
+#
+# Required for Jira API access
+JIRA_BASE_URL=https://coursedog.atlassian.net
+[email protected]
+JIRA_API_TOKEN=your-jira-api-token
+
+# Optional: Jira project key for filtering (leave empty to search all projects)
+JIRA_PROJECT_KEY=
+
+# ==============================================================================
+# GitHub Context Variables (for local testing)
+# ==============================================================================
+# These are automatically set when running in GitHub Actions
+# For local testing, set them manually to simulate different scenarios
+
+# Git reference (branch or tag)
+# Examples: refs/heads/main, refs/heads/staging, refs/heads/dev
+GITHUB_REF=refs/heads/staging
+
+# Event type that triggered the workflow
+# Options: push, pull_request, pull_request_target
+GITHUB_EVENT_NAME=push
+
+# Path to the GitHub event payload file
+# For local testing, use ./update_jira/event.local.json
+GITHUB_EVENT_PATH=./update_jira/event.local.json
+
+# Repository in owner/repo format
+GITHUB_REPOSITORY=coursedog/notion-scripts
+
+# GitHub token for API access (required for fetching commit data)
+GITHUB_TOKEN=your-github-token
+
+# ==============================================================================
+# Testing Variables
+# ==============================================================================
+# For running verification and test scripts
+
+# Test issue key for custom field verification
+TEST_JIRA_ISSUE_KEY=DEX-36
+
+# Enable dry-run mode (will log actions but not actually update Jira)
+# DRY_RUN=true
+
+# ==============================================================================
+# Custom Field Configuration Reference
+# ==============================================================================
+# The following custom fields are used for deployment tracking (from ALL-593):
+#
+# customfield_11473: Release Environment (select field)
+#   - Option ID 11942: staging
+#   - Option ID 11943: production
+#
+# customfield_11474: Stage Release Timestamp (datetime)
+#   - Set automatically on staging deployments
+#
+# customfield_11475: Production Release Timestamp (datetime)
+#   - Set automatically on production deployments
+#
+# To verify these field IDs are correct for your Jira instance:
+#   node utils/verify-custom-fields.js
+#
+# To test updating these fields:
+#   node utils/test-custom-field-update.js DEX-36

.eslintrc.js

@@ -10,6 +10,8 @@ module.exports = {
   },
   globals: {
     process: 'readonly',
+    Buffer: 'readonly',
+    structuredClone: 'readonly',
   },
   rules: {
     'no-extend-native': [ 'error', { exceptions: [ 'Array' ] } ],

.gitignore

@@ -73,6 +73,7 @@ web_modules/
 .yarn-integrity
 
 # dotenv environment variables file
+.env
 .env.development.local
 .env.test.local
 .env.production.local

README.md

@@ -1 +1,95 @@
-# notion-scripts
+# GitHub Actions for Jira Integration
+
+This repository contains GitHub Actions for automating Jira issue management based on GitHub events.
+
+## Actions
+
+### update_jira
+
+Automatically updates Jira issues based on pull request events and deployments.
+
+**Features:**
+
+- Transitions Jira issues based on PR status and target branch
+- Updates deployment metadata (environment, timestamps) for staging/production releases
+- Supports dry-run mode for testing
+- Handles multiple Jira issues in PR titles/descriptions
+
+**Configuration:**
+
+```yaml
+- uses: ./update_jira
+  with:
+    jira-base-url: ${{ secrets.JIRA_BASE_URL }}
+    jira-email: ${{ secrets.JIRA_EMAIL }}
+    jira-api-token: ${{ secrets.JIRA_API_TOKEN }}
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+    dry-run: 'false'
+```
+
+**Custom Fields:**
+
+- `customfield_11473`: Release Environment (staging/production)
+- `customfield_11474`: Stage Release Timestamp
+- `customfield_11475`: Production Release Timestamp
+
+**Local Testing:**
+
+1. Copy `.env.example` to `.env` and fill in credentials
+2. Create `update_jira/event.local.json` with a sample GitHub event
+3. Run: `node update_jira/index.js`
+
+**Verification Scripts:**
+
+- `utils/verify-custom-fields.js`: Verify custom field IDs exist in your Jira instance
+- `utils/test-custom-field-update.js`: Test custom field updates with rollback
+
+**Integration Tests:**
+
+Run comprehensive Jira API integration tests:
+
+```bash
+node utils/jira.integration.test.js
+```
+
+This test suite will:
+
+- Test all Jira utility methods (workflows, transitions, custom fields, etc.)
+- Capture the original state of your test issue before making changes
+- Perform real API calls to your Jira instance
+- Prompt you to rollback all changes at the end
+
+**Required environment variables:**
+
+- `JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN` (required)
+- `TEST_JIRA_ISSUE_KEY` (default: `DEX-36`)
+- `TEST_JIRA_PROJECT_KEY` (default: `DEX`)
+- `TEST_JIRA_CUSTOM_FIELD` (default: `customfield_10001`)
+- `TEST_JIRA_CUSTOM_VALUE` (default: `test-value`)
+- `TEST_JIRA_STATUS` (default: `Done`)
+- `TEST_JIRA_PR_URL` (optional)
+
+Add these to your `.env` file before running the test.
+
+## Development
+
+**Prerequisites:**
+
+- Node.js 16+
+- Jira account with API token
+- GitHub repository access
+
+**Installation:**
+
+```bash
+npm install
+```
+
+**Environment Variables:**
+
+See `.env.example` for required configuration.
+
+## Related Tickets
+
+- **DEX-36**: Fix GitHub <> JIRA integration malfunctions
+- **ALL-593**: Push deployment metadata to Jira custom fields