Coding Agent Workflow Documentation

Overview

The Coding Agent is an automated system that integrates Jira issues with GitHub Actions and Cursor CLI to automatically implement code changes based on Jira ticket requirements. It can create branches, implement features, deploy to custom environments, create Pull Requests, and iteratively fix issues based on PR feedback.

Important

The files in this repository are placed outside of .git folder for better visibility. At the end of this document there is a decription as to how to place the files in a real project

General Flows

Flow 1: Initial Implementation (New Jira Ticket)

1. Trigger: User add a label coding_agent in a Jira issue comment
2. Jira Webhook: Sends coding_agent event to GitHub
3. Event Dispatch Workflow (coding-agent-event-dispatch.yaml):
   • Validates Jira issue key format (RND-123 or RES-123)
   • Checks if branch {JIRA_KEY}-Coding-Agent exists
   • Routes to initial-commit workflow if branch doesn't exist
4. Initial Commit Workflow (coding-agent-initial-commit.yaml):
   • Downloads existing files from Azure Blob Storage (if any)
   • Creates new branch: {JIRA_KEY}-Coding-Agent
   • Extracts Jira issue information (if no files from blob storage exist)
   • Runs Cursor CLI to implement changes
   • Formats and commits changes
   • Uploads files to Azure Blob Storage
   • Deploys to custom Azure Static Web App environment
   • Creates Pull Request with deployment URL
   • Sends Slack notification

Flow 2: Fix PR Comments (Existing Branch)

1. Trigger: User comments @coding_agent on a GitHub Pull Request
2. Comment Dispatch Workflow (coding-agent-comment-dispatch.yaml):
   • Validates comment contains @coding_agent
   • Verifies PR exists and is open
   • Extracts Jira issue key from branch name
   • Triggers fix-pr workflow
3. Fix PR Workflow (coding-agent-fix-pr.yaml):
   • Downloads existing files from Azure Blob Storage
   • Checks out existing branch
   • Extracts Jira issue if .coding_agent folder missing
   • Generates branch diff (current vs default branch)
   • Fetches PR comments (issue comments and review comments)
   • Processes and converts comments to YAML
   • Runs Cursor CLI with combined context (Jira issue + PR comments + branch diff)
   • Formats and commits fixes
   • Uploads files to Azure Blob Storage
   • Deploys updated changes
   • Updates PR with completion status
   • Sends Slack notification

Flow 3: Direct Workflow Dispatch

Both workflows can also be triggered manually via workflow_dispatch:

• Navigate to Actions → Select workflow → Run workflow
• Provide jira_issue_key and branch_name as inputs

Workflow Files

Entry Point Workflows

coding-agent-event-dispatch.yaml

• Purpose: Main entry point for Jira-triggered events
• Trigger: repository_dispatch event with type coding_agent
• Function:
  • Validates Jira issue key format
  • Checks if branch exists
  • Routes to either initial-commit or fix-pr workflow based on branch existence
• Key Features:
  • Validates issue key format: RND-123 or RES-123 (case insensitive)
  • Concurrency control per Jira issue key

coding-agent-comment-dispatch.yaml

• Purpose: Entry point for PR comment triggers
• Trigger: issue_comment event (when comment contains @coding_agent)
• Function:
  • Validates comment is on a PR (not an issue)
  • Extracts Jira issue key from branch name
  • Triggers fix-pr workflow
  • Posts confirmation comment on PR
• Key Features:
  • Only processes open PRs
  • Extracts Jira key from branch name pattern: {JIRA_KEY}-Coding-Agent

Supporting Workflows

deploy-custom-url.yaml

• Purpose: Deploys to custom Azure Static Web App environment
• Function: Creates a deployment slot named after the Jira issue key
• Used by: Both initial-commit and fix-pr workflows

Azure Blob Storage

All coding agent files are stored in Azure Blob Storage instead of being committed to the repository:

• Container: coding-agent
• Path Structure: {jira_key}/ (e.g., RND_123/issue_info.json)
• Files Stored:
  • issue_info.json - Complete Jira issue data
  • issue_info.md - Human-readable issue summary
  • plan.md - Implementation plan
  • summary.md - Implementation summary
  • pr_comments.json - Processed PR comments
  • pr_comments.yaml - PR comments in YAML format
  • handled_comments.yaml - Tracks processed comments
  • branch_diff.txt - Git diff
  • issue_comments.json - Raw PR comments
  • review_comments.json - Raw review comments
  • attachments/ - Jira attachments (images, etc.)

Workflow:

1. Files are downloaded at the beginning of each workflow job (if they exist)
2. All operations work on local .coding_agent folder
3. Files are uploaded to blob storage at the end of each workflow job
4. The .coding_agent folder is in .gitignore and not committed

Setup

Required GitHub Secrets

Jira Integration

• JIRA_API_TOKEN
  • Description: Jira API token for authentication
    • How to get:
    1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
    2. Click "Create API token"
    3. Give it a label (e.g., "Coding Agent")
    4. Copy the generated token
  • Required for: All workflows

Cursor CLI

• CURSOR_API_KEY
  • Description: API key for Cursor CLI
  • How to get:
    1. Sign up/login at https://cursor.com
    2. Navigate to API settings
    3. Generate an API key
  • Required for: All workflows

GitHub App (for repository access)

• GITHUB_CODING_AGENT_APP_ID

  • Description: GitHub App ID
  • How to get:
    1. Create a GitHub App at https://github.com/settings/apps/new
    2. Set permissions:
       • Repository permissions:
         • Contents: Read and write
         • Pull requests: Read and write
         • Issues: Read
         • Actions: Read
         • Checks: Read and write
       • Account permissions:
         • None required
    3. Copy the App ID from the app settings page
  • Required for: All workflows

• GITHUB_CODING_AGENT_KEY

  • Description: GitHub App private key (PEM format)
  • How to get:
    1. In your GitHub App settings, go to "Private keys"
    2. Click "Generate a private key"
    3. Download the .pem file
    4. Copy the entire contents (including -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY-----)
  • Required for: All workflows

Azure Static Web Apps

• AZURE_STATIC_WEB_APPS_API_TOKEN
  • Description: Deployment token for Azure Static Web Apps
  • How to get:
    1. Go to Azure Portal → Your Static Web App
    2. Navigate to "Manage deployment token"
    3. Copy the deployment token
  • Required for: All workflows

Azure Blob Storage

• AZURE_STORAGE_ACCOUNT
  • Description: Azure Storage Account name
  • Example: mystorageaccount
  • How to get:
    1. Go to Azure Portal → Storage accounts
    2. Find or create a storage account
    3. Copy the storage account name
  • Required for: All workflows
  • Note: The container coding-agent must be created manually or via infrastructure as code

Azure Authentication (for Blob Storage access)

• AZURE_CLIENT_ID
  • Description: Azure AD Application (Service Principal) Client ID
  • How to get:
    1. Go to Azure Portal → Azure Active Directory → App registrations
    2. Create a new app registration or use existing
    3. Copy the Application (client) ID
    4. Create a client secret in "Certificates & secrets"
    5. Grant the app "Storage Blob Data Contributor" role on the storage account
  • Required for: All workflows

Required GitHub Variables

These variables should be set in the dev environment (Settings → Environments → dev → Environment variables).

Jira Configuration

• JIRA_BASE_URL

  • Description: Your Jira instance URL
  • Example: https://yourcompany.atlassian.net
  • How to get: Your Jira instance URL
  • Required for: All workflows

• JIRA_USER_EMAIL

  • Description: Email address of the Jira user account
    • Example: coding-agent@yourcompany.com
  • How to get: Create a service account in Jira or use an existing user
  • Required for: All workflows

Azure Configuration

• AZURE_TENANT_ID

  • Description: Azure AD Tenant ID
  • How to get:
    1. Go to Azure Portal → Azure Active Directory
    2. Copy the Tenant ID from "Overview"
  • Required for: All workflows

• AZURE_SUBSCRIPTION_ID

  • Description: Azure Subscription ID
  • How to get:
    1. Go to Azure Portal → Subscriptions
    2. Copy the Subscription ID
  • Required for: All workflows

Notifications

• CODING_AGENT_SLACK_RND_WEBHOOK
  • Description: Slack webhook URL for notifications
  • How to get:
    1. Go to Slack → Apps → Incoming Webhooks
    2. Create a new webhook
    3. Select the channel for notifications
    4. Copy the webhook URL
  • Required for: Slack notifications (optional but recommended)

GitHub Environment Setup

The workflows require a GitHub environment named dev to be configured:

1. Go to Settings → Environments → New environment
2. Create an environment named dev
3. Add the required environment variables (see "Required GitHub Variables" above)
4. Optionally configure environment protection rules (reviewers, wait timer, etc.)

All workflow jobs that need Azure authentication must have environment: name: dev specified to access the environment-scoped variables.

Required Permissions

GitHub Repository Permissions

The workflows require the following permissions (configured in workflow files):

• contents: write - To create branches and commit changes
• pull-requests: write - To create and update Pull Requests
• issues: read - To read PR comments
• actions: write - To trigger other workflows
• checks: write - For deployment checks
• id-token: write - For Azure authentication

These are automatically configured in the workflow files and don't require manual setup.

Azure Permissions

The Azure Service Principal (identified by AZURE_CLIENT_ID) needs:

1. Storage Blob Data Contributor role on the storage account

   • How to set:
     1. Go to Azure Portal → Storage Account → Access control (IAM)
     2. Click "Add role assignment"
     3. Select "Storage Blob Data Contributor"
     4. Assign to your Service Principal (App Registration)

2. Static Web Apps Contributor role (if deploying)

   • How to set:
     1. Go to Azure Portal → Static Web App → Access control (IAM)
     2. Click "Add role assignment"
     3. Select "Static Web Apps Contributor"
     4. Assign to your Service Principal

Jira Webhook Setup

To enable Jira-triggered workflows:

1. Create Jira Webhook:

   • Go to Jira Settings → System → Webhooks
   • Create a new webhook
   • URL: https://api.github.com/repos/{owner}/{repo}/dispatches
   • Events: Select "Comment created"
   • Authentication: Use Basic Auth with a GitHub Personal Access Token

2. Webhook Payload (when @coding_agent is mentioned):

   {
     "event_type": "coding_agent",
     "client_payload": {
       "jira_issue_key": "RND-123"
     }
   }

3. GitHub Personal Access Token (for webhook):

   • Create at https://github.com/settings/tokens
   • Scopes needed: repo (full control of private repositories)
   • Use this token in Jira webhook Basic Auth

Verification

After setup, verify the configuration:

1. Test Initial Commit Flow:

   • Tag @coding_agent in a Jira issue comment
   • Check GitHub Actions for workflow run
   • Verify branch is created and PR is opened

2. Test Fix PR Flow:

   • Comment @coding_agent on an existing PR
   • Check GitHub Actions for workflow run
   • Verify changes are committed

3. Check Azure Blob Storage:

   • Verify files are uploaded to coding-agent container
   • Check files are organized by Jira issue key

Troubleshooting

Common Issues

1. Workflow fails with "No existing files found in blob storage"

   • This is normal for first runs
   • The workflow will create new files

2. Azure authentication fails

   • Verify AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_SUBSCRIPTION_ID are correct
   • Ensure Service Principal has required roles
   • Ensure the workflow job has environment: name: dev set (required to access environment-scoped variables)

3. Blob storage upload/download fails

   • Verify AZURE_STORAGE_ACCOUNT is correct
   • Ensure container coding-agent exists
   • Check Service Principal has "Storage Blob Data Contributor" role

4. Cursor CLI fails

   • Verify CURSOR_API_KEY is valid
   • Check Cursor API quota/limits

5. GitHub App authentication fails

   • Verify GITHUB_CODING_AGENT_APP_ID and GITHUB_CODING_AGENT_KEY are correct
   • Ensure GitHub App has required permissions
   • Check the App is installed on the repository

File Structure

.github/
├── workflows/
│   ├── coding-agent-event-dispatch.yaml      # Main entry point (Jira → GitHub)
│   ├── coding-agent-comment-dispatch.yaml     # PR comment entry point
│   ├── coding-agent-initial-commit.yaml       # First-time implementation
│   ├── coding-agent-fix-pr.yaml               # Iterative fixes
│   └── deploy-custom-url.yaml                 # Custom environment deployment
├── scripts/
│   └── jira_issue_extractor/                 # Jira issue extraction scripts
README.md                                     # This file

Additional Notes

• The .coding_agent folder is in .gitignore and should never be committed
• All files are stored in Azure Blob Storage, organized by Jira issue key
• Image URLs in PR descriptions point to Azure Blob Storage, not GitHub
• Each workflow run is isolated - files are downloaded at the start and uploaded at the end
• Concurrency is controlled per Jira issue key to prevent duplicate runs