Monorepos

Each Openstead service can point to a different application in the same GitHub repository. The repository is shared; the build configuration, variables, plan, and release history belong to each service.

Independent application directoriesCopy Anchor Link

Consider this repository:

apps/
  web/package.json
  api/pyproject.toml
packages/
  shared/

If apps/web and apps/api are independently installable, create two services and set their Root directory to apps/web and apps/api. Commands run relative to the selected application root. Do not include that path again in commands or publish-directory settings unless the tool expects it.

Shared package workspacesCopy Anchor Link

For a pnpm, Yarn, npm, or other workspace that needs the repository's top-level lockfile and shared packages, use the repository root as the service root. Set a build command targeting the intended package, such as:

pnpm --filter @example/web build

The package name must match your repository. Set the corresponding start command for a web service or the generated publish directory for a static site. Ensure dependent packages are built too; this is controlled by your workspace build tool.

A Dockerfile is useful when the selected app needs files from several directories. Keep the application root at the repository root, use a nested Dockerfile path such as apps/api/Dockerfile, and set Docker context to ..

Filter automatic deploymentsCopy Anchor Link

Service settings include Included build paths and Ignored build paths, with one pattern per line. Push-triggered deployment filtering works on repository-relative changed paths, including the application root prefix.

For a frontend built from the repository root, include relevant patterns such as:

apps/web/*
packages/shared/*
package.json
pnpm-lock.yaml
pnpm-workspace.yaml

These are wildcard path patterns, not regular expressions. Ignored matches take precedence over included matches. When a nonempty root is selected, changes outside that root do not pass its root filter. Use the repository root if shared packages outside an app directory must trigger its deployments.

Path filtering applies to push-triggered automatic deployments. Do not rely on those filters to isolate the After CI checks pass policy; configure the CI workflow and service policy deliberately. If a webhook does not include enough changed-file information, Openstead can deploy rather than incorrectly skip a change.

Coordinate related releasesCopy Anchor Link

Changing a shared interface can require more than one service deployment. Keep API changes backward compatible while releases roll out. Use a Blueprint to describe related configuration, and inspect each service's result rather than treating the repository as one atomic application release.

Common failures include a missing root lockfile, a shared package excluded from the build context, and a publish directory that repeats the application root. Check those paths first when the same build works locally.