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

# Issue to code

> Use Upsun Dispatch Issue to code to turn a GitHub issue, Jira ticket, or Linear issue into a planned code change and pull or merge request when supported by your version control integration.

The **Issue to code** workflow turns a GitHub issue, Jira ticket, or Linear issue into a planned code change, generated implementation, critic review, pull or merge request (when supported by your version control integration), and link-back comment. See [Integrations](/dispatch/docs/integrations) for supported publish targets.

Use Issue to code when you want Upsun Dispatch to:

* read issue or ticket context,
* plan an implementation,
* post that plan back to the issue or ticket,
* generate code changes,
* run a critic pass before opening a pull or merge request (when supported by your version control integration),
* push a branch and open or update a pull or merge request (when supported by your version control integration), and
* comment on the issue or ticket with a link to the pull or merge request (when supported by your version control integration).

<Note>
  Issue to code has no automatic mode and no manual trigger setting. It starts only when an issue body, ticket body, or comment is a valid Issue to code trigger.
</Note>

## Start from an issue or ticket

Issue to code starts from a GitHub issue, Jira ticket, or Linear issue when the whole trimmed issue or ticket body, or whole trimmed comment, is exactly this request:

```text theme={null}
@upsun-dispatch implement
```

A trailing `!`, `.`, or `?` is allowed. Leading and trailing whitespace is ignored.

Upsun Dispatch starts Issue to code when:

* a new issue or ticket is opened with only the trigger text in the body, or
* a new comment is added to an issue or ticket with only the trigger text in the comment body.

A longer issue body, ticket body, or comment does not start Issue to code, even if it contains the trigger phrase. For example, these do not start a run:

```text theme={null}
@upsun-dispatch implement this
```

```text theme={null}
We need to update the payment flow.

@upsun-dispatch implement
```

When Upsun Dispatch sees a nonmatching mention or command, it posts the command list instead of starting a run.

For most issues and tickets, open the item with your description as usual, then add a comment whose entire text is:

```text theme={null}
@upsun-dispatch implement
```

You can also open the item with only `@upsun-dispatch implement` as the body.

<Note>
  For Jira-triggered runs, include the target repository in the Jira issue description as `owner/repo` or as the full repository URL. Start the run by posting the trigger as a separate comment whose entire body is the trigger text. Do not put the trigger in the Jira issue description, because the whole-body trigger rule applies there too. The repository reference does not need to be a clickable link.
</Note>

Upsun Dispatch does not start Issue to code when:

* the trigger text appears only in the issue or ticket title,
* an existing issue or ticket body is edited to add the trigger text,
* an existing comment is edited to add the trigger text,
* the comment is on a pull or merge request conversation instead of a plain issue or ticket, or
* the trigger was posted by Upsun Dispatch itself.

If you add a valid trigger while Issue to code is already active for that issue or ticket, Upsun Dispatch drops the repeated trigger instead of queuing another run. After the active run ends (completes, fails, or is canceled), a later valid trigger starts a new run. For the same source issue or ticket, Upsun Dispatch reuses the same branch, such as `upsun-dispatch/issue-42`, so the next run updates the existing branch and, when supported by your version control integration, the existing pull or merge request instead of opening a separate one.

You cannot cancel an active run from the [Upsun Dispatch console](/dispatch/docs/dashboard). While Issue to code is still in progress before a pull or merge request exists for an integration that supports one, close the source issue or ticket to stop it. After Upsun Dispatch opens or updates a pull or merge request (when supported by your version control integration) and posts the link back, later implementation work starts from a new valid trigger and follows the same branch reuse behavior.

## What the workflow does

Issue to code runs through these stages:

1. **Check push access.** Upsun Dispatch verifies that it has permission to write repository contents before spending time on planning and code generation.
2. **Gather context.** Upsun Dispatch reads issue or ticket metadata, comments, linked references, related pull or merge requests or issues, and relevant repository files into a bounded context bundle.
3. **Plan.** The planning agent creates an implementation plan and Upsun Dispatch posts the plan back to the originating issue or ticket. For Jira-triggered runs, if **Plan approval** is enabled in [Settings > Workflows](/dispatch/docs/workflows#workflow-settings), the run pauses here until an approval decision is posted. For other trigger sources, Issue to code does not use a separate plan approval gate.
4. **Code.** The coding agent works from a fresh clone and the plan. It produces materialized file contents, a summary, a pull or merge request title (when supported by your version control integration), a commit message, changed-file metadata, and review material for the critic.
5. **Critic.** The critic reviews a capped projection of the generated change before a pull or merge request is opened, when supported by your version control integration. Fatal findings block pull or merge request creation. Nonfatal findings can appear in the pull or merge request body when one is opened, or in run presentation.
6. **Push and open.** Upsun Dispatch applies the generated file contents, pushes a branch, and opens or updates a pull or merge request (when supported by your version control integration).
7. **Link back.** When a pull or merge request is opened or updated (when supported by your version control integration), Upsun Dispatch posts a final comment on the originating issue or ticket with a link to it.

The workflow is single-pass after planning is approved or allowed to continue: it codes, runs the critic, and then opens or updates a pull or merge request (when supported by your version control integration). Issue to code does not revise the implementation after critic feedback.

## Understand the plan

The Issue to code plan is structured so you can review both the proposed work and its expected scope. A plan includes:

* **Summary:** two or three sentences describing the intended change.
* **Full plan:** a detailed Markdown plan.
* **Files affected:** repo-relative paths the run expects to change. At least one file is listed.
* **Complexity:** one of `trivial`, `simple`, `moderate`, or `complex`.
* **Assumptions:** important conditions the plan depends on.
* **Risks:** potential issues or uncertainties to review before implementation continues.

You can inspect run activity, logs, and details in the [Upsun Dispatch console](/dispatch/docs/dashboard). Planning output can also include per-run usage reporting.

## Approve or revise a Jira plan

The plan approval gate applies only to Jira-triggered Issue to code runs when **Plan approval** is enabled in **Settings > Workflows**. For other trigger sources, there is no separate plan approval gate.

When the gate is active, a Jira-triggered run pauses after posting the plan and waits for a comment that mentions the Upsun Dispatch bot followed by one of these commands:

```text theme={null}
@upsun-dispatch plan approve
```

```text theme={null}
@upsun-dispatch plan reject [reason]
```

```text theme={null}
@upsun-dispatch plan revise <feedback>
```

Use `plan approve` to continue to coding. Use `plan reject [reason]` to stop the run. Use `plan revise <feedback>` to send feedback and rerun planning; the feedback text is required.

If no approval decision is posted for 7 days, the gate expires and the agent's context for the request clears. Resuming the work later reruns the request from scratch and consumes additional usage.

## Branch naming

For GitHub issues, Upsun Dispatch uses a stable branch for the same issue, based on the configured branch prefix and the issue number. Repeated completed runs for the same issue can update the same pull request branch.

A typical branch name looks like this:

```text theme={null}
upsun-dispatch/issue-42
```

## When a pull or merge request is not opened

A run can end without opening a pull or merge request for different reasons. Unsupported Issue to code publishing is separate from fatal blockers.

When your version control integration does not support Issue to code publishing, the workflow does not open a pull or merge request. For example, GitLab currently does not support Issue to code publishing. See [Integrations](/dispatch/docs/integrations) for supported publish targets. For GitLab merge request automation, use [Code review](/dispatch/docs/workflows/code-review).

Upsun Dispatch refuses to open a pull or merge request when it cannot safely do so. For example:

* Upsun Dispatch does not have repository contents write permission,
* the coding action reports incomplete work with blocking issues,
* the critic reports fatal findings such as compile or parse failures or clear contradictions with the plan, or
* the generated result is blocked or incomplete.

For fatal blockers, Upsun Dispatch posts a blocked explanation instead of a pull or merge request link. Check the issue or ticket comments and the run detail in the [Upsun Dispatch console](/dispatch/docs/dashboard) for the reported blocker.

If no pull or merge request is opened because of a fatal blocker, the run fails so you do not see a successful run that delivered no code change.