Environments

Environments connect a repository to a PaaS provider so deploy results show up in Codebahn: a status on the commit and a preview link on the pull request. This is the Codebahn-specific layer behind Deploy to a PaaS, which walks through provider setup end to end.

You deploy from your own CI workflow using the provider’s CLI (vercel deploy, netlify deploy, railway up, and so on). Codebahn does not connect to the provider or trigger deploys. It receives a callback you configure and records the outcome.

How it works

1. Receive a callback. The provider POSTs to your environment’s callback URL when a deploy finishes. Codebahn parses the payload and updates the deployment record.
2. Write a commit status. When a deploy reaches a terminal state, a status appears on the commit: success on ready, failure on error or cancelled.
3. Post a PR comment. On a successful preview deploy, the deployed URL is posted as a comment on the pull request.
4. Show history. Deployments are listed in the repository’s Environments tab.

Callback URL

Creating an environment generates a callback URL:

https://{instance}/-/environments/callback/{env_id}/{callback_token}

Paste it into your provider’s webhook settings. The token in the path is the authentication: 24 bytes from crypto/rand, encrypted at rest, compared in constant time. Codebahn does not discover deploys on its own, so this URL is the only way status reaches a commit.

The endpoint accepts POST, reads up to 1 MB of body, runs provider-specific parsing, and falls back to a generic format.

Callback payload formats

Set the provider when you create the environment so Codebahn uses the right parser. Recognized providers: Vercel, Netlify, Render, Railway, and Cloudflare Pages. Anything else (or a parse failure) is read as the generic format:

{
  "status": "success",
  "url": "https://my-app.example.com",
  "id": "deploy-123",
  "error": ""
}

Field	Required	Values
status	Yes	success, ready, error, failed, cancelled, building, pending
url	No	Deployed URL (must be http:// or https://)
id	No	External deployment ID, used to correlate callbacks
error	No	Error message on failure

Provider notes

Vercel. Events: deployment.succeeded, deployment.ready, deployment.promoted (success), deployment.error (failure), deployment.created, deployment.build-requested (building), deployment.canceled. Deployed URL from payload.deployment.url.

Netlify. Payload is the deploy API object. Status from state: ready (success) or error (failure). URL from deploy_ssl_url, error from error_message.

Render. Thin Standard Webhooks payload. Event type deploy_ended; status from data.status (succeeded, failed, canceled). No deployed URL or commit SHA in the payload. Render gates webhooks behind its paid plans, so check what your Render plan includes.

Railway. Event type Deployment.<state> (e.g. Deployment.completed, Deployment.failed, Deployment.crashed). Commit SHA from details.commitHash. No deployed URL, no signature.

Cloudflare Pages. Event type pages_event_alert, events EVENT_DEPLOYMENT_SUCCESS, EVENT_DEPLOYMENT_FAILED, EVENT_DEPLOYMENT_STARTED. Point a Cloudflare notification at your callback URL.

Deployment lifecycle

queued -> building -> ready

From queued or building, a deploy can also move to error or cancelled. Those three (ready, error, cancelled) are terminal.

The deployment record is created on the first callback for a new external deployment ID. Transitions are enforced, and a repeat callback for the current state is ignored.

A deployment stuck in queued or building for more than 30 minutes is marked failed.

Commit statuses

Deployment state	Commit status	Description
ready	success	”Deployment ready” (links to the deployed URL)
error	failure	Error message from the provider
cancelled	failure	”Deployment cancelled”

A commit status is written only on these terminal states. The queued and building states update the deployment record (visible in the Environments tab) but do not write a commit status.

The status context is deploy/{provider} (e.g. deploy/vercel) and appears in the PR merge box.

Security

• Callback token. Encrypted at rest, compared in constant time. The token alone authenticates a callback.
• Optional signature verification. Vercel uses HMAC-SHA1 (x-vercel-signature); Render uses Standard Webhooks HMAC-SHA256 (webhook-signature). Providers without signing (Railway, Cloudflare Pages, generic) rely on the callback token. The signing secret is encrypted at rest.
• Payload limits. Body capped at 1 MB, deployed URLs must be http(s), error messages truncated to 200 characters.
• Access control. Only repo admins configure environments. Deployment history is visible to anyone with repo read access.
• Audit trail. Connect, disconnect, and each callback are logged with a timestamp.