Skip to content
Spinbox is experimental: APIs change and data may be lost. Status lists what is built and what proves it.

ForgeService

View Markdown

ForgeService is a person’s account on a forge, connected through the installation’s GitHub App. (spin#758): the control plane keeps the token, lists the person’s repositories with it, and a. host’s egress proxy sets it on their workspaces’ brokered requests. No workspace holds it.

POST /spin.v1.ForgeService/CompleteAppCreation

Request

FieldTypeWhat it is
codestring
statestring
bindingstring

Response

FieldTypeWhat it is
appForgeApp

POST /spin.v1.ForgeService/CompleteConnect

Request

FieldTypeWhat it is
codestring
statestring
bindingstring

Response

FieldTypeWhat it is
connectionForgeConnection

POST /spin.v1.ForgeService/DeleteForgeApp

Takes the app out of use at once. Every connection through it is revoked at the forge, and the app is gone when that is done.

Request

FieldTypeWhat it is
forgestring

Response

No fields: {}.

POST /spin.v1.ForgeService/Disconnect

Forgets the token and revokes it at the forge.

Request

FieldTypeWhat it is
forgestring

Response

No fields: {}.

POST /spin.v1.ForgeService/ListConnections

Request

No fields: {}.

Response

FieldTypeWhat it is
connectionslist of ForgeConnection

POST /spin.v1.ForgeService/ListForgeApps

The installation’s app on each forge: whether a person can connect, and where. Its secrets are never answered with.

Request

No fields: {}.

Response

FieldTypeWhat it is
appslist of ForgeApp

POST /spin.v1.ForgeService/PollDeviceConnect

Request

FieldTypeWhat it is
handlestring

Response

FieldTypeWhat it is
connectionForgeConnectionSet once the person approved: the connection, kept. Unset is pending: poll again after interval_seconds, which the forge may have lengthened.
intervalSecondsinteger (int32)

POST /spin.v1.ForgeService/SearchRepositories

The repositories the person’s account reaches that match query, as the forge searches them with the person’s token: what they can see there is what they can pick here.

Request

FieldTypeWhat it is
forgestring
querystringEmpty lists the account’s repositories, most recently pushed first.

Response

FieldTypeWhat it is
repositorieslist of ForgeRepository

POST /spin.v1.ForgeService/SetForgeApp

Keeping an app that was made elsewhere. Refused while the forge has one: an app is never edited, because another client id could not revoke what this one granted.

Request

FieldTypeWhat it is
forgestring
appIdstring (int64)
slugstring
clientIdstring
clientSecretstring
webhookSecretstring
apiUrlstringAs StartAppCreationRequest’s.
webUrlstring

Response

FieldTypeWhat it is
appForgeApp

POST /spin.v1.ForgeService/StartAppCreation

Making the app, by an instance admin, through the forge’s manifest flow: StartAppCreation answers the form the browser posts to the forge, which makes the app and sends the admin back with a code; CompleteAppCreation exchanges it for the app’s credentials. Nobody copies a key.

Request

FieldTypeWhat it is
forgestring
organizationstringThe organization the app belongs to; empty is the admin’s own account.
apiUrlstringEmpty is github.com’s; a GitHub Enterprise Server’s API is https://<host>/api/v3, and its web origin https://<host>.
webUrlstring
publicbooleanWhether any account can install it. A private app installs only on the account that owns it, so only that account’s repositories are reached.

Response

FieldTypeWhat it is
formUrlstringWhere to send the browser: a page of this control plane’s that posts the manifest to the forge, because the dashboard’s own policy lets it post nowhere else.
statestring
bindingstringA secret for the client that began this, kept where only it reads it and never in a URL: CompleteAppCreation requires it with the state.

POST /spin.v1.ForgeService/StartConnect

Connecting: StartConnect answers where the person authorizes the app and a binding only this client keeps; the forge sends the browser back to redirect_uri with a code and the state, and CompleteConnect exchanges them, with the binding, for the person’s token.

Request

FieldTypeWhat it is
forgestring
redirectUristringThe dashboard’s /git/callback, over https; anything else is refused. Empty is the installation’s own.

Response

FieldTypeWhat it is
authorizeUrlstring
statestring
bindingstringA secret for the client that began this, kept where only it reads it and never in a URL: CompleteConnect requires it with the state.

POST /spin.v1.ForgeService/StartDeviceConnect

Connecting from somewhere with no browser to send back to, the CLI: the control plane asks the forge for a device code (RFC 8628) and keeps it, and answers with the code the person types on the forge’s page and a handle only the caller can poll with. PollDeviceConnect asks the forge, at most once an interval, and on the person’s approval keeps their token as CompleteConnect does: once, for the person who began it.

Request

FieldTypeWhat it is
forgestring

Response

FieldTypeWhat it is
handlestringWhat PollDeviceConnect is asked with: a secret of the caller’s, polled by them alone. The forge’s device code stays on the control plane.
userCodestringWhat the person types at verification_uri, signed in to the forge.
verificationUristring
expiresAtTimestamp
intervalSecondsinteger (int32)How long to wait before each poll.

Generated by task reference from spin/internal/controlplane/apidocs/spin.v1.openapi.json at 51f7e0dea.

Installations run Spinbox v20261027.01; the reference is generated from spin v20261114.01 (51f7e0dea). This page as Markdown, for a model or a terminal.