Source Services

Source services are services Forge builds from code. Use them for most web apps, APIs, workers, and static sites.

Source Options

Forge supports two GitHub source paths:

• GitHub repository: browse repositories available to the connected GitHub App, choose a branch, and select a root directory.
• GitHub URL: enter an uncredentialed https://github.com/owner/repository URL manually, then provide the branch and root directory.

Use the connected GitHub repository path for repository discovery and push-triggered deployments. Use a manual GitHub URL for a public repository or a private repository with its own project-scoped token. GitLab, Bitbucket, arbitrary Git hosts, embedded URL credentials, SSH URLs, ports, query strings, and fragments are not supported by the current source provider.

Repository Settings

Each source service stores:

• Service name.
• Connected repository or GitHub URL.
• Branch.
• Root directory.
• Runtime mode.
• Internal port for web services.
• Optional static output directory.
• Optional install, build, and start command overrides.

The root directory matters for monorepos. Choose the folder that contains the app you want Forge to build. For manually entered GitHub URLs, type the root directory manually.

Build Detection and Overrides

Forge uses Railpack through BuildKit to detect and build the app. Leave install, build, and start commands blank when auto detection is correct.

Use command overrides when:

• The repo has a custom install command.
• The build script is not the default script.
• The service needs a custom start command.
• A monorepo package must be launched from a specific path.

The static output setting turns a source service into a static site deployment. Forge extracts the output directory from the verified build and serves those files instead of running an app server.

Build and Runtime Variables

Forge keeps private service variables out of source-analysis and Railpack build processes. Normal variables and secrets imported from Doppler are supplied to release commands and runtime containers, not to source builds.

Only variables using a framework-defined client-public prefix are supplied during source builds:

VITE_*
NEXT_PUBLIC_*
PUBLIC_*
REACT_APP_*
NUXT_PUBLIC_*
GATSBY_*
EXPO_PUBLIC_*

Frameworks can embed these values in browser or mobile bundles. Never store passwords, tokens, private keys, database URLs, or provider credentials under one of these names. Forge rejects private variable names at the Railpack build boundary instead of exposing them to install or build scripts.

Private package-registry credentials and other build-only secrets are not supported by the current source-build path. Do not convert them to public-prefixed variables. Use a Docker image built by a trusted external pipeline until Forge provides a dedicated ephemeral build-secret mount.

Runtime Mode

web services must listen on the configured internal port. Forge starts the deployment, checks the port, and switches traffic only after the health check passes.

worker services run without a published port. Forge checks that the container process stays running.

GitHub Push Deploys

When a workspace GitHub App connection is active, pushes can enqueue deployments for connected services.

Forge also supports manual deployments from the service Deployments tab. Manual deployments are useful for first deploys, retries, and manually entered GitHub services.

Common Failures

• The selected server’s build runtime is unavailable.
• The selected root directory does not contain the app.
• The app listens on a different port than the service internal port.
• The static output folder does not contain index.html.
• The GitHub App cannot read the repository.
• A manual private GitHub repository is missing a valid project-scoped token.