ContextQMD
Back to Airbyte

Jira

docs/integrations/sources/jira.md

2.0.041.6 KB
Original Source

Jira

<HideInUI>

This page contains the setup guide and reference information for the Jira source connector.

</HideInUI>

Prerequisites

  • API Token
  • Domain
  • Email

Setup guide

Step 1: Set up Jira

  1. To get access to the Jira API you need to create an API token, please follow the instructions in this documentation.

Step 2: Set up the Jira connector in Airbyte

<!-- env:cloud -->

For Airbyte Cloud:

  1. Log into your Airbyte Cloud account.
  2. Click Sources and 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. Enter the API Token that you have created. API Token is used for Authorization to your account by BasicAuth.
  6. Enter the Domain for your Jira account, e.g. airbyteio.atlassian.net.
  7. Enter the Email for your Jira account which you used to generate the API token. This field is used for Authorization to your account by BasicAuth.
  8. Enter the list of Projects (Optional) for which you need to replicate data, or leave it empty if you want to replicate data for all projects.
  9. Enter the Start Date (Optional) from which you'd like to replicate data for Jira in the format YYYY-MM-DDTHH:MM:SSZ. All data generated after this date will be replicated, or leave it empty if you want to replicate all data. Note that it will be used only in the following streams: Board Issues, Issue Comments, Issue Properties, Issue Remote Links, Issue Votes, Issue Watchers, Issue Worklogs, Issues, Pull Requests, Sprint Issues. For other streams it will replicate all data.
<!-- /env:cloud --> <!-- env:oss -->

For Airbyte Open Source:

  1. Navigate to the Airbyte Open Source dashboard.
  2. Click Sources and 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. Enter the API Token that you have created. API Token is used for Authorization to your account by BasicAuth.
  6. Enter the Domain for your Jira account, e.g. airbyteio.atlassian.net.
  7. Enter the Email for your Jira account which you used to generate the API token. This field is used for Authorization to your account by BasicAuth.
  8. Enter the list of Projects (Optional) for which you need to replicate data, or leave it empty if you want to replicate data for all projects.
  9. Enter the Start Date (Optional) from which you'd like to replicate data for Jira in the format YYYY-MM-DDTHH:MM:SSZ. All data generated after this date will be replicated, or leave it empty if you want to replicate all data. Note that it will be used only in the following streams: Board Issues, Issue Comments, Issue Properties, Issue Remote Links, Issue Votes, Issue Watchers, Issue Worklogs, Issues, Pull Requests, Sprint Issues. For other streams it will replicate all data.
<!-- /env:oss -->

Supported sync modes

The Jira source connector supports the following sync modes:

Supported Streams

This connector outputs the following full refresh streams:

This connector outputs the following incremental streams:

If there are more endpoints you'd like Airbyte to support, please create an issue.

Streams on I/O Usage

In the list above, there is a subset of streams which requires to make one HTTP request per issue. Those streams can significantly slow down that a sync given a high number of issues. If you have one or many of those streams and experience slowness, we recommend filtering the list of issues using the list of projects in the configuration or simply removing those streams from the sync.

  • Issue comments
  • Issue properties
  • Issue remote links
  • Issue transactions
  • Issue votes
  • Issue watchers
  • Issue worklogs

Entity-Relationship Diagram (ERD)

<EntityRelationshipDiagram></EntityRelationshipDiagram>

Experimental Tables

The following tables depend on undocumented internal Jira API endpoints and are therefore subject to stop working if those endpoints undergo major changes. While they will not cause a sync to fail, they may not be able to pull any data. Use the "Enable Experimental Streams" option when setting up the source to allow or disallow these tables to be selected when configuring a connection.

:::note The experimental Pull Requests stream was removed in version 4.0.0 and is no longer available in the catalog. If you want to sync data using this stream, you must use version <= 3.5.4. This is only possible on self-deployed instances of Airbyte, and this stream is no longer supported on Airbyte Cloud. :::

Troubleshooting

Check out common troubleshooting issues for the Jira connector on our Airbyte Forum here.

Rate Limiting & Performance

The Jira connector should not run into Jira API limitations under normal usage. Please create an issue if you see any rate limit issues that are not automatically retried successfully.

Changelog

<details> <summary>Expand to review</summary>
VersionDatePull RequestSubject
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.
</details>