Reuse builds across services

Deploy one build across multiple services for consistent, faster deploys.

Build reuse is in limited early access.

During this private beta period, this feature is continuing to evolve and might introduce breaking changes.

By default, each Render service builds independently, even if multiple services deploy code from the same repository or image.

Build reuse lets you deploy the same build across multiple services:

Build reuse cuts redundant build time for services sharing the same source code, and lets you maintain a consistent build environment across multiple services.

How it works

Build reuse works in three steps:

Create a build source to define what you want a service to deploy.
Link services to that build source.
When your build source's underlying code or configuration changes, Render creates a build and deploys it to linked services.

For example, the following diagram shows a build source that creates a new build on each commit and deploys it to every linked service:

Though linked services use the same build, you can still change their runtime configuration.

Build sources

Create a build source to share source code and build configurations across multiple services.

A build source can be either:

Git-backed, built from a repository, branch, and build command, or
Image-backed, deployed from a prebuilt image in an external registry.

Each time you push code changes or update a build source's configuration, Render creates a new build and deploys it to any linked service with auto-deploy enabled.

Render doesn't create builds for image-backed build sources.

As with services, Render uses prebuilt images for image-backed build sources. Instead of building, Render pulls a prebuilt image from your external registry and deploys that image version to linked services.

Create a build source

Build sources belong to a workspace, and after creating one, you can link it to any supported service in your workspace.

Create a build source in any of the following ways:

Using the Render API, send a request to the Create a build source endpoint with everything Render needs to build a service:

bash

curl -s https://api.render.com/v1/build-sources \
  -X POST \
  -H "Authorization: Bearer $RENDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ownerId": "own-cot1234abcd5678efgh",
    "name": "example-build-source",
    "git": {
      "repoUrl": "https://github.com/render-examples/express-hello-world",
      "branch": "main",
      "runtime": "node",
      "buildCommand": "npm install",
      "region": "oregon"
    },
    "envVars": [
      {
        "key": "BUILD_SECRET",
        "generateValue": true
      }
    ]
  }'

Next, link your new build source to services.

If your build source is Git-backed, you can continue to configure your build environment as needed. However, you can't change a build source's region after creating it.

You can define build sources in Blueprints with the buildSources field:

render.yaml

yaml

buildSources:
  # A Git-backed build source
  - name: example-build-source
    git:
      repo: https://github.com/render-examples/express-hello-world
      branch: main
      runtime: node
      buildCommand: npm install
  # An image-backed build source
  - name: example-image-build-source
    image:
      url: docker.io/library/nginx:latest

Each buildSources entry defines a build source. For a full list of supported fields, see Build source fields.

If you are setting up a Git-backed source, configure your build-time environment to make sure your builds have everything they need.

Image-backed build sources can skip this step because they are prebuilt.
Link services to your build source by setting the buildSource field to your source's name.

Trigger a build

Trigger a build for a Git-backed build source in any of the following ways:

Use the Trigger a build API endpoint:

bash

curl -s https://api.render.com/v1/build-sources/bds-d1u4abcd5678efgh1234/builds \
  -X POST \
  -H "Authorization: Bearer $RENDER_API_KEY"

Whenever your build source's code or configuration changes, Render creates a build and deploys it to linked services with auto-deploy enabled.

Image-backed build sources are already prebuilt, so you don't need to trigger builds for them.

When you update your build source's image URL (including its tag or digest) or registry credentials, Render deploys the new image version to linked services with auto-deploy enabled.

Update a build source

Update source settings

Update a build source's settings in any of the following ways:

From your workspace home in the Render Dashboard, click Build Sources in the left pane, then select the build source you want to update.
On the Settings page, click Edit next to the setting you want to change.
Save your changes, and Render automatically rolls them out to linked services with auto-deploy enabled.

Use the Update a build source API endpoint with the fields you want to update:

bash

curl -s https://api.render.com/v1/build-sources/bds-d1u4abcd5678efgh1234 \
  -X PATCH \
  -H "Authorization: Bearer $RENDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"git": {"branch": "production"}}'

Note that you can't update a Git-backed build source's region after creation.

Trigger a build to roll out your changes to linked services with auto-deploy enabled.

You can directly update the values in the buildSources field:

yaml

buildSources:
  - name: example-build-source
    git:
      repo: https://github.com/render-examples/express-hello-world
      branch: main
      runtime: node
      buildCommand: npm install
      buildFilter:
        paths:
          - app.js
          - package.json

You can edit most build source fields, and switch the source type between git and image.

Configure the build environment

Build source configuration only affects builds.

Although linked services share the same build, each retains its own runtime configuration, such as environment variables and a start command.

If you need an environment variable during build and runtime, define it on both the build source and the linked service.

Set up a build source's environment before you link services, so your first build has everything it needs.

After creating a build source, you can modify its build environment in any of the following ways:

From your workspace home in the Render Dashboard, click Build Sources in the left pane, then select the build source you want to edit.
On the Environment page, you can manage environment variables, secret files, and environment groups.

After you save any changes, Render automatically creates a new build and deploys it to linked services with auto-deploy enabled.

You can use the Update environment variables API endpoint to replace all of the environment variables for a build source at once:

bash

# Replace the source's env vars (bulk)
curl -s https://api.render.com/v1/build-sources/bds-d1u4abcd5678efgh1234/env-vars \
  -X PUT \
  -H "Authorization: Bearer $RENDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"key": "NODE_ENV", "value": "production"}]'

For finer-grained changes, you can also use the following endpoints:

Manage individual variables with the Retrieve environment variable, Add or update environment variable, and Delete environment variable endpoints.
Manage secret files with the List secret files, Update secret files, Retrieve secret file, Add or update secret file, and Delete secret file endpoints.
Link or unlink an environment group with the Link environment group and Unlink environment group endpoints.

After configuring the build environment, trigger a build to roll out your changes to linked services with auto-deploy enabled.

You can edit a build source's environment variables with the git.envVars field:

yaml

buildSources:
  - name: example-build-source
    git:
      repo: https://github.com/render-examples/express-hello-world
      branch: main
      runtime: node
      buildCommand: npm install
      envVars:
        - key: NODE_ENV
          value: production
        - key: APP_SECRET
          generateValue: true
        - fromGroup: my-env-group

For a full list of supported values, see envVars fields.

Build sources can update environment variables, but they can't delete an existing variable or unlink an environment variable group.

View build sources and builds

Each source keeps a limited number of recent builds, based on your workspace's build retention.

View build sources and their builds in any of the following ways:

During early access, you can view the following in the Render Dashboard:

The Build Sources page lists your workspace's build sources.
- Each build source lists its build history, logs, and source repository or image URL.
Each linked service displays its build source on its Settings page, in the Build section.

Use the following API endpoints to view build sources and their builds:

List build sources in your workspace.
Retrieve a build source to view a specific source.
List builds in a build source to see the builds a source created.

Delete a build source

You can't delete a build source while any service still links to it.

After removing all linked services, you can delete a build source by doing any of the following:

From your workspace home in the Render Dashboard, click Build Sources in the left pane, then select the build source you want to delete.
On the Settings page, go to the bottom of the page and click Delete Build Source.
Follow the on-screen instructions to confirm the deletion.

Use the Delete a build source API endpoint:

bash

curl -s https://api.render.com/v1/build-sources/bds-d1u4abcd5678efgh1234 \
  -X DELETE \
  -H "Authorization: Bearer $RENDER_API_KEY"

Blueprints don't support deleting a build source directly.

To remove a build source from a Blueprint:

Remove the build source and all references to it from your Blueprint.
Apply your Blueprint to unlink your services.
Then delete the build source through the Dashboard or API.

Link services to a build source

Manage build configuration on build sources, not services.

After linking a service, manage its build settings using the build source.

You can link build sources to web services, private services, and background workers.

A linked service inherits its build source's configuration, including the build's runtime and build command. If the source uses a native runtime (such as Node, Python, or Go), the service must define its own start command.

Link a service to a build source in any of the following ways:

To link an existing service to an existing build source:

Navigate to the service in the Render Dashboard.
On the Settings page, under Build, click Edit.
Select the Existing Build Source tab and choose a build source.
Click Deploy.

Linking new services

Using the Create service API endpoint, set buildSourceId in serviceDetails:

bash

curl -s https://api.render.com/v1/services \
  -X POST \
  -H "Authorization: Bearer $RENDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "web_service",
    "name": "example-service",
    "ownerId": "own-cot1234abcd5678efgh",
    "serviceDetails": {
      "buildSourceId": "bds-d1u4abcd5678efgh1234",
      "envSpecificDetails": {
        "startCommand": "node app.js"
      }
    }
  }'

Omit the fields that your build source now provides, such as repo, branch, buildFilter, runtime, and build-related envSpecificDetails.

Linking existing services

Using the Update service API endpoint, set buildSourceId to replace the service's build configuration with the build source's:

bash

curl -s https://api.render.com/v1/services/srv-cabc1234def5678ghij \
  -X PATCH \
  -H "Authorization: Bearer $RENDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"buildSourceId": "bds-d1u4abcd5678efgh1234"}'

Omit the fields that your build source now provides, such as repo, branch, buildFilter, runtime, and build-related envSpecificDetails.

Set buildSource on a service, using the build source's name:

render.yaml

yaml

buildSources:
  - name: example-build-source
    git:
      repo: https://github.com/render-examples/express-hello-world
      branch: main
      runtime: node
      buildCommand: npm install

services:
  - type: web
    name: example-service
    buildSource: example-build-source
    startCommand: node app.js

On your newly linked service, omit the fields that the source now provides, such as repo, branch, buildFilter, and runtime.

Auto-deploy to linked services

Git-backed build sources need an auto-deploying service to build automatically.

You can trigger builds manually at any time.

After linking a service to a build source, that service's auto-deploy setting determines when Render deploys new builds:

Option	Description
On Commit	The service deploys each new build as soon as it's created.
After CI Checks Pass	The service deploys the build only after the commit's CI checks pass.
Off	The service doesn't deploy automatically. You must manually deploy builds to it.

Unlink a service from a build source

To unlink a service, replace its build source with its own build configuration (a repository or image).

For example, in a Blueprint, you can replace a service's buildSource field with its own build configuration (repo, branch, and so on).

Deploy a specific build

You can deploy a specific, successful build to a linked service using the API:

Use the Trigger deploy API endpoint with the build's ID:

bash

curl -s https://api.render.com/v1/services/srv-cabc1234def5678ghij/deploys \
  -X POST \
  -H "Authorization: Bearer $RENDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"buildId": "bui-d2f8abcd5678efgh1234"}'

Omit the value of buildId to deploy your build source's latest build. If a build source doesn't have a build when you make this request, Render creates one and deploys it.

Current limitations

Build reuse is in early access, so the following limitations apply during this period:

Build sources don't support cron jobs, pull request previews, static sites, or workflows.
A build source is tied to a single region, and you can only link it to services in that same region.
You can configure build sources with the API and Blueprints.
- Dashboard support is rolling out progressively, and we plan to expand support to the CLI and Terraform.
Image-backed sources have minimal support.
- Build sources that use images from external registries don't build, so they don't track build logs or history.

Feedback

Build reuse is in early access, and we're eager to hear your feedback. Share it with your Render account contact or in your shared Slack channel.

Blueprint field reference

Blueprints can create new build sources with the buildSources field.

The following example creates a build source and links it to two services:

Expand for full Blueprint example

yaml

buildSources:
- name: example-build-source
  git:
    repo: https://github.com/render-examples/express-hello-world
    branch: main
    runtime: node
    buildCommand: npm install
    envVars:
    - key: EXAMPLE_ENV_VAR
      value: GOOD_VALUE

services:
# These services are linked to a build source.
- name: hello-from-source-a
  type: web
  plan: free
  buildSource: example-build-source
  startCommand: node app.js

- name: hello-from-source-b
  type: web
  plan: free
  buildSource: example-build-source
  startCommand: node app.js


# This service does not use a build source.
- name: no-build-source
  type: web
  plan: free
  runtime: node
  repo: https://github.com/render-examples/express-hello-world
  branch: main
  buildCommand: npm install
  startCommand: node app.js

You can define build sources at the workspace level, in a project, or under ungrouped:

yaml

projects:
  - name: hello-world-project
    buildSources:
      - name: example-build-source
        git:
          repo: https://github.com/render-examples/express-hello-world
          runtime: node
          buildCommand: npm install

ungrouped:
  buildSources:
    - name: another-example-build-source
      image:
        url: docker.io/library/nginx:latest

Build source fields

Field Description

Field	Description
`name`	Required. A unique name for the build source within your workspace. Services can link to your build source with its name by setting `buildSource`. Changing the name creates or adopts a different source rather than renaming the existing one.
`git`	Create a build source that uses a Git repository. A build source can use either `git` or `image`. See `git` fields for build configuration options.
`image`	Create a build source that uses an image from an external registry. A build source can use either `git` or `image`. See `image` fields for build configuration options.

`name`

Required. A unique name for the build source within your workspace.

Services can link to your build source with its name by setting buildSource.

Changing the name creates or adopts a different source rather than renaming the existing one.

`git`

Create a build source that uses a Git repository.

A build source can use either git or image.

See git fields for build configuration options.

`image`

Create a build source that uses an image from an external registry.

A build source can use either git or image.

See image fields for build configuration options.

`git` fields

Configure a Git-backed build source with a git block:

Field	Description
`repo`	Required. The URL of the Git repository to build from.
`branch`	The branch to build. Defaults to the repository's default branch.
`runtime`	Required. The runtime for the build. Supported values are `docker`, `elixir`, `go`, `node`, `python`, `ruby`, and `rust`.
`buildCommand`	The command Render runs to build the source.
`buildFilter`	Limits which file changes trigger a build. If `buildFilter` is present, you must specify either `paths` inclusion patterns or `ignoredPaths` exclusion patterns.
`envVars`	A list of build-time environment variables. See `envVars` fields.
`rootDir`	The directory Render treats as the root when building. Useful for monorepos.
`baseDir`	The Docker build-context directory, relative to `rootDir`. Only applicable if the `runtime` is `docker`. Defaults to `rootDir`, or to the repository root if `rootDir` is not set.
`region`	The region where your builds take place. Defaults to `oregon`. You can't modify this value after creation. Supported values are `frankfurt`, `ohio`, `oregon`, `singapore`, and `virginia`.
`dockerfilePath`	The path to the build source's `Dockerfile`, relative to `rootDir`. Only applicable if the `runtime` is `docker`. Defaults to `./Dockerfile`.
`registryCredential`	The credential used to pull private Docker base images. Only applicable if the `runtime` is `docker`.

`image` fields

Configure an image-backed build source with an image block:

yaml

buildSources:
  - name: example-image-build-source
    image:
      url: docker.io/library/nginx:latest
      creds:
        fromRegistryCreds:
          name: my-registry-credentials

Field	Description
`url`	Required. The image's URL, including any tag or digest.
`creds`	Credentials for pulling the image from a private registry.
`creds.fromRegistryCreds.name`	Required when `creds` is present. References a registry credential by its Blueprint name.

`envVars` fields

Git-backed build sources can use envVars to configure their build-time environment.

Each keyed entry must use exactly one value source: value, generateValue, sync: false, fromDatabase, or fromService.

Field	Description
`key`	The environment variable's name. Required for every form except `fromGroup`.
`value`	A literal value for the variable.
`generateValue`	Set to `true` to have Render generate a secure value. Render generates the value when the variable is first created and preserves it during later Blueprint syncs.
`sync`	Defaults to `true`. Set to `false` to prompt for the value in the Dashboard when the source is first created instead of storing it in the Blueprint. Render ignores `sync: false` during later updates.
`fromDatabase`	Pulls a value from a Render Postgres database. Provide `name` and `property`.
`fromService`	Pulls a value from another service. Provide `name`, `type`, and exactly one of `property` or `envVarKey`.
`fromGroup`	The name of a workspace-level environment group to link. Links every variable in the group. Can't be combined with `key`, and environment-scoped groups aren't supported.

How it works

Build sources

Create a build source

Trigger a build

Update a build source

Update source settings

Configure the build environment

View build sources and builds

Delete a build source

Link services to a build source

Linking new services

Linking existing services

Auto-deploy to linked services

Unlink a service from a build source

Deploy a specific build

Current limitations

Feedback

Blueprint field reference

Build source fields

name

git

image

git fields

repo

branch

runtime

buildCommand

buildFilter

envVars

rootDir

baseDir

region

dockerfilePath

registryCredential

image fields

url

creds

creds.fromRegistryCreds.name

envVars fields

key

value

generateValue

sync

fromDatabase

fromService

fromGroup

Reuse builds across services

`name`

`git`

`image`

`git` fields

`repo`

`branch`

`runtime`

`buildCommand`

`buildFilter`

`envVars`

`rootDir`

`baseDir`

`region`

`dockerfilePath`

`registryCredential`

`image` fields

`url`

`creds`

`creds.fromRegistryCreds.name`

`envVars` fields

`key`

`value`

`generateValue`

`sync`

`fromDatabase`

`fromService`

`fromGroup`