Atlassian Projects

TL;DR

Save one Atlassian Platform Credential with two scoped tokens, then register a Bitbucket Cloud repository and a Jira Cloud project. Both tokens must read valid for Dispatch. Atlassian supports Small and Medium Intake and Wayfinder; Medium and Wayfinder require a Spec Issue Type, and Prototyping Sessions are refused.

A Project belongs to one Platform, the pairing that supplies its repository and tracker. Each Stack can watch Projects on both supported Platforms:

Platform	Repository	Tracker	Intake	Wayfinder	Prototyping
GitHub	GitHub	GitHub Issues	Small, Medium, Large	Supported	Supported
Atlassian	Bitbucket Cloud	Jira Cloud	Small; Medium and Large with a Spec Issue Type	Research, grilling, and task Tickets with a Spec Issue Type	Refused

Choose the Platform before registration

The Platform, Jira site, project key, and Platform Credential are fixed at registration. Moving a repository or backlog requires a new Project. GitHub repositories paired with Jira are refused, including stored Projects from older versions.

Bitbucket Issues, Bitbucket Server or Data Center, and Jira Server or Data Center are unsupported.

Provide the Platform Credential

A Platform Credential is the Dispatcher's authentication record for one Platform, with exactly one per Platform per Stack. GitHub uses a single token. Atlassian uses one account email, two scoped API tokens, one bound Bitbucket workspace, and one bound Jira Cloud site. Atlassian scopes tokens per app, so create a separate token for each app.

1. For Bitbucket, open Atlassian's API token page, choose Create API token with scopes, and select Bitbucket. Give it the scopes below. The account must have access to every repository Zozo will watch.

Permission	Scope	Registration validates
Repository read	read:repository:bitbucket	Reading the selected repository and its default branch
Pull Requests read	read:pullrequest:bitbucket	Nothing at registration; the Dispatcher lists open pull requests on every Selection Pass and Landing tick, and a token without it fails those with HTTP 403
Pull Requests write	write:pullrequest:bitbucket	The granted scopes reported by Bitbucket include write permission
Pipelines read	read:pipeline:bitbucket	Reading the selected repository's Pipelines
Repositories admin (optional)	admin:repository:bitbucket	Nothing at registration; needed only to create a repository through Zozo
Repositories write (optional)	write:repository:bitbucket	Nothing at registration; needed with Repositories admin to push the first commit when you create a repository. Admin alone can't push
Projects read (optional)	read:project:bitbucket	Nothing at registration; lists the workspace's Bitbucket projects when you create a repository. Without it, type the project key

2. For Jira, open Atlassian's API token page, choose Create API token with scopes, select Jira and Classic scopes, then select read:jira-work, write:jira-work, and read:jira-user.
3. In Setup, choose the Atlassian Platform tile. Enter the account email, Bitbucket API token and workspace, and Jira Cloud site name (the part before .atlassian.net) and API token, then select Save Atlassian Credential. You can also save the same record on Credentials, where GitHub and Atlassian cards are always visible, including empty forms for unconfigured Platforms.

Enter the workspace as a bare slug, such as team in https://bitbucket.org/team/payments. Zozo trims whitespace and lowercases it; letters, digits, underscores, and hyphens are accepted. Verification reads that workspace's repository listing; an empty listing is valid. Zozo discovers the Jira site's cloud id automatically and validates Jira through the Atlassian API gateway.

One workspace and site per Stack

Every Atlassian Project must use the bound Bitbucket workspace and Jira site. The workspace and site freeze once any Atlassian Project exists. Use another Stack for another workspace or site.

The Atlassian card shows separate Bitbucket and Jira Credential health readings: valid, invalid, unproven, or unconfigured. Validate probes both tokens again. Authentication rejection marks the affected token invalid; a Jira HTTP 403 names the required scopes. Network failures, throttling, and server errors leave the reading unproven. A save that rejects either token preserves the previous record.

Replace scoped tokens when they expire

A scoped token expires on the date chosen at creation. Enter its replacement in the Atlassian card and save. Leave the other token blank to retain it. The workspace and site can't change while any Atlassian Project exists.

Select Remove on a Platform card and explicitly confirm permanent removal when it has no dependencies. Zozo refuses while any Project on that Platform remains, Active or not, and names those Projects.

The Platform Credential stays in one owner-only secrets file. Responses include health and account metadata but never tokens. The tokens never reach a Run, Cell, Event journal, Stack Backup, or Stack Audit Export.

Setup lets you continue once the record is stored; completion requires every watched Project's Platform to have all token readings valid. The Dashboard checklist uses the same state. An Atlassian Project is held from every Dispatch pick while either token isn't valid; its Attention Item names the token to repair.

Re-enter Atlassian authentication after upgrading

Older separate Bitbucket and Jira credential files are ignored. Save the complete Atlassian Platform Credential again in Setup before dispatching existing Atlassian Projects.

Pick the Repository

1. Save the Atlassian Platform Credential in Setup or on Credentials.
2. Under Add a Project on Projects, choose Atlassian as the Platform. The select offers only stored Platforms.
3. Filter the repository picker and select your repository. It lists repositories in the bound workspace.
4. Pick the Jira project from the bound site, then pick its required Publish Issue Type from the base-level types (hierarchy level 0), such as Task or Story. Optionally pick a Spec Issue Type from the parent-capable types (hierarchy level 1 or above), such as Epic, to enable Medium Intake and Wayfinder. Subtask types (level -1) appear in neither picker. Optionally pick a component and enter labels to narrow the scope. Label Authority defaults to Observed; choose Owned explicitly to allow background label maintenance. Complete the activity authentication and work settings described in Watch a Project.
5. Submit the registration. Zozo validates repository access, Pull Request write permission, Pipelines access, and the Jira binding.

The Project key is bitbucket.org/<workspace>/<repo>, for example bitbucket.org/team/payments. GitHub keys remain owner/repo. The Base Branch, the branch future work targets, defaults to Bitbucket's main branch at registration and is saved as a concrete branch name. The repository needs at least one commit on that branch: registering an empty repository fails with "Repository has no commits yet", so push a first commit, then register it.

If the picker shows a rate-limit failure with a reset time, retry after that time. The picker preserves allowance for Dispatch, the activity that works eligible Issues, and Landing. A picker failure doesn't raise a Fleet Fault, a condition that pauses affected fleet work. When Bitbucket's allowance is exhausted by Dispatch, only Bitbucket Projects wait; GitHub Projects continue.

Create a Repository

Under Add a Project on Projects, choose Atlassian as the Platform and Create a new repository. Enter a repository name and, optionally, the key of the Bitbucket project to file it under, then select Create repository and complete the same Jira project picker, narrowing, and work settings as above.

Zozo creates an empty private repository in the bound workspace, under the Bitbucket project you named or the workspace's default project when you leave the key empty, pushes one empty commit so a Base Branch named main exists, validates the repository exactly as it validates an existing one, and starts watching it. The Project key is bitbucket.org/<workspace>/<name> with the name lowercased. There is no visibility picker.

Creation needs the optional Repositories admin and Repositories write permissions on the Platform Credential: admin creates the repository and write pushes its first commit. Without either, Zozo refuses before anything is created and names the missing scope. With the optional Projects read permission, the form lists the workspace's Bitbucket projects as suggestions; without it, type the key. The account behind the token also needs Create repositories permission on the target project, which workspace admins have on every project. Bitbucket answering that you can't create repositories under this project usually means the workspace has no default project that account may create in: create a project in Bitbucket and enter its key. If the first push fails after the repository exists, push a commit to it yourself and watch it as an existing repository.

The Jira project is chosen by hand from the bound site, never inferred from a repository link. The issue type and component pickers list the Jira project's own base-level Publish Issue Types, parent-capable Spec Issue Types, and components; when Jira can't be read the pickers stay empty and registration waits. Each component or label narrowing value uses equality, and all supplied values must match. Zozo validates the project key, issue types, and component against Jira. A label is accepted as typed, since Jira creates labels on use, and matches nothing until an Issue carries it. Free JQL and board scopes are unsupported.

Edit the Jira Scope

The Jira site, project key, and Platform Credential are fixed at registration. The Publish Issue Type, Spec Issue Type, component, and labels stay editable: open the Project's row menu on Projects and use Jira scope. These fields save as one change, Zozo validates them against Jira before storing them, and a refusal shows inline. Changing the component or labels changes which Issues the Dispatcher considers next; Threads and Runs already in flight continue unchanged. The Publish Issue Type can be replaced but not cleared. The optional Spec Issue Type can be replaced or cleared.

Clearing the Spec Issue Type leaves existing Specs recognized by their wayfinder:spec label. Medium Intake and Wayfinder refuse new starts until you pick one again, with a message pointing to Projects. Small Intake remains available with a valid Publish Issue Type.

Repair a missing or non-base Publish Issue Type

A Project without a Publish Issue Type shows No Publish issue type. An Epic or another non-base type stored as the Publish Issue Type shows Invalid Publish issue type. Use Jira scope to pick a base-level type before starting Intake; existing Threads and Runs continue.

Landing on Bitbucket

Label an eligible Jira Issue ready-for-agent and enable Auto-dispatch to start work. The Dispatcher opens a Bitbucket Pull Request with a Resolves PAY-142 line tying it to the Jira Issue. Jira resolution uses the Done status category, as described below.

A Checks Verdict is Zozo's current summary of the Pull Request's build statuses. Failure takes precedence over pending work:

Bitbucket build statuses	Checks Verdict
Any FAILED or STOPPED	failing
Otherwise, any INPROGRESS	pending
All SUCCESSFUL	passing
No statuses	none

Landing integrates an authorized Pull Request into its Base Branch. On Bitbucket it uses a squash merge through Bitbucket's merge API. Zozo detects branch conflicts locally while updating the branch. A Bitbucket merge check or branch restriction that refuses the merge blocks Landing with reason merge-refused; inspect and satisfy the restriction before retrying.

When Bitbucket Pipelines fails, a Landing Repair Run receives the failed steps' log tails within Zozo's evidence limits. External CI contributes its status name, state, and URL only. Configure review and automatic merge behavior using the Pace and merge policy settings in Watch a Project.

Read the Dashboard

The Dashboard's Project panel shows open Jira Issues with keys such as PAY-142, linking to Jira. Zozo retains the immutable Jira issue id as identity; a key can change when an issue moves. Queue Position orders Jira Issues by issue id. Descriptions are converted from Jira's document format to Markdown, with unknown nodes retained as plain text.

Each Project has an independently usable Issue Snapshot, its last successful observation. If Jira can't be read, the previous slice remains visible with a refresh error while other Projects continue refreshing.

Dispatch a Jira Issue

Apply ready-for-agent to an Issue in the Project's Jira scope. Fleet Dispatch picks it when eligible, or choose Dispatch issue in its Dashboard row. The same Control Label and Classification Label vetoes apply as on GitHub. Materializing the Control Label Catalog makes no Jira writes because Jira creates labels on use.

Jira Issues are resolved when their status category is Done, regardless of the status name.

Choose ambiguous Done transitions manually

After Landing, Zozo transitions the Jira Issue only when exactly one available transition leads to a Done-category status. If there are none or several, it leaves the Issue open and comments with the reason. Choose the appropriate transition manually.

Blocked derives only from incoming native Blocks links; a ## Blocked by description section is ignored. A blocker in another tracker stays unreadable and is treated as open.

With Owned Label Authority, background reconciliation maintains Blocked and removes stale Control Labels from resolved Issues. Before each pick, the inline sweep demotes an Issue with an open blocker and restores a previously blocked Issue once its blockers resolve, subject to the usual promotion vetoes. An open Pull Request awaiting Landing vetoes promotion. With Observed Label Authority, neither background reconciler writes Jira labels.

Claiming adds agent-in-progress as a Jira label. The Thread records the tracker-qualified Issue identity, the head branch carries the key, for example agent/issue-PAY-142-fix-payments, and the Run prompt carries the description converted to Markdown. The resulting Pull Request stays on Bitbucket Cloud and carries Resolves PAY-142. Pacing, Outstanding Pull Request detection, and the Landing Queue recognize this tie.

Images referenced in the description reach the Run as Attachments, image blobs sanitized before the Runtime receives them. Each Issue allows up to 10 image fetches and 20 MiB of total downloaded image bytes. Images must decode successfully through the sanitizing boundary. Other files and images over either cap are listed by name in the prompt. Permission errors, missing files, timeouts, and undecodable images leave Dispatch proceeding with the attachment name and failure reason in the prompt. Images attached only to comments aren't fetched.

Zozo converts every comment it writes on Jira into Jira's document format, including needs-info, Human Input, and Clarification records. Answer Clarifications in the Dashboard.

Publish Flat Issues (Small)

Choose Small when starting an Intake Session on an Atlassian Project. Publish creates flat Issues of the configured issue type, stamping the component and labels from the Project scope so its own query includes every new Issue. It applies the same publish labels as GitHub: ready-for-agent on the Frontier, blocked on dependents, and the plan's other labels. Dependencies become native Blocks links. The tracer Issue carries the Doc Delta, converted to Jira's document format.

A Prototyping Handoff into Small is allowed. Prototyping Sessions require a GitHub tracker.

Publish a Spec with Children (Medium and Wayfinder)

Medium and Large Intake require a Spec Issue Type, a parent-capable Jira issue type picked on Projects. Publish creates a Spec of that type with the wayfinder:spec label and implementation children of the Publish Issue Type, each linked to the Spec through Jira's parent field. The Project scope's component and labels are stamped on both the Spec and its children. Dependencies become Blocks links, child descriptions point to the Spec by key, and, when enabled at plan review, a Spec Branch uses the lowercased key, for example spec/pay-12-payments-spec.

Large Intake opens a Wayfinder Map of the Spec Issue Type with the wayfinder:map label. Its Tickets are children of the Publish Issue Type. Jira Projects admit research, grilling, and task Tickets; starting a prototype Ticket is refused inline because Prototyping requires a GitHub tracker. The Map endgame publishes a Spec and its implementation children, with the glossary seed child under that Spec for a corpus Map.

With a Spec Branch, a Spec Pull Request opens on Bitbucket once every child is closed and at least one is completed. A Done-category child with no resolution or a resolution named Done is completed; any other resolution, including Won't Do, is not planned and doesn't block the remaining children. Spec Pull Request titles and descriptions reference the Jira key. Spec Refresh integrates changes from the Base Branch into the Spec Branch, and Auto-land controls automatic Landing. Landing the Spec Pull Request closes the Jira Spec through the Done transition rule above. Closing the Spec as Won't Do, or with any other not-planned resolution, abandons its remaining child work. A status outside the Done category remains open regardless of its resolution.

The Dashboard renders a Jira Spec as a Spec Group headed by its key, with child rows, the Spec Branch, Auto-land, and the Spec Pull Request.

Author a Spec by Hand in Jira

1. Create an Epic, or another parent-capable issue of the Project's Spec Issue Type, within the Project's Jira scope.
2. Add the wayfinder:spec label. Recognition depends on that label, so an unlabeled Epic doesn't become a Spec.
3. Write the to-spec template in its description: problem statement, solution, user stories, implementation and testing decisions, and out of scope. Include the shared Doc Delta on the Spec.
4. Create implementation children as the Publish Issue Type, set their Jira parent to the Spec, and add Blocks links for dependencies. Apply the scope's component and labels to the parent and every child.
5. Label eligible children ready-for-agent. The Dispatcher supplies the parent Spec as context for their Runs.

Unsupported Jira Workflows

• Prototyping Sessions and prototype Tickets are refused on Jira Projects.
• Jira subtasks can't serve as Spec or Map children; use base-level Publish Issue Type issues.
• Jira projects without a parent-capable type can use Small Intake. Medium Intake and Wayfinder require a Spec Issue Type.

Quota Pools

The quota picker groups jira and bitbucket under Atlassian. These are independent pools, with no site qualifier on Jira. A Jira HTTP 429 with a future Retry-After holds Jira requests until that reset; Bitbucket learns its allowance from response headers. A quota Fleet Fault names the affected pool and reset time. GitHub Projects continue while Atlassian work waits. Repository pickers preserve a dispatch reserve and never raise a Fleet Fault. See Understand Your Quotas.

Continue After an Onramp

An Onramp carries the Project, its host-qualified key, and Jira scope. The entire Platform Credential stays behind without a Credential Placeholder, which is reserved for Runtime authentication. Setup asks for the email, both tokens, workspace, and site again. Older bundles' tracker placeholders are ignored. Atlassian Projects wait until both token readings are valid.