Deploying from Git

You can deploy an app version two ways:

• From your machine or CI with agentserve app deploy, which builds locally and uploads the result. See agentserve app deploy.
• From Git. Connect a repository, and every push to a branch you choose builds a draft version on Agent Serve.

Both produce the same kind of draft version, which someone then publishes and installs.

Connect a repository

Open the app's page under Apps → Library. In the Source section, pick a connection and a repository, then Connect. You need write access in the workspace that manages the app, and your permission group must allow building apps.

The connection comes from Integrations:

• GitHub: an installation of the Agent Serve GitHub App on the account or organization that owns the repository. The section links to the install page if you have none.
• GitLab: a personal access token with the api scope and the Maintainer role on the project. Connecting creates the project webhook for you.

An app deploys from one repository. To switch, disconnect the current one first. Disconnecting stops new builds and, for GitLab, removes the project webhook when your token allows it. Past deployments and the versions they built stay.

What a push does

Agent Serve builds a push when it lands on the repository's default branch, or on a branch one of your branch rules names. Pushes to other branches, tags and branch deletions are ignored. The same commit is never built twice for one app.

Each build:

1. Downloads the commit and checks that agentserve.app.yaml is at the repository root.
2. Installs dependencies, if there is a package.json, with the package manager your lockfile belongs to: Bun (bun.lock), npm (package-lock.json), pnpm (pnpm-lock.yaml) or Yarn (yarn.lock). A lockfile is required, and installs never change it.
3. Runs the dependency audit.
4. Runs the build command: build.command from the manifest, or bun run build.
5. Runs your tests with test from package.json, if there is one. A failing test fails the build.
6. Packs the bundle and uploads it as a draft version, recording the repository, branch and commit it came from.

The bundle is the manifest plus the paths in build.output, or by default the folders that hold your page, panel and Chat card entries, the icon and the requires files. Your code tools are always included. The bundle may be at most 25 MB.

build:
  command: npm run build:prod
  output: [./web/dist, ./public]

Builds run in an isolated sandbox that has no access to workspace data, app secrets or your repository credentials, and stop after 10 minutes. Their compute is metered to the workspace that manages the app.

Agent Serve reports the build back on the commit as a status named Agent Serve app deploy, which moves from pending to running to success or failure and links to the deployment. A successful status says whether the version is live or a draft is ready to publish.

Dependency audit

After install, every build checks your production dependencies:

An audit that cannot run also fails the build, so an outage never lets an unchecked build through. A binary bun.lockb cannot be checked: commit the text bun.lock instead (bun install --save-text-lockfile).

To let a build through anyway, set build.allowVulnerable: true. The findings are still recorded on the version and shown wherever it is listed, marked as allowed.

Branch rules

Without rules, every build waits as a draft until someone publishes it.

A branch rule auto-publishes builds from one branch and moves chosen workspaces' installs to the new version. For example, main can auto-publish and upgrade a test workspace, while production workspaces are upgraded by hand. Rules are set under Auto-publish in the Source section and need admin access.

• A branch name matches exactly, and a rule's branch is also built even when it is not the default branch.
• Each workspace a rule names must already have the app installed, and you must be an admin there.
• A rule cannot auto-publish while publish approval is on (see below). Its builds wait as drafts instead.

Publish approval

An admin can turn on Publishing in this workspace in the Source section, so that a second person must approve every publish. The first admin's Publish records a request; a different admin's Publish approves it and makes the version installable. Nobody can approve their own request. This applies to every publish in the workspace, from the versions list, Deployments, agentserve app publish or the API, whether the version was uploaded or built from Git.

Deployments

The Deployments section on the app's page lists every build: commit, author, message, status, the audit result and the build log. A deployment is Queued, Building, Ready (a draft), Failed or Live.

From there an admin can publish a ready draft (or approve someone else's request), and you can rebuild a failed deployment. To roll back, move an install to an earlier deployment's version.

When a version built from Git goes live, members with write access see a notice in the workspace.

The same information is available through the API: GET /api/v2/apps/{appId}/repos, GET /api/v2/apps/{appId}/deployments and GET /api/v2/apps/{appId}/deployments/{deploymentId}, with POST …/rebuild and POST …/publish on a deployment. See the API reference.

Where a version came from

Every version records its source, which the API returns with the version:

Setting up the GitHub App

Create a GitHub App for your deployment with:

• Repository permissions: Contents: read, Metadata: read, Commit statuses: read and write.
• Events: subscribe to Push.
• Webhook URL: https://<your Agent Serve address>/api/apps/git/github, with a webhook secret.

Then set these on the server: GITHUB_APP_ID, GITHUB_APP_SLUG, GITHUB_APP_CLIENT_ID, GITHUB_APP_CLIENT_SECRET, GITHUB_APP_PRIVATE_KEY and GITHUB_APP_WEBHOOK_SECRET (the webhook secret). Deliveries whose X-Hub-Signature-256 does not match the secret are refused.

GitLab needs no server setup. Each connected project gets its own webhook to /api/apps/git/gitlab with a secret token of its own, and deliveries without the right token are refused.