API
The stagd.api.v1 API behind the dashboard, the CLI and the MCP server, over Connect. Every service and method, with their fields.
Everything Stagd does is in one API, stagd.api.v1, defined in Protocol Buffers and served with Connect. The dashboard, the CLI and stagd mcp use it, and so can your scripts. Its contract is the public Buf module buf.build/stagdhq/stagd, for generating a client in your language.
Calling it
Each method is an HTTP POST of JSON to /stagd.api.v1.<Service>/<Method>, with your session token:
curl https://app.stagd.dev/stagd.api.v1.AuthService/GetMe \
-H "Authorization: Bearer $STAGD_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
Every call runs as the signed-in person, in their current org. No request names the org: it comes from the session. stagd login gets a token; the CLI’s --token and STAGD_TOKEN take one.
Reading the tables
- Names are the JSON names:
previewId, notpreview_id. - Unset fields are left out of answers: a missing
limitis 0, a missing list is empty, a missing flag is false. - Numbers that are int64 come as strings in JSON (
"sizeBytes": "1820"), as Protocol Buffers’ JSON has them. - Timestamps are RFC 3339 strings (
"2026-11-02T09:15:00Z"); durations are seconds with ans("30s"). - Enums are their values’ names (
"PREVIEW_STATUS_LIVE"). - Streams: a method marked as streaming answers with a stream of messages, which Connect’s clients read as they come; over plain HTTP it takes Connect’s streaming format, not one JSON body.
Errors
Errors use Connect’s codes: unauthenticated when you’re not signed in, permission_denied when your role can’t do something, not_found, already_exists, invalid_argument (a field breaks its rule in the tables below) and failed_precondition, with a message that says what to do.
Services
| Service | What it does |
|---|---|
AuthService |
AuthService tells callers who they are |
AccountService |
AccountService is the signed-in person’s own account |
OrgService |
OrgService creates orgs and moves between them |
InviteService |
InviteService brings people into the active org |
ScmService |
ScmService connects code hosts to the active org and lists the repositories they give Stagd access to |
ComputeService |
ComputeService connects the compute that previews run on to the active org |
PreviewService |
PreviewService starts, watches and tears down preview environments |
SecretService |
SecretService keeps the secrets previews get as variables |
SeedService |
SeedService keeps the org’s seeds |
IntegrationService |
IntegrationService connects the services an org’s previews use, beside compute and GitHub |
ActivityService |
ActivityService is the org’s activity log |
EventService |
EventService tells the dashboard when something in its org changed, so it refetches what it shows instead of polling |
AuthService
AuthService tells callers who they are.
Signing in is not part of this service. Browsers sign in at /auth (GitHub,
and other providers later), and the CLI signs in with device login
(RFC 8628) at /auth/device/code and /auth/device/token. Both give a session
token, sent to this API as Authorization: Bearer <token>.
AuthService.GetMe
POST /stagd.api.v1.AuthService/GetMe.
GetMe returns the signed-in user, the org this session acts in, and every org they belong to. Works before the user has any org.
Request (GetMeRequest):
No fields.
Answer (GetMeResponse):
| Field | Type | |
|---|---|---|
user |
User |
|
active |
Membership |
The org this session acts in; unset when the user has no org yet. |
memberships |
list of Membership |
|
preferences |
Preferences |
How Stagd looks and behaves for them. |
canCreateOrg |
bool | Whether CreateOrg would let them make an org now. A server may run one org, or let each person create only one of their own. |
AccountService
AccountService is the signed-in person’s own account: their profile, how Stagd looks for them, and where they’re signed in. It follows them across orgs, and anyone signed in may use it, viewers too.
AccountService.GetAccount
POST /stagd.api.v1.AccountService/GetAccount.
GetAccount returns the caller’s profile, the emails they may use, how they sign in, and their preferences.
Request (GetAccountRequest):
No fields.
Answer (GetAccountResponse):
| Field | Type | |
|---|---|---|
account |
Account |
AccountService.UpdateProfile
POST /stagd.api.v1.AccountService/UpdateProfile.
UpdateProfile changes the caller’s display name and email. The email must be one of the account’s verified emails.
Request (UpdateProfileRequest):
| Field | Type | |
|---|---|---|
name |
string | Required, at most 100 characters. |
email |
string | Required. |
Answer (UpdateProfileResponse):
| Field | Type | |
|---|---|---|
account |
Account |
AccountService.UpdatePreferences
POST /stagd.api.v1.AccountService/UpdatePreferences.
UpdatePreferences replaces the caller’s preferences.
Request (UpdatePreferencesRequest):
| Field | Type | |
|---|---|---|
preferences |
Preferences |
Required. |
Answer (UpdatePreferencesResponse):
| Field | Type | |
|---|---|---|
preferences |
Preferences |
AccountService.ListSessions
POST /stagd.api.v1.AccountService/ListSessions.
ListSessions lists where the caller is signed in: browsers and the CLI.
Request (ListSessionsRequest):
No fields.
Answer (ListSessionsResponse):
| Field | Type | |
|---|---|---|
sessions |
list of Session |
Most recently used first. |
AccountService.RevokeSession
POST /stagd.api.v1.AccountService/RevokeSession.
RevokeSession signs one of the caller’s sessions out at once.
Request (RevokeSessionRequest):
| Field | Type | |
|---|---|---|
id |
string | Required. |
Answer (RevokeSessionResponse):
No fields.
AccountService.RevokeOtherSessions
POST /stagd.api.v1.AccountService/RevokeOtherSessions.
RevokeOtherSessions signs out every session of the caller’s but this one.
Request (RevokeOtherSessionsRequest):
No fields.
Answer (RevokeOtherSessionsResponse):
| Field | Type | |
|---|---|---|
revoked |
int32 |
OrgService
OrgService creates orgs and moves between them. Every other service acts in the session’s active org.
OrgService.CreateOrg
POST /stagd.api.v1.OrgService/CreateOrg.
CreateOrg creates an org with the caller as its owner, an admin, and makes it the session’s active org. Refused with FAILED_PRECONDITION when the server runs one org that exists already, or lets each person create only one and the caller has.
Request (CreateOrgRequest):
| Field | Type | |
|---|---|---|
name |
string | Required, at most 64 characters. |
slug |
string | Required, 2 to 39 characters, matches ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$. Lower-case letters, digits and dashes, e.g. “acme”. Must be free. |
Answer (CreateOrgResponse):
| Field | Type | |
|---|---|---|
membership |
Membership |
OrgService.ListOrgs
POST /stagd.api.v1.OrgService/ListOrgs.
ListOrgs lists the orgs the caller belongs to.
Request (ListOrgsRequest):
No fields.
Answer (ListOrgsResponse):
| Field | Type | |
|---|---|---|
activeOrgId |
string | The session’s active org; unset when the caller has none. |
memberships |
list of Membership |
OrgService.SwitchOrg
POST /stagd.api.v1.OrgService/SwitchOrg.
SwitchOrg makes another of the caller’s orgs the active one for this session.
Request (SwitchOrgRequest):
| Field | Type | |
|---|---|---|
slug |
string | Required. A slug of an org the caller belongs to. |
Answer (SwitchOrgResponse):
| Field | Type | |
|---|---|---|
active |
Membership |
OrgService.ListMembers
POST /stagd.api.v1.OrgService/ListMembers.
ListMembers lists the people in the active org.
Request (ListMembersRequest):
No fields.
Answer (ListMembersResponse):
| Field | Type | |
|---|---|---|
members |
list of Member |
OrgService.UpdateMemberRole
POST /stagd.api.v1.OrgService/UpdateMemberRole.
UpdateMemberRole changes someone’s role. The last admin can’t be demoted: make someone else an admin first. Nor can the owner: they hand the org on first (TransferOwnership).
Request (UpdateMemberRoleRequest):
| Field | Type | |
|---|---|---|
userId |
string | Required. |
role |
Role |
Required. |
Answer (UpdateMemberRoleResponse):
| Field | Type | |
|---|---|---|
member |
Member |
OrgService.RemoveMember
POST /stagd.api.v1.OrgService/RemoveMember.
RemoveMember takes someone out of the active org and ends their sessions in it. The last admin can’t be removed, nor the owner.
Request (RemoveMemberRequest):
| Field | Type | |
|---|---|---|
userId |
string | Required. |
Answer (RemoveMemberResponse):
No fields.
OrgService.TransferOwnership
POST /stagd.api.v1.OrgService/TransferOwnership.
TransferOwnership hands the org to another of its admins, who becomes its owner; the caller, its owner until then, stays an admin. Owner only.
Request (TransferOwnershipRequest):
| Field | Type | |
|---|---|---|
userId |
string | Required. An admin of the org, who becomes its owner. |
Answer (TransferOwnershipResponse):
No fields.
OrgService.DeleteOrg
POST /stagd.api.v1.OrgService/DeleteOrg.
DeleteOrg deletes the active org and everything Stagd keeps for it. The owner only, with the org’s slug typed as confirmation. The org is gone for its members at once, its previews are stopped and its members told by email. 30 days later its connections, repositories, secrets, seeds and activity are deleted, and Stagd’s GitHub App is uninstalled from its GitHub accounts; until then Stagd’s support can restore it. Backups keep it until they age out (90 days).
Request (DeleteOrgRequest):
| Field | Type | |
|---|---|---|
slug |
string | Required. The active org’s slug, typed again: it must match. |
reason |
LeaveReason |
|
reasonText |
string | At most 2000 characters. In the person’s own words; kept by Stagd without any of the org’s data. |
Answer (DeleteOrgResponse):
| Field | Type | |
|---|---|---|
compute |
list of string | Compute connections whose relay or access is still installed on the customer’s side, which Stagd can’t remove itself: by name, for the person to uninstall (stagd compute uninstall, or deleting the manifest). |
OrgService.UpdateOrg
POST /stagd.api.v1.OrgService/UpdateOrg.
UpdateOrg changes the active org’s name, admins only. Its slug stays: it’s in links and the CLI’s commands.
Request (UpdateOrgRequest):
| Field | Type | |
|---|---|---|
name |
string | Required, at most 64 characters. The org’s new name, e.g. “Acme Inc”; trimmed. |
Answer (UpdateOrgResponse):
| Field | Type | |
|---|---|---|
membership |
Membership |
The caller’s membership in the org, with its new name. |
OrgService.GetOnboarding
POST /stagd.api.v1.OrgService/GetOnboarding.
GetOnboarding is the active org’s way to its first live preview, worked out from what Stagd knows: the dashboard’s Home, stagd setup and the MCP server’s onboarding_status all read it, so they can’t disagree.
Request (GetOnboardingRequest):
No fields.
Answer (GetOnboardingResponse):
| Field | Type | |
|---|---|---|
onboarding |
Onboarding |
OrgService.DismissOnboarding
POST /stagd.api.v1.OrgService/DismissOnboarding.
DismissOnboarding hides the steps for everyone in the org. Admins only.
Request (DismissOnboardingRequest):
No fields.
Answer (DismissOnboardingResponse):
| Field | Type | |
|---|---|---|
onboarding |
Onboarding |
InviteService
InviteService brings people into the active org: invites by email or by code-host username, and one invite link. Accepting happens in the browser, at /join/, or on its own when someone signs in with an invited email or username.
InviteService.CreateInvites
POST /stagd.api.v1.InviteService/CreateInvites.
CreateInvites invites people with a role. Emails get a message with a link; usernames join when they next sign in with that account.
Request (CreateInvitesRequest):
| Field | Type | |
|---|---|---|
invitees |
list of string | 1 to 50 items. Emails, or code-host usernames (GitHub’s, with or without @). |
role |
Role |
Required. |
Answer (CreateInvitesResponse):
| Field | Type | |
|---|---|---|
invites |
list of Invite |
|
problems |
list of InviteProblem |
Invitees that weren’t invited, and why: already a member, not an email or a username. |
InviteService.ListInvites
POST /stagd.api.v1.InviteService/ListInvites.
ListInvites lists the invites not yet accepted, revoked or expired.
Request (ListInvitesRequest):
No fields.
Answer (ListInvitesResponse):
| Field | Type | |
|---|---|---|
invites |
list of Invite |
InviteService.ResendInvite
POST /stagd.api.v1.InviteService/ResendInvite.
ResendInvite sends the invite again with a new link and a new expiry.
Request (ResendInviteRequest):
| Field | Type | |
|---|---|---|
id |
string | Required. |
Answer (ResendInviteResponse):
| Field | Type | |
|---|---|---|
invite |
Invite |
InviteService.RevokeInvite
POST /stagd.api.v1.InviteService/RevokeInvite.
RevokeInvite cancels an invite; its link stops working.
Request (RevokeInviteRequest):
| Field | Type | |
|---|---|---|
id |
string | Required. |
Answer (RevokeInviteResponse):
No fields.
InviteService.GetInviteLink
POST /stagd.api.v1.InviteService/GetInviteLink.
GetInviteLink returns the org’s invite link; none while it’s off (the default) or expired. The link is only shown to admins.
Request (GetInviteLinkRequest):
No fields.
Answer (GetInviteLinkResponse):
| Field | Type | |
|---|---|---|
link |
InviteLink |
Unset while the link is off. |
InviteService.ResetInviteLink
POST /stagd.api.v1.InviteService/ResetInviteLink.
ResetInviteLink turns the invite link on, or replaces it, optionally with another role; an old one stops working.
Request (ResetInviteLinkRequest):
| Field | Type | |
|---|---|---|
role |
Role |
The role people join with; the current one when unset. |
Answer (ResetInviteLinkResponse):
| Field | Type | |
|---|---|---|
link |
InviteLink |
InviteService.DisableInviteLink
POST /stagd.api.v1.InviteService/DisableInviteLink.
DisableInviteLink turns the invite link off; it stops working.
Request (DisableInviteLinkRequest):
No fields.
Answer (DisableInviteLinkResponse):
No fields.
ScmService
ScmService connects code hosts to the active org and lists the repositories they give Stagd access to.
Connecting works the same way from the dashboard and the CLI:
- StartConnect returns a link to the code host (for GitHub, the Stagd
GitHub App’s install page) and a
statetied to this org. - The person opens the link and picks repositories. The code host sends
them back to Stagd, which checks
stateand links the installation to the org. - The client calls GetConnectStatus with
stateuntil it is CONNECTED.
ScmService.StartConnect
POST /stagd.api.v1.ScmService/StartConnect.
StartConnect begins connecting a code host account to the active org.
Request (StartConnectRequest):
| Field | Type | |
|---|---|---|
provider |
ScmProvider |
Only SCM_PROVIDER_GITHUB. |
Answer (StartConnectResponse):
| Field | Type | |
|---|---|---|
url |
string | Where to send the person: the code host’s install or consent page. |
state |
string | Opaque; pass to GetConnectStatus. |
expireTime |
timestamp |
ScmService.GetConnectStatus
POST /stagd.api.v1.ScmService/GetConnectStatus.
GetConnectStatus reports how a connect started by StartConnect is going.
Request (GetConnectStatusRequest):
| Field | Type | |
|---|---|---|
state |
string | Required. |
Answer (GetConnectStatusResponse):
| Field | Type | |
|---|---|---|
status |
ConnectStatus |
|
connection |
Connection |
Set when CONNECTED. |
error |
string | Set when FAILED, in words a person can act on. |
ScmService.ListConnections
POST /stagd.api.v1.ScmService/ListConnections.
ListConnections lists the code host accounts connected to the active org.
Request (ListConnectionsRequest):
No fields.
Answer (ListConnectionsResponse):
| Field | Type | |
|---|---|---|
connections |
list of Connection |
ScmService.DeleteConnection
POST /stagd.api.v1.ScmService/DeleteConnection.
DeleteConnection disconnects a code host account. Its repositories stop getting previews; running previews are torn down.
Request (DeleteConnectionRequest):
| Field | Type | |
|---|---|---|
id |
string | Required. |
Answer (DeleteConnectionResponse):
No fields.
ScmService.ListRepositories
POST /stagd.api.v1.ScmService/ListRepositories.
ListRepositories lists the repositories the active org can preview.
Request (ListRepositoriesRequest):
| Field | Type | |
|---|---|---|
connectionId |
string | Only this connection’s repositories; all of them when empty. |
Answer (ListRepositoriesResponse):
| Field | Type | |
|---|---|---|
repositories |
list of Repository |
ScmService.SetPreviewsEnabled
POST /stagd.api.v1.ScmService/SetPreviewsEnabled.
SetPreviewsEnabled turns previews on or off for a repository. Turning them off tears down its running previews.
Request (SetPreviewsEnabledRequest):
| Field | Type | |
|---|---|---|
repository |
string | Required. A repository id or “owner/name”. |
enabled |
bool |
Answer (SetPreviewsEnabledResponse):
| Field | Type | |
|---|---|---|
repository |
Repository |
|
destroyed |
int32 | Previews torn down because previews were turned off. |
ScmService.CheckRepository
POST /stagd.api.v1.ScmService/CheckRepository.
CheckRepository looks at how a repository’s app is described on its default branch (its setup), unless it looked in the last few minutes. Only for repositories with previews on: Stagd never reads the others.
Request (CheckRepositoryRequest):
| Field | Type | |
|---|---|---|
repository |
string | Required. A repository id or “owner/name”. |
force |
bool | Look again even if it looked lately, e.g. right after a push. |
Answer (CheckRepositoryResponse):
| Field | Type | |
|---|---|---|
repository |
Repository |
ScmService.SetRepositoryHidden
POST /stagd.api.v1.ScmService/SetRepositoryHidden.
SetRepositoryHidden hides a repository from the org’s lists, or shows it again. Its previews are left as they are.
Request (SetRepositoryHiddenRequest):
| Field | Type | |
|---|---|---|
repository |
string | Required. A repository id or “owner/name”. |
hidden |
bool |
Answer (SetRepositoryHiddenResponse):
| Field | Type | |
|---|---|---|
repository |
Repository |
ComputeService
ComputeService connects the compute that previews run on to the active org. Previews run on the customer’s own compute; Stagd only orchestrates.
Compute is pluggable: every provider (Namespace first, then Fly.io, Azure Container Apps, Kubernetes, Unikraft Cloud, and later Stagd-managed compute) sits behind the same interface. ListProviders describes each provider’s credential and setting fields, so clients build their connect forms from it instead of knowing providers themselves.
ComputeService.ListProviders
POST /stagd.api.v1.ComputeService/ListProviders.
ListProviders lists the compute providers this Stagd server supports.
Request (ListProvidersRequest):
No fields.
Answer (ListProvidersResponse):
| Field | Type | |
|---|---|---|
providers |
list of ProviderInfo |
ComputeService.CreateComputeConnection
POST /stagd.api.v1.ComputeService/CreateComputeConnection.
CreateConnection checks the credentials with the provider and, if they work, saves them (encrypted) as a connection of the active org.
Request (CreateComputeConnectionRequest):
| Field | Type | |
|---|---|---|
provider |
ComputeProvider |
Required. |
name |
string | Required, at most 64 characters, matches ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$. |
values |
map of string to string | Every field the provider lists, by key: secret and non-secret alike. |
Answer (CreateComputeConnectionResponse):
| Field | Type | |
|---|---|---|
connection |
ComputeConnection |
|
relayToken |
string | For a connection through stagd relay: the token the relay connects with. Only ever shown here; Stagd keeps a hash. |
relayInstallUrl |
string | Deprecated. Never set: a Kubernetes cluster’s install is CreateInstallManifest’s manifest, piped to kubectl, not a link. |
relayInstallExpireTime |
timestamp | Deprecated. |
tunnelToken |
string | For a Docker host, when Stagd reaches previews through a Cloudflare Tunnel of the connection’s own: what cloudflared runs it with, next to the relay (stagd compute connect docker –run). Only ever shown here. |
ComputeService.ListComputeConnections
POST /stagd.api.v1.ComputeService/ListComputeConnections.
Request (ListComputeConnectionsRequest):
No fields.
Answer (ListComputeConnectionsResponse):
| Field | Type | |
|---|---|---|
connections |
list of ComputeConnection |
ComputeService.TestComputeConnection
POST /stagd.api.v1.ComputeService/TestComputeConnection.
TestConnection checks a saved connection’s credentials again.
Request (TestComputeConnectionRequest):
| Field | Type | |
|---|---|---|
id |
string | Required. |
Answer (TestComputeConnectionResponse):
| Field | Type | |
|---|---|---|
connection |
ComputeConnection |
ComputeService.UpdateComputeConnection
POST /stagd.api.v1.ComputeService/UpdateComputeConnection.
UpdateConnection changes a connection’s fields, e.g. a new token, and checks the result with the provider before saving it. A secret not given stays as it was.
Request (UpdateComputeConnectionRequest):
| Field | Type | |
|---|---|---|
id |
string | Required. |
values |
map of string to string | Only the fields to change, by key. |
Answer (UpdateComputeConnectionResponse):
| Field | Type | |
|---|---|---|
connection |
ComputeConnection |
ComputeService.SetDefaultComputeConnection
POST /stagd.api.v1.ComputeService/SetDefaultComputeConnection.
SetDefaultConnection makes a connection the one new previews run on.
Request (SetDefaultComputeConnectionRequest):
| Field | Type | |
|---|---|---|
id |
string | Required. |
Answer (SetDefaultComputeConnectionResponse):
| Field | Type | |
|---|---|---|
connection |
ComputeConnection |
ComputeService.DeleteComputeConnection
POST /stagd.api.v1.ComputeService/DeleteComputeConnection.
DeleteConnection forgets a connection and its credentials.
Request (DeleteComputeConnectionRequest):
| Field | Type | |
|---|---|---|
id |
string | Required. |
Answer (DeleteComputeConnectionResponse):
No fields.
ComputeService.CreateRelayInstall
POST /stagd.api.v1.ComputeService/CreateRelayInstall.
CreateRelayInstall gives a relay connection a new relay token: the old one stops working, and a relay using it is cut off. For a Docker host’s relay (and cloudflared, with its tunnel’s token); Kubernetes uses CreateInstallManifest.
Request (CreateRelayInstallRequest):
| Field | Type | |
|---|---|---|
id |
string | Required. |
Answer (CreateRelayInstallResponse):
| Field | Type | |
|---|---|---|
relayToken |
string | The new token the relay connects with. Only ever shown here. |
relayInstallUrl |
string | Deprecated. Never set: Kubernetes uses CreateInstallManifest. |
relayInstallExpireTime |
timestamp | Deprecated. |
tunnelToken |
string | When Stagd reaches the Docker host’s previews through a Cloudflare Tunnel of the connection’s own: what cloudflared runs it with, next to the relay (stagd compute install –run). Only ever shown here. |
ComputeService.CreateInstallManifest
POST /stagd.api.v1.ComputeService/CreateInstallManifest.
CreateInstallManifest is everything a Kubernetes connection’s cluster
needs, as one manifest for kubectl apply -f -: Stagd’s access, the
relay, and what the connection chooses (the builder, the Cloudflare
Tunnel with its token). While its relay is connected, an install updates
it and keeps its token: the manifest leaves out the relay’s secret, so
the one in the cluster stays. Otherwise, or with new_token, the relay
gets a new token (the old one stops working) and the manifest has it.
The tokens are in the manifest and nowhere else.
Request (CreateInstallManifestRequest):
| Field | Type | |
|---|---|---|
id |
string | Required. |
newToken |
bool | A new relay token even while the relay is connected: the relay running now is cut off until the manifest is applied. |
Answer (CreateInstallManifestResponse):
| Field | Type | |
|---|---|---|
manifest |
string | Multi-document YAML, for kubectl apply -f -. It can hold the new relay token and the tunnel’s: print it, pipe it, don’t keep it around. |
newToken |
bool | Whether the relay got a new token, in the manifest; when not, the relay keeps the one in the cluster’s stagd-relay secret. |
ComputeService.GetComputeConnectionDetails
POST /stagd.api.v1.ComputeService/GetComputeConnectionDetails.
GetComputeConnectionDetails is everything Stagd can tell about one connection, asked for now: its relay and tunnel as they are, what the compute says about itself, and what’s been done to it. Slower than ListComputeConnections, which answers from what Stagd keeps.
Request (GetComputeConnectionDetailsRequest):
| Field | Type | |
|---|---|---|
id |
string | Required. |
Answer (GetComputeConnectionDetailsResponse):
| Field | Type | |
|---|---|---|
connection |
ComputeConnection |
With its relay and tunnel asked for now, so with their details. |
facts |
list of ComputeFact |
What the compute says about itself, e.g. a Docker host’s CPUs, memory and engine, or a cluster’s version and nodes; empty when it can’t be asked. |
factsProblem |
string | Why there are no facts, or not all of them, e.g. “the relay isn’t connected”; empty when there’s nothing missing. |
activity |
list of Activity |
What’s been done to the connection, newest first: made, changed, new relay tokens. At most 20. |
PreviewService
PreviewService starts, watches and tears down preview environments.
A webhook from a code host and a call to CreatePreview take the same path: a pull request opening on GitHub is just one more way to start a preview. That is what lets teams without a connected code host start previews from CI or the CLI.
PreviewService.CreatePreview
POST /stagd.api.v1.PreviewService/CreatePreview.
CreatePreview starts a preview, or updates the existing one for the same change request or branch to the new commit.
Request (CreatePreviewRequest):
| Field | Type | |
|---|---|---|
repository |
string | Required. A repository id, or its “owner/name”. |
source |
PreviewSource |
Required. |
Answer (CreatePreviewResponse):
| Field | Type | |
|---|---|---|
preview |
Preview |
PreviewService.ListSources
POST /stagd.api.v1.PreviewService/ListSources.
ListSources lists what a repository’s previews can be of, from its code host: its open pull requests (not from forks: those never get previews), newest first, and its branches. Only for repositories with previews on: Stagd never reads the others.
Request (ListSourcesRequest):
| Field | Type | |
|---|---|---|
repository |
string | Required. A repository id or “owner/name”. |
Answer (ListSourcesResponse):
| Field | Type | |
|---|---|---|
changes |
list of ChangeRequest |
Open pull requests, most recently updated first; at most 100. |
branches |
list of string | Branch names, the default branch first; at most 100. |
PreviewService.GetPreview
POST /stagd.api.v1.PreviewService/GetPreview.
Request (GetPreviewRequest):
| Field | Type | |
|---|---|---|
id |
string | Required. |
Answer (GetPreviewResponse):
| Field | Type | |
|---|---|---|
preview |
Preview |
PreviewService.ListPreviews
POST /stagd.api.v1.PreviewService/ListPreviews.
Request (ListPreviewsRequest):
| Field | Type | |
|---|---|---|
repository |
string | A repository id or “owner/name”; all repositories when empty. |
statuses |
list of PreviewStatus |
Only previews in these states; all but DESTROYED when empty. |
pageSize |
int32 | 0 to 200. |
pageToken |
string |
Answer (ListPreviewsResponse):
| Field | Type | |
|---|---|---|
previews |
list of Preview |
|
nextPageToken |
string |
PreviewService.WatchPreview
POST /stagd.api.v1.PreviewService/WatchPreview. Streams its answers.
WatchPreview streams the preview’s state until it is live, failed or destroyed, starting with its current state.
Request (WatchPreviewRequest):
| Field | Type | |
|---|---|---|
id |
string | Required. |
Answer (WatchPreviewResponse):
| Field | Type | |
|---|---|---|
preview |
Preview |
|
message |
string | A log line or step that explains the change, e.g. “api: building (2/3)”. |
component |
string | The component the message is about; empty when it’s about the whole preview. |
PreviewService.ListPreviewEvents
POST /stagd.api.v1.PreviewService/ListPreviewEvents.
ListPreviewEvents returns what happened to a preview: all of it, oldest first; or, with a page_size, a page at a time, newest first.
Request (ListPreviewEventsRequest):
| Field | Type | |
|---|---|---|
id |
string | Required. |
pageSize |
int32 | 0 to 200. With a page size, events come newest first, a page at a time; without one, all of them, oldest first. |
pageToken |
string | The next_page_token of the page before: the events older than it. |
Answer (ListPreviewEventsResponse):
| Field | Type | |
|---|---|---|
events |
list of PreviewEvent |
|
nextPageToken |
string | Set when there are older events; empty on the last page and without a page size. |
PreviewService.WakePreview
POST /stagd.api.v1.PreviewService/WakePreview.
WakePreview starts a sleeping preview again.
Request (WakePreviewRequest):
| Field | Type | |
|---|---|---|
id |
string | Required. |
Answer (WakePreviewResponse):
| Field | Type | |
|---|---|---|
preview |
Preview |
PreviewService.DestroyPreview
POST /stagd.api.v1.PreviewService/DestroyPreview.
DestroyPreview tears a preview down now.
Request (DestroyPreviewRequest):
| Field | Type | |
|---|---|---|
id |
string | Required. |
Answer (DestroyPreviewResponse):
| Field | Type | |
|---|---|---|
preview |
Preview |
PreviewService.GetPreviewFailure
POST /stagd.api.v1.PreviewService/GetPreviewFailure.
GetPreviewFailure answers what was collected about a failed preview’s current failure: its explanation, and the masked error and log lines it was explained from, for a coding agent to read with its own model.
Request (GetPreviewFailureRequest):
| Field | Type | |
|---|---|---|
id |
string | Required. The failed preview’s id. |
Answer (GetPreviewFailureResponse):
| Field | Type | |
|---|---|---|
failure |
PreviewFailure |
PreviewService.ListTesters
POST /stagd.api.v1.PreviewService/ListTesters.
ListTesters lists the users stagd.yaml names for signing in to the preview (testers), and how each signs in.
Request (ListTestersRequest):
| Field | Type | |
|---|---|---|
id |
string | Required. |
Answer (ListTestersResponse):
| Field | Type | |
|---|---|---|
testers |
list of PreviewTester |
In stagd.yaml’s order, as at the preview’s last deploy. |
PreviewService.CheckTesters
POST /stagd.api.v1.PreviewService/CheckTesters.
CheckTesters signs in to the preview as each tester, as stagd.yaml says, and says how each step went.
Request (CheckTestersRequest):
| Field | Type | |
|---|---|---|
id |
string | Required. |
names |
list of string | Testers by name; every one when empty. |
Answer (CheckTestersResponse):
| Field | Type | |
|---|---|---|
checks |
list of TesterCheck |
PreviewService.GetPreviewPolicy
POST /stagd.api.v1.PreviewService/GetPreviewPolicy.
GetPreviewPolicy returns who may open previews and how their URLs look: the org’s default, or a repository’s (its own, or the default it inherits).
Request (GetPreviewPolicyRequest):
| Field | Type | |
|---|---|---|
repository |
string | A repository id or “owner/name”; empty for the org’s default. |
Answer (GetPreviewPolicyResponse):
| Field | Type | |
|---|---|---|
policy |
PreviewPolicy |
|
inherited |
bool | For a repository: true when it has no override and follows the org’s default. |
start |
PreviewStartInEffect |
When pull requests get previews, with where that comes from. |
PreviewService.UpdatePreviewPolicy
POST /stagd.api.v1.PreviewService/UpdatePreviewPolicy.
UpdatePreviewPolicy sets the org’s default, or a repository’s override. Access applies to existing previews on their next deploy; URL style only to new previews, so links already shared keep working.
Request (UpdatePreviewPolicyRequest):
| Field | Type | |
|---|---|---|
policy |
PreviewPolicy |
Required. |
reset |
bool | With a repository: drop its override, so it follows the org’s default again. Its start (when previews start) is kept: set start to unspecified for that. |
startOnly |
bool | Only the start and its label: the rest of the policy stays as it is, and a repository without an override keeps following the org’s for the rest. |
Answer (UpdatePreviewPolicyResponse):
| Field | Type | |
|---|---|---|
policy |
PreviewPolicy |
|
inherited |
bool | |
start |
PreviewStartInEffect |
PreviewService.ValidateApp
POST /stagd.api.v1.PreviewService/ValidateApp.
ValidateApp checks a repository’s stagd.yaml and compose file exactly as
previews read them, without starting anything (stagd validate). The
client sends the files it has; when stagd.yaml points at another file,
the response asks for it in requested, and the client calls again.
Request (ValidateAppRequest):
| Field | Type | |
|---|---|---|
files |
map of string to string | At most 16 entries. Root-relative path → contents, e.g. “stagd.yaml”, “deploy/compose.yaml”. |
absent |
list of string | At most 32 items. Paths the client looked for and didn’t find. |
Answer (ValidateAppResponse):
| Field | Type | |
|---|---|---|
requested |
list of string | Files the server needs to answer and the client didn’t send or rule out; send them (or list them as absent) and call again. |
files |
list of string | The files the answer comes from, e.g. [“stagd.yaml”, “deploy/compose.yaml”]. |
problems |
list of string | Empty when previews would start; each says what to fix. |
notes |
list of string | What a preview leaves out on purpose, e.g. bind mounts. |
components |
list of AppComponent |
|
ingresses |
list of PreviewIngress |
Ingress names, components and ports; URLs come with a real preview. |
config |
stagd.config.v1.Config |
stagd.yaml as previews read it, defaults filled in: unset when it has problems, empty when there’s no stagd.yaml. |
starter |
string | A stagd.yaml to start from, made from the compose file, as a repository’s page offers it: set when there’s no stagd.yaml. stagd init writes it. |
PreviewService.ListMail
POST /stagd.api.v1.PreviewService/ListMail.
ListMail lists the mail a preview captured, newest first. Only for
previews with mail capture on (stagd.yaml services: { mail: {} }) and
running: a sleeping preview keeps its mail, but has to wake to show it.
Request (ListMailRequest):
| Field | Type | |
|---|---|---|
previewId |
string | Required. |
limit |
int32 | 0 to 500. At most this many, newest first; 0 means 50. |
after |
string | Only messages that arrived after this cursor, from an earlier ListMail or WaitForMail; empty means all. |
filter |
MailFilter |
Answer (ListMailResponse):
| Field | Type | |
|---|---|---|
messages |
list of MailSummary |
|
total |
int32 | How many the preview captured in all; messages may stop at limit. |
cursor |
string | Where the inbox stands now, matching the filter or not: pass it as after to get only what arrives from here on. |
PreviewService.GetMail
POST /stagd.api.v1.PreviewService/GetMail.
GetMail returns one captured message with its text, HTML and headers.
Request (GetMailRequest):
| Field | Type | |
|---|---|---|
previewId |
string | Required. |
id |
string | Required. |
Answer (GetMailResponse):
| Field | Type | |
|---|---|---|
message |
MailMessage |
PreviewService.ClearMail
POST /stagd.api.v1.PreviewService/ClearMail.
ClearMail deletes everything a preview captured.
Request (ClearMailRequest):
| Field | Type | |
|---|---|---|
previewId |
string | Required. |
Answer (ClearMailResponse):
No fields.
PreviewService.DeleteMail
POST /stagd.api.v1.PreviewService/DeleteMail.
DeleteMail deletes one message a preview captured.
Request (DeleteMailRequest):
| Field | Type | |
|---|---|---|
previewId |
string | Required. |
id |
string | Required. The message’s id, from ListMail. |
Answer (DeleteMailResponse):
No fields.
PreviewService.WaitForMail
POST /stagd.api.v1.PreviewService/WaitForMail.
WaitForMail answers as soon as a message matching the filter arrives after the cursor, or with none when the timeout passes: what a test waits on after the step that should send it, and how it checks that a step sent nothing.
Request (WaitForMailRequest):
| Field | Type | |
|---|---|---|
previewId |
string | Required. |
after |
string | As in ListMail: take it before the step that should send the message. Empty means any message captured so far counts too. |
filter |
MailFilter |
|
timeout |
duration | 0s to 1m. How long to wait: up to a minute; unset means 30 seconds. |
limit |
int32 | 0 to 500. At most this many, newest first; 0 means 50. |
Answer (WaitForMailResponse):
| Field | Type | |
|---|---|---|
messages |
list of MailSummary |
The matching messages after the cursor, newest first; none when the timeout passed without one. |
cursor |
string |
PreviewService.ListTexts
POST /stagd.api.v1.PreviewService/ListTexts.
ListTexts lists the text messages (SMS) a preview’s app sent, newest
first, caught by Stagd’s mock of the vendors’ APIs. Only for previews
with text capture on (stagd.yaml services: { sms: {} }) and running.
Request (ListTextsRequest):
| Field | Type | |
|---|---|---|
previewId |
string | Required. |
limit |
int32 | 0 to 500. At most this many, newest first; 0 means 50. |
after |
string | Only those that arrived after this cursor, from an earlier ListTexts or WaitForTexts; empty means all. |
filter |
TextFilter |
Answer (ListTextsResponse):
| Field | Type | |
|---|---|---|
texts |
list of TextMessage |
|
cursor |
string | Where the texts stand now, matching the filter or not: pass it as after to get only what arrives from here on. |
PreviewService.WaitForTexts
POST /stagd.api.v1.PreviewService/WaitForTexts.
WaitForTexts is WaitForMail for text messages.
Request (WaitForTextsRequest):
| Field | Type | |
|---|---|---|
previewId |
string | Required. |
after |
string | As in ListTexts: take it before the step that should send the text. Empty means any captured so far counts too. |
filter |
TextFilter |
|
timeout |
duration | 0s to 1m. How long to wait: up to a minute; unset means 30 seconds. |
limit |
int32 | 0 to 500. At most this many, newest first; 0 means 50. |
Answer (WaitForTextsResponse):
| Field | Type | |
|---|---|---|
texts |
list of TextMessage |
The matching texts after the cursor, newest first; none when the timeout passed without one. |
cursor |
string |
PreviewService.GetServiceUsage
POST /stagd.api.v1.PreviewService/GetServiceUsage.
GetServiceUsage returns CPU and memory per service of a preview over a window up to 24 hours. Stagd samples them every 30 seconds while a preview is live, on compute that can say: nothing while it sleeps, so the series have gaps.
Request (GetServiceUsageRequest):
| Field | Type | |
|---|---|---|
previewId |
string | Required. |
window |
duration | 1m to 24h. How far back: up to 24 hours. Points are averaged into about 120 buckets. |
Answer (GetServiceUsageResponse):
| Field | Type | |
|---|---|---|
services |
list of ServiceUsage |
By service name; services never sampled aren’t here. |
PreviewService.ListLogs
POST /stagd.api.v1.PreviewService/ListLogs.
ListLogs returns the latest lines a preview’s services wrote, read from its compute when asked: Stagd keeps no copy. Each line is read for its level and message, and JSON and logfmt lines for their fields. The preview’s secrets are hidden. A sleeping preview has to wake first; a torn-down one’s logs are gone.
Request (ListLogsRequest):
| Field | Type | |
|---|---|---|
previewId |
string | Required. |
services |
list of string | Only these services; all when empty. |
since |
timestamp | Lines at or after this time; as far back as kept when unset. To follow a preview’s logs, ask again with the last line’s time. |
limit |
int32 | 0 to 5000. At most this many of the latest lines; 500 when unset. |
Answer (ListLogsResponse):
| Field | Type | |
|---|---|---|
lines |
list of LogLine |
Oldest first. |
truncated |
bool | There were more lines than the limit; older ones were left out. |
PreviewService.ListBuildLogs
POST /stagd.api.v1.PreviewService/ListBuildLogs.
ListBuildLogs returns what each service’s build printed, for those its compute builds, read from the compute when asked: Stagd keeps no copy. There while it builds, to follow by asking again, and after, until the preview’s instance goes; the preview’s secrets are hidden.
Request (ListBuildLogsRequest):
| Field | Type | |
|---|---|---|
previewId |
string | Required. |
Answer (ListBuildLogsResponse):
| Field | Type | |
|---|---|---|
builds |
list of BuildLog |
One per service that’s built, in the order they build. |
PreviewService.ListTraces
POST /stagd.api.v1.PreviewService/ListTraces.
ListTraces lists a preview’s traces, newest first, from its own
OpenTelemetry endpoint (stagd.yaml services: { otel: {} }), read when
asked: Stagd keeps no copy. A sleeping preview has to wake first.
Request (ListTracesRequest):
| Field | Type | |
|---|---|---|
previewId |
string | Required. |
service |
string | Only traces with spans from this service; all when empty. |
since |
timestamp | Traces started at or after this time; the last 15 minutes when unset. |
until |
timestamp | Traces started before this time; now when unset. |
errorsOnly |
bool | Only traces where a span failed, or the root answered 5xx. |
minDuration |
duration | Only traces that took at least this long. |
limit |
int32 | 0 to 500. At most this many of the newest; 100 when unset. |
Answer (ListTracesResponse):
| Field | Type | |
|---|---|---|
traces |
list of TraceSummary |
Newest first. |
services |
list of string | The services that sent traces, by name. |
PreviewService.GetTrace
POST /stagd.api.v1.PreviewService/GetTrace.
GetTrace returns one trace’s spans, for a waterfall.
Request (GetTraceRequest):
| Field | Type | |
|---|---|---|
previewId |
string | Required. |
traceId |
string | Matches ^[0-9a-f]{32}$. |
Answer (GetTraceResponse):
| Field | Type | |
|---|---|---|
traceId |
string | |
spans |
list of Span |
Oldest first. |
SecretService
SecretService keeps the secrets previews get as variables: the org’s, and
a repository’s own, which win by name. A preview’s compose file uses them
like any variable (${SESSION_SECRET}, or a bare - SESSION_SECRET).
Values are encrypted at rest. Listing gives names only; an admin reads a
value with RevealSecret, which the activity log records.
SecretService.ListSecrets
POST /stagd.api.v1.SecretService/ListSecrets.
Request (ListSecretsRequest):
| Field | Type | |
|---|---|---|
repository |
string | A repository id or “owner/name”; empty for the org’s own. |
Answer (ListSecretsResponse):
| Field | Type | |
|---|---|---|
secrets |
list of Secret |
SecretService.SetSecrets
POST /stagd.api.v1.SecretService/SetSecrets.
SetSecrets creates or replaces secrets, all or none.
Request (SetSecretsRequest):
| Field | Type | |
|---|---|---|
repository |
string | A repository id or “owner/name”; empty for the org’s own. |
values |
map of string to string | 1 to 100 entries. |
Answer (SetSecretsResponse):
| Field | Type | |
|---|---|---|
secrets |
list of Secret |
|
unmasked |
list of string | Secrets too short to be masked in logs: Stagd can’t redact them from build and start output it shows. |
SecretService.DeleteSecret
POST /stagd.api.v1.SecretService/DeleteSecret.
Request (DeleteSecretRequest):
| Field | Type | |
|---|---|---|
repository |
string | |
name |
string | Required. |
Answer (DeleteSecretResponse):
No fields.
SecretService.RevealSecret
POST /stagd.api.v1.SecretService/RevealSecret.
RevealSecret answers a secret’s value, for admins only. Each reveal is in the activity log, by name.
Request (RevealSecretRequest):
| Field | Type | |
|---|---|---|
repository |
string | A repository id or “owner/name”; empty for the org’s own. |
name |
string | Required. |
Answer (RevealSecretResponse):
| Field | Type | |
|---|---|---|
value |
string |
SeedService
SeedService keeps the org’s seeds: the data a preview’s database starts with, a database dump (pg_dump’s now; MySQL’s and others’ as Stagd runs those databases) in a blob store one of the org’s integrations reaches: Azure Blob Storage, or S3 and the stores that speak it. stagd.yaml names a seed (services: { postgres: { seed: } }); what it is, only the org’s admins say, so a pull request can’t point its preview at other data.
SeedService.ListSeeds
POST /stagd.api.v1.SeedService/ListSeeds.
Request (ListSeedsRequest):
No fields.
Answer (ListSeedsResponse):
| Field | Type | |
|---|---|---|
seeds |
list of Seed |
SeedService.CreateSeed
POST /stagd.api.v1.SeedService/CreateSeed.
CreateSeed saves a seed once its integration finds a file at its path.
Request (CreateSeedRequest):
| Field | Type | |
|---|---|---|
name |
string | Required, at most 64 characters, matches ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$. |
integration |
string | Required. An id or a name. |
path |
string | Required, at most 1024 characters. |
Answer (CreateSeedResponse):
| Field | Type | |
|---|---|---|
seed |
Seed |
SeedService.UpdateSeed
POST /stagd.api.v1.SeedService/UpdateSeed.
UpdateSeed changes where a seed is; the file is looked up again.
Request (UpdateSeedRequest):
| Field | Type | |
|---|---|---|
seed |
string | Required. An id or a name. |
integration |
string | Left empty, it stays as it is. |
path |
string | At most 1024 characters. |
Answer (UpdateSeedResponse):
| Field | Type | |
|---|---|---|
seed |
Seed |
SeedService.DeleteSeed
POST /stagd.api.v1.SeedService/DeleteSeed.
Request (DeleteSeedRequest):
| Field | Type | |
|---|---|---|
seed |
string | Required. |
Answer (DeleteSeedResponse):
No fields.
SeedService.FindSeedFile
POST /stagd.api.v1.SeedService/FindSeedFile.
FindSeedFile says which file a path finds now, without saving anything: for a form, before the seed is saved.
Request (FindSeedFileRequest):
| Field | Type | |
|---|---|---|
integration |
string | Required. |
path |
string | Required, at most 1024 characters. |
Answer (FindSeedFileResponse):
| Field | Type | |
|---|---|---|
file |
SeedFile |
IntegrationService
IntegrationService connects the services an org’s previews use, beside compute and GitHub: Neon for a database branch per preview now; key vaults, secret stores and blob stores for seeding later. Each kind lists its own fields, so clients build their forms from it.
IntegrationService.ListIntegrationKinds
POST /stagd.api.v1.IntegrationService/ListIntegrationKinds.
Request (ListIntegrationKindsRequest):
No fields.
Answer (ListIntegrationKindsResponse):
| Field | Type | |
|---|---|---|
kinds |
list of IntegrationKind |
IntegrationService.CreateIntegration
POST /stagd.api.v1.IntegrationService/CreateIntegration.
CreateIntegration checks the values with the service and saves them, the secret ones encrypted, if they work.
Request (CreateIntegrationRequest):
| Field | Type | |
|---|---|---|
kind |
string | Required. |
name |
string | Required, at most 64 characters, matches ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$. |
values |
map of string to string | Every field the kind lists, by key: secret and not. |
Answer (CreateIntegrationResponse):
| Field | Type | |
|---|---|---|
integration |
Integration |
IntegrationService.ListIntegrations
POST /stagd.api.v1.IntegrationService/ListIntegrations.
Request (ListIntegrationsRequest):
No fields.
Answer (ListIntegrationsResponse):
| Field | Type | |
|---|---|---|
integrations |
list of Integration |
IntegrationService.UpdateIntegration
POST /stagd.api.v1.IntegrationService/UpdateIntegration.
UpdateIntegration changes settings, and secrets when given again.
Request (UpdateIntegrationRequest):
| Field | Type | |
|---|---|---|
integration |
string | Required. An id or a name. |
values |
map of string to string | Only the fields to change; a secret not given stays as it was. |
Answer (UpdateIntegrationResponse):
| Field | Type | |
|---|---|---|
integration |
Integration |
IntegrationService.TestIntegration
POST /stagd.api.v1.IntegrationService/TestIntegration.
Request (TestIntegrationRequest):
| Field | Type | |
|---|---|---|
integration |
string | Required. |
Answer (TestIntegrationResponse):
| Field | Type | |
|---|---|---|
integration |
Integration |
IntegrationService.DeleteIntegration
POST /stagd.api.v1.IntegrationService/DeleteIntegration.
DeleteIntegration forgets it and its credentials; refused while a preview still has something from it, e.g. a database branch.
Request (DeleteIntegrationRequest):
| Field | Type | |
|---|---|---|
integration |
string | Required. |
Answer (DeleteIntegrationResponse):
No fields.
ActivityService
ActivityService is the org’s activity log: who changed what its previews depend on (secrets, compute, integrations, access), and when. It never holds a secret’s value.
ActivityService.ListActivity
POST /stagd.api.v1.ActivityService/ListActivity.
Request (ListActivityRequest):
| Field | Type | |
|---|---|---|
pageSize |
int32 | 0 to 500. At most this many, newest first; 50 when unset. |
pageToken |
string | The next_page_token of the page before, asked with the same filters. |
area |
string | Only this area, empty for all: “secrets”, “seeds”, “compute”, “integrations”, “repositories”, “github”, “members” or “workspace”. |
actor |
string | At most 320 characters. Only what this person did, by email; empty for everyone. |
Answer (ListActivityResponse):
| Field | Type | |
|---|---|---|
activity |
list of Activity |
|
nextPageToken |
string | Empty on the last page. |
EventService
EventService tells the dashboard when something in its org changed, so it refetches what it shows instead of polling. It says what changed, never the data itself: the client reads that through the usual calls, with their permission checks.
EventService.WatchEvents
POST /stagd.api.v1.EventService/WatchEvents. Streams its answers.
WatchEvents streams the active org’s changes until the client goes away. A heartbeat (kind unspecified) comes every 25 seconds, so proxies keep the connection open. Viewers only hear about previews. A client that reconnects may have missed changes: it refetches what it shows.
Request (WatchEventsRequest):
No fields.
Answer (WatchEventsResponse):
| Field | Type | |
|---|---|---|
kind |
ChangeKind |
|
id |
string | The thing’s id, e.g. a preview’s; empty when the kind is enough. |
Types
The messages and enums the requests and answers use.
Account
| Field | Type | |
|---|---|---|
user |
User |
|
emails |
list of string | The verified emails the account may use as its email, the current one among them. |
signInMethods |
list of SignInMethod |
How the person signs in. |
preferences |
Preferences |
Activity
| Field | Type | |
|---|---|---|
id |
string | |
createTime |
timestamp | |
actor |
string | Who, by email; empty for Stagd itself. |
via |
string | How: “web”, “cli”, “stagd”, “relay”, or “github” for what someone did on GitHub (detail “by” holds their login). |
action |
string | What happened, “.”: e.g. “secret.set”, “compute.default_set”. Every one is listed in the platform’s docs/activity.md. |
target |
string | What it happened to, in words. |
detail |
map of string to string |
AppComponent
One component as a preview would run it.
| Field | Type | |
|---|---|---|
name |
string | |
buildContext |
string | Built from this context, or |
image |
string | pulled as this image. |
BuildLog
BuildLog is one service’s build output. Whether it’s building, built or failed is the preview’s component for the service.
| Field | Type | |
|---|---|---|
service |
string | |
text |
string | As printed, its last 512 KB; the preview’s secrets hidden. |
truncated |
bool | There was more before; the start was left out. |
ChangeKind
What kind of thing changed.
| Value | |
|---|---|
CHANGE_KIND_UNSPECIFIED |
A heartbeat: nothing changed. |
CHANGE_KIND_PREVIEW |
A preview: its state, components, events or title. |
CHANGE_KIND_COMPUTE |
A compute connection. |
CHANGE_KIND_CONNECTION |
A code host connection, e.g. the GitHub App installation. |
CHANGE_KIND_REPOSITORY |
A repository: shared, unshared, previews on or off. |
CHANGE_KIND_SECRET |
A secret’s name or where it applies; never its value. |
CHANGE_KIND_MEMBER |
A member or an invite. |
CHANGE_KIND_INTEGRATION |
An integration, e.g. Neon. |
CHANGE_KIND_POLICY |
The preview policy: access, sleep and expiry. |
ChangeRequest
ChangeRequest is a GitHub pull request or a GitLab merge request.
| Field | Type | |
|---|---|---|
number |
int64, as a string | |
title |
string | |
headRef |
string | The branch with the changes. |
headSha |
string | |
baseRef |
string | The branch it merges into. |
author |
string | The author’s login on the code host. |
url |
string |
ComponentPhase
| Value | |
|---|---|
COMPONENT_PHASE_UNSPECIFIED |
|
COMPONENT_PHASE_PENDING |
|
COMPONENT_PHASE_BUILDING |
|
COMPONENT_PHASE_BUILT |
Built, or nothing to build (a prebuilt or unchanged image). |
COMPONENT_PHASE_STARTING |
|
COMPONENT_PHASE_RUNNING |
|
COMPONENT_PHASE_FAILED |
ComputeCapabilities
ComputeCapabilities says what a provider can do. Stagd works around what it can’t: without sleep, a sleeping preview is destroyed and recreated on wake; without volume snapshots, data is seeded on every create.
| Field | Type | |
|---|---|---|
sleep |
bool | Instances can be stopped and resumed. |
volumeSnapshots |
bool | A volume can be snapshotted once and restored into new instances. |
regions |
list of string | Where instances can run, e.g. “eu”, “us”. |
maxLifetime |
duration | The longest an instance can live; unset when there is no limit. |
ComputeConnection
ComputeConnection is one compute account linked to an org.
| Field | Type | |
|---|---|---|
id |
string | |
provider |
ComputeProvider |
|
name |
string | A name chosen by the org, e.g. “namespace-eu”. Unique in the org. |
settings |
map of string to string | The non-secret field values, e.g. {“region”: “eu”}. |
account |
string | What the provider reported about the account when last checked, e.g. the workspace name. |
status |
ComputeConnectionStatus |
|
statusMessage |
string | |
capabilities |
ComputeCapabilities |
|
default |
bool | New previews run on the default connection. |
createdBy |
User |
|
createTime |
timestamp | |
checkTime |
timestamp | |
tunnel |
StagdTunnel |
Set when the connection’s previews are reached through a Cloudflare Tunnel Stagd made for the cluster (Kubernetes, settings “previews”). |
ingress |
StagdIngress |
Deprecated. Never set: Stagd’s own ingress in clusters was replaced by the tunnel. |
relay |
StagdRelay |
For a connection through stagd relay, while its relay is connected: its release, and whether there’s a newer one. |
ComputeConnectionStatus
| Value | |
|---|---|
COMPUTE_CONNECTION_STATUS_UNSPECIFIED |
|
COMPUTE_CONNECTION_STATUS_ACTIVE |
The last check worked. |
COMPUTE_CONNECTION_STATUS_FAILING |
The last check failed; see status_message. |
ComputeFact
ComputeFact is one thing the compute says about itself, e.g. {“CPUs”, “8”}, in the provider’s own terms, to show as it is.
| Field | Type | |
|---|---|---|
label |
string | |
value |
string |
ComputeProvider
| Value | |
|---|---|
COMPUTE_PROVIDER_UNSPECIFIED |
|
COMPUTE_PROVIDER_FAKE |
A stand-in that runs nothing; local development and tests only. |
COMPUTE_PROVIDER_NAMESPACE |
|
COMPUTE_PROVIDER_FLY |
Planned. |
COMPUTE_PROVIDER_AZURE_CONTAINER_APPS |
Planned. |
COMPUTE_PROVIDER_KUBERNETES |
Any cluster, directly or through stagd relay. |
COMPUTE_PROVIDER_UNIKRAFT |
Planned. |
COMPUTE_PROVIDER_DOCKER |
A Docker host, through stagd relay. |
Connection
Connection is one code host account linked to an org: for GitHub, one installation of the Stagd GitHub App on a user or organization.
| Field | Type | |
|---|---|---|
id |
string | |
provider |
ScmProvider |
|
account |
string | The account’s login on the code host, e.g. “acme-inc”. |
externalId |
string | The code host’s id for the link: the GitHub App installation id. |
status |
ConnectionStatus |
|
createdBy |
User |
Who connected it. |
createTime |
timestamp | |
manageUrl |
string | Where to change it on the code host: which repositories it shares, new permissions to accept. For GitHub, the installation’s settings page. |
unapproved |
list of UnapprovedGrant |
What Stagd’s App asks for now that this installation hasn’t approved yet. A code host keeps an installation on what it approved until its owner approves more, at manage_url; until then, what needs these doesn’t work for its repositories. Empty when it has everything, or when Stagd couldn’t ask. |
ConnectionStatus
| Value | |
|---|---|
CONNECTION_STATUS_UNSPECIFIED |
|
CONNECTION_STATUS_ACTIVE |
|
CONNECTION_STATUS_SUSPENDED |
The code host suspended the installation; webhooks stop arriving. |
CONNECTION_STATUS_REMOVED |
Uninstalled on the code host’s side. |
ConnectStatus
| Value | |
|---|---|
CONNECT_STATUS_UNSPECIFIED |
|
CONNECT_STATUS_PENDING |
Waiting for the person to finish on the code host. |
CONNECT_STATUS_CONNECTED |
|
CONNECT_STATUS_FAILED |
|
CONNECT_STATUS_EXPIRED |
Integration
| Field | Type | |
|---|---|---|
id |
string | |
kind |
string | |
name |
string | |
settings |
map of string to string | The non-secret field values. |
account |
string | What the service reported about the account at the last check. |
status |
IntegrationStatus |
|
statusMessage |
string | |
createdBy |
string | Who connected it, by email. |
createTime |
timestamp | |
checkTime |
timestamp | |
expireTime |
timestamp | When its credentials stop working, as the service says, e.g. an Azure SAS token’s expiry; unset when they don’t. |
IntegrationField
| Field | Type | |
|---|---|---|
key |
string | |
label |
string | |
help |
string | |
secret |
bool | Encrypted at rest and never returned. |
required |
bool | |
multiline |
bool | Several lines, e.g. a list. |
checkbox |
bool | A yes or no: its value is “true”, or empty for no. |
shownWith |
string | The key of a checkbox field this one belongs to, or “key=value” for an option of a choice: shown, and asked for, only while that one is ticked or chosen. |
options |
list of IntegrationFieldOption |
A choice of one, e.g. how to sign in: the value is an option’s value, the first option’s when none is given. |
IntegrationFieldOption
| Field | Type | |
|---|---|---|
value |
string | |
label |
string | |
help |
string |
IntegrationKind
| Field | Type | |
|---|---|---|
id |
string | e.g. “neon”. |
name |
string | |
description |
string | |
fields |
list of IntegrationField |
IntegrationStatus
| Value | |
|---|---|
INTEGRATION_STATUS_UNSPECIFIED |
|
INTEGRATION_STATUS_ACTIVE |
|
INTEGRATION_STATUS_FAILING |
Invite
| Field | Type | |
|---|---|---|
id |
string | |
email |
string | One of the two. |
login |
string | |
role |
Role |
|
invitedBy |
User |
|
createdAt |
timestamp | |
expiresAt |
timestamp | |
url |
string | The invite’s own link, only in CreateInvites’ and ResendInvite’s answers: to send by hand when the server sends no email, or for a username. |
emailed |
bool | An email went out with the link. |
InviteLink
| Field | Type | |
|---|---|---|
url |
string | |
role |
Role |
|
expiresAt |
timestamp |
InviteProblem
| Field | Type | |
|---|---|---|
invitee |
string | |
reason |
string |
LeaveReason
Why an org is deleted, to learn from; optional.
| Value | |
|---|---|
LEAVE_REASON_UNSPECIFIED |
|
LEAVE_REASON_TOO_EXPENSIVE |
|
LEAVE_REASON_MISSING_FEATURE |
|
LEAVE_REASON_HARD_TO_SET_UP |
|
LEAVE_REASON_OTHER_TOOL |
|
LEAVE_REASON_JUST_TRYING |
|
LEAVE_REASON_OTHER |
LogField
| Field | Type | |
|---|---|---|
key |
string | |
value |
string | Strings as they are, other JSON values as JSON: 1540, false, [“a”]. |
LogFormat
How a line was written.
| Value | |
|---|---|
LOG_FORMAT_UNSPECIFIED |
Plain text. |
LOG_FORMAT_JSON |
|
LOG_FORMAT_LOGFMT |
LogLevel
How bad a line says it is.
| Value | |
|---|---|
LOG_LEVEL_UNSPECIFIED |
The line doesn’t say. |
LOG_LEVEL_DEBUG |
|
LOG_LEVEL_INFO |
|
LOG_LEVEL_WARN |
|
LOG_LEVEL_ERROR |
Errors, and worse: fatal, panic, critical. |
LogLine
One line a service wrote.
| Field | Type | |
|---|---|---|
time |
timestamp | When the engine got it. |
service |
string | |
level |
LogLevel |
|
message |
string | The message: a structured line’s msg or message, a plain line whole. |
fields |
list of LogField |
A structured line’s other keys, in the order written; nested objects are dotted keys (user.id). Its time, level and message aren’t here. |
format |
LogFormat |
|
text |
string | The line as written, secrets hidden. |
MailAddress
| Field | Type | |
|---|---|---|
name |
string | |
address |
string |
MailAttachment
| Field | Type | |
|---|---|---|
partId |
string | Mailpit’s part id. |
fileName |
string | |
contentType |
string | |
sizeBytes |
int64, as a string |
MailFilter
Which messages: each field set must match. Case-insensitive.
| Field | Type | |
|---|---|---|
to |
string | Part of an address or name it went to: in To, Cc or Bcc (which holds whoever it was delivered to that the headers don’t name). |
from |
string | Part of the sender’s address or name. |
subject |
string | Part of the subject. |
MailHeader
| Field | Type | |
|---|---|---|
name |
string | |
value |
string |
MailMessage
| Field | Type | |
|---|---|---|
summary |
MailSummary |
|
cc |
list of MailAddress |
As summary.cc. |
text |
string | |
html |
string | As the app sent it. Show it sandboxed: it’s the preview’s content. |
headers |
list of MailHeader |
|
attachments |
list of MailAttachment |
|
links |
list of string | The links in the HTML and the text, each once, in order. |
unfilled |
list of UnfilledText |
Text a template seems to have left unfilled, in the subject, the text or the HTML as it reads: {{name}}, ${name}, undefined, null, NaN, [object Object], Invalid Date. |
MailSummary
A captured message, without its body.
| Field | Type | |
|---|---|---|
id |
string | |
from |
MailAddress |
|
to |
list of MailAddress |
|
subject |
string | |
snippet |
string | The start of the text, for lists. |
receiveTime |
timestamp | |
sizeBytes |
int64, as a string | |
cc |
list of MailAddress |
|
bcc |
list of MailAddress |
Whoever it was delivered to that To and Cc don’t name. |
attachmentCount |
int32 |
Member
| Field | Type | |
|---|---|---|
user |
User |
|
role |
string | “admin”, “member” or “viewer”; kept as text for older clients. |
roleKind |
Role |
|
joinedVia |
string | How they joined: “created” (made the org), “invite”, “link”, “server” (a single-org server lets everyone in). |
joinedAt |
timestamp | |
lastActiveAt |
timestamp | Their last request in this org; unset when unknown. |
login |
string | Their code-host login, e.g. GitHub’s, when they have one. |
owner |
bool | The org’s owner: an admin who also may delete the org or hand it on. Exactly one member is. |
Membership
Membership is a user’s place in one org.
| Field | Type | |
|---|---|---|
org |
Org |
|
role |
string | admin | member | viewer (“owner” from servers before roles; read it as admin) |
owner |
bool | Whether they own the org: an admin who also may delete it or hand it on. |
Onboarding
| Field | Type | |
|---|---|---|
steps |
list of OnboardingStep |
The steps in order: the required ones, then the optional ones. |
done |
int32 | How many required steps are done, of how many. |
required |
int32 | |
next |
string | The id of the first required step not done; empty when all are. |
completeTime |
timestamp | When the org’s first preview went live; unset until then. |
dismissTime |
timestamp | When an admin dismissed it, and who; unset until then. |
dismissedBy |
string | |
admins |
list of User |
Its admins, for others waiting on an admin step. |
OnboardingStep
OnboardingStep is one step on the way to the first live preview.
| Field | Type | |
|---|---|---|
id |
string | “github”, “repositories”, “compute”, “secrets”, “first_preview”, “describe” or “invite”; clients may show steps they don’t know by title. |
title |
string | |
done |
bool | |
optional |
bool | Doesn’t hold the way open, e.g. inviting the team; listed after the required steps. |
adminOnly |
bool | Only an admin can do it; others wait for one (Onboarding.admins). |
detail |
string | Done: what was set up, e.g. “acme-inc on GitHub”. Not done: what’s missing or how, in a sentence. |
url |
string | Where it’s done or seen, in the dashboard. |
skipped |
bool | Done because there’s nothing to do, e.g. no secrets the app needs. |
Org
Org is one customer account. It belongs to Stagd and is not the same thing as a GitHub organization: one Stagd org can connect several GitHub accounts, and later other code hosts.
| Field | Type | |
|---|---|---|
id |
string | |
slug |
string | Human name for URLs and the CLI, e.g. “acme”. |
name |
string | |
createTime |
timestamp |
Preferences
Preferences are how Stagd looks and behaves for one person, in every org.
| Field | Type | |
|---|---|---|
theme |
Theme |
|
timeZone |
string | An IANA time zone, e.g. “Europe/Oslo”; empty follows the browser. |
reduceMotion |
bool | No animated build bars or live pulses. |
Preview
Preview is one preview environment.
| Field | Type | |
|---|---|---|
id |
string | |
repository |
Repository |
|
change |
ChangeRequest |
Set when the preview is for a change request. |
branch |
string | The branch it runs. |
sha |
string | The commit it runs (or is building). |
status |
PreviewStatus |
|
error |
string | Why it failed, in words a person can act on; set when FAILED. |
url |
string | The primary ingress’s stable URL, e.g. https://pr-42-web-acme.stagd.dev. Every ingress URL wakes the preview if it’s asleep. |
trigger |
PreviewTrigger |
|
startedBy |
string | Who started it: the change request’s author, or the API caller. |
createTime |
timestamp | |
updateTime |
timestamp | |
expireTime |
timestamp | When it will be torn down if nothing happens before. |
ingresses |
list of PreviewIngress |
Every public URL, the primary one first. |
components |
list of PreviewComponent |
The app’s parts and what each is doing. |
access |
PreviewAccess |
Who may open it; individual ingresses may be public (see ingresses). |
note |
string | stagd.yaml’s comment: what someone opening the preview needs to know, e.g. “Sign in with code 123456”. Also on the pull request comment. |
waiting |
string | What a queued preview waits for before it deploys, from stagd.yaml’s wait: the commit’s checks and how they stand, e.g. “build-images (running)”. Empty when it isn’t waiting. |
compute |
PreviewCompute |
The compute it runs on: the org’s default when it started, or the one its stagd.yaml names (compute:). Unset once that connection is deleted. |
thumbnailTime |
timestamp | When Stagd last took a picture of its primary ingress, as it went live; unset while it has none. The dashboard shows it on the preview’s card, from /thumbnails/.jpg on the server, for people in the preview’s org. |
seed |
PreviewSeed |
The first of seeds, for clients from before there could be several. |
seeds |
list of PreviewSeed |
The seeds its databases started from, and their files, as of its last deploy on a new instance: stagd.yaml’s services: { postgres: { seed } }, and mysql, mariadb, mongodb. |
failure |
PreviewFailure |
Why it failed, as far as Stagd can tell from what it failed on and the logs it left: set when FAILED, unset when nothing was found to say. |
testers |
int32 | How many testers its stagd.yaml names (ListTesters), as at its last deploy. |
PreviewAccess
Who may open a preview.
| Value | |
|---|---|
PREVIEW_ACCESS_UNSPECIFIED |
|
PREVIEW_ACCESS_ORG |
Members of the org, signed in to Stagd. Opt-in. |
PREVIEW_ACCESS_PUBLIC |
Anyone with the link. The default. |
PreviewComponent
| Field | Type | |
|---|---|---|
name |
string | The service name, e.g. “web”, “api”, “db”. |
phase |
ComponentPhase |
|
message |
string | What it’s doing or why it failed, e.g. “building (2/3)”. |
builtin |
string | Set when Stagd runs it itself: mail, otel or postgres. |
PreviewCompute
PreviewCompute is the compute connection a preview runs on.
| Field | Type | |
|---|---|---|
id |
string | |
name |
string | As on Settings → Compute, e.g. “kind”. |
provider |
ComputeProvider |
PreviewEvent
| Field | Type | |
|---|---|---|
time |
timestamp | |
status |
PreviewStatus |
|
component |
string | The component it’s about; empty for the whole preview. |
message |
string |
PreviewFailure
A failed deploy explained: where it failed, the lines that show why, and the likely cause and fix. Secrets and anything that looks like a key are masked out of it.
| Field | Type | |
|---|---|---|
stage |
string | Where in the deploy: config, checks, source, build, pull, seed, start. |
service |
string | The compose service it’s about; empty for the whole preview. |
cause |
string | The cause, in a sentence; empty when no explanation was found. |
fix |
string | What to change; backticks around code. |
confidence |
PreviewFailureConfidence |
How sure: high when the fix is mechanical, likely when it’s the usual reason. |
evidence |
list of PreviewFailureEvidence |
The lines that show it, at most five. |
explainedBy |
string | What explained it: a rule’s id, e.g. rule:seed-download. |
createTime |
timestamp | |
error |
string | Stagd’s error, keys masked. Only from GetPreviewFailure. |
logExcerpt |
string | The failing service’s last log lines (its build’s, for a build), secrets and keys masked, under “== ” headings; at most 64 KB. Only from GetPreviewFailure. |
PreviewFailureConfidence
| Value | |
|---|---|
PREVIEW_FAILURE_CONFIDENCE_UNSPECIFIED |
|
PREVIEW_FAILURE_CONFIDENCE_HIGH |
|
PREVIEW_FAILURE_CONFIDENCE_LIKELY |
PreviewFailureEvidence
One line that shows why, and where it’s from: “error”, “ logs” or “ build”.
| Field | Type | |
|---|---|---|
source |
string | |
text |
string |
PreviewIngress
A public URL into the preview. Every ingress is one DNS label under stagd.dev: the primary one is https://.stagd.dev, the others https://–.stagd.dev.
| Field | Type | |
|---|---|---|
name |
string | Lower-case letters, digits and dashes, e.g. “web”, “api”, “admin”. |
component |
string | The component it routes to, and its port. |
port |
int32 | |
url |
string | |
primary |
bool | The preview’s main link, the one on the pull request. |
protected |
bool | Only org members, signed in to Stagd, can open it. |
builtin |
string | Set on ingresses Stagd adds for its own services: “mail” is the captured mail’s inbox. They’re always protected. |
PreviewPolicy
PreviewPolicy is who may open previews and how their URLs look.
| Field | Type | |
|---|---|---|
repository |
string | A repository id or “owner/name”; empty for the org’s default. |
access |
PreviewAccess |
|
publicIngresses |
list of string | Ingresses anyone can reach even when access is ORG, e.g. “api” for a third-party webhook. Matched by ingress name. |
unguessableUrls |
bool | Add a random token to every new preview’s host, e.g. pr-42-web-acme-k3x9q2m7wd. Makes URLs hard to guess; it doesn’t replace access control, since links get shared. |
hideMailFromViewers |
bool | Viewers don’t see the previews’ captured mail. They see it by default: a sign-up or reset email is often what they’re checking. |
sleepAfter |
duration | 45m to 24h. How long a preview nobody opens stays awake before it sleeps; opening it wakes it again. Unset for Stagd’s default, 45 minutes, which is also the least; up to 24 hours. A repository’s stagd.yaml can set its own (lifecycle: { sleep_after: 2h }), which wins. |
expireAfter |
duration | 1h to 48h. How long a preview lives without a new commit before it’s torn down; a new commit starts it over. Unset for Stagd’s default, 24 hours; from 1 to 48 hours. stagd.yaml can set its own (lifecycle: { expire_after: 36h }). |
start |
PreviewStart |
When a pull request gets a preview. Unset: a repository follows the org’s default, and the org’s default is on demand. A repository’s stagd.yaml can set its own (previews: always), which wins over both. |
startLabel |
string | At most 50 characters. With PREVIEW_START_LABEL: the GitHub label that deploys a pull request’s preview when it’s added and tears it down when it’s removed, e.g. “preview”. It has to exist in each repository. |
PreviewSeed
One part of the app: a service from the compose file. A seed a preview’s database started from: its name in Stagd (empty for a URL in stagd.yaml), and the file.
| Field | Type | |
|---|---|---|
name |
string | |
file |
SeedFile |
|
database |
string | The database it seeded: postgres, mysql, mariadb or mongodb. |
PreviewSource
Where a preview’s code comes from.
| Field | Type | |
|---|---|---|
changeNumber |
int64, as a string | More than 0. Not with branch. A pull or merge request on the repository’s code host. |
branch |
string | Not with changeNumber. A branch. With sha set, that commit; else the branch’s head on the code host. |
sha |
string | Matches ^([0-9a-f]{7,40})?$. Pin a commit. Required for generic repositories, where Stagd can’t ask a code host for the branch head. |
PreviewStart
PreviewStart is when a pull request gets a preview.
| Value | |
|---|---|
PREVIEW_START_UNSPECIFIED |
A repository: follow the org’s default. The org: on demand. |
PREVIEW_START_ON_DEMAND |
When someone asks: /stagd deploy, or Stagd’s dashboard, CLI or MCP. |
PREVIEW_START_ALWAYS |
Every pull request, when it’s opened and on each new commit. |
PREVIEW_START_LABEL |
Pull requests with start_label: adding it deploys, removing it tears down. |
PreviewStartInEffect
PreviewStartInEffect is when a repository’s (or the org’s) pull requests get previews, all settings considered, and which one decided.
| Field | Type | |
|---|---|---|
start |
PreviewStart |
|
label |
string | |
source |
PreviewStartSource |
PreviewStartSource
PreviewStartSource is where the start that applies comes from, first to last: the repository’s stagd.yaml, its override, the org’s default, Stagd’s.
| Value | |
|---|---|
PREVIEW_START_SOURCE_UNSPECIFIED |
|
PREVIEW_START_SOURCE_STAGD |
|
PREVIEW_START_SOURCE_ORG |
|
PREVIEW_START_SOURCE_REPOSITORY |
|
PREVIEW_START_SOURCE_STAGD_YAML |
previews: in stagd.yaml on the repository’s default branch; a pull request’s own stagd.yaml is read when its events arrive. |
PreviewStatus
PreviewStatus follows the environment’s state machine: queued → provisioning → building → deploying → live → sleeping → destroyed.
| Value | |
|---|---|
PREVIEW_STATUS_UNSPECIFIED |
|
PREVIEW_STATUS_QUEUED |
|
PREVIEW_STATUS_PROVISIONING |
Restoring data: a volume snapshot or a Neon branch. |
PREVIEW_STATUS_BUILDING |
|
PREVIEW_STATUS_DEPLOYING |
|
PREVIEW_STATUS_LIVE |
|
PREVIEW_STATUS_SLEEPING |
Idle; the preview URL wakes it. |
PREVIEW_STATUS_FAILED |
|
PREVIEW_STATUS_DESTROYED |
PreviewTester
A user Stagd signs in as on the preview (stagd.yaml’s testers).
| Field | Type | |
|---|---|---|
name |
string | |
note |
string | |
email |
string | |
username |
string | |
signIn |
string | The sign-in it uses, by its name under stagd.yaml’s sign_in. |
how |
string | How to sign in as it, for a person, e.g. “email, then code 123456”, with values written in stagd.yaml; a secret only by its name. |
password |
string | The password, when stagd.yaml has it written out; for members. |
passwordSecret |
string | The secret it’s from, when stagd.yaml names one, e.g. ADMIN_PASSWORD. |
headers |
bool | Whether it signs in with headers (an API’s token) rather than a form. |
PreviewTrigger
What started a preview.
| Value | |
|---|---|
PREVIEW_TRIGGER_UNSPECIFIED |
|
PREVIEW_TRIGGER_WEBHOOK |
A code host event: a pull request opened or pushed to. |
PREVIEW_TRIGGER_API |
CreatePreview, from the dashboard, the CLI, CI or an agent. |
PREVIEW_TRIGGER_COMMENT |
A /stagd command in a pull request comment. |
ProviderField
ProviderField is one value a provider needs to connect, e.g. an API token or a region.
| Field | Type | |
|---|---|---|
key |
string | |
label |
string | |
help |
string | How to get or choose the value. |
secret |
bool | Secret values are encrypted at rest and never returned by the API. |
required |
bool | |
choices |
list of string | When set, the value must be one of these. |
ProviderInfo
| Field | Type | |
|---|---|---|
provider |
ComputeProvider |
|
name |
string | |
description |
string | |
fields |
list of ProviderField |
|
capabilities |
ComputeCapabilities |
Repository
Repository is a repository Stagd can build previews for.
| Field | Type | |
|---|---|---|
id |
string | |
connectionId |
string | The connection it was reached through; empty for generic repositories. |
provider |
ScmProvider |
|
fullName |
string | “owner/name” on the code host, or a name chosen for a generic repository. |
externalId |
string | The code host’s own id for the repository. |
defaultBranch |
string | |
private |
bool | |
url |
string | Link to the repository on the code host. |
previewsEnabled |
bool | Previews are opt-in per repository: until they’re enabled, Stagd ignores its pull requests and never reads its code. |
setup |
RepositorySetup |
How the app is described on the default branch, as previews would read it; unset until Stagd has looked, and never while previews are off. |
hidden |
bool | Hidden by an org admin: left out of the lists (repositories, the new-preview picker, the command palette) unless asked for. Only the lists: previews carry on as they are. |
RepositorySetup
RepositorySetup is what Stagd found on a repository’s default branch: whether it has a stagd.yaml, the compose file it reads, and what would stop a preview, the same check as stagd validate.
| Field | Type | |
|---|---|---|
configFile |
string | “stagd.yaml” or “.stagd.yaml”; empty when the repository has none and Stagd reads the compose file alone. |
composeFile |
string | The compose file, e.g. “compose.yaml” or “deploy/compose.preview.yaml”; empty when none was found. |
ingresses |
list of string | The URLs previews get, by ingress name, the primary one first. |
problems |
list of string | What would stop a preview, in words a person can act on; empty when it would deploy. |
starter |
string | A stagd.yaml to start from, made from what was found; set when the repository has none. |
checkTime |
timestamp | |
secrets |
list of string | The secrets the app needs: names the compose file and stagd.yaml refer to as ${NAME} without a default, that stagd.yaml’s env doesn’t set and Stagd doesn’t provide (its own are STAGD_*). Sorted. Whether each has a value is for ListSecrets to say: a repository’s own or the workspace’s. |
Role
What someone may do in an org. One of its admins is also its owner (Member.owner, Membership.owner): the one who may delete it or hand it on.
| Value | |
|---|---|
ROLE_UNSPECIFIED |
|
ROLE_ADMIN |
Everything, members and settings included. |
ROLE_MEMBER |
Previews: deploy, tear down, read; no settings. |
ROLE_VIEWER |
Opens the workspace’s previews, and reads their captured mail unless the preview access policy hides it; no dashboard beyond the list of previews. For people who review rather than build: product, design, QA. They sign in with a code by email; no code-host account needed. |
ScmProvider
ScmProvider is the code host a repository lives on.
| Value | |
|---|---|
SCM_PROVIDER_UNSPECIFIED |
|
SCM_PROVIDER_GITHUB |
|
SCM_PROVIDER_GITLAB |
Planned. |
SCM_PROVIDER_BITBUCKET |
Planned. |
SCM_PROVIDER_GENERIC |
No code host integration: previews are started from CI or the CLI, and source comes as an uploaded archive or a prebuilt image. |
Secret
Secret is a secret’s name and when it last changed; never its value.
| Field | Type | |
|---|---|---|
name |
string | |
repository |
string | “owner/name”, or empty for the org’s. |
updateTime |
timestamp | |
updatedBy |
string | Who set it last, by email; empty once they’re deleted. |
Seed
| Field | Type | |
|---|---|---|
id |
string | |
name |
string | As stagd.yaml names it, e.g. app-anonymized. |
integrationId |
string | The integration whose store it’s in: its id and name. |
integrationName |
string | |
path |
string | A file’s name, or a prefix ending in / for the newest file under it. |
file |
SeedFile |
The file the path found at the last look. |
problem |
string | Why the last look found nothing, when it didn’t. |
createdBy |
string | Who made it, by email. |
createTime |
timestamp | |
checkTime |
timestamp |
SeedFile
A file a seed restores.
| Field | Type | |
|---|---|---|
name |
string | Its name in the store, e.g. seeds/platform/2026-10-28.dump. |
sizeBytes |
int64, as a string | |
modifyTime |
timestamp |
ServiceUsage
One service’s CPU and memory over the window, and how it runs now.
| Field | Type | |
|---|---|---|
service |
string | |
points |
list of UsagePoint |
Oldest first, one per bucket that has samples. |
sampledAt |
timestamp | From the latest sample. |
cpuPercent |
number | Of one CPU: 150 is one and a half. |
memoryBytes |
int64, as a string | |
memoryLimitBytes |
int64, as a string | What the service may use; without a limit of its own, the machine’s memory. |
restarts |
int32 | |
startedAt |
timestamp | |
image |
string |
Session
Session is one signed-in browser or CLI.
| Field | Type | |
|---|---|---|
id |
string | |
kind |
SessionKind |
|
userAgent |
string | The browser’s user agent, for a web session. |
clientVersion |
string | For a CLI session: what the CLI said about itself when it logged in. |
clientPlatform |
string | |
deviceName |
string | |
signInMethod |
string | How it signed in: “github”, “email”, or “device” for a CLI login approved in the browser. |
createTime |
timestamp | |
lastSeenTime |
timestamp | |
expireTime |
timestamp | |
current |
bool | The session this call came from. |
SessionKind
| Value | |
|---|---|
SESSION_KIND_UNSPECIFIED |
|
SESSION_KIND_WEB |
|
SESSION_KIND_CLI |
SignInMethod
SignInMethod is one way someone signs in, e.g. GitHub as @ada, or a code sent to an email.
| Field | Type | |
|---|---|---|
provider |
string | “github”, “email”, … |
login |
string | The username or email at that provider. |
Span
| Field | Type | |
|---|---|---|
spanId |
string | |
parentSpanId |
string | Empty for the root; or the caller’s span outside this trace’s spans. |
name |
string | |
service |
string | |
kind |
SpanKind |
|
startTime |
timestamp | |
duration |
duration | |
error |
bool | |
statusMessage |
string | |
attributes |
list of LogField |
Keys and values, as in a log line’s fields. |
events |
list of SpanEvent |
SpanEvent
Something a span recorded as it happened, e.g. an exception.
| Field | Type | |
|---|---|---|
name |
string | |
time |
timestamp | |
attributes |
list of LogField |
SpanKind
What a span did.
| Value | |
|---|---|
SPAN_KIND_UNSPECIFIED |
|
SPAN_KIND_INTERNAL |
|
SPAN_KIND_SERVER |
Handled a request. |
SPAN_KIND_CLIENT |
Made a request: another service, a database. |
SPAN_KIND_PRODUCER |
|
SPAN_KIND_CONSUMER |
stagd.config.v1.App
Where the app is described: a compose file only, for now (Helm, Kustomize and manifests come later).
| Field | Type | |
|---|---|---|
compose |
string | The compose file’s path in the repository, e.g. deploy/compose.yaml. Left out, compose.yaml (or compose.yml, docker-compose.yaml…) at the root. |
stagd.config.v1.AzureBlob
Forks Azure Blob Storage containers, each under its own name.
| Field | Type | |
|---|---|---|
from |
list of string | At least 1 items. The org’s Azure Blob Storage integrations whose containers to fork, by name, as on the Integrations page. Each integration’s SAS needs read and list (sp=rl), and nothing more. |
stagd.config.v1.Build
A service’s image: built from the repository, or one built elsewhere.
| Field | Type | |
|---|---|---|
context |
string | Not with image. Built from this directory in the repository, e.g. “.” or services/api. |
image |
string | Not with context. Pulled as it is, e.g. ghcr.io/acme/api:${STAGD_SHA}: pushed by CI. |
dockerfile |
string | With context: the Dockerfile’s path, from the context. |
target |
string | With context: the Dockerfile’s stage to build. |
args |
map of string to string | With context: build arguments. |
wait |
duration | 1m to 2h. With image: how long to keep trying to pull it, as CI may push it after the deploy starts; between 1m and 2h. Left out, a missing image fails the deploy at once. |
stagd.config.v1.Commands
| Field | Type | |
|---|---|---|
handled |
string | What happens to a /stagd comment once it’s handled: delete (the default), collapse or keep. |
stagd.config.v1.Config
Config is a repository’s stagd.yaml, as Stagd reads it: the optional file at the repository’s root that says where the app is described and what Stagd adds on top.
The messages have stagd.yaml’s own shape: a message’s JSON (protojson, with the proto field names) is the file in its plain form. A file may also use a few shorthands, which read as their plain form:
previews: always previews: { when: always } services: { mail: true } services: { mail: {} } mail: false (or otel) left out
A reader fills in the defaults, e.g. a Neon database’s name, and gives durations as protojson’s (“1200s” for 20m). Who may open previews is never set here: a pull request mustn’t be able to loosen its own preview’s access by editing a file. That’s set in Stagd.
stagd/config/v1/testdata in the stagd repository holds files with how they read, or the problems they have: every reader runs them.
| Field | Type | |
|---|---|---|
version |
int32 | The file’s format: 1, the only one so far. |
app |
stagd.config.v1.App |
Where the app is described. |
ingress |
map of string to stagd.config.v1.Ingress |
The preview’s URLs by name, e.g. web: { service: web, port: 3000 }. When set, it replaces the dev.stagd.* labels in the compose file. |
build |
map of string to stagd.config.v1.Build |
Where each service’s image comes from, by the compose file’s service name. |
services |
stagd.config.v1.Services |
What Stagd runs next to the app. |
env |
map of string to string | Variables the compose file can use, like compose’s .env file. Values may use Stagd’s variables and secrets, ${STAGD_PR_NUMBER} or ${SESSION_SECRET}; a secret wins over a variable of the same name. |
database |
stagd.config.v1.Database |
The preview’s own database. |
previews |
stagd.config.v1.Previews |
When pull requests get previews: when someone asks with /stagd deploy (on-demand, the default), always, or while they have a label. |
comment |
string | Added to the pull request comment once the preview is live, e.g. how to sign in. Markdown. |
commands |
stagd.config.v1.Commands |
What happens to /stagd commands. |
wait |
stagd.config.v1.Wait |
GitHub checks on the commit that must pass before it deploys, e.g. the workflow that pushes the images. |
registries |
map of string to stagd.config.v1.Registry |
Logins for pulling private images, by the registry’s host, e.g. ghcr.io. |
lifecycle |
stagd.config.v1.Lifecycle |
How long previews stay awake and live, in place of the org’s setting. |
compute |
string | The compute connection previews run on, by its name on Settings → Compute, e.g. kind. Left out, the org’s default. |
testers |
map of string to stagd.config.v1.Tester |
At most 20 entries. The users Stagd signs in as on the preview, by name, e.g. admin or member: users the app already has, in its seed or let in by a test login. Stagd signs in as them to check the sign-in works, and later to run tests; people see them on the preview’s QA tab. |
signIn |
map of string to stagd.config.v1.SignIn |
At most 10 entries. How the app signs people in, by name, e.g. email-otp or token. A tester names the one it uses; with only one, every tester uses it. |
stagd.config.v1.Database
The preview’s own database.
| Field | Type | |
|---|---|---|
neon |
stagd.config.v1.Neon |
A branch of a Neon database, forked for each preview. |
stagd.config.v1.Fill
| Field | Type | |
|---|---|---|
field |
string | Required. |
value |
string |
stagd.config.v1.Form
A sign-in page, and the steps a browser takes on it.
| Field | Type | |
|---|---|---|
url |
string | Matches ^/[^ #]*$. The page’s path on the primary ingress, e.g. /login. |
steps |
list of stagd.config.v1.Step |
1 to 20 items. |
stagd.config.v1.Ingress
One of the preview’s URLs: a service’s port.
| Field | Type | |
|---|---|---|
service |
string | Required. The compose file’s service. |
port |
int32 | 1 to 65535. |
primary |
bool | The URL the pull request comment and the dashboard link to first. |
stagd.config.v1.Lifecycle
How long previews stay awake and live, in place of the org’s setting.
| Field | Type | |
|---|---|---|
sleepAfter |
duration | 45m to 24h. How long a preview nobody opens stays awake: 45m to 24h. |
expireAfter |
duration | 1h to 48h. How long a preview lives without a new commit: 1h to 48h. |
stagd.config.v1.Mail
Captures mail in Mailpit, the preview’s inbox. Every way Stagd catches is pointed at it unless catch names some: smtp (SMTP_HOST, SMTP_PORT, SMTP_URL, MAIL_HOST, EMAIL_HOST), resend (RESEND_BASE_URL, RESEND_API_URL) and ses (AWS_ENDPOINT_URL_SES, AWS_ENDPOINT_URL_SESV2). Without catch, ways added later are caught too, so a preview never sends real mail by surprise; with it, only those named.
| Field | Type | |
|---|---|---|
skip |
list of string | Deprecated, at most 2 items. Deprecated: the ways left alone, the rest caught. Read as catch with those taken out; use catch. |
catch |
list of string | At least 1 items. Only these ways are pointed at the inbox, e.g. [smtp] for Mailpit alone: stagd-mock runs only for resend or ses. The rest reach the real vendor. |
stagd.config.v1.MariaDB
| Field | Type | |
|---|---|---|
version |
string | The version: 11.4 or 11.8; 11.8 when left out. |
database |
string | Matches ^[a-z_][a-z0-9_]{0,62}$. The database the app uses: preview when left out. |
seed |
string | Matches `^(https://.* |
stagd.config.v1.MongoDB
| Field | Type | |
|---|---|---|
version |
string | The version: 7.0 or 8.0; 8.0 when left out. |
database |
string | Matches ^[a-z_][a-z0-9_]{0,62}$. The database the app uses: preview when left out. |
seed |
string | Matches `^(https://.* |
stagd.config.v1.MySQL
| Field | Type | |
|---|---|---|
version |
string | The version: 8.4 or 9; 8.4 when left out. |
database |
string | Matches ^[a-z_][a-z0-9_]{0,62}$. The database the app uses: preview when left out. |
seed |
string | Matches `^(https://.* |
stagd.config.v1.Neon
A Neon branch per preview, forked from a parent branch. Which parents may be forked is the org’s Neon integration’s to say: a pull request that could name any parent could fork production into its preview.
| Field | Type | |
|---|---|---|
integration |
string | Which of the org’s Neon integrations, when it has several. |
project |
string | Required. |
parent |
string | Required. The branch to fork: its id or name. |
database |
string | The database, neondb by default. |
role |
string | The role the URLs sign in as, neondb_owner by default. |
pooled |
bool | Whether url is the pooled URL. |
params |
map of string to string | Added to the URLs, e.g. sslmode: verify-full. |
env |
map of string to string | The variables the URLs are given as, by kind: url (pooled or not, as pooled says), pooled and unpooled. By default url: DATABASE_URL. |
stagd.config.v1.OTel
| Field | Type | |
|---|---|---|
export |
stagd.config.v1.OTelExport |
Where a copy of what the app sends goes on to: the team’s own backend. |
ignore |
list of string | Request paths whose traces aren’t kept, a * matching the rest, e.g. [/healthz, /internal/*]. |
stagd.config.v1.OTelExport
| Field | Type | |
|---|---|---|
endpoint |
string | Required. An OTLP endpoint, e.g. https://otlp.example.com. |
protocol |
string | How it’s sent: http/protobuf (the default) or grpc. |
headers |
map of string to string | Headers sent with it, e.g. Authorization: “Bearer ${DASH0_TOKEN}”. |
stagd.config.v1.Postgres
| Field | Type | |
|---|---|---|
version |
string | The major version: 16, 17, 18 (the default) or 19. A seed made with a newer pg_dump than this doesn’t restore. |
database |
string | Matches ^[a-z_][a-z0-9_]{0,62}$. The database the app uses: postgres when left out. |
seed |
string | Matches `^(https://.* |
extensions |
list of string | Extensions made in the database as it’s created, before the seed restores, by the name CREATE EXTENSION takes: Postgres’s own (contrib: pg_trgm, pgcrypto, uuid-ossp, citext, hstore …) and any the PostgreSQL apt repository packages (vector, postgis, pg_cron, h3, hypopg …), which Stagd installs as the database starts, on Debian’s image of the version. Those that load at start (pg_cron, pg_stat_statements, timescaledb …) are preloaded. |
stagd.config.v1.Previews
When pull requests get previews.
| Field | Type | |
|---|---|---|
when |
string | Not with label. on-demand, when someone asks with /stagd deploy; or always. |
label |
string | At most 50 characters. Not with when. A GitHub label: adding it deploys the preview, removing it tears the preview down. |
stagd.config.v1.Registry
A login for pulling images from one registry.
| Field | Type | |
|---|---|---|
username |
string | Required. |
password |
string | Matches \$\{. A secret of Stagd’s, written as “${NAME}”: a password in the repository is a leaked password. |
stagd.config.v1.S3
Forks S3 buckets, each under its own name.
| Field | Type | |
|---|---|---|
from |
list of string | At least 1 items. The org’s S3 integrations whose buckets to fork, by name, as on the Integrations page. They’re read at one endpoint, in one region, with one key: integrations that differ in those can’t be forked together. Each key needs s3:ListBucket and s3:GetObject, and nothing more. |
stagd.config.v1.Services
What Stagd runs next to the app.
| Field | Type | |
|---|---|---|
mail |
stagd.config.v1.Mail |
Captures the mail the app sends (Mailpit), for the dashboard and the preview’s own inbox. |
otel |
stagd.config.v1.OTel |
An OpenTelemetry endpoint for the app’s traces, with a viewer (Jaeger). |
postgres |
stagd.config.v1.Postgres |
A Postgres database for the preview, started from a seed when there is one. The app gets its URL in DATABASE_URL. |
mysql |
stagd.config.v1.MySQL |
A MySQL database for the preview, started from a seed (a mysqldump) when there is one. The app gets its URL in MYSQL_URL, and in DATABASE_URL unless another database has it. |
mariadb |
stagd.config.v1.MariaDB |
A MariaDB database, as mysql is: MYSQL_URL and DATABASE_URL. |
mongodb |
stagd.config.v1.MongoDB |
A MongoDB database for the preview, started from a seed (a mongodump archive) when there is one. The app gets its URL in MONGODB_URI. |
sms |
stagd.config.v1.Sms |
Catches the text messages (SMS) the app sends through Amazon SNS, for the dashboard’s Messages tab: SNS is pointed at Stagd’s mock in previews. |
azureBlob |
stagd.config.v1.AzureBlob |
A fork of the org’s Azure Blob Storage containers (blobfork): the app reads every file of the real ones, and what it writes or deletes stays in the preview. The app gets AZURE_STORAGE_CONNECTION_STRING. |
s3 |
stagd.config.v1.S3 |
A fork of the org’s S3 buckets (blobfork), as azure_blob is for Azure: the app gets AWS_ENDPOINT_URL_S3, and its own AWS key works there. |
stagd.config.v1.SignedIn
How Stagd tells a sign-in worked. Exactly one.
| Field | Type | |
|---|---|---|
text |
string | Not with url or request. This text shows on the page, e.g. Sign out. |
url |
string | Not with text or request. The browser ends on this path, e.g. /dashboard; a * matches the rest. |
request |
string | Not with text or url. A GET of this path answers 2xx, e.g. /api/me: for headers. |
stagd.config.v1.SignIn
One way the app signs people in: a form a browser fills in, or headers sent with every request (an API’s token). Exactly one of form and headers.
| Field | Type | |
|---|---|---|
form |
stagd.config.v1.Form |
|
headers |
map of string to string | Sent with every request, e.g. Authorization: “Bearer ${tester.token}”. |
signedIn |
stagd.config.v1.SignedIn |
Required. How Stagd tells the sign-in worked. |
stagd.config.v1.Sms
Catches text messages: Amazon SNS, pointed at Stagd’s mock (AWS_ENDPOINT_URL_SNS).
No fields.
stagd.config.v1.Step
One thing the browser does. Values may use ${tester.*}, secrets as “${NAME}”, and, after wait_for_mail, ${mail.code} and ${mail.link}.
| Field | Type | |
|---|---|---|
fill |
stagd.config.v1.Fill |
Not with click or open or waitFor or waitForMail. Types into a field, found by its label, placeholder or name. |
click |
string | Not with fill or open or waitFor or waitForMail. Clicks a button or link, found by its text. |
open |
string | Not with fill or click or waitFor or waitForMail. Goes to a path on the preview, or ${mail.link}. |
waitFor |
string | Not with fill or click or open or waitForMail. Waits for this text to show on the page. |
waitForMail |
stagd.config.v1.WaitForMail |
Not with fill or click or open or waitFor. Waits for an email the step before sent, and reads its code or link. |
stagd.config.v1.Tester
A user Stagd signs in as. Its values are what the sign-in’s steps and headers use as ${tester.email}, ${tester.username}, ${tester.password} and ${tester.token}; each may be plain, or a secret of Stagd’s written as “${NAME}”.
| Field | Type | |
|---|---|---|
note |
string | At most 200 characters. Who they are, for people and models, e.g. “org admin, sees billing”. |
email |
string | |
username |
string | |
password |
string | |
token |
string | |
signIn |
string | The sign-in it uses, by its name under sign_in; left out when there’s only one. |
stagd.config.v1.Wait
| Field | Type | |
|---|---|---|
checks |
list of string | 1 to 20 items. Check run or workflow names, e.g. [build-images]; one failing fails the preview at once. |
timeout |
duration | 1m to 2h. How long to wait for them, from when the deploy starts: 30m by default, 1m to 2h. |
stagd.config.v1.WaitForMail
An email in the preview’s inbox (services: { mail: {} }), sent after the step before this one started.
| Field | Type | |
|---|---|---|
to |
string | Who it’s to: ${tester.email} by default. |
subject |
string | Part of its subject, when the app sends other mail too. |
within |
duration | 5s to 2m. How long to wait: 30s by default, 5s to 2m. |
code |
string | A regular expression for ${mail.code}, its first group the code: by default the first 4 to 8 digits on their own in the subject, then the text. |
link |
string | A regular expression for ${mail.link}, matched against the links to the preview: by default the first. |
StagdIngress
Unused: Stagd’s own ingress in clusters, replaced by StagdTunnel.
| Field | Type | |
|---|---|---|
host |
string | |
address |
string | |
certificateExpireTime |
timestamp | |
problem |
string | |
checkTime |
timestamp |
StagdRelay
A connection’s relay, as it said when it connected.
| Field | Type | |
|---|---|---|
version |
string | The relay’s release, e.g. “v0.4.1”; for a build that isn’t a release, what it calls itself, e.g. “v0.4.1-3-g1a2b3c4” or “dev”. |
connectTime |
timestamp | |
latestVersion |
string | The newest release, e.g. “v0.5.0”, when it’s newer than the relay’s; empty when the relay is up to date, isn’t a release, or Stagd can’t tell. The connection’s install command updates it. |
updateRecommended |
bool | Whether it should be updated rather than may be: a minor release or more behind, e.g. v0.4.1 with v0.5.0 out, not v0.5.0 with v0.5.1. |
remoteAddress |
string | Where it connects from: the address Stagd sees, and the Cloudflare location it reached, e.g. “CPH”. Only in GetComputeConnectionDetails. |
location |
string | |
roundTrip |
duration | A ping’s round trip over its connection, from Stagd to the relay and back. Only in GetComputeConnectionDetails; unset when it didn’t answer. |
StagdTunnel
The Cloudflare Tunnel Stagd made for a cluster (deploy/kubernetes/stagd-tunnel.yaml), as Stagd last found it.
| Field | Type | |
|---|---|---|
host |
string | The tunnel’s host name, e.g. “tunnel-0f3a9c2e81d4.stagd.run”: Stagd’s edge sends preview requests there; visitors never see it. |
locations |
list of string | The Cloudflare locations its connectors are at, e.g. “cph01”; empty while none is connected. |
problem |
string | What stops previews being reached through it, e.g. “waiting for cloudflared in the cluster to connect”; empty when they are. |
checkTime |
timestamp | When Stagd last looked; unset before it has. |
connectors |
list of TunnelConnector |
Its connectors as Cloudflare has them now. Only in GetComputeConnectionDetails. |
TesterCheck
How signing in as one tester went.
| Field | Type | |
|---|---|---|
name |
string | |
ok |
bool | |
error |
string | Why it didn’t work, e.g. “step 3: no field named Code”. |
steps |
list of TesterStep |
|
url |
string | Where the browser ended, for a form. |
screenshot |
bytes, base64 | The page when it stopped, as a JPEG, when it didn’t work. |
TesterStep
| Field | Type | |
|---|---|---|
text |
string | What it did, e.g. “fill Email” or “wait for mail to admin@acme.test”. |
ok |
bool | |
error |
string | |
duration |
duration |
TextFilter
Which text messages: each field set must match. Case-insensitive.
| Field | Type | |
|---|---|---|
to |
string | Part of the number it went to, e.g. 4791234567. |
body |
string | Part of the body. |
TextMessage
A text message the app sent, as the vendor’s API was asked to send it.
| Field | Type | |
|---|---|---|
id |
string | |
vendor |
string | The API it went through, e.g. “sns”. |
to |
string | A phone number, e.g. +4791234567. |
from |
string | |
body |
string | |
sendTime |
timestamp |
Theme
| Value | |
|---|---|
THEME_UNSPECIFIED |
Follows the operating system. |
THEME_LIGHT |
|
THEME_DARK |
TraceSummary
A trace for a list: its root span, how long it all took, whether anything failed.
| Field | Type | |
|---|---|---|
traceId |
string | |
name |
string | The root span’s name and service. |
service |
string | |
startTime |
timestamp | |
duration |
duration | |
spanCount |
int32 | |
services |
list of string | |
error |
bool | |
httpMethod |
string | From the root span’s HTTP attributes, when it has them. |
httpStatusCode |
int32 |
TunnelConnector
One connection from cloudflared next to the relay to Cloudflare; each cloudflared keeps several, at nearby locations.
| Field | Type | |
|---|---|---|
location |
string | The Cloudflare location, e.g. “cph01”. |
version |
string | cloudflared’s release, e.g. “2026.9.1”. |
originAddress |
string | The address it connects from, as Cloudflare sees it. |
openTime |
timestamp |
UnapprovedGrant
UnapprovedGrant is one permission or event a code host installation hasn’t approved.
| Field | Type | |
|---|---|---|
name |
string | As the code host names it: a permission (“checks”) or an event (“check_run”). |
title |
string | In words, with the access asked for: “Checks (read and write)”, “Check run events”. |
why |
string | What Stagd needs it for: “Preview checks on pull requests”. |
UnfilledText
| Field | Type | |
|---|---|---|
part |
string | “subject”, “text” or “html”. |
found |
string | What was found, e.g. “{{name}}”. |
near |
string | The words around it. |
UsagePoint
Average CPU and peak memory over one bucket of time.
| Field | Type | |
|---|---|---|
time |
timestamp | |
cpuPercent |
number | |
memoryBytes |
int64, as a string |
User
User is someone who can sign in.
| Field | Type | |
|---|---|---|
id |
string | |
email |
string | |
name |
string | |
imageUrl |
string |