Guide

Build and deploy

Builds

Mesh builds an immutable image from each commit of a repository service. A build starts when you release a staged source change, when you push to the tracked branch with auto-deploy on, or when you redeploy.

Connect GitHub

Sign in with GitHub, then install the Mesh GitHub App on the repositories Mesh may read. The console asks for this the first time you add a repository. Mesh reads source code through the app installation; it never asks for your password or a personal token.

With MCP, call connect_github and open its authorization_url to approve the connection. Then call get_github_connection and list_github_repositories. Use list_github_branches and list_github_dockerfiles to choose build inputs, then create_service_from_repository to stage a service. Release its environment to deploy it. disconnect_github previews the change and needs confirm: true.

The API exposes the same flow at POST /v1/github/connection, GET /v1/github/connection, GET /v1/github/repositories, and POST /v1/environments/{environmentId}/services/from-repository. The control plane stores and refreshes the grant; API and MCP clients do not handle GitHub tokens.

A repository service records:

  • the repository, such as acme/storefront;
  • the tracked branch, such as main. Commits to this branch deploy when auto-deploy is on for the environment;
  • the builder and its options.

Railpack

Railpack inspects the repository, detects the language, framework, package manager, and start command, and produces an image. Most apps build with no configuration.

  • Set the app directory to build an app inside a monorepo, such as apps/web.
  • Override the start command in Settings when the detected one is wrong.

Dockerfile

Choose Dockerfile to build a Dockerfile in the repository. Mesh lists the Dockerfiles it finds; pick one and set the build context directory.

Dockerfile
FROM node:22-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

Isolation

Each build runs on its own and is thrown away when it ends. One build never sees another workspace's source, cache, or secrets.

The service's variables are runtime configuration: they are not passed into the build.

Waiting and failures

A deployment that needs a build shows Waiting for builder until a builder is free, then Building. Your plan limits concurrent builds (one on the trial, two on Hobby, five on Pro); extra builds wait in line.

When a build fails, the deployment keeps the previous one serving. Read the build logs in the deployment's Build log tab, or ask the MCP server's diagnose_service tool for a summary.