Skip to main content
Connect Codemod to your Jira workspace to sync issues with your projects and automatically track progress of your code transformation campaigns.

​
Why Integrate Jira?

Integrating Codemod with Jira allows you to:
  • Link code transformation projects to Jira epics for tracking
  • Automatically sync task progress between Codemod and Jira
  • Trigger codemods based on Jira issue updates

​
Setting Up the Integration

​
Step 1: Navigate to Organization Settings

Sign in to Codemod and navigate to your organization settings:
  1. Select your organization from the team switcher
  2. Go to Settings from the organization menu
  3. Scroll down to the Project Management Integrations section

​
Step 2: Connect Jira

Click the “Connect Jira” button to begin the integration process. Screenshot of organization settings page with PM integrations section

​
Step 3: Create a Jira API Token

Before proceeding, you’ll need to create an Atlassian API token:
1

Navigate to Atlassian Account Settings

Go to Atlassian API Tokens and sign in to your account.
2

Create API Token

  1. Click “Create API token”
  2. Enter a label (e.g., “Codemod Integration”)
  3. Click “Create”
  4. Copy the generated token immediately
Make sure to copy the token right away. Atlassian will only show it once for security reasons.
Screenshot of Atlassian API token creation page

​
Step 4: Configure Jira Integration

Fill in the Jira integration form with your workspace details:
​
baseUrl
string
required
Your Jira Cloud instance URL (e.g., https://your-domain.atlassian.net)
​
email
string
required
The email address associated with your Jira account
​
apiToken
string
required
The API token you created in the previous step
​
webhookSecret
string
Optional webhook secret for validating webhook signatures (recommended for security)
Screenshot of Jira integration configuration form Click “Connect Jira” to complete the initial setup. Webhooks allow Codemod to receive real-time updates when Jira issues change. This is optional but recommended for the best experience.

​
Step 1: Access Webhook Settings

After connecting Jira, you’ll see webhook configuration options in your organization settings:
  1. Find your connected Jira integration in the settings
  2. Click the webhook icon to configure webhooks
Screenshot showing webhook configuration button in settings

​
Step 2: Configure Webhook in Jira

1

Copy webhook URL

Copy the webhook URL provided in the Codemod webhook configuration modal.
2

Navigate to Jira webhook settings

Go to your Jira workspace at https://your-domain.atlassian.net/plugins/servlet/webhooksOr navigate manually:
  1. Go to Jira Settings (⚙️ icon)
  2. Select System → Webhooks
  3. Click “Create a webhook”
3

Create webhook

Fill in the webhook details:
  • Name: Codemod Integration
  • Status: Enabled
  • URL: Paste the webhook URL from Codemod
  • Issue related events: Check all issue events (created, updated, deleted)
4

Add webhook secret

Generate a webhook secret and copy it. This will be used to validate the webhook signature.

​
Step 3: Save Webhook Configuration

Back in Codemod, enter your webhook secret and save the configuration.

​
Managing Your Jira Integration

​
Updating Credentials

To update your Jira API token or email:
  1. Go to Organization Settings → Project Management Integrations
  2. Find your Jira integration and click the credentials icon (🔑)
  3. Enter your updated email and API token
  4. Click “Update Credentials”

​
Updating Webhook Settings

To modify webhook configuration:
  1. Go to Organization Settings → Project Management Integrations
  2. Find your Jira integration and click the webhook icon
  3. Update your webhook secret
  4. Click “Save Webhook Configuration”

​
Linking Projects to Jira Epics

Once Jira is integrated, you can link individual Codemod projects (campaigns) to Jira epics for tracking.

​
From a Project Page

1

Navigate to your project

Open any Codemod project/campaign from your dashboard.
2

Click 'Link to Jira Epic'

In the project header area, you’ll see a “Link to a Jira Epic” button with the Jira logo.Screenshot showing the link button in project header
3

Select Jira workspace

If you have multiple PM integrations, select your Jira workspace from the provider dropdown.
4

Search and select epic

  1. Search for your Jira project or epic by typing in the search field
  2. Select the appropriate Jira project from the dropdown
  3. The format will show: PROJECT-KEY - Project Name
Screenshot of project linking modal with Jira project selection
5

Confirm linking

Click “Link Project” to establish the connection between your Codemod campaign and the Jira epic.

​
Viewing Linked Projects

Once linked, you’ll see the connection status in your project:
  • Linked projects display the Jira project key and name
  • Status sync shows progress updates from Jira
  • Quick access provides direct links to the associated Jira epic

​
Benefits of Project Linking

Progress Tracking

Automatically sync task progress between Codemod campaigns and Jira epics for unified reporting.

Team Visibility

Keep your entire team informed about code transformation progress through familiar Jira workflows.

Project Management

Integrate code modernization efforts into your existing project management and sprint planning.

Audit Trail

Maintain complete visibility and traceability of all code changes through Jira issue tracking.

​
Required Permissions

Your Jira API token needs the following permissions: Read access to:
  • Projects and project configurations
  • Issues and issue metadata
  • User information
Write access to:
  • Issues (to sync status updates)
  • Comments (for progress notifications)
These permissions are typically included with standard Jira user accounts. Admin permissions are not required.

​
Troubleshooting

  • Verify your Jira base URL is correct (should be https://your-domain.atlassian.net)
  • Check that your email matches your Jira account email exactly
  • Ensure your API token is valid and hasn’t expired
  • Try generating a new API token from Atlassian
  • Confirm you have access to the Jira projects you’re trying to link
  • Check that the projects exist in the Jira workspace you connected
  • Verify your API token has read access to the specific projects
  • Try refreshing the project list or searching with different terms
  • Verify the webhook URL is correctly configured in Jira
  • Check that the webhook is enabled in Jira settings
  • Ensure the webhook secret matches between Jira and Codemod (if used)
  • Confirm that issue events are selected in the Jira webhook configuration
  • Check that webhooks are properly configured and enabled
  • Verify network connectivity between Jira and Codemod
  • Ensure your API token has write access to update issues
  • Try unlinking and relinking the project

​
Security Considerations

Keep your Jira API token secure and never share it publicly or commit it to version control.
  • Token Security: All API tokens are encrypted at rest and in transit using industry-standard encryption
  • Webhook Validation: Use webhook secrets to validate incoming requests from Jira
  • Minimal Access: Only grant the minimum required permissions for your integration needs
  • Regular Rotation: Consider rotating API tokens regularly for enhanced security
  • Access Review: Regularly review which projects and issues have access in your Jira workspace

​
Managing the Integration

To disconnect or modify the Jira integration:
  1. Go to Organization Settings → Project Management Integrations
  2. Find your Jira integration and click “Disconnect” or the configure buttons
To revoke access from Jira’s side:
  1. Go to Atlassian API Tokens
  2. Find the Codemod token and click “Delete”
Need help? If you encounter any issues setting up the Jira integration, please contact our support team or visit our documentation for additional troubleshooting steps.
⌘I