tap-jira

tap-jira tap class.

Built with the Meltano Singer SDK.

Capabilities

• catalog
• state
• discover
• about
• stream-maps
• schema-flattening
• batch

Supported Python Versions

• 3.10
• 3.11
• 3.12
• 3.13

Settings

Setting	Required	Default	Description
start_date	False	None	Earliest record date to sync
end_date	False	None	Latest record date to sync
domain	True	None	The Domain for your Jira account, e.g. mycompany.atlassian.net
api_token	True	None	Jira API Token.
email	True	None	The user email for your Jira account.
cloud_id	False	None	The Cloud ID for your Jira account. Optional - use with granular access tokens and OAuth to access Atlassian's cloud-based API URLs.
page_size	False	None
page_size.issues	False	100	Page size for issues stream
stream_options	False	None	Options for individual streams
stream_options.issues	False	None	Options specific to the issues stream
stream_options.issues.jql	False	id != null	A JQL query to filter issues
stream_options.issues.fields	False	*all	A comma-separated list of fields to include. All fields are included by default.
include_audit_logs	False	False	Include the audit logs stream

Built-in capabilities

Setting	Required	Default	Description
stream_maps	False	None	Config object for stream maps capability. For more information check out Stream Maps.
stream_map_config	False	None	User-defined config values to be used within map expressions.
faker_config	False	None	Config for the Faker instance variable fake used within map expressions. Only applicable if the plugin specifies faker as an addtional dependency (through the singer-sdk faker extra or directly).
faker_config.seed	False	None	Value to seed the Faker generator for deterministic output: https://faker.readthedocs.io/en/master/#seeding-the-generator
faker_config.locale	False	None	One or more LCID locale strings to produce localized output for: https://faker.readthedocs.io/en/master/#localization
flattening_enabled	False	None	'True' to enable schema flattening and automatically expand nested properties.
flattening_max_depth	False	None	The max depth to flatten schemas.
batch_config	False	None	Configuration for BATCH message capabilities.
batch_config.encoding	False	None	Specifies the format and compression of the batch files.
batch_config.encoding.format	False	None	Format to use for batch files.
batch_config.encoding.compression	False	None	Compression format to use for batch files.
batch_config.storage	False	None	Defines the storage layer to use when writing batch files
batch_config.storage.root	False	None	Root path to use when writing batch files.
batch_config.storage.prefix	False	None	Prefix to use when writing batch files.

A full list of supported settings and capabilities is available by running: tap-jira --about

Elastic License 2.0

The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license to use, copy, distribute, make available, and prepare derivative works of the software.

Installation

uv tool install git+https://github.com/ryan-miranda-partners/tap-jira.git

Configure using environment variables

This Singer tap will automatically import any environment variables within the working directory's .env if the --config=ENV is provided, such that config values will be considered if a matching environment variable is set either in the terminal context or in the .env file.

Source Authentication and Authorization

tap-jira uses Basic Authentication with Jira API tokens. All requests require your domain, email, and API token credentials.

Basic Authentication (API Token)

Required Configuration:

• domain: Your Atlassian domain (e.g., mycompany.atlassian.net)
• email: Your Atlassian account email
• api_token: A Jira API token (see Atlassian API Tokens)

Standard Configuration Example:

{
  "domain": "mycompany.atlassian.net",
  "email": "user@example.com",
  "api_token": "your_api_token_here"
}

Required Scopes

Stream	Classic scopes	Granular scopes
users	read:jira-user	read:application-role:jira read:avatar:jira read:group:jira read:user:jira
fields	read:jira-work	read:avatar:jira read:field-configuration:jira read:field:jira read:project-category:jira read:project:jira
custom_field_contexts	manage:jira-configuration	read:custom-field-contextual-configuration:jira read:field:jira
custom_field_options	manage:jira-configuration	read:field.option:jira
server_info	Any	Any
issue_types	read:jira-work	read:avatar:jira read:issue-type:jira read:project-category:jira read:project:jira
workflow_statuses	read:jira-work	read:status:jira
projects	read:jira-work	read:application-role:jira read:avatar:jira read:group:jira read:issue-type-hierarchy:jira read:issue-type:jira read:project-category:jira read:project-version:jira read:project.component:jira read:project.property:jira read:project:jira read:user:jira
project_versions	read:jira-work	read:project-version:jira
issues	read:jira-work	read:audit-log:jira read:avatar:jira read:field-configuration:jira read:issue-details:jira read:issue-meta:jira
permissions	manage:jira-configuration	read:permission:jira
project_roles	manage:jira-configuration	read:avatar:jira read:group:jira read:project-category:jira read:project-role:jira read:project:jira read:user:jira
priorities	read:jira-work	read:priority:jira
permission_holders	read:jira-work	read:application-role:jira read:avatar:jira read:field:jira read:group:jira read:permission-scheme:jira read:permission:jira read:project-category:jira read:project-role:jira read:project:jira read:user:jira
boards	N/A	read:board-scope:jira-software read:project:jira
sprints	N/A	read:sprint:jira-software
project_role_actors	read:jira-work manage:jira-configuration	read:application-role:jira read:avatar:jira read:group:jira read:issue-type-hierarchy:jira read:issue-type:jira read:project-category:jira read:project-role:jira read:project-version:jira read:project.component:jira read:project.property:jira read:project:jira read:user:jira
audit_records	manage:jira-configuration	read:audit-log:jira read:user:jira
dashboards	read:jira-work	read:application-role:jira read:avatar:jira read:dashboard:jira read:group:jira read:issue-type-hierarchy:jira read:issue-type:jira read:project-category:jira read:project-role:jira read:project-version:jira read:project.component:jira read:project:jira read:user:jira
filters	read:jira-work	read:application-role:jira read:avatar:jira read:filter:jira read:group:jira read:issue-type-hierarchy:jira read:jql:jira read:project-role:jira read:project:jira read:user:jira
filter_default_share_scopes	read:jira-work	read:filter.default-share-scope:jira
groups_pickers	read:jira-user	read:group:jira
licenses	manage:jira-configuration	read:license:jira
screens	manage:jira-project	read:avatar:jira read:project-category:jira read:project:jira read:screen:jira
screen_schemes	manage:jira-project	read:issue-type-screen-scheme:jira read:screen-scheme:jira
statuses	manage:jira-configuration	read:workflow:jira
resolutions	read:jira-work	read:resolution:jira
workflows	manage:jira-configuration	read:workflow:jira
issue_watchers	read:jira-work	read:avatar:jira read:issue.watcher:jira read:user:jira
issue_changelog	read:jira-work	read:avatar:jira read:issue-meta:jira read:issue.changelog:jira
issue_comments	read:jira-work	read:avatar:jira read:comment.property:jira read:comment:jira read:group:jira read:project-role:jira read:project:jira read:user:jira
issue_worklogs	read:jira-work	read:avatar:jira read:group:jira read:issue-worklog.property:jira read:issue-worklog:jira read:project-role:jira read:user:jira
components	read:jira-work	read:application-role:jira read:avatar:jira read:group:jira read:project.component:jira read:project:jira read:user:jira

Cloud ID (Optional)

For OAuth2.0 or granular access tokens, you need to use Atlassian's cloud-based API URLs instead of your domain. When provided, cloud_id changes the API URL structure from https://{domain}/rest/api/3 to https://api.atlassian.com/ex/jira/{cloud_id}/rest/api/3. Authentication still uses your Basic Auth credentials.

Configuration with Cloud ID:

{
  "domain": "mycompany.atlassian.net",
  "email": "user@example.com",
  "api_token": "your_api_token_here",
  "cloud_id": "11223344-a1b2-3b33-c444-def123456789"
}

When to use cloud_id:

• Required when using OAuth-based or granular access token-based Atlassian integrations that require the scoped API
• Specified by your Atlassian administrator or integration documentation
• See Atlassian Community Discussion for more context

How to find your Cloud ID:

With a granular access token, you can find your cloud ID using the Atlassian tenant info endpoint:

# Get your accessible resources
curl -u "your-email@example.com:your-api-token" \
  https://mycompany.atlassian.net/_edge/tenant_info

The response will include your cloud ID:

  {"cloudId": "11223344-a1b2-3b33-c444-def123456789"}

Use the cloudId field as your cloud_id configuration value.

Usage

You can easily run tap-jira by itself or in a pipeline using Meltano.

Stream Inheritance

This project uses parent-child streams. Learn more about them here.

Executing the Tap Directly

tap-jira --version
tap-jira --help
tap-jira --config CONFIG --discover > ./catalog.json

Developer Resources

Follow these instructions to contribute to this project.

Initialize your Development Environment

curl -LsSf https://astral.sh/uv/install.sh | sh  # see https://docs.astral.sh/uv/getting-started/installation/
uv sync

Create and Run Tests

Create tests within the tests subfolder and then run:

uv run pytest

You can also test the tap-jira CLI interface directly using uv run:

uv run tap-jira --help

Testing with Meltano

Note: This tap will work in any Singer environment and does not require Meltano. Examples here are for convenience and to streamline end-to-end orchestration scenarios.

Your project comes with a custom meltano.yml project file already created. Open the meltano.yml and follow any "TODO" items listed in the file.

Next, install Meltano (if you haven't already) and any needed plugins:

# Install meltano
uv tool install meltano
# Initialize meltano within this directory
cd tap-jira
meltano install

Now you can test and orchestrate using Meltano:

# Test invocation:
meltano invoke tap-jira --version
# OR run a test `elt` pipeline:
meltano elt tap-jira target-jsonl

SDK Dev Guide

See the dev guide for more instructions on how to use the SDK to develop your own taps and targets.