Issue trackers

Used with cascade ticket <provider>:<id> to fetch a ticket from your tracker and run it through the pipeline. The same module also backs cascade build when stories were originally extracted from tickets.

Supported

Tracker	Identifier format	Example	Hosted/Self-hosted
GitHub Issues	`github:owner/repo#N`	`github:myorg/myrepo#42`	Both (Enterprise via `--base-url`)
Jira	`jira:KEY-N`	`jira:PROJ-123`	Cloud + Server / Data Center
Linear	`linear:KEY-N`	`linear:ENG-456`	Cloud only
Azure DevOps Boards	`azure_devops:org/project/N`	`azure_devops:myorg/myproj/123`	Cloud + Server
GitLab Issues	`gitlab:group/project#N`	`gitlab:myteam/myrepo#42`	Cloud + Self-hosted

Setup

GitHub Issues

cascade configure issue github --token ghp_xxx

Reuses the same token type as the GitHub VCS provider. If you already ran cascade configure vcs github, you can use the same token.

Required scopes:

repo (full) for private repos
public_repo is enough for public repos

Jira (Cloud)

cascade configure issue jira \
  --token JIRA_API_TOKEN \
  --base-url https://yourcompany.atlassian.net \
  --user [email protected]

Create the API token at id.atlassian.com/manage-profile/security/api-tokens. The token is sent with your email as HTTP Basic auth (Atlassian’s standard scheme).

Required permissions: Browse Projects, View Issues on the project containing the tickets.

Jira (Server / Data Center)

Same configure command, but --base-url points at your installation:

cascade configure issue jira \
  --token JIRA_API_TOKEN \
  --base-url https://jira.acme.com \
  --user your-jira-username

Note: Jira Server uses your Jira username (not email) for the --user flag.

Linear

cascade configure issue linear --token lin_api_xxx

Create the token at linear.app/settings/api. Tokens are workspace-scoped; if you work across multiple Linear workspaces, you need one token per workspace.

Required permissions: Read access to the team containing the tickets. Linear’s permission model is per-workspace, not per-token.

Azure DevOps Boards

cascade configure issue azure_devops --token your_pat

PAT scopes:

Work Items (Read) for fetching tickets
Code (Read) if you also want Cascade to push to the same Azure DevOps repo

If you already configured Azure DevOps as your VCS provider, you can reuse that PAT as long as it has Work Items (Read).

GitLab Issues

cascade configure issue gitlab --token glpat-xxx

# Self-hosted GitLab
cascade configure issue gitlab --token glpat-xxx --base-url https://gitlab.acme.io

Token needs api scope (read is sufficient for fetching issues).

What gets imported

For each tracker, Cascade pulls the ticket and converts it into a Story:

Story field	Source
Title	Ticket title
Description	Ticket body. Format conversion: Jira ADF → plain text; Linear markdown → preserved; GitHub markdown → preserved; Azure HTML → plain text; GitLab markdown → preserved.
Acceptance criteria	One placeholder criterion. If you want richer criteria, run with `--no-pr` and edit before building, or pre-extract via `cascade ticket --extract-only`.
Status	Set to `APPROVED` automatically. Tracker tickets are assumed pre-approved by whoever ticketed them.
Source link	Included in the story notes and the opened PR description.
Size	Estimated by the LLM from the description length and complexity.
Notes	Includes the original ticket URL and the fetched timestamp.

What does not get imported

Custom fields (Jira story points, Linear estimates, etc.)
Labels and tags
Sprint / iteration assignments
Assignee and reporter
Sub-tasks and linked tickets
Attachments
Comments

These all live in the tracker. If your team relies on them, capture the relevant detail in the ticket description before running Cascade, or in your team-memory/conventions.md.

Permissions troubleshooting

What happens	Why	Fix
`404 Not Found` from any tracker	Wrong identifier, or no read access to the project	Verify the identifier format. Confirm your token has read access.
Jira: `401 Unauthorized`	Wrong email or token	For Cloud, email is your Atlassian login (not display name). For Server, it is your Jira username.
Linear: `Unauthorized`	Wrong workspace or token revoked	Verify token at linear.app/settings/api. Tokens are workspace-scoped.
GitHub: `403 Forbidden` on org repo	Organization has not approved your fine-grained PAT	Org admin must approve. Or use a classic PAT with `repo` scope.
Azure DevOps: `Resource not found`	PAT lacks Work Items (Read), or wrong org/project in identifier	Check PAT scopes and identifier format.
GitLab: `Insufficient scope`	Token has only `read_user`, not `api`	Recreate with `api` scope.

Bulk operations

Cascade does not currently have a built-in bulk ticket import. For a sprint of tickets, loop:

for ticket in PROJ-101 PROJ-102 PROJ-105 PROJ-110; do
  echo "==> Building $ticket"
  cascade ticket "jira:$ticket" --max-cost 1.00 || break
done

--max-cost aborts the loop if cumulative cost exceeds budget. || break stops on the first failure.

For a Linear cycle:

# Get a list of ticket IDs from Linear's API or CLI, then:
for ticket in $(cat sprint-tickets.txt); do
  cascade ticket "linear:$ticket"
done

When tickets are not enough

Tracker tickets are written for humans, not for AI agents. They often lack technical detail. Two patterns:

Pattern 1: Enrich the ticket

Edit the ticket in the tracker, add file references, acceptance criteria, and out-of-scope notes. Re-run cascade ticket. Cascade fetches the latest version every time. This works well if your team treats tickets as the source of truth.

Pattern 2: Use a prompt with ticket context inline

cascade prompt "Implement PROJ-123 (cursor pagination on /api/users): use ?limit (default 50, max 200) and ?after (last seen ID), wrap responses in {data: [...], cursor: '...'}, update the OpenAPI schema in docs/api.yaml"

This works well when you have specific technical context not worth adding to the ticket itself.

Coming later

Bulk import: cascade ticket --query "project = PROJ AND status = 'To Do'" to fetch a backlog as a StoryBatch
Bidirectional sync: post a comment on the ticket when the PR opens, update status when the PR merges
ClickUp, Asana, Shortcut, Trello as additional trackers
Sub-task expansion: walk the link graph and fetch related tickets

What is next

Build from a ticket for the end-to-end workflow
Build from a prompt when tickets are too vague
VCS providers for the related write-side integrations