Deployment environments

Deployment environments in dbt Cloud are crucial for deploying dbt jobs in production and using features or integrations that depend on dbt metadata or results. To execute dbt, environments determine the settings used during job runs, including:

The version of dbt Core that will be used to run your project
The warehouse connection information (including the target database/schema settings)
The version of your code to execute

A dbt Cloud project can have multiple deployment environments, providing you the flexibility and customization to tailor the execution of dbt jobs. You can use deployment environments to create and schedule jobs, enable continuous integration, or more based on your specific needs or requirements.

Learn how to manage dbt Cloud environments

To learn different approaches to managing dbt Cloud environments and recommendations for your organization's unique needs, read dbt Cloud environment best practices.

This page reviews the different types of environments and how to configure your deployment environment in dbt Cloud.

Types of environments

In dbt Cloud, there are two types of environments:

Deployment environment — Determines the settings used when jobs created within that environment are executed.
Development environment — Determines the settings used in the dbt Cloud IDE or dbt Cloud CLI, for that particular project.

Each dbt Cloud project can only have a single development environment but can have any number of deployment environments.

	Development Environments	Deployment Environments
Determines settings for	dbt Cloud IDE or dbt Cloud CLI	dbt Cloud Job runs
How many can I have in my project?	1	Any number

note

For users familiar with development on dbt Core, each environment is roughly analogous to an entry in your profiles.yml file, with some additional information about your repository to ensure the proper version of code is executed. More info on dbt core environments here.

Common environment settings

Both development and deployment environments have a section called General Settings, which has some basic settings that all environments will define:

Setting	Example Value	Definition	Accepted Values
Name	Production	The environment name	Any string!
Environment Type	Deployment	The type of environment	[Deployment, Development]
dbt Version	1.4 (latest)	The dbt version used	Any dbt version in the dropdown
Default to Custom Branch	☑️	Determines whether to use a branch other than the repository’s default	See below
Custom Branch	dev	Custom Branch name	See below

About dbt version

dbt Cloud allows users to select any dbt release. At this time, environments must use a dbt version greater than or equal to v1.0.0; lower versions are no longer supported.
If you select a current version with (latest) in the name, your environment will automatically install the latest stable version of the minor version selected.

Git repository caching

At the start of every job run, dbt Cloud clones the project's Git repository so it has the latest versions of your project's code and runs dbt deps to install your dependencies.

For improved reliability and performance on your job runs, you can enable dbt Cloud to keep a cache of the project's Git repository. So, if there's a third-party outage that causes the cloning operation to fail, dbt Cloud will instead use the cached copy of the repo so your jobs can continue running as scheduled.

dbt Cloud caches your project's Git repo after each successful run and retains it for 8 days if there are no repo updates. It caches all packages regardless of installation method and does not fetch code outside of the job runs.

To enable Git repository caching, select Account settings from the gear menu and enable the Repository caching option.

Example of the Repository caching option

note

This feature is only available on the dbt Cloud Enterprise plan.

Custom branch behavior

By default, all environments will use the default branch in your repository (usually the main branch) when accessing your dbt code. This is overridable within each dbt Cloud Environment using the Default to a custom branch option. This setting have will have slightly different behavior depending on the environment type:

Development: determines which branch in the dbt Cloud IDE or dbt Cloud CLI developers create branches from and open PRs against.
Deployment: determines the branch is cloned during job executions for each environment.

For more info, check out this FAQ page on this topic!

Extended attributes

note

Extended attributes are retrieved and applied only at runtime when profiles.yml is requested for a specific Cloud run. Extended attributes are currently not taken into consideration for Cloud-specific features such as PrivateLink or SSH Tunneling that do not rely on profiles.yml values.

Extended Attributes is a feature that allows users to set a flexible profiles.yml snippet in their dbt Cloud Environment settings. It provides users with more control over environments (both deployment and development) and extends how dbt Cloud connects to the data platform within a given environment.

Extended Attributes is a text box extension at the environment level that overrides connection or environment credentials, including any custom environment variables. You can set any YAML attributes that a dbt adapter accepts in its profiles.yml.

Something to note, Extended Attributes doesn't mask secret values. We recommend avoiding setting secret values to prevent visibility in the text box and logs.

Extended Attributes helps users add profiles.yml attributes to dbt Cloud Environment settings using a free form text box.

If you're developing in the dbt Cloud IDE, dbt Cloud CLI, or orchestrating job runs, Extended Attributes parses through the provided YAML and extracts the profiles.yml attributes. For each individual attribute:

If the attribute exists in another source (such as your project settings), it will replace its value (like environment-level values) in the profile. It also overrides any custom environment variables.
If the attribute doesn't exist, it will add the attribute or value pair to the profile.

Only the top-level keys are accepted in extended attributes. This means that if you want to change a specific sub-key value, you must provide the entire top-level key as a JSON block in your resulting YAML. For example, if you want to customize a particular field within a service account JSON for your BigQuery connection (like 'project_id' or 'client_email'), you need to provide an override for the entire top-level keyfile_json main key/attribute using extended attributes. Include the sub-fields as a nested JSON block.

The following code is an example of the types of attributes you can add in the Extended Attributes text box:

dbname: jaffle_shop      
schema: dbt_alice      
threads: 4

Create a deployment environment

To create a new dbt Cloud development environment, navigate to Deploy -> Environments and then click Create Environment. Select Deployment as the environment type.

Navigate to Deploy -> Environments to create a deployment environment

Set as production environment

In dbt Cloud, each project can have one designated deployment environment, which serves as its production environment. This production environment is essential for using features like dbt Explorer and cross-project references. It acts as the source of truth for the project's production state in dbt Cloud.

Set your production environment as the default environment in your Environment Settings

Semantic Layer

For Semantic Layer-eligible customers, the next section of environment settings is the Semantic Layer configurations. The Semantic Layer setup guide has the most up-to-date setup instructions!

Deployment connection

Warehouse Connections

Warehouse connections are set at the Project level for dbt Cloud accounts, and each Project can have one connection (Snowflake account, Redshift host, Bigquery project, Databricks host, etc.). Some details of that connection (databases/schemas/etc.) can be overridden within this section of the dbt Cloud environment settings.

This section determines the exact location in your warehouse dbt should target when building warehouse objects! This section will look a bit different depending on your warehouse provider.

This section will not appear if you are using Postgres, as all values are inferred from the project's connection.

Deployment credentials

This section allows you to determine the credentials that should be used when connecting to your warehouse. The authentication methods may differ depending on the warehouse and dbt Cloud tier you are on.

Postgres Deployment Credentials Settings

Editable fields

Username: Postgres username to use (most likely a service account)
Password: Postgres password for the listed user
Schema: Target schema

Types of environments​

Common environment settings​

Git repository caching​

Custom branch behavior​

Extended attributes​

Create a deployment environment​

Set as production environment​

Semantic Layer​

Deployment connection​

Editable fields​

Editable fields​

Deployment credentials​

Editable fields​

Editable fields​

Editable fields​

Editable fields​

Editable fields​

Editable fields​

Related docs​

Types of environments

Common environment settings

Git repository caching

Custom branch behavior

Extended attributes

Create a deployment environment

Set as production environment

Semantic Layer

Deployment connection

Editable fields

Editable fields

Deployment credentials

Editable fields

Editable fields

Editable fields

Editable fields

Editable fields

Editable fields

Related docs