Jira Integration
TwoWeeks can pull ticket titles and descriptions from Jira and push final estimates back.
Supported Jira Deployments
Section titled “Supported Jira Deployments”| Type | URL format | Auth | API base |
|---|---|---|---|
| Jira Cloud | https://your-domain.atlassian.net | Email + API Token | /rest/api/3/ |
| Jira Server | https://jira.your-company.com | Username + Password or PAT | /rest/api/2/ |
| Jira Data Center | Same as Server | Same | /rest/api/2/ |
Self-signed certificates on private servers are supported via the Allow insecure toggle.
Prerequisites
Section titled “Prerequisites”Jira Cloud
Section titled “Jira Cloud”- Go to Atlassian API tokens
- Create an API token
- Use your email address and the API token for authentication
Jira Server / Data Center
Section titled “Jira Server / Data Center”Option A — Personal Access Token (recommended):
- In Jira, go to your profile → Personal Access Tokens
- Create a token with read/write access
- Use your username and the token for authentication
Option B — Basic Auth:
- Use your username and password for authentication
Connecting to Jira
Section titled “Connecting to Jira”- As a session host, click Import from Jira in the sidebar
- Fill in the connection form:
| Field | Description |
|---|---|
| Jira URL | Full URL to your Jira instance |
| Server type | Cloud or Server/DC |
| Email / Username | Your Jira login |
| API Token / Password | Your token or password |
| Estimate field ID | Jira custom field for story points (e.g. customfield_10026) |
| Allow insecure | Enable for self-signed certificates on private servers. Your administrator can disable this (INTEGRATION_ALLOW_INSECURE_TLS=false); you’ll then see a warning and the certificate is always checked |
- Click Test connection & continue
If successful, you’ll see the list of available projects.
Security Note
Section titled “Security Note”Your Jira API token is encrypted at rest in the database when the server is configured with an ENCRYPTION_KEY environment variable. Without it, the token is stored in plaintext (a warning is logged at server startup). The Jira URL, email, and field ID are persisted so you don’t need to re-enter them when you come back to a draft session.
A token saved in your host defaults is never sent back to the browser: the settings form shows Token saved · Replace, and the importer can leave the token field empty (“Saved token will be used”) because the server uses the saved token for the same Jira URL. Changing the saved URL without entering a new token clears the old one.
Filtering Issues
Section titled “Filtering Issues”After connecting, use the filter panel to build a JQL query:
| Filter | JQL equivalent |
|---|---|
| Project | project = KEY |
| Issue type | issuetype = Story |
| Status | status = "To Do" |
| Labels | labels = "needs-estimation" |
| Text search | text ~ "search term" |
Filters combine with AND. For example:
project = PROJ AND issuetype = Story AND labels = "needs-estimation"Toggle Use raw JQL to write custom JQL directly — useful for complex queries like sprint filters or date ranges.
Importing Issues
Section titled “Importing Issues”- Click Search issues after setting up filters
- Review the results — you’ll see key, summary, type, and status for each issue
- Check the boxes for issues you want to import (or use Select all)
- Click Review import
- Confirm the list and click Import N tickets
Imported tickets appear in your session ticket queue. Each ticket stores its Jira key (PROJ-123) and URL for later updates.
Pushing Estimates Back to Jira
Section titled “Pushing Estimates Back to Jira”After finalizing an estimate for a Jira-imported ticket:
- Click Confirm & update to finalize the estimate
- An Update PROJ-123 in Jira button appears
- Click it to push the final estimate to the configured custom field in Jira
The estimate value is sent as-is (string for T-Shirt sizes, number for story points). If the field expects a number, TwoWeeks attempts numeric conversion.
Resyncing a Ticket
Section titled “Resyncing a Ticket”If a Jira issue’s title, description, or labels change after it’s been imported, the host can pull the latest version without re-importing:
- Open the ticket’s details panel (double-click the ticket)
- Click 🔄 Resync next to the Jira key
- The title, description, and labels update from Jira and sync to everyone currently viewing the ticket
Resync is only available for tickets that were imported from Jira — manually-added tickets have nothing to resync from.
Troubleshooting
Section titled “Troubleshooting”| Error | Fix |
|---|---|
| Could not reach Jira | Check the URL and network. Error messages are deliberately generic — your administrator can see the detailed reason in the server log |
| URL is not allowed | The server’s integration policy blocks that address (for example cloud-metadata addresses, or localhost unless your administrator allow-lists it with INTEGRATION_HOST_ALLOWLIST) |
| Jira rejected the credentials | Verify email/username and token/password. For Cloud, make sure you’re using an API token, not your login password |
| Could not verify Jira’s TLS certificate | Enable “Allow insecure” for self-signed certificates (if your administrator allows it), or ask your administrator to configure CA_BUNDLE_PATH |
| Search returns no results | Check JQL syntax. Try using the filter widgets instead of raw JQL |
| Update fails | Verify the estimate field ID is correct. Check that the field exists on the issue’s project screen |
| Resync fails | The issue may have been deleted or moved in Jira, or the connection may have expired — reconnect to Jira and try again |