# Jira Software

Create, find, update and move Jira issues from status to status, and work with their comments, attachments, worklogs and links, and with users.

## Connect Jira Software

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `jira software` and choose **Jira Software**.
3. Choose **Sign in with Jira Software**.
4. Press **Sign in with Jira Software** at the bottom of the sheet, then choose your account in Jira Software’s window and allow access.

Or choose **Paste your API token**, paste it, and press **Test and save**. It stays until someone deletes it.

Sign in with Atlassian and allow a Jira site, or use an API token: the email of your Atlassian account, an API token (id.atlassian.com → Security → Create and manage API tokens) and your site address. For Jira Data Center or Server on your own server, enter its Server address and a personal access token in API token (or a Username, with the password in API token).

**What if it says “Sign-in isn’t set up here yet”?**

Signing in with Jira Software needs a Jira Software app on this installation, and it has none yet. Until it is set up, **Paste your API token** works without it.

**On Cloud:** The sheet says “It’s set up once for everyone who uses this service, not by an organization.”

**Self-hosted:** An admin of the installation sees **Set up Jira Software sign-in** instead, and sets it up once for everyone. Everyone else sees who to ask.

1. Create an app in Jira Software’s developer settings ([Jira Software’s guide](https://id.atlassian.com/manage-profile/security/api-tokens)).
2. In GoRunner, copy the **Redirect address to add in Jira Software’s developer settings**, and add it to the app.
3. Paste the **Client ID** and **Client secret**, then press **Save and sign in**.

[Set up a sign-in app](https://docs.gorunner.io/self-host/oauth-apps#other-providers)

**Can I use my own Jira Software app?**

Yes. In the sheet, open **Use your own Jira Software app** and paste its **Client ID** and **Client secret**. Add the redirect address it shows to your app first. The connection then signs in through your app instead of the installation’s.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Start a workflow

Add a trigger and choose **Jira Software**. The trigger uses the same connection as the steps.

### On Jira Event

Fires when Jira sends a chosen event. Publishing registers a Jira webhook and unpublishing removes it. With an Atlassian sign-in it is a dynamic webhook (Jira needs Projects or an Issue Filter for it, and keeps it 30 days; it is refreshed before then; Jira lets one sign-in send webhooks to one address per site, so a sign-in serves the Jira trigger of one workflow per site; with your own Atlassian app that is not shared, the app's owner must be the one who signs in). With an API token it is an admin webhook, which needs a Jira administrator's token; Jira signs each delivery. A delivery that cannot be verified starts nothing, and Jira's retry of a delivery starts no second run. Jira Cloud only: with a connection to Jira Data Center on your own server, publishing is refused; use the Webhook trigger with a Jira administrator's webhook instead.

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Events · Required**: Which Jira events start it. Any event: every event Jira sends to this kind of webhook (a sign-in's or an API token's). Options: Any event to Version merged (sign-in only) (56 options).
- **Projects · Optional**: Only issues in these projects. With a sign-in, Projects or an Issue Filter is required.
- **Issue Filter (JQL) · Optional**: Only issues that match this JQL (with Projects: both). A sign-in's webhook takes only project, issueKey, issuetype, status, priority, assignee and reporter with =,!=, in and not in.

A later step can use its data, such as `{{trigger.changelog}}`, `{{trigger.comment}}`, `{{trigger.issue}}` and 4 more. See [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Do things in Jira Software

Add a **Jira Software** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields.

- [Issue](https://docs.gorunner.io/apps/jira-software#fields-f-issue): Create · Get · Get Many · Update · Delete · Get Changelog · Notify by Email · Get Transitions · Change Status · Assign
- [Issue Comment](https://docs.gorunner.io/apps/jira-software#fields-f-issuecomment): Add · Get · Get Many · Update · Remove
- [Issue Attachment](https://docs.gorunner.io/apps/jira-software#fields-f-issueattachment): Add · Get · Get Many · Remove
- [Issue Worklog](https://docs.gorunner.io/apps/jira-software#fields-f-issueworklog): Add · Get · Get Many · Update · Remove
- [Issue Link](https://docs.gorunner.io/apps/jira-software#fields-f-issuelink): Create · Get · Remove
- [User](https://docs.gorunner.io/apps/jira-software#fields-f-user): Create · Get · Delete

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A reply from Jira Software can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When Jira Software says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, Jira Software is `pieceId: "jira"` with `actionId: "jira"`, set by `resource` and an `operation_…` field, such as `operation_issue`. Its trigger is `jiratrigger` / `jira_event`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### Jira Software › Issue

### Create

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Project · Required**: The project the issue goes in.
- **Issue Type · Required**: The kind of issue: Task, Bug, Story … (the project's own types).
- **Summary · Required**: The issue's title (at most 255 characters).
- **Description · Optional**: The issue's description. On Update, empty leaves it as it is. Plain text (a blank line starts a new paragraph), or an Atlassian Document as JSON.
- **Assignee · Optional**: Who the issue is assigned to. On Update, empty leaves it as it is (use Assign to unassign).
- **Reporter · Optional**: Who reported the issue. Empty: the signed-in account (on Create), or as it is (on Update).
- **Priority · Optional**: The issue's priority.
- **Labels · Optional**: Labels, separated by commas (a label has no spaces). On Update they replace the issue's labels.
- **Parent · Optional**: The parent issue (an epic, or the issue a subtask belongs to).
- **Due Date · Optional**: The due date, as YYYY-MM-DD.
- **Other Fields · Optional**: More fields by their id, as Jira takes them, such as {"customfield_10016": 5, "components": [{"name": "API"}]}. A field here wins over the same field above.

### Get

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Issue · Required**: The issue to work with.
- **Fields · Optional**: Which fields to return, separated by commas (such as summary,status,assignee; *all for every field; -description leaves one out). Empty: Get returns every field, Get Many the navigable ones.
- **Include · Optional**: More to return with each issue. Options: Fields as HTML, Field names, Field types, Available transitions, How each field can be edited, Recent changes.

### Get Many

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **JQL · Optional**: The search, in Jira Query Language. Write? where a value from earlier steps goes and put the values in JQL Values. Empty searches the issues created in the last 30 days, newest first (Jira Cloud refuses a search with no condition).
- **JQL Values · Optional**: The values for the JQL's? placeholders, in order, such as ["In Progress", "{{steps.trigger.key}}"].
- **Fields · Optional**: Which fields to return, separated by commas (such as summary,status,assignee; *all for every field; -description leaves one out). Empty: Get returns every field, Get Many the navigable ones.
- **Include · Optional**: More to return with each issue. Options: Fields as HTML, Field names, Field types, Available transitions, How each field can be edited, Recent changes.
- **Return All · Optional**: Read every item, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many items to return (1–1000). Default: 50. Shows when **Return All** is off.

### Update

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Issue · Required**: The issue to work with.
- **Summary · Optional**: A new title (at most 255 characters). Empty leaves it as it is.
- **Issue Type · Optional**: A new issue type, by name or id. Empty leaves it as it is.
- **Description · Optional**: The issue's description. On Update, empty leaves it as it is. Plain text (a blank line starts a new paragraph), or an Atlassian Document as JSON.
- **Assignee · Optional**: Who the issue is assigned to. On Update, empty leaves it as it is (use Assign to unassign).
- **Reporter · Optional**: Who reported the issue. Empty: the signed-in account (on Create), or as it is (on Update).
- **Priority · Optional**: The issue's priority.
- **Labels · Optional**: Labels, separated by commas (a label has no spaces). On Update they replace the issue's labels.
- **Parent · Optional**: The parent issue (an epic, or the issue a subtask belongs to).
- **Due Date · Optional**: The due date, as YYYY-MM-DD.
- **Other Fields · Optional**: More fields by their id, as Jira takes them, such as {"customfield_10016": 5, "components": [{"name": "API"}]}. A field here wins over the same field above.

### Delete

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Issue · Required**: The issue to work with.
- **Delete Subtasks · Optional**: Delete the issue's subtasks too. Off, Jira refuses to delete an issue that has subtasks. Off by default.

### Get Changelog

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Issue · Required**: The issue to work with.
- **Return All · Optional**: Read every item, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many items to return (1–1000). Default: 50. Shows when **Return All** is off.

### Notify by Email

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Issue · Required**: The issue to work with.
- **Subject · Optional**: The email's subject. Empty: the issue's key and summary.
- **Text Body · Optional**: The email's plain text.
- **HTML Body · Optional**: The email as HTML.
- **Send To · Optional**: Who on the issue receives it. Options: Reporter, Assignee, Watchers, Voters.
- **Users · Optional**: More people, by Atlassian account id (Jira Data Center: username), separated by commas.
- **Groups · Optional**: Groups, by group id or name, separated by commas.

### Get Transitions

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Issue · Required**: The issue to work with.
- **Include Screen Fields · Optional**: Also return the fields each transition's screen asks for. Off by default.

### Change Status

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Issue · Required**: The issue to work with.
- **Transition · Required**: The transition to make: its id, its name (Start Progress) or the status it leads to (In Progress).
- **Comment · Optional**: A comment added with the transition. Plain text (a blank line starts a new paragraph), or an Atlassian Document as JSON.
- **Screen Fields · Optional**: Fields the transition's screen sets, by id, such as {"resolution": {"name": "Done"}}.

### Assign

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Issue · Required**: The issue to work with.
- **Assign To · Required**: A person, nobody, or the project's default assignee. Options: A person, Nobody (unassign), The project's default assignee. Default: A person.
- **Person · Required**: Who to assign the issue to. Shows when **Assign To** is **A person**.

### Jira Software › Issue Comment

### Add

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Issue · Required**: The issue the comments are on.
- **Comment · Required**: The comment. Plain text (a blank line starts a new paragraph), or an Atlassian Document as JSON.

### Get and Remove

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Issue · Required**: The issue the comments are on.
- **Comment ID · Required**: The comment's id (a number).

### Get Many

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Issue · Required**: The issue the comments are on.
- **Order · Optional**: Oldest or newest first. Options: Oldest first, Newest first. Default: Oldest first.
- **Return All · Optional**: Read every comment, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many comments to return (1–1000). Default: 50. Shows when **Return All** is off.

### Update

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Issue · Required**: The issue the comments are on.
- **Comment ID · Required**: The comment's id (a number).
- **Comment · Required**: The comment. Plain text (a blank line starts a new paragraph), or an Atlassian Document as JSON.

### Jira Software › Issue Attachment

### Add

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Issue · Required**: The issue the attachments are on.
- **File · Required**: Upload a file, or switch to an expression to use one from an earlier step (such as {{steps.download.result}}). Jira keeps its name and type.

### Get

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Attachment ID · Required**: The attachment's id (a number).
- **Download · Optional**: Also return the file itself (under file), for a later step to use. At most 11 MB of files per step. Off by default.

### Get Many

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Issue · Required**: The issue the attachments are on.
- **Download · Optional**: Also return the file itself (under file), for a later step to use. At most 11 MB of files per step. Off by default.
- **Return All · Optional**: Read every attachment, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many attachments to return (1–1000). Default: 50. Shows when **Return All** is off.

### Remove

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Attachment ID · Required**: The attachment's id (a number).

### Jira Software › Issue Worklog

### Add

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Issue · Required**: The issue the time is logged on.
- **Time Spent · Required**: How long, in Jira's form (2d, 3h 20m, 45m), or a number of seconds.
- **Started · Optional**: When the work started (ISO 8601). Empty: now on Add, as it is on Update.
- **Comment · Optional**: What the time was spent on. Plain text (a blank line starts a new paragraph), or an Atlassian Document as JSON.
- **Remaining Estimate · Optional**: How the issue's remaining estimate changes. Change by an amount: Add reduces it, Remove increases it. Options: Adjust automatically, Leave as it is, Set to a new value, Change by an amount. Default: Adjust automatically.
- **Estimate · Optional**: The new remaining estimate, or the amount to change it by (2d, 3h, 30m). Shows when **Remaining Estimate** is **Set to a new value** or **Change by an amount**.

### Get

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Issue · Required**: The issue the time is logged on.
- **Worklog ID · Required**: The worklog's id (a number).

### Get Many

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Issue · Required**: The issue the time is logged on.
- **Return All · Optional**: Read every worklog, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many worklogs to return (1–1000). Default: 50. Shows when **Return All** is off.

### Update

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Issue · Required**: The issue the time is logged on.
- **Worklog ID · Required**: The worklog's id (a number).
- **Time Spent · Optional**: A new duration (2d, 3h 20m, 45m, or seconds). Empty leaves it as it is.
- **Started · Optional**: When the work started (ISO 8601). Empty: now on Add, as it is on Update.
- **Comment · Optional**: What the time was spent on. Plain text (a blank line starts a new paragraph), or an Atlassian Document as JSON.
- **Remaining Estimate · Optional**: How the issue's remaining estimate changes. Change by an amount: Add reduces it, Remove increases it. Options: Adjust automatically, Leave as it is, Set to a new value, Change by an amount. Default: Adjust automatically.
- **Estimate · Optional**: The new remaining estimate, or the amount to change it by (2d, 3h, 30m). Shows when **Remaining Estimate** is **Set to a new value** or **Change by an amount**.

### Remove

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Issue · Required**: The issue the time is logged on.
- **Worklog ID · Required**: The worklog's id (a number).
- **Remaining Estimate · Optional**: How the issue's remaining estimate changes. Change by an amount: Add reduces it, Remove increases it. Options: Adjust automatically, Leave as it is, Set to a new value, Change by an amount. Default: Adjust automatically.
- **Estimate · Optional**: The new remaining estimate, or the amount to change it by (2d, 3h, 30m). Shows when **Remaining Estimate** is **Set to a new value** or **Change by an amount**.

### Jira Software › Issue Link

### Create

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Link Type · Required**: How the issues relate: Blocks, Relates, Duplicate, Cloners … (the site's own link types).
- **From Issue · Required**: The issue the link reads from: it blocks, duplicates or relates to the To Issue.
- **To Issue · Required**: The issue that is blocked, duplicated or related to.
- **Comment · Optional**: A comment added to the From Issue with the link. Plain text (a blank line starts a new paragraph), or an Atlassian Document as JSON.

### Get and Remove

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Link ID · Required**: The link's id (a number; an issue's issuelinks field lists them).

### Jira Software › User

### Create

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **Email Address · Required**: The person's email. Someone without an Atlassian account is sent an invitation to make one. Only an organization admin may add people. Jira Cloud only.
- **Products · Optional**: Which Jira products the person may use. None: an account without product access. Options: Jira Software, Jira Work Management, Jira Service Management, Jira Product Discovery.

### Get

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **User · Required**: The person.
- **Include · Optional**: More to return with the user. Options: Groups, Product access.

### Delete

- **Site · Optional**: Which Jira site. Only needed when your Atlassian account reaches more than one site; empty: the one you signed in to or entered.
- **User · Required**: The person.

Source: https://docs.gorunner.io/apps/jira-software