# Jira

Jira integration connects CoderFlow to your Atlassian Jira instance, allowing users to create tasks directly from Jira issues and post task results back as comments. This keeps your issue tracker in sync with the work CoderFlow performs.

## Overview

When Jira is configured:

- **Import issues** — Create CoderFlow tasks or objectives from Jira issues. The issue summary, description, type, status, priority, assignee, and labels are pulled in as context for the agent.
- **Import comments** — Optionally import comments from the Jira issue to give the agent additional context from team discussions.
- **Post results** — After a task completes, post the summary back to the Jira issue as a comment.
- **Search** — Search Jira by text or issue key from the Web UI when creating tasks.
- **Link tracking** — Tasks and objectives display a Jira badge linking back to the source issue.

Jira configuration is global — it applies to all environments and users on the server.

## Prerequisites

- A Jira Cloud instance (e.g., `https://your-company.atlassian.net`)
- An Atlassian account or service account with access to the projects you want to import from
- A Jira API token for that account

### Service Accounts

We recommend using an Atlassian service account rather than a personal account. When CoderFlow posts comments back to Jira, they appear under the account that owns the API token. A service account (e.g., named "CoderFlow") makes it clear that comments were posted by CoderFlow rather than an individual team member.

Atlassian provides built-in service account functionality through the Atlassian Admin console. To set one up:

1. Go to **admin.atlassian.com** and navigate to your organization's settings
2. Create a service account (e.g., named "CoderFlow")
3. Grant the service account access to Jira
4. Create an API token for the service account

For details, see [Manage API tokens for service accounts](https://support.atlassian.com/user-management/docs/manage-api-tokens-for-service-accounts/) in the Atlassian documentation.

### Creating an API Token

For a **personal account**:

1. Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click **Create API token**
3. Give it a descriptive name (e.g., "CoderFlow")
4. Copy the token — you won't be able to see it again

For a **service account**, create the API token through the Atlassian Admin console as described above.

The API token authenticates as the associated account. The integration will have the same project access as that account.

## Setup

Jira can be configured using the interactive CLI wizard or by editing the configuration file directly.

### CLI Setup (Recommended)

The server CLI provides a guided setup that tests the connection before saving:

```bash
coder-server jira connect
```

The wizard walks through four steps:

1. **Jira Base URL** — Your Jira instance URL (e.g., `https://your-company.atlassian.net`)
2. **Email** — The email address associated with the Atlassian account (for service accounts, this is the generated service account email)
3. **API Token** — The Jira API token (the wizard can open your browser to the token creation page)
4. **Test Connection** — Verifies the credentials work before saving

On success, the configuration is saved and the server will use it automatically.

### Manual Configuration

Create a `jira.json` file in your coder setup directory:

```json
{
  "enabled": true,
  "baseUrl": "https://your-company.atlassian.net",
  "auth": {
    "email": "your-account@example.com",
    "apiToken": "your-api-token"
  }
}
```

After creating or modifying the file, restart the server.

## Managing the Integration

### CLI Commands

Use `coder-server jira <command>` to manage the integration:

| Command | Description |
|---------|-------------|
| `connect` | Interactive setup wizard |
| `status` | Show current configuration |
| `test` | Test the connection |
| `disconnect` | Remove Jira configuration entirely |

### Checking Status

```bash
coder-server jira status
```

Displays the configured URL, email, whether the integration is enabled, and a partial view of the API token for verification.

## Usage

### Importing Issues in the Web UI

When Jira is enabled, an **Import from Jira** option appears in the task and objective creation menus:

1. Click **Import from Jira**
2. Search by issue key (e.g., `PROJ-123`) or text
3. Preview the issue details — summary, description, type, status, priority, assignee, and labels
4. Confirm to create the task or objective with the issue context

The agent receives the full issue details as formatted instructions. If you provide additional instructions, they are appended to the Jira issue content.

Comments from the Jira issue can also be imported to provide the agent with additional context from team discussions.

### Jira Badge

Tasks and objectives linked to a Jira issue display a badge with the issue key that links directly to the issue in Jira. You can unlink an issue from the badge if needed.

### Posting Results to Jira

After a task completes, you can post the task summary back to the linked Jira issue as a comment using the **Post to Jira** button on the task page. Comments are converted from Markdown to Atlassian Document Format automatically.

If you're using a service account, these comments will appear under the service account name (e.g., "CoderFlow") rather than a personal account.

## Troubleshooting

### "Jira integration not enabled"

This appears when users try to import issues but Jira is not configured. Run `coder-server jira connect` or create the `jira.json` configuration file.

### Authentication Failed

- Verify the email address matches the Atlassian account (for service accounts, use the generated email address)
- Regenerate the API token — tokens can expire or be revoked
- Ensure the account has access to the projects you're importing from
- Run `coder-server jira test` to verify the connection

### Issue Not Found

- Check the issue key format — it must be `PROJECT-123`
- Verify the authenticated account has permission to view the issue
- The project may use a different key than expected — check in Jira

### Connection Timeout

- Verify the base URL is correct and accessible from the server
- Check network connectivity between the CoderFlow server and Jira Cloud
- Ensure no firewall rules are blocking outbound HTTPS to `*.atlassian.net`
