Skip to main content

Projects

Projects connect one or more repositories to Jaah: their branches, gate commands, members, environment variables, node groups, MCP links and issue-tracker links. A project's endpoints also cover its release pipeline and history, its merge lane, its project memory, how its deploys reach Jaah, its outcome scan and its Live Cast settings; List merge lane rows across projects reads every merge lane you can view.

๐Ÿ“„๏ธCreate project

Connects an existing repository as a new project without adding any files to it; to connect several, send `repos` instead of `repo_url`, each row with its `repo_url` and `integration_branch` and exactly one marked `is_primary`; with neither, the project has no repository and each of its tasks runs in an empty folder instead of a git worktree. With `placement`, which requires the Org Owner or Org Admin role, checks the nodes named (404 for an unknown node or another organization's, 409 for a disabled one) and answers a `placement_warning` when cloning on them would fail, but declares nothing, since a new project runs on every node of its organization. Returns 201 with the project, or 422 naming each bad `repos` row by its index.

๐Ÿ“„๏ธDelete project

Deletes the project from Jaah, and every task in it, without touching its repository; an Easy Mode project's hosted app goes with it, only when `confirm` is the app's address (422 otherwise). Returns 409 while the project's hosted app is still being set up or one of its worktrees has no node that can address it; otherwise erases its worktrees on their nodes and returns 204 with no body; a system project cannot be deleted (422). Requires the Org Owner or Org Admin role.

๐Ÿ“„๏ธUpdate project

Changes the fields sent on a project; null clears an optional field, but null on the name, branch, prefix, gate or stack commands, or push setting returns 422. `repos` replaces the connected repositories as a whole set (a row with `id` is updated, one without is added, any left out is removed); changing branch, gate, stack or push settings, or the primary repository's branch, needs governance authority; changing Run jobs as needs the Org Owner or Org Admin role; connecting a project's first repository or removing its last needs the Org Owner or Org Admin role and permission to both create and delete projects (an empty `repos`, or a null `repo_url`), which stops every task running in one of its git worktrees and queues it again to run in an empty folder. `merge_lane_enabled` turns the project's merge lane on or off; turning it on answers 409 when the organization's plan has no merge lane, and null is a 422; returns the project, or 422 naming each bad `repos` row by its index.

๐Ÿ“„๏ธCreate project environment variable

Adds an environment variable to the project, as a literal value, drawn from a credential, or a Port (`source` `port`): no value, the node gives each slot a free port, trying `port_preferred` (1024 to 65535) first when set; a Port variable is project-wide only (422 for a personal one, a name Jaah sets on every slot, or a preferred port inside the organization's auto-assign range). A project default requires project edit permission; anyone who can view the project may add their own override. Returns 201 with the variable.

๐Ÿ“„๏ธGet merge lane

Returns the project's merge lane at a glance, read-only: whether it is active (and why not), whether it is still draining after a switch-off, how many entries its queue, history, runs, certificates and flaky tests hold, and when it last swept. It also names the integration branch when the lane found it red (the failing tests and the fix task), a lane run that holds the lane without taking batches (its task id and state: `paused`, `awaiting_response` or `draft`), the nodes its runs are kept off and until when, and PRs whose auto-merge was armed outside the lane.

๐Ÿ“„๏ธGet pipeline

Gets a project's pipeline: its stages in order (name, branch, address and where it came from, the level the branch implies, the deploy target, the address's last health check, and the gates that verify a change after it arrives), the step into each stage after the first (what it does, who may do it, approvals needed, whether it runs by itself, and its gates in order with a one-line summary each), each step's approval, timing and concurrency rules, the freezes, Freeze now, and whether a release is running.

๐Ÿ“„๏ธSave project pipeline

Replaces a project's pipeline in one save, in the order sent: a stage with an id is updated, one without is added, one left out is removed, with one step per stage after the first; `freezes`, a step's `gates` and a stage's `after` gates and `target`, when sent, replace what is stored, and are kept when left out. A running release finishes on its old settings, and each save that changes something is recorded in the pipeline's history. Requires Edit on the project, and custom mode on a plan with custom pipelines (409 otherwise); a stage out of order, a name or branch used twice, a step or freeze rule out of range (named in `field`), a gate the step cannot take (naming the stage and gate), or a step an org pipeline rule set to Block refuses is refused with 422, and the response's warnings list the rules set to Warn it breaks.

๐Ÿ“„๏ธGet pipeline items

Lists a project's pipeline items in screen order: one stage's (`stage` is its id or `not_started`, `done`, `archived`) or every stage's, each a task as the task list shows it or a merged change no task owns (never a pull request), with its group in the stage, which `group` filters by. Takes the task list's filters and pages by keyset, at most 200 rows a page: pass the `X-Next-Cursor` header back as `after`. A release stage adds its releases, newest first, the newest grouped by feature.

๐Ÿ“„๏ธAct on pipeline step

Acts on the step into a stage: `go` presses it (Start, Move, Merge, or Deploy on a release, which `scheduled_for` schedules), `approve` or `reject` (an approver's, each with an optional `comment`), or `cancel`. A step on tasks takes `subjects` (`task_ids`, `shas`, or `all_in_stage` for every item of the stage before the step, rows never loaded included) and answers how many were done, which were refused and why, and how many wait for approvals; `reject` refuses an item not waiting for approvals as `not_waiting`. A release step acts on its release and answers a refusal with its status (403 for a caller the step does not allow, 409 `not_signed_off` while a sign-off stage before it misses changes, 409 `verifying` while the stage before it still verifies its newest change, 422 `no_source` for a step with no branch stage before it, and 409 `no_release` for `approve`, `reject` or `cancel` with no open release into the stage); `override_reason` on a `go` of a step that merges or deploys runs that one request through a freeze, audited (at least 10 characters, else 422 `reason_short`; a caller who may also edit the project, else 403 `override_forbidden`), and with any other verb answers 422 `override_not_supported`; a `go` on a step whose ticket gate asks when pressed needs `ticket`, a ticket key like `OAM-123` (422 `ticket_required` without one, unless an open release into that stage already carries one; `ticket_invalid` for text that is not a key), a step that asks for none ignores it, and a field the body does not declare returns 422.

๐Ÿ“„๏ธGet pipeline view

Gets a project's daily pipeline: each stage in order with its count (always present, 0 included), its failures and the version live on it; the version live on Production; each step between two stages with what is in flight, failed or waiting on it, its approvals, its open or failed release, what the caller can do (act, approve, cancel, schedule) and any freeze; and the counts of tasks not started, done without code, and archived. Each count equals the items `GET โ€ฆ/pipeline/items` lists for it.

๐Ÿ“„๏ธDeploy release

Deploys one step: everything waiting on `from_stage_id` moves to the next stage, or only the waiting changes listed in `change_ids`; answers 201 with the new release, or 200 with the step's release already open; a pick of only some waiting changes answers 409 `open` while a release into the stage is open, `state` when a listed change is not waiting, and 422 `no_changes` for an empty list. A freeze covering now answers 409 with `code` `frozen` and `until`, unless `scheduled_for` is later, or `override_reason` or `through_freeze` (no reason typed) runs it through the freeze; the caller must be allowed to deploy to the target stage (else 403), and a step whose ticket gate asks for a ticket when pressed needs `ticket` (else 422 `ticket_required`); a sign-off stage before the target that misses waiting changes answers 409 `not_signed_off` with their `count`, and a source stage still verifying its newest change 409 `verifying` with a `reason`. `untested_reason`, or `untested` with no reason typed, ships the stage's head without waiting for its tests, with the same right as `override_reason` and, for a typed reason, its minimum length (403 `override_forbidden`, 422 `reason_short`), never with `change_ids` (422 `untested_pick`) and never once the step's release is running or approved (409 `open`).