Skip to content

Set App Source

PUT
/apps/{app_id}/source

Bind this app to the repository a build should fetch (J1).

Idempotent, and a REPLACE rather than a merge: every field is written, so rebinding from one provider to another cannot leave the previous provider’s credential pointer behind. A build fetching a new repo with a stale credential is the failure this shape exists to prevent.

There is no GET here on purpose. Source is 1:1 with the app and comes back on GET /apps/{app_id} through AppResponse, so a separate read would be a second thing to keep in step for no new information.

credential_ref is a POINTER to a secret, never a secret. The DTO says so and the column comment says so, because a token written here would also live in every backup of the control plane and in this route’s own response.

Authorizations

Parameters

Path Parameters

app_id
required
string

Header Parameters

X-Org-Id
Any of:
string

Request Body required

Bind an app to the repository a build should fetch (J1).

PROVIDER IS VALIDATED HERE, NOT BY A CHECK CONSTRAINT. ensure_public_tables emits ADD COLUMN IF NOT EXISTS, which cannot add a CHECK to an already created table, and editing the constraint tuple alone is a silent no-op. So the vocabulary lives in SOURCE_PROVIDERS and this DTO is what enforces it, the same way repos_router already validates its provider.

credential_ref is a POINTER, and the description says so on the wire. A builder who pastes a token here has put it in the control-plane row, in every backup of it, and in the response body of GET /apps/{app_id}. There is no way to un-send that, so the field is named and documented to make the mistake hard rather than merely regrettable.

object
credential_ref
Any of:
string
<= 500 characters
default_branch
Any of:
string
<= 255 characters
provider
required

One of: github, gitlab, bitbucket.

string
repo_url
required

Clone URL.

string
>= 1 characters <= 2000 characters

Responses

200

Successful Response

object
data
required

One builder-owned app. Mirrors AppDto.

object
app_id
required
string
archived_at
Any of:
string format: date-time
builder_org_id
required
string
created_at
Any of:
string format: date-time
default_hostname
Any of:
string
name
required
string
registered_origins

Https-only origins a browser app token may be presented from.

Array<string>
slug
required
string
source_credential_ref
Any of:
string
source_default_branch
Any of:
string
source_provider
Any of:
string
source_repo_url
Any of:
string
status
required

Lifecycle state: draft, published, suspended or archived. active is accepted on write as a legacy spelling of published.

string
pagination
Any of:
object
has_next
required

Whether there are more pages

boolean
limit
required

Items per page

integer
next_cursor
Any of:
string
page
required

Current page number (1-indexed)

integer
total
required

Total number of items

integer

422

Validation Error

object
detail
Array<object>
object
loc
required
Array
msg
required
string
type
required
string