# Start work from Jira tickets

import { Steps } from '@astrojs/starlight/components';

A Jira trigger starts a Docs Agent session when a ticket in the projects you choose, assigned to the people you choose, moves into a status you choose.

The agent reads the ticket, drafts the docs change, opens a pull request, and comments on the ticket with what it did. Triggers start the Docs Agent only, never the Marketing Agent.

Linear works differently: once connected, the agent can read Linear issues for context, but a Linear issue cannot start a session.

## Before you begin

- A documentation repository connected through [GitHub](/agent/github-app-setup/) or [GitLab](/agent/gitlab-setup/). The agent opens its pull requests there.
- A **Jira triggers** tab under **Settings** > **Docs Agent**. If you do not see it, contact support@ekline.io.

Any member of your organization can add, edit, and delete triggers.

## Steps

<Steps>

1. **Connect Jira.** Go to **Settings** > **Integrations**, find **Jira**, and click **Connect**. In **Jira Subdomain**, enter the first part of your Atlassian URL (for `acme.atlassian.net`, enter `acme`), click **Connect**, and finish the Atlassian sign-in. The card then shows **Connected**.

2. **Open the triggers.** Go to **Settings** > **Docs Agent** > **Jira triggers** and click **Add trigger**.

3. **Select the tickets.** Fill in the form:

   | Field | What to enter |
   | --- | --- |
   | **Projects** | One or more Jira projects. |
   | **Assignees** | One or more people. Type in **Search people by name** and select from the results. |
   | **Statuses** | One or more statuses, for example `Ready for docs`. |
   | **Labels (optional)** | Leave empty, or limit the trigger to tickets that carry at least one of these labels. Type a label and press Enter. |

4. **Save it.** Click **Create trigger**. The trigger appears as a sentence, such as "When a ticket in Acme Help (ACME), assigned to Alex Kim, enters Ready for docs", with a switch to turn it off and buttons to edit or delete it.

</Steps>

### How tickets match

- **Any value within a field, every field together.** A ticket matches when its project, assignee, and status are each one of the trigger's values, and, with labels set, it carries at least one of them. Unassigned tickets never match.
- **On the way in.** The trigger fires when a change of status, assignee, or (with labels set) labels makes a ticket match, or when a ticket is created already matching. Editing the summary or description does not fire it.
- **Statuses match by name**, ignoring case. If several workflows have a status called `Ready for docs`, the list shows it once and all of them count.
- **One session per ticket.** Once a ticket has started a session, moving it out of the status and back does not start another.

### What the agent does

<Steps>

1. Checks the ticket again immediately before it starts. If the ticket no longer matches, it stops without doing anything.
2. Reads the ticket, its comments, and any linked pull requests and Confluence pages.
3. Decides which documentation repository and pages the change belongs in, from the ticket, the linked code, and your connected repositories. There is no setting for a target repository.
4. Drafts the update and opens a pull request for your team to review.
5. Posts one comment on the ticket: what it changed and why, the pull request link, and anything it could not read.

</Steps>

If the agent cannot tell where the docs belong, or the change needs no docs, it opens no pull request and says so in its ticket comment. For what the pull request contains, see [How EkLine opens pull requests](/agent/how-ekline-opens-pull-requests/).

## Check it worked

Move a test ticket into the trigger's status, assigned to one of its assignees, then look for:

- **A comment on the ticket** with the pull request link.
- **A session** under **Sessions**, titled with the ticket's summary. Filter by **Source** > **Jira**, or paste the ticket's URL into session search. See [Find a past session](/agent/find-sessions/).
- **A pull request** in your documentation repository.

## Troubleshooting

| Problem | What to do |
| --- | --- |
| The tab says "Connect Jira first to configure triggers" | Connect Jira in **Settings** > **Integrations**, then reopen the tab. |
| **Create trigger** stays grayed out | Select at least one project, one assignee, and one status. |
| A ticket reached the status and nothing happened | Check that the trigger is switched on, the ticket's assignee and labels match, and the ticket has not started a session before. |
| The agent commented but opened no pull request | It could not tell where the docs live, or found nothing to change. Open the session and tell the agent where the docs live. |

## Next

- [Work in the editor](/agent/editor/)
- [How EkLine opens pull requests](/agent/how-ekline-opens-pull-requests/)
- [Slack](/agent/slack-bot/)
- [GitHub pull requests](/agent/github-integration/)