VCS providers

Cascade auto-detects which VCS your repo is hosted on from the git remote get-url origin URL and opens the PR on the right service.

Supported

Provider	Self-hosted	Default base URL	Auth method
GitHub	Yes (GitHub Enterprise)	`https://api.github.com`	Personal Access Token (classic or fine-grained)
GitLab	Yes (cloud + self-hosted)	`https://gitlab.com/api/v4`	Personal Access Token
Bitbucket Cloud	Cloud only	`https://api.bitbucket.org/2.0`	App Password (username:password)
Azure DevOps Repos	Yes (cloud + Server)	`https://dev.azure.com`	Personal Access Token

GitHub

# github.com
cascade configure vcs github --token ghp_xxx

# GitHub Enterprise
cascade configure vcs github \
  --token ghp_xxx \
  --base-url https://github.acme.com/api/v3

Create the token at github.com/settings/tokens.

Required scopes

Classic PAT:

repo (full) - required for private repos and to open PRs

Fine-grained PAT (recommended):

Repository access: select the specific repos Cascade should be able to work on
Permissions:
- Contents: Read and write (to push branches)
- Pull requests: Read and write (to open PRs)
- Metadata: Read (auto-granted)
- Issues: Read (only if using cascade ticket github:...)

Notes

The same token is reused for cascade configure issue github if you want to fetch GitHub Issues.
GitHub’s API rate limit is 5,000 requests per hour authenticated; Cascade typically uses fewer than 10 per story.
For organization-owned repos, the org may need to approve fine-grained PATs before they work. Check at Organization Settings → Personal access tokens.

GitLab

# gitlab.com
cascade configure vcs gitlab --token glpat-xxx

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

Create the token at GitLab → Edit Profile → Access Tokens. Required scopes: api, write_repository.

Notes

Self-hosted GitLab works identically to gitlab.com; just pass --base-url.
GitLab calls them “Merge Requests” rather than “Pull Requests”; the terminology is unified to “PR” in Cascade output.
If your GitLab instance uses a custom API path (rare), --base-url should include it: https://gitlab.acme.io/api/v4 (the /api/v4 suffix is automatic if you omit it).

Bitbucket Cloud

# Using an App Password (recommended)
cascade configure vcs bitbucket --token "your_username:your_app_password"

Bitbucket uses HTTP Basic auth with username:password format. Create an App Password at Bitbucket → Personal Settings → App passwords.

Required scopes

Pull requests: Write
Repositories: Write

Notes

Bitbucket Cloud only. Bitbucket Server (Data Center) is coming in a future release.
Some Bitbucket workspaces restrict who can create App Passwords; if you cannot, ask a workspace admin.

Azure DevOps

cascade configure vcs azure_devops \
  --token your_pat \
  --organization myorg

The --organization flag is the Azure DevOps organization name (the part of the URL after dev.azure.com/). Create the PAT at Azure DevOps → User Settings → Personal Access Tokens.

Required scopes

Code: Read and write
Pull Request Threads: Read and write (only if Cascade needs to comment on PRs later)

Notes

For self-hosted Azure DevOps Server, pass --base-url https://devops.acme.com (no /_apis suffix; Cascade adds it).
Azure DevOps groups repos by Project. The Project name is derived from the git remote URL.

How auto-detection works

When cascade build or cascade prompt runs, it reads git remote get-url origin and parses the URL. The hostname determines the provider:

URL pattern	Detected as
`github.com/owner/repo` or `github`	GitHub
`gitlab.com/group/project` or any URL containing `gitlab`	GitLab
`bitbucket.org/team/repo`	Bitbucket
`dev.azure.com/org/project/_git/repo` or `visualstudio.com`	Azure DevOps

Both HTTPS and SSH origin URLs are recognized. Examples that all resolve correctly:

https://github.com/myorg/myrepo.git
[email protected]:myorg/myrepo.git
[email protected]:team/myrepo.git
https://[email protected]/myorg/myproj/_git/myrepo

Forcing a specific provider

If you have a non-standard URL, your repo is mirrored, or auto-detection picks the wrong provider, override it in ~/.config/cascade/config.yaml:

defaults:
  vcs_provider: gitlab

Or on the command line:

cascade build stories/sprint.yaml --vcs-provider gitlab

PR description content

Cascade writes a structured PR description for every PR it opens:

## Summary
Add cursor-based pagination to /api/users with ?limit and ?after query params.

## Acceptance criteria
1. Given an existing /api/users endpoint, when called with no params, returns
   the first 50 users with a `cursor` field in the response.
2. Given a previous response's cursor, when called with ?after=cursor, returns
   the next page.
3. Given ?limit=N, when N is between 1 and 200, returns up to N users.

## Files changed
- modify: `src/api/users.py` - Add pagination to the users endpoint
- modify: `src/schemas/users.py` - Add cursor-based response schema
- create: `tests/test_users_pagination.py` - Cover all acceptance criteria

## Tests
✅ Passed: 47 passed in 0.21s
Command: `pytest`

## Source
Story: story-jira-PROJ-123
Generated by Cascade. Human review required before merge.

The format renders well on every supported VCS.

Branch naming

Cascade-created branches follow the pattern:

cascade/{story-id}/{slugified-story-title}

Examples:

cascade/story-prompt-20260925-103045/add-cursor-pagination
cascade/story-jira-PROJ-123/add-cursor-pagination
cascade/story-meeting-standup-2026-09-26-001/refactor-user-class

This naming makes it easy to find the Cascade-generated branches in git branch --list "cascade/*" and correlate PRs back to stories.

Branch protection interaction

If your default branch (main) has branch protection (required reviews, required status checks), Cascade-generated PRs are subject to the same rules as human-created PRs. Cascade has no special permissions.

This is by design: Cascade should never bypass your team’s review process.

Common gotchas

What happens	Why	Fix
`403 Forbidden` from GitHub	Token scope is missing or org has not approved the token	Verify scope at github.com/settings/tokens. For org repos, check organization PAT policy.
`401 Unauthorized` from GitLab	Token expired or scope mismatch	Create a new token at GitLab profile settings; verify it has `api` scope.
`Push rejected: protected branch`	Trying to push directly to `main` instead of a feature branch	Should not happen; Cascade always pushes to a feature branch. If it does, file a bug.
Bitbucket: `Unauthorized` despite correct token	App Password lacks Pull request write or wrong username	Token format is `username:app_password`; double-check both halves.
Azure DevOps: wrong organization	`--organization` does not match the org in the git URL	The org is the URL segment after dev.azure.com/.
PR opens but reviewers are not assigned	Cascade does not auto-assign reviewers	Configure CODEOWNERS or auto-reviewer settings in your VCS.

Coming later

Bitbucket Server (Data Center) support
Gitea / Codeberg support
PR comment loop: Cascade reads PR review comments and iterates on the change

What is next

Issue trackers for fetching tickets from Jira / Linear / etc.
Build from a ticket for using the trackers end-to-end
Security model for what Cascade can and cannot do with your VCS access