jira-api_skill

Overview

This skill integrates Jira Cloud via a managed OAuth gateway so you can search issues with JQL, create and update issues, manage projects, and drive workflow transitions. It handles OAuth token injection and connection selection, letting you call Jira REST endpoints through a single gateway URL. Use it when you need programmatic, authenticated access to Jira without managing OAuth flows yourself.

How this skill works

The skill proxies requests to api.atlassian.com through https://gateway.maton.ai and automatically injects your Maton API key and the selected OAuth connection. First fetch the Jira cloud ID via /oauth/token/accessible-resources, then call Jira endpoints under /jira/ex/jira/{cloudId}/rest/api/3/.... You can list projects, run JQL searches, create/update/delete issues, manage transitions, comments, and users.

When to use it

• Search issues across a project or team using JQL.
• Create, update, assign, or delete Jira issues programmatically.
• Automate workflow transitions and status changes for CI/CD or ticket triage.
• Fetch project metadata (issue types, priorities, statuses) for integrations.
• Manage OAuth connections centrally without embedding credentials in your code.

Best practices

• Always retrieve cloud ID first via /oauth/token/accessible-resources before calling other endpoints.
• URL-encode JQL queries and bound them (e.g., project=KEY) to avoid large result sets.
• Set MATON_API_KEY as an environment variable and include Authorization: Bearer $MATON_API_KEY on requests.
• When multiple connections exist, send Maton-Connection header to pick the correct Jira account.
• Handle 204 responses for Update/Delete/Transition as success; respect 10 req/sec rate limit to avoid 429 errors.

Example use cases

• Backend job that nightly exports recent issues from a Jira project to a data warehouse.
• Chatbot that creates or updates Jira issues from user messages and posts the issue link back.
• CI pipeline step that transitions test-related issues to a new status after builds complete.
• Admin script to bulk-update issue fields or assign issues to a new owner via the API.
• Dashboard that lists active sprints, priorities, and issue counts by calling Agile/issue endpoints (ensure scopes).