> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Jira

> Issues, projects, boards, sprints, and versions.

Jira is included in Archal's environment catalog. Use it in a sandbox for issues, projects, boards, sprints, and versions.

|                 |                                             |
| --------------- | ------------------------------------------- |
| Environment ID  | `jira`                                      |
| Transport       | REST and MCP                                |
| State           | JSON                                        |
| Contract        | `archal.environment-state.jira` version `1` |
| Channel         | Preview                                     |
| Curated samples | 5                                           |

Preview means the environment is included for testing, but its upstream coverage is incomplete. Verify the operations your test depends on.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

<Note>
  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.
</Note>

* Only published supported routes should be used as release gates.

## Curated starting states

List the five samples with `archal sample list jira`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

<AccordionGroup>
  <Accordion title="Jira project baseline">
    List one empty project, then create and reset its first task.

    **Sample ID:** `jira.small-project.v1`

    **Category:** `minimal`

    **Starting state:** 6 records across `issueTypes`: 1, `priorities`: 1, `projects`: 1, `statusCategories`: 1, `statuses`: 1, `users`: 1

    **Supported surface:** Stateful projects, issues, comments, transitions, boards, sprints, and modeled administration.

    **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.issues`

    **First read:** `GET /rest/api/3/project/search`. Expected result: HTTP 200.

    **Representative mutation:** `POST /rest/api/3/issue`. Expected result: HTTP 200, 201, 204.

    **Mutation input**

    ```json theme={null}
    {
      "fields": {
        "issuetype": {
          "name": "Task"
        },
        "project": {
          "key": "TEST"
        },
        "summary": "Add idempotency coverage for webhook retries"
      }
    }
    ```

    **Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

    **Expected reset:** restores loaded sample.

    **Known limits**

    * Only published supported routes should be used as release gates.

    **Start this sample**

    ```bash theme={null}
    archal sample show jira.small-project.v1 --raw > archal-jira-small-project.json
    archal state validate jira archal-jira-small-project.json
    archal session create jira \
      --state jira=archal-jira-small-project.json
    ```

    **Inspect the raw state**

    ```bash theme={null}
    archal sample show jira.small-project.v1 --raw
    ```

    The packaged JSON artifact is `samples/states/jira/small-project/state.json` and is 6,135 bytes. The CLI verifies SHA-256 `d341d84e2396cccfa283bd8d671963849539b283800ed980c2eda01cea49268a` before printing it.

    Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.
  </Accordion>

  <Accordion title="Jira active sprint team">
    Exercise a small delivery team with an active sprint, ten issues, comments, worklogs, filters, and notifications.

    **Sample ID:** `jira.active-sprint.v1`

    **Category:** `small-team`

    **Starting state:** 75 records across `boards`: 1, `comments`: 2, `dashboards`: 1, `fields`: 8, `filters`: 2, `issueLinks`: 1, `issueLinkTypes`: 4, `issues`: 10, `issueTypes`: 6, `notifications`: 3, `priorities`: 5, `projects`: 2, `sprintIssues`: 7, `sprints`: 3, `statusCategories`: 4, `statuses`: 6, `transitions`: 5, `users`: 3, `worklogs`: 2

    **Supported surface:** Stateful projects, issues, comments, transitions, boards, sprints, and modeled administration.

    **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.issues`

    **First read:** `GET /rest/api/3/project/search`. Expected result: HTTP 200.

    **Representative mutation:** `POST /rest/api/3/issue`. Expected result: HTTP 200, 201, 204.

    **Mutation input**

    ```json theme={null}
    {
      "fields": {
        "issuetype": {
          "name": "Task"
        },
        "project": {
          "key": "SPRINT"
        },
        "summary": "Add idempotency coverage for webhook retries"
      }
    }
    ```

    **Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

    **Expected reset:** restores loaded sample.

    **Known limits**

    * Only published supported routes should be used as release gates.

    **Start this sample**

    ```bash theme={null}
    archal sample show jira.active-sprint.v1 --raw > archal-jira-active-sprint.json
    archal state validate jira archal-jira-active-sprint.json
    archal session create jira \
      --state jira=archal-jira-active-sprint.json
    ```

    **Inspect the raw state**

    ```bash theme={null}
    archal sample show jira.active-sprint.v1 --raw
    ```

    The packaged JSON artifact is `samples/states/jira/active-sprint/state.json` and is 38,525 bytes. The CLI verifies SHA-256 `668bf98afaefaadf245eb49230ca489a129f3f74bc6cf08bcd6f70dd7e22df1b` before printing it.

    Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.
  </Accordion>

  <Accordion title="Jira populated backlog">
    Exercise search, filters, boards, sprints, worklogs, links, and pagination over fifty-five issues.

    **Sample ID:** `jira.large-backlog.v1`

    **Category:** `populated`

    **Starting state:** 147 records across `boards`: 2, `comments`: 12, `fields`: 3, `issueLinks`: 3, `issueLinkTypes`: 4, `issues`: 55, `issueTypes`: 9, `priorities`: 5, `projects`: 2, `sprintIssues`: 15, `sprints`: 3, `statusCategories`: 3, `statuses`: 7, `transitions`: 7, `users`: 6, `versions`: 2, `watchers`: 3, `worklogs`: 6

    **Supported surface:** Stateful projects, issues, comments, transitions, boards, sprints, and modeled administration.

    **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.issues`

    **First read:** `GET /rest/api/3/search/jql?jql=project%20%3D%20PROJ&maxResults=10&startAt=0`. Expected result: HTTP 200.

    **Representative mutation:** `POST /rest/api/3/issue`. Expected result: HTTP 200, 201, 204.

    **Mutation input**

    ```json theme={null}
    {
      "fields": {
        "issuetype": {
          "name": "Task"
        },
        "project": {
          "key": "PROJ"
        },
        "summary": "Add idempotency coverage for webhook retries"
      }
    }
    ```

    **Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

    **Expected reset:** restores loaded sample.

    **Known limits**

    * Only published supported routes should be used as release gates.

    **Start this sample**

    ```bash theme={null}
    archal sample show jira.large-backlog.v1 --raw > archal-jira-large-backlog.json
    archal state validate jira archal-jira-large-backlog.json
    archal session create jira \
      --state jira=archal-jira-large-backlog.json
    ```

    **Inspect the raw state**

    ```bash theme={null}
    archal sample show jira.large-backlog.v1 --raw
    ```

    The packaged JSON artifact is `samples/states/jira/large-backlog/state.json` and is 86,750 bytes. The CLI verifies SHA-256 `a7541de90f06d8739bdc415a0cfb181da6505b58c293d1d56aa4ce41c94ead62` before printing it.

    Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.
  </Accordion>

  <Accordion title="Jira read-only permissions">
    Verify behavior for a read-only user alongside an administrator in a project with no board or sprint.

    **Sample ID:** `jira.read-only-permissions.v1`

    **Category:** `edge-case`

    **Starting state:** 51 records across `fields`: 19, `issueLinkTypes`: 4, `issues`: 2, `issueTypes`: 5, `priorities`: 5, `projects`: 1, `statusCategories`: 4, `statuses`: 4, `transitions`: 5, `users`: 2

    **Supported surface:** Stateful projects, issues, comments, transitions, boards, sprints, and modeled administration.

    **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.issues`

    **First read:** `GET /rest/api/3/project/search`. Expected result: HTTP 200.

    **Representative mutation:** `POST /rest/api/3/issue`. Expected result: HTTP 403.

    **Mutation input**

    ```json theme={null}
    {
      "fields": {
        "issuetype": {
          "name": "Task"
        },
        "project": {
          "key": "TEST"
        },
        "summary": "Change the production webhook retry policy"
      }
    }
    ```

    **Expected diff:** no state change is expected. Exact match required: yes. The provider-native mutation is expected to fail and produce no state diff.

    **Expected reset:** restores loaded sample.

    **Known limits**

    * Only published supported routes should be used as release gates.

    **Start this sample**

    ```bash theme={null}
    archal sample show jira.read-only-permissions.v1 --raw > archal-jira-read-only-permissions.json
    archal state validate jira archal-jira-read-only-permissions.json
    archal session create jira \
      --state jira=archal-jira-read-only-permissions.json
    ```

    **Inspect the raw state**

    ```bash theme={null}
    archal sample show jira.read-only-permissions.v1 --raw
    ```

    The packaged JSON artifact is `samples/states/jira/read-only-permissions/state.json` and is 20,945 bytes. The CLI verifies SHA-256 `08d17a51948fa33a4f50db16efe8164c71d0b858f447ef0ce6e2480d97bd41d5` before printing it.

    Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.
  </Accordion>

  <Accordion title="Jira reopened ticket workflow">
    Trace INC-2027-014 from a disproven api-gateway\@3.1.0 fix through rollback evidence, reopened status, comments, and a follow-up task.

    **Sample ID:** `jira.reopened-ticket-workflow.v1`

    **Category:** `workflow`

    **Starting state:** 48 records across `boards`: 1, `comments`: 4, `fields`: 3, `issueLinkTypes`: 2, `issues`: 4, `issueTypes`: 5, `priorities`: 5, `projects`: 1, `sprintIssues`: 4, `sprints`: 1, `statusCategories`: 4, `statuses`: 5, `transitions`: 5, `users`: 4

    **Supported surface:** Stateful projects, issues, comments, transitions, boards, sprints, and modeled administration.

    **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.issues`

    **First read:** `GET /rest/api/3/issue/ENG-200`. Expected result: HTTP 200.

    **Representative mutation:** `POST /rest/api/3/issue`. Expected result: HTTP 200, 201, 204.

    **Mutation input**

    ```json theme={null}
    {
      "fields": {
        "issuetype": {
          "name": "Task"
        },
        "project": {
          "key": "ENG"
        },
        "summary": "INC-2027-014: add Retry-After and idempotency regression coverage"
      }
    }
    ```

    **Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

    **Expected reset:** restores loaded sample.

    **Known limits**

    * Only published supported routes should be used as release gates.

    **Start this sample**

    ```bash theme={null}
    archal sample show jira.reopened-ticket-workflow.v1 --raw > archal-jira-reopened-ticket-workflow.json
    archal state validate jira archal-jira-reopened-ticket-workflow.json
    archal session create jira \
      --state jira=archal-jira-reopened-ticket-workflow.json
    ```

    **Inspect the raw state**

    ```bash theme={null}
    archal sample show jira.reopened-ticket-workflow.v1 --raw
    ```

    The packaged JSON artifact is `samples/states/jira/reopened-ticket-workflow/state.json` and is 23,208 bytes. The CLI verifies SHA-256 `763bd66992207e0603ceb8b9a9bc9c6e9b01aa09c03a96dfe5f8afe82f2d740f` before printing it.

    Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.
  </Accordion>
</AccordionGroup>

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe jira`, then validate the file before creating a sandbox:

```bash theme={null}
archal state validate jira state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](/sandboxes/starting-state) before replacing state in an existing sandbox.