Advanced Analytica Advanced Analytica: IBOM
← All connectors
Jira logo

Source connector

Jira

Set up Jira as a source and move its data into your chosen destination.

Version 6.1.1 certified generally available

Jira

Use this page to set up the Jira source connector and find reference information.

Before you start

You need:

  • A Jira Cloud site hostname, for example airbyteio.atlassian.net
  • One of these authentication methods:
    • OAuth 2.0 access to Jira
    • An Atlassian account email and an Atlassian API token without scopes
    • An Atlassian Service Account API token
  • Jira permissions for the data you want to sync. The authenticating user needs the Administer Jira global permission to sync all workflow records. Project-scoped workflows require at least one of the Administer projects and View (read-only) workflow project permissions.

Set up Jira

Step 1: Prepare Jira

Choose how Airbyte will authenticate to Jira.

  • For OAuth 2.0, authorise Airbyte to access your Jira site. For a custom OAuth app, see Atlassian’s OAuth 2.0 (3LO) documentation. The connector requests its required scopes, including offline_access, read:workflow:jira, and manage:jira-configuration.
  • For an API token, follow Atlassian’s API token instructions to create a token without scopes. API token authentication uses HTTP Basic authentication with your Atlassian account email and Jira site hostname.
  • For a Service Account token, follow Atlassian’s Service Account API token instructions to create an Atlassian Service Account API token with scopes.

Step 2: Set up the connector

Airbyte Cloud

  1. Open your Log into your Airbyte Cloud account.
  2. Click Sources, then click + New source.
  3. On the Set up the source page, select Jira from the Source type dropdown.
  4. Enter a name for the Jira connector.
  5. Choose an authentication method. For OAuth 2.0, authenticate your Jira account. For API token authentication, enter your Atlassian account’s Email and the API Token you created. For Service Account authentication, enter the Service Account Token.
  6. Enter your Jira site’s Domain, for example airbyteio.atlassian.net. Don’t include https:// or a path.
  7. Enter the Projects (Optional) whose data you want to replicate. Leave this empty to replicate all projects the authenticated user can access.
  8. Enter the Start Date (Optional) for replicating Jira data in the format YYYY-MM-DDTHH:MM:SSZ. The connector uses this value only for Board Issues, Issue Changelogs, Issue Comments, Issue Worklogs, Issues, and Sprint Issues. Other streams always sync every available record.

For Airbyte Open Source:

  1. Go to the Airbyte Open Source dashboard.
  2. Click Sources, then click + New source.
  3. On the Set up the source page, select Jira from the Source type dropdown.
  4. Enter a name for the Jira connector.
  5. Choose an authentication method. For API token authentication, enter your Atlassian account’s Email and the API Token you created. For OAuth 2.0, enter the client ID, client secret, and refresh token from your Atlassian OAuth app. For Service Account authentication, enter the Service Account Token.
  6. Enter your Jira site’s Domain, for example airbyteio.atlassian.net. Don’t include https:// or a path.
  7. Enter the Projects (Optional) whose data you want to replicate. Leave this empty to replicate all projects the authenticated user can access.
  8. Enter the Start Date (Optional) for replicating Jira data in the format YYYY-MM-DDTHH:MM:SSZ. The connector uses this value only for Board Issues, Issue Changelogs, Issue Comments, Issue Worklogs, Issues, and Sprint Issues. Other streams always sync every available record.

Use Service Account API tokens

Atlassian Service Account API tokens must use Atlassian’s Platform API Gateway. In Airbyte, set Authentication to Service Account and enter your Jira site’s Domain. The connector resolves the Cloud ID from the domain. It routes Jira requests through https://api.atlassian.com/ex/jira/{cloudId}/ and authenticates with a Bearer token.

Create a Service Account API token as follows:

  1. Go to admin.atlassian.com.
  2. Go to Directory > Service accounts.
  3. Create a service account or choose an existing one.
  4. Under Credentials, click Create credential.
  5. Select API token.
  6. Set a token name and expiration date. The maximum expiration is 365 days.
  7. Add the required scopes. Paste the full comma-separated scope list into scope search to filter the list.
  8. Select the scopes, click Next, and create the token.

Service Account API tokens use the same Jira OAuth scopes as OAuth 2.0 credentials. Select these scopes when you create the token:

read:jira-work
read:jql:jira
read:group:jira
read:project-role:jira
read:issue-details:jira
read:status:jira
read:jira-user
read:user:jira
read:avatar:jira
read:webhook:jira
read:project-category:jira
read:screenable-field:jira
read:screen-field:jira
offline_access
read:board-scope:jira-software
read:project:jira
read:sprint:jira-software
read:application-role:jira
read:notification-scheme:jira
read:issue-security-scheme:jira
read:issue-security-level:jira
read:issue-type-scheme:jira
read:issue-type-screen-scheme:jira
read:permission-scheme:jira
read:screen:jira
read:screen-scheme:jira
read:screen-tab:jira
read:workflow:jira
read:workflow-scheme:jira
read:project.email:jira
read:custom-field-contextual-configuration:jira
manage:jira-configuration

Paste this comma-separated scope list into Atlassian’s scope search:

read:jira-work,read:jql:jira,read:group:jira,read:project-role:jira,read:issue-details:jira,read:status:jira,read:jira-user,read:user:jira,read:avatar:jira,read:webhook:jira,read:project-category:jira,read:screenable-field:jira,read:screen-field:jira,offline_access,read:board-scope:jira-software,read:project:jira,read:sprint:jira-software,read:application-role:jira,read:notification-scheme:jira,read:issue-security-scheme:jira,read:issue-security-level:jira,read:issue-type-scheme:jira,read:issue-type-screen-scheme:jira,read:permission-scheme:jira,read:screen:jira,read:screen-scheme:jira,read:screen-tab:jira,read:workflow:jira,read:workflow-scheme:jira,read:project.email:jira,read:custom-field-contextual-configuration:jira,manage:jira-configuration

The service account also needs Jira app access and the project permissions required for your synced streams. It needs the Administer Jira global permission to sync all workflow records.

Supported sync modes

The Jira source connector supports these sync modes:

Supported streams

The connector outputs these full refresh streams:

The connector outputs these incremental streams:

If you want Airbyte to support more endpoints, create an issue.

Workflows stream

The workflows stream uses Jira’s GET /rest/api/3/workflows/search endpoint. Jira plans to remove the deprecated GET /rest/api/3/workflow/search endpoint on June 1, 2026. Version 5.0.0 of this connector moved the stream to the replacement endpoint.

If you sync workflows and upgrade from before 5.0.0, refresh the source schema. Then clear the workflows stream before syncing again. For details, see the Jira migration guide.

Streams with high I/O usage

Some streams above make one HTTP request for each issue. With many issues, these streams can significantly slow your sync. If they cause slowness, filter the issue list using the Projects configuration field. You can also remove these streams from the sync.

  • Issue changelogs
  • Issue comments
  • Issue properties
  • Issue remote links
  • Issue transitions
  • Issue votes
  • Issue watchers
  • Issue worklogs

Entity-relationship diagram

Troubleshooting

A stream returns fewer records than expected

Jira only returns records visible to the authenticating user or service account. A missing stream therefore usually indicates a permissions problem, not a connector problem. Check the account has Jira app access and project permissions for each project you sync. For the full workflows stream, also check it has the Administer Jira global permission.

The connector skips requests that Jira answers with HTTP 400 instead of failing the sync. Jira returns 400 for requests it considers invalid. This can happen when a stream queries a Jira feature that your site hasn’t enabled. The stream can therefore finish successfully without records. If a stream returns less data than expected, check the sync logs for 400 responses. board_issues is the exception and fails the sync on HTTP 400. However, it skips boards that Jira reports as having no columns with a mapped status.

Recent issues are late or missing from issues, board_issues, or sprint_issues

The issues, board_issues, and sprint_issues streams read from Jira’s eventually consistent issue search. Most changes become searchable within seconds, but bulk edits can take minutes. With Lookback window (lookback_window_minutes) set to 0, unsearchable changes arrive one sync later. This happens when the connector queries a board, sprint, or issue search before the change becomes searchable. An earlier change can be skipped if a later change from the same board, sprint, or search was already synced. Jira won’t return that earlier change until the issue is updated again. Set Lookback window to a few minutes, for example 5. Each incremental sync then rereads recent changes and emits records in that window again.

The sync is slow

See Streams on I/O usage. These streams make one request for each issue, so runtime increases with your issue count.

For other problems, search the Airbyte forum or create an issue.

Rate limits and performance

Jira Cloud applies three independent rate limits. These include an hourly points-based quota, per-second burst limits for each endpoint, and per-issue write limits. Jira returns HTTP 429 when you exceed any limit. The connector retries throttled and other transient responses up to 10 times before failing the sync.

Most syncs stay within these quotas. If you see repeated 429 responses, lower num_workers to reduce concurrent requests. You can also limit the sync to specific projects using Projects. Alternatively, remove the per-issue streams listed in Streams on I/O usage. Create an issue if retries don’t resolve the rate limit errors.

IP allow list

If you use Airbyte Cloud and your organisation restricts access by IP, add the Airbyte Cloud IP addresses to your allow list.

Reference

For programmatic setup with PyAirbyte, Terraform, or the Airbyte API, use these connector configuration fields:

FieldRequiredDescription
credentials.auth_typeYesAuthentication method. Valid values are API Token, OAuth2.0, and Service Account.
credentials.emailRequired for API token authenticationAtlassian account email used with the API token.
credentials.api_tokenRequired for API token authenticationAtlassian API token. Use an API token without scopes.
credentials.client_idRequired for OAuth 2.0 authenticationClient ID of your Atlassian OAuth app.
credentials.client_secretRequired for OAuth 2.0 authenticationClient secret of your Atlassian OAuth app.
credentials.refresh_tokenRequired for OAuth 2.0 authenticationRefresh token returned by the Atlassian OAuth flow.
credentials.service_account_tokenRequired for Service Account authenticationAtlassian Service Account API token with the required Jira scopes.
domainYesJira site hostname, for example airbyteio.atlassian.net. Don’t include https:// or a path.
projectsNoList of Jira project keys to replicate. Leave empty to replicate all projects the authenticated user can access.
start_dateNoUTC date and time in the format YYYY-MM-DDTHH:MM:SSZ. Applies to the Board Issues, Issue Changelogs, Issue Comments, Issue Worklogs, Issues, and Sprint Issues streams. If you leave it empty, those streams start 730 days (two years) before the first sync.
lookback_window_minutesNoNumber of minutes to re-read on each incremental sync. Defaults to 0.
num_workersNoNumber of concurrent threads to use for the sync. Valid values are 1 through 40. Defaults to 5.

Changelog

Expand to review
VersionDatePull RequestSubject
6.1.12026-11-1091822Update to source-declarative-manifest 7.47.0 base image
6.1.02026-10-2080198Migrate board_issues and sprint_issues from the deprecated /rest/agile/1.0/ issue endpoints to /rest/software/1.0/ before Atlassian removes them after 2026-11-01. board_issues now retries HTTP 500 errors instead of skipping the board; boards with no columns with a mapped status are still skipped
6.0.42026-10-1388409Type rendered comment bodies in issues (renderedFields.comment.comments[].body) as HTML strings. Avro/Parquet destinations now receive this value (previously null) as a string instead of a struct
6.0.32026-09-1786357Fix issues stream failing with UndefinedError when an issue has no fields.project
6.0.22026-09-1085802Stop config migration from adding empty api_token, email, and domain fields to OAuth or partially-migrated configs
6.0.12026-07-2782702Increase issue_worklogs page size to 5000 to reduce the number of paginated requests
6.0.02026-06-2480279Remove deprecated issue_field_configurations stream (Atlassian removing endpoint July 2026)
5.1.12026-06-0979606Clean up cancelled RC; revert source to previous stable
5.1.1-rc.12026-05-2678441Adjust default concurrency to 7 and enable progressive rollout for concurrency tuning
5.1.02026-05-2178130Add Service Account authentication support
5.0.02026-05-2070448Migrate the workflows stream from the deprecated /rest/api/3/workflow/search endpoint to its replacement /rest/api/3/workflows/search. Primary key changes from [entityId, name] to [id], and the record schema is updated to match the new endpoint.
4.4.12026-05-1478088Fix domain validation regression: auto-normalize domains with https:// prefix or trailing slashes
4.4.02026-05-1176067Add OAuth 2.0 authentication support with config migration
4.3.212026-05-0577751Add input validation for domain field
4.3.202026-04-2276354Bump SDM base image for deadlock fix
4.3.192026-04-2176631Update dependencies
4.3.182026-04-1376276Rename “concurrent workers” to “concurrent threads” in connector spec
4.3.172026-03-1775080Update dependencies
4.3.162026-03-1074500Update dependencies
4.3.152026-02-2473898Update dependencies
4.3.142026-02-1773494Update dependencies
4.3.132026-02-1073044Update dependencies
4.3.122026-02-0372758Update dependencies
4.3.112026-01-2071963Update dependencies
4.3.102026-01-1471423Update dependencies
4.3.92025-12-1870533Update dependencies
4.3.82025-11-2570186Update dependencies
4.3.72025-11-1869571Update dependencies
4.3.62025-10-2968818Update dependencies
4.3.52025-10-2168478Update dependencies
4.3.42025-10-1467962Update dependencies
4.3.32025-10-0767375Update dependencies
4.3.22025-09-3066791Update dependencies
4.3.12025-09-0965900Update dependencies
4.3.02025-09-0865917Add issue_changelogs stream
4.2.52025-08-2765565Increases maxSecondsBetweenMessages and defaults start_date to 2 years in the past
4.2.42025-08-2365337Update dependencies
4.2.32025-08-0964583Update dependencies
4.2.22025-08-0264216Update dependencies
4.2.12025-07-2663916Update dependencies
4.2.02025-07-2463761Promoting release candidate 4.2.0-rc.1 to a main version.
4.2.0-rc.12025-07-2163366Migrate the issues stream from /search to /search/jql due to API deprecation
4.1.72025-07-1963461Update dependencies
4.1.62025-07-1263104Update dependencies
4.1.52025-07-0562640Update dependencies
4.1.42025-06-2862186Update dependencies
4.1.32025-06-2161812Update dependencies
4.1.22025-06-1452790Update dependencies
4.1.12025-05-2660908Update dependencies
4.1.02025-05-1560298Promoting release candidate 4.1.0-rc.1 to a main version.
4.1.0-rc.12025-05-1259689Migrate to manifest-only format
4.0.02025-05-0759172Remove deprecated pull_requests stream and Python stream code
3.5.42025-04-1658100Fix cdk conflicts & upgrade
3.5.32025-01-2552291Update dependencies
3.5.22025-01-2552291Update dependencies
3.5.12025-01-2452134Fix low-code state migration
3.5.02025-01-2352105Update incremental per partition streams to use concurrency
3.4.82025-01-1151189Update dependencies
3.4.72025-01-0450886Update dependencies
3.4.62024-12-2850625Update dependencies
3.4.52024-12-2150108Update dependencies
3.4.42024-12-1449224Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64
3.4.32024-12-1247087Update dependencies
3.4.22024-12-0948838Fixing timezone gaps with state
3.4.12024-12-0948859Add a couple of fixes regarding memory usage
3.4.02024-12-0548738Enable concurrency for substreams without cursor
3.3.12024-11-1848539Update dependencies
3.3.0-rc.32024-11-1448395Change JQL filters comparing cursor values to use milliseconds since unix epoch so that data isn’t skipped when the active timezone is a negative UTC offset
3.3.0-rc.22024-11-0838612Add substream state migration. Update CDK to v6.
3.3.0-rc.12024-10-2838612Migrate IssueComments and IssueWorklogs streams to low-code (This change is irreversible)
3.2.12024-10-1244650Update dependencies
3.2.02024-10-1046344Update CDK v5
3.1.12024-08-1744251Update dependencies
3.1.02024-08-1339558Ensure config_error when state has improper format
3.0.142024-08-1243885Update dependencies
3.0.132024-08-1043542Update dependencies
3.0.122024-08-0343196Update dependencies
3.0.112024-07-2742802Update dependencies
3.0.102024-07-2042231Update dependencies
3.0.92024-07-1341842Update dependencies
3.0.82024-07-1041453Update dependencies
3.0.72024-07-0941175Update dependencies
3.0.62024-07-0640785Update dependencies
3.0.52024-06-2740215Replaced deprecated AirbyteLogger with logging.Logger
3.0.42024-06-2640549Migrate off deprecated auth package
3.0.32024-06-2540444Update dependencies
3.0.22024-06-2140121Update dependencies
3.0.12024-06-1339458Fix skipping custom_field_options entities when schema.items is options
3.0.02024-06-1439467Update pk for Workflows stream from Id(object) to entityId, name(string, string)
2.0.32024-06-1039347Update state handling for incremental Python streams
2.0.22024-06-0639310Fix projects substreams for deleted projects
2.0.12024-05-2038341Update CDK authenticator package
2.0.02024-04-2037374Migrate to low-code and fix Project Avatars stream
1.2.22024-04-1936646Updating to 0.80.0 CDK
1.2.12024-04-1236646schema descriptions
1.2.02024-03-1936267Pin airbyte-cdk version to ^0
1.1.02024-02-2735656Add new fields to streams board_issues, filter_sharing, filters, issues, permission_schemes, sprint_issues, users_groups_detailed, and workflows
1.0.22024-02-1235160Manage dependencies with Poetry.
1.0.12024-01-2434470Add state checkpoint interval for all streams
1.0.02024-01-0133715Save state for stream Board Issues per board
0.14.12023-12-1933625Skip 404 error
0.14.02023-12-1533532Add lookback window
0.13.02023-12-1233353Fix check command to check access for all available streams
0.12.02023-12-0133011Fix BoardIssues stream; increase number of retries for backoff policy to 10
0.11.02023-11-2932927Fix incremental syncs for stream Issues
0.10.22023-10-2631896Provide better guidance when configuring the connector with an invalid domain
0.10.12023-10-2331702Base image migration: remove Dockerfile and use the python-connector-base image
0.10.02023-10-13#31385Fixed aggregatetimeoriginalestimate, timeoriginalestimate field types for the Issues stream schema
0.9.02023-09-26#30688Added createdDate field to sprints schema, Removed Expand Issues stream from spec
0.8.02023-09-26#30755Add new streams: Issue custom field options, IssueTypes, Project Roles
0.7.22023-09-19#30675Ensure invalid URL does not trigger Sentry alert
0.7.12023-09-19#30585Add skip for 404 error in issue properties steam
0.7.02023-09-17#30532Add foreign key to stream record where it missing
0.6.32023-09-19#30515Add transform for invalid date-time format, add 404 handling for check
0.6.22023-09-19#30578Fetch deleted and archived Projects
0.6.12023-09-17#30550Update Issues expand settings
0.6.02023-09-17#30507Add new stream IssueTransitions
0.5.02023-09-14#29960Add boardId to sprints stream
0.3.142023-09-11#30297Remove requests and pendulum from setup dependencies
0.3.132023-09-01#30108Skip 404 error for stream IssueWatchers
0.3.122023-06-01#26652Expand on leads for projects stream
0.3.112023-06-01#26906Handle project permissions error
0.3.102023-05-26#26652Fixed bug when board doesn’t support sprints
0.3.92023-05-16#26114Update fields info in docs and spec, update to latest airbyte-cdk
0.3.82023-05-04#25798Add sprint info to sprint_issues and sprints streams for team-managed projects
0.3.72023-04-18#25275Add missing types to issues json schema
0.3.62023-04-10#24636Removed Connector Domain Pattern from Spec
0.3.52023-04-05#24890Fix streams “IssuePropertyKeys”, “ScreenTabFields”
0.3.42023-02-14#23006Remove caching for Issues stream
0.3.32023-01-04#20739fix: check_connection fails if no projects are defined
0.3.22022-12-23#20859Fixed pagination for streams issue_remote_links, sprints
0.3.12022-12-14#20128Improved code to become beta
0.3.02022-11-03#18901Adds UserGroupsDetailed schema, fix Incremental normalization, add Incremental support for IssueComments, IssueWorklogs
0.2.232022-10-28#18505Correcting max_results bug introduced in connector stream
0.2.222022-10-03#16944Adds support for max_results to users stream
0.2.212022-07-28#15135Adds components to fields object on issues stream
0.2.202022-05-25#13202Adds resolutiondate to fields object on issues stream
0.2.192022-05-04#10835Change description for array fields
0.2.182021-12-23#7378Adds experimental endpoint Pull Request
0.2.172021-12-23#9079Update schema for filters stream + fix fetching filters stream
0.2.162021-12-21#8999Update connector fields title/description
0.2.152021-11-01#7398Add option to render fields in HTML format and fix sprint_issue ids
0.2.142021-10-27#7408Fix normalization step error. Fix schemas. Fix acceptance-test-config.yml. Fix streams.py.
0.2.132021-10-20#7222Source Jira: Make recently added configs optional for backwards compatibility
0.2.122021-10-19#6621Add Board, Epic, and Sprint streams
0.2.112021-09-02#6523Add cache and more streams (boards and sprints)
0.2.92021-07-28#5426Changed cursor field from fields.created to fields.updated for Issues stream. Made Issues worklogs stream full refresh.
0.2.82021-07-28#4947Source Jira: fixing schemas accordingly to response.
0.2.72021-07-19#4817Fixed labels schema properties issue.
0.2.62021-06-15#4113Fixed user stream with the correct endpoint and query param.
0.2.52021-06-09#3973Added AIRBYTE_ENTRYPOINT in base Docker image for Kubernetes support.
0.2.4Implementing base_read acceptance test dived by stream groups.
0.2.3Implementing incremental sync. Migrated to airbyte-cdk. Adding all available entities in Jira Cloud.
Advanced Analytica

Most businesses are sitting on information they can’t use at speed. The people who hold it are busy, and when they leave, the knowledge goes with them. The documents are static, and the processes around them weren’t designed for AI.

Advanced Analytica works with these businesses to turn that information into structured data assets. Once they're integrated, AI systems can govern it, and the business can use it. We bring in the strategy, the specification and the AI skills to rework how the business operates.

MOVE FAST. STAY SAFE.