Triage, update, and search Jira issues from Guild agents

Integrations · Jira

Guild agents create, edit, transition, and search Jira Cloud issues using OAuth 2.0 credentials that never enter agent code. Guild stores credentials server-side and injects them through its credential proxy, so every call is governed by credential policies you write. Each webhook event that fires a trigger starts a new auditable session.

Book a demo

See how teams govern agents that use Jira.

Start free

Connect Jira and scope your first agent.

What the Jira integration exposes

The tools cover issues and subtasks, comments, worklogs, watchers, transitions, issue links, priorities, issue types, custom fields, filters, dashboards, projects, users, and permissions. JQL search runs via two tools: a GET variant and a POST variant. Webhook triggers fire on issue and comment events, with optional filters by project and by newly added labels.

How it works

Open Credentials in Guild

Go to Credentials in Guild under Access & setup. The page lists services you can connect.

Authorize through Atlassian

Click Jira and complete the Atlassian OAuth flow. Select your Jira site; Guild retrieves your Cloud ID automatically.

Import tools in your agent

Import jiraTools from the package and spread it into your agent’s tools object. Use pick to include only the tools your agent needs; agents perform better with fewer tools.

Why Jira access needs governing in a multi-agent platform

Guild’s credential proxy sits between every agent call and Jira. It checks credential policies before any request leaves Guild. Policies use ALLOW and DENY rules matched on operation name, HTTP method, agent identity, and workspace. A DENY rule always wins over an ALLOW rule, so you can block destructive operations such as jira_delete_issue or jira_delete_project while permitting read and triage operations for every other agent on the same credential. Credentials are scoped to an account, a single workspace, a member, or one agent, and the proxy selects the right one server-side. Agents never see the OAuth token. Credential policies are enforced before the request reaches Jira; if no rule allows the call, it is denied. That default-deny posture contrasts with a raw OAuth token handed directly to an agent, where the token’s full scope is available to anything that runs.

About the Jira integration

The @guildai-services/guildai~jira package provides agents with access to the Jira Cloud REST API through Guild’s OAuth 2.0 integration.

Authentication

Type: OAuth 2.0 (Atlassian Cloud)
Token expiration: 1 hour (auto-refreshed)
Refresh token expiration: 90 days
Note: Only Jira Cloud is supported — not Jira Server or Data Center

Setup

Open Credentials

Go to Credentials in Guild.

Connect Jira

Click Jira and authorize access through Atlassian.

Grant access

Select your Jira site. Guild automatically retrieves your Cloud ID.

Usage

import { jiraTools } from "@guildai-services/guildai~jira"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that manages Jira issues",
  tools: { ...jiraTools },
})

Selecting specific tools

Agents perform better with fewer tools. Use pick() to include only what your agent needs. Tools are named with the jira_ prefix — for example, get_issue becomes jira_get_issue.

import { jiraTools } from "@guildai-services/guildai~jira"
import { llmAgent, pick } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that triages Jira bugs",
  tools: {
    ...pick(jiraTools, [
      "jira_search_and_reconsile_issues_using_jql",
      "jira_get_issue",
      "jira_edit_issue",
      "jira_add_comment",
    ]),
  },
})

Tools

Tools in the latest published version of guildai~jira:

All 74 tools

Tool	What it does
`jira_add_comment`	Adds a comment to an issue.
`jira_add_watcher`	Adds a user as a watcher of an issue by passing the account ID of the user.
`jira_add_worklog`	Adds a worklog to an issue.
`jira_bulk_delete_worklogs`	Deletes a list of worklogs from an issue.
`jira_create_custom_field`	Creates a custom field.
`jira_create_dashboard`	Creates a dashboard.
`jira_create_filter`	Creates a filter.
`jira_create_issue`	Creates an issue or, where the option to create subtasks is enabled in Jira, a subtask.
`jira_create_issue_link_type`	Creates an issue link type.
`jira_create_issue_type`	Creates an issue type and adds it to the default issue type scheme.
`jira_create_notification_scheme`	Creates a notification scheme with notifications.
`jira_create_priority`	Creates an issue priority.
`jira_create_project`	Creates a project based on a project type template, as shown in the following table.
`jira_create_user`	Creates a user.
`jira_delete_comment`	Deletes a comment.
`jira_delete_dashboard`	Deletes a dashboard.
`jira_delete_filter`	Delete a filter.
`jira_delete_issue`	Deletes an issue.
`jira_delete_issue_link`	Deletes an issue link.
`jira_delete_issue_type`	Deletes the issue type.
`jira_delete_priority`	Deletes an issue priority.
`jira_delete_project`	Deletes a project.
`jira_delete_worklog`	Deletes a worklog from an issue.
`jira_do_transition`	Performs an issue transition and, if the transition has a screen, updates the fields from the transition screen.
`jira_edit_issue`	Edits an issue.
`jira_find_assignable_users`	Returns a list of users that can be assigned to an issue.
`jira_find_users`	Returns a list of active users that match the search string and property.
`jira_get_all_dashboards`	Returns a list of dashboards owned by or shared with the user.
`jira_get_all_permissions`	Returns all permissions, including.
`jira_get_all_projects`	Returns all projects visible to the user.
`jira_get_all_statuses`	Returns the valid statuses for a project.
`jira_get_change_logs`	Returns a paginated list of all changelogs for an issue sorted by date, starting from the oldest.
`jira_get_comment`	Returns a comment.
`jira_get_comments`	Returns all comments for an issue.
`jira_get_current_user`	Returns details for the current user.
`jira_get_dashboard`	Returns a dashboard.
`jira_get_fields`	Returns system and custom issue fields according to the following rules.
`jira_get_filter`	Returns a filter.
`jira_get_filters_paginated`	Returns a paginated list of filters.
`jira_get_issue`	Returns the details for an issue.
`jira_get_issue_all_types`	Returns all issue types.
`jira_get_issue_link`	Returns an issue link.
`jira_get_issue_link_types`	Returns a list of all issue link types.
`jira_get_issue_type`	Returns an issue type.
`jira_get_issue_types_for_project`	Returns issue types for a project.
`jira_get_issue_watchers`	Returns the watchers for an issue.
`jira_get_issue_worklog`	Returns a worklog.
`jira_get_issue_worklogs`	Returns worklogs for an issue (ordered by created time), starting from the oldest worklog or from the worklog started on or after a date and time.
`jira_get_my_permissions`	Returns a list of permissions indicating which permissions the user has.
`jira_get_notification_schemes`	Returns a paginated list of notification schemes ordered by the display name.
`jira_get_priorities`	Returns the list of all issue priorities.
`jira_get_priority`	Returns an issue priority.
`jira_get_project`	Returns the project details for a project.
`jira_get_project_components`	Returns all components in a project.
`jira_get_project_versions`	Returns all versions in a project.
`jira_get_server_info`	Returns information about the Jira instance.
`jira_get_status`	Returns a status.
`jira_get_statuses`	Returns a list of all statuses associated with active workflows.
`jira_get_transitions`	Returns either all transitions or a transition that can be performed by the user on an issue, based on the issue’s status.
`jira_get_user`	Returns a user.
`jira_link_issues`	Creates a link between two issues.
`jira_remove_user`	Deletes a user.
`jira_remove_watcher`	Deletes a user as a watcher of an issue.
`jira_search_and_reconsile_issues_using_jql`	Searches for issues using JQL.
`jira_search_and_reconsile_issues_using_jql_post`	Searches for issues using JQL.
`jira_set_issue_property`	Sets a JSON property value on one Jira issue.
`jira_update_comment`	Updates a comment.
`jira_update_custom_field`	Updates a custom field.
`jira_update_dashboard`	Updates a dashboard, replacing all the dashboard details with those provided.
`jira_update_filter`	Updates a filter.
`jira_update_issue_type`	Updates the issue type.
`jira_update_priority`	Updates an issue priority.
`jira_update_project`	Updates the project details of a project.
`jira_update_worklog`	Updates a worklog.

Webhook events

Jira uses a credential-scoped webhook model. When you enable the first Jira trigger on a connection, Guild registers one webhook on the Jira site for all projects the connected account can see, and routes its events to matching triggers. Disabling the last trigger removes it. A trigger can narrow an event to one action, such as guild trigger create --type webhook --integration jira --event issue --action created --agent <identifier>. Without an action it fires on every action of that event.

Event	Description	Actions
`comment`	Comment created, updated, or deleted on an issue	`created`, `deleted`, `updated`
`issue`	Issue created, updated, or deleted	`created`, `deleted`, `updated`

Events can be filtered by project using the project field in the service config. Jira expires webhooks after 30 days; Guild refreshes the webhook every week, so it stays active. Each event starts a new session. Guild doesn’t filter out changes the agent makes itself, so an agent that edits an issue from an issue updated trigger fires that trigger again. Have the agent skip changes made by the connected account. The optional label_added field narrows a trigger to newly added labels. Set it to a non-empty list of label names, and the trigger fires only when one of them is newly added — on issue creation, when the issue carries the label, and on issue update, when the label appears in the change. Label matching is case-sensitive, unlike project.

{
  "project": "ENG",
  "label_added": ["needs-triage"]
}

Setting label_added also restricts the trigger to issue events: comment events never fire while it is set.

Limitations

OAuth refresh tokens expire after 90 days of inactivity
Only Jira Cloud is supported (not Jira Server or Data Center)

Frequently asked questions

Does the integration work with Jira Server or Data Center?

No. Only Jira Cloud is supported. Jira Server and Data Center are not supported by this integration.

How do I trigger an agent only when a specific label is added to an issue?

Set the label_added field in the trigger’s service config to a list of label names. The trigger fires only when one of those labels is newly added to an issue. Label matching is case-sensitive. Setting label_added restricts the trigger to issue events; comment events never fire while it is set.

What happens if my agent edits an issue that it is also watching for updates?

Guild does not filter out changes the agent makes itself. An agent that edits an issue from an issue updated trigger will fire that trigger again. The page recommends having the agent skip changes made by the connected account.

Can I limit an agent to read-only JQL searches without allowing it to create or delete issues?

Yes. Write a credential policy with a DENY rule covering operations such as jira_create_issue and jira_delete_issue, and an ALLOW rule covering jira_search_and_reconsile_issues_using_jql. DENY rules take precedence, so the destructive operations are blocked even if a broader ALLOW rule is present. You can also scope the rule to a specific agent or workspace.

Put a governed agent on Jira this week

Book a demo

See how teams govern agents that use Jira.

Start free

Connect Jira and scope your first agent.

Also runs on Guild: Google Calendar Read: Docs: Credential policies · Credentials · Tools in agents

Overview

Models

Inference providers

Code & CI/CD

Communication

Project management

Testing

Productivity

Monitoring & observability

Data

Customer support

Sales & finance

Recruiting

Triage, update, and search Jira issues from Guild agents

Book a demo

Start free

What the Jira integration exposes

How it works

Why Jira access needs governing in a multi-agent platform

About the Jira integration

Authentication

Setup

Usage

Selecting specific tools

Tools

Webhook events

Limitations

Frequently asked questions

Put a governed agent on Jira this week

Book a demo

Start free

Book a demo

Start free

​What the Jira integration exposes

​How it works

​Why Jira access needs governing in a multi-agent platform

​About the Jira integration

​Authentication

​Setup

​Usage

​Selecting specific tools

​Tools

​Webhook events

​Limitations

​Frequently asked questions

​Put a governed agent on Jira this week

Book a demo

Start free

​Related

What the Jira integration exposes

How it works

Why Jira access needs governing in a multi-agent platform

About the Jira integration

Authentication

Setup

Usage

Selecting specific tools

Tools

Webhook events

Limitations

Frequently asked questions

Put a governed agent on Jira this week

Related