# 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:

```mermaid
flowchart LR;
    source["Specify where code lives<br/>and how to build it."]
    build["A deployable build"]
    a["Service A"]
    b["Service B"]
    source -->|"Creates"| build
    build edge1@-->|"Deploys"| a
    build edge2@-->|"Deploys"| b
    edge1@{animation: slow}
    edge2@{animation: slow}
    class source success;
```

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:

1. Create a *build source* to define what you want a service to deploy.
2. Link services to that build source.
3. 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:

```mermaid
flowchart LR;
    source["<strong>Example build source</strong><br/>A repo + branch + build command"]
    build["<strong>Build</strong><br/>An immutable, reusable output"]
    staging["api-staging"]
    prod["api-prod"]
    worker["api-worker"]
    source -->|"Creates"| build
    build edge1@-->|"Deploys"| staging
    build edge2@-->|"Deploys"| prod
    build edge3@-->|"Deploys"| worker
    edge1@{animation: slow}
    edge2@{animation: slow}
    edge3@{animation: slow}
    class source success;
```

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](#auto-deploy-to-linked-services) enabled.

> *Render doesn't create builds for image-backed build sources.*
>
> As with [services](/deploying-an-image), 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:

**Tab: API**

1. Using the [Render API](api), send a request to the [Create a build source](https://api-docs.render.com/reference/create-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
         }
       ]
     }'
   ```

2. Next, [link your new build source to services](#link-services-to-a-build-source).

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

**Tab: Blueprint (render.yaml)**

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

   ```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](#build-source-fields).

2. If you are setting up a Git-backed source, [configure your build-time environment](#configure-the-build-environment) to make sure your builds have everything they need.

   Image-backed build sources can skip this step because they are prebuilt.

3. [Link services to your build source](#link-services-to-a-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:

**Tab: API**

Use the [Trigger a build](https://api-docs.render.com/reference/trigger-build-source-build) API endpoint:

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

**Tab: Blueprint (render.yaml)**

Whenever your build source's code or configuration changes, Render creates a build and deploys it to linked services with [auto-deploy](#auto-deploy-to-linked-services) 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](#auto-deploy-to-linked-services) enabled.

### Update a build source

#### Update source settings

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

**Tab: Dashboard**

1. From your workspace home in the [Render Dashboard](https://dashboard.render.com), click *Build Sources* in the left pane, then select the build source you want to update.
2. On the *Settings* page, click *Edit* next to the setting you want to change.
3. Save your changes, and Render automatically rolls them out to linked services with [auto-deploy](#auto-deploy-to-linked-services) enabled.

**Tab: API**

1. Use the [Update a build source](https://api-docs.render.com/reference/update-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.

2. [Trigger a build](#trigger-a-build) to roll out your changes to linked services with [auto-deploy](#auto-deploy-to-linked-services) enabled.

**Tab: Blueprint (render.yaml)**

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](#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:

**Tab: Dashboard**

1. From your workspace home in the [Render Dashboard](https://dashboard.render.com), click *Build Sources* in the left pane, then select the build source you want to edit.
2. 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](#auto-deploy-to-linked-services) enabled.

**Tab: API**

You can use the [Update environment variables](https://api-docs.render.com/reference/update-env-vars-for-build-source) 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](https://api-docs.render.com/reference/retrieve-build-source-env-var), [Add or update environment variable](https://api-docs.render.com/reference/update-build-source-env-var), and [Delete environment variable](https://api-docs.render.com/reference/delete-build-source-env-var) endpoints.
- Manage secret files with the [List secret files](https://api-docs.render.com/reference/list-secret-files-for-build-source), [Update secret files](https://api-docs.render.com/reference/update-secret-files-for-build-source), [Retrieve secret file](https://api-docs.render.com/reference/retrieve-build-source-secret-file), [Add or update secret file](https://api-docs.render.com/reference/add-or-update-build-source-secret-file), and [Delete secret file](https://api-docs.render.com/reference/delete-build-source-secret-file) endpoints.
- Link or unlink an environment group with the [Link environment group](https://api-docs.render.com/reference/link-env-group-to-build-source) and [Unlink environment group](https://api-docs.render.com/reference/unlink-env-group-from-build-source) endpoints.

After configuring the build environment, [*trigger a build*](#trigger-a-build) to roll out your changes to linked services with [auto-deploy](#auto-deploy-to-linked-services) enabled.

**Tab: Blueprint (render.yaml)**

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](#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](rollbacks#build-retention).

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

**Tab: Dashboard**

During early access, you can view the following in the [Render Dashboard](https://dashboard.render.com):

- 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.

**Tab: API**

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

- [List build sources](https://api-docs.render.com/reference/list-build-sources) in your workspace.
- [Retrieve a build source](https://api-docs.render.com/reference/get-build-source) to view a specific source.
- [List builds in a build source](https://api-docs.render.com/reference/list-builds-in-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:

**Tab: Dashboard**

1. From your workspace home in the [Render Dashboard](https://dashboard.render.com), click *Build Sources* in the left pane, then select the build source you want to delete.
2. On the *Settings* page, go to the bottom of the page and click *Delete Build Source*.
3. Follow the on-screen instructions to confirm the deletion.

**Tab: API**

Use the [Delete a build source](https://api-docs.render.com/reference/delete-build-source) API endpoint:

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

**Tab: Blueprint (render.yaml)**

Blueprints don't support deleting a build source directly.

To remove a build source from a Blueprint:

1. Remove the build source and all references to it from your Blueprint.
2. Apply your Blueprint to unlink your services.
3. 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:

**Tab: Dashboard**

To link an _existing_ service to an _existing_ build source:

1. Navigate to the service in the [Render Dashboard](https://dashboard.render.com).
2. On the *Settings* page, under *Build*, click *Edit*.
3. Select the *Existing Build Source* tab and choose a build source.
4. Click *Deploy*.

**Tab: API**

#### Linking new services

Using the [Create service](https://api-docs.render.com/reference/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](https://api-docs.render.com/reference/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`.

**Tab: Blueprint (render.yaml)**

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

```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](#trigger-a-build) at any time.

After linking a service to a build source, that service's [auto-deploy setting](/deploys#configuring-auto-deploys) 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](/deploys#integrating-with-ci) pass. |
| *Off* | The service doesn't deploy automatically. You must [manually deploy builds](#deploy-a-specific-build) 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:

**Tab: API**

Use the [Trigger deploy](https://api-docs.render.com/reference/create-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:

```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`](blueprint-spec#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 |
| --- | --- |
| `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`](#link-services-to-a-build-source). 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](#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](#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](#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. |


---

##### Appendix: Glossary definitions

###### region

Each Render service runs in one of the following regions: *Oregon*, *Ohio*, *Virginia*, *Frankfurt*, or *Singapore*.

Services in the same region can communicate over their *private network*.

Related article: https://render.com/docs/regions.md

###### Render Blueprints

Render's infrastructure-as-code model.

Configure multiple related services and datastores in a single YAML file. Render automatically syncs any changes you push.

Related article: https://render.com/docs/infrastructure-as-code.md