Create the isolated context layer

Run all of these from the root of your dbt project (the directory containing dbt_project.yml).

1. Create the context directory

mkdir -p context/assets

You'll end up with context/.bruin.yml, context/pipeline.yml, and a populated context/assets/ after the next step.

2. Write a scoped .bruin.yml

Drop this into context/.bruin.yml. Replace the project ID with your own warehouse's:

# context/.bruin.yml
default_environment: default
environments:
  default:
    connections:
      google_cloud_platform:
        - name: contoso_dbt_bq
          project_id: bruin-playground-arsalan
          location: EU
          use_application_default_credentials: true

This connection uses Application Default Credentials - the same gcloud auth application-default login session you already use for dbt. No service account keyfile to rotate, no secret to gitignore, and the AI agent inherits your identity at query time.

Gotcha - wrong field name. The field is use_application_default_credentials, not use_default_credentials. The latter is silently ignored and Bruin will look for a keyfile that isn't there.

Gotcha - repo-root config. By default, bruin loads .bruin.yml from the repo root. If the root config has a broken or unrelated connection, every command will use that file instead of yours. Always pass --config-file context/.bruin.yml so Bruin loads this scoped file instead.

For Redshift, ClickHouse, or Postgres, swap the connection block. Examples:

# Postgres
connections:
  postgres:
    - name: contoso_dbt_pg
      host: db.example.internal
      port: 5432
      username: analyst_ro
      password: ${POSTGRES_PASSWORD}
      database: contoso
      ssl_mode: require

# Redshift
connections:
  redshift:
    - name: contoso_dbt_rs
      host: contoso.abcd1234.eu-west-1.redshift.amazonaws.com
      port: 5439
      username: analyst_ro
      password: ${REDSHIFT_PASSWORD}
      database: contoso

# ClickHouse
connections:
  clickhouse:
    - name: contoso_dbt_ch
      host: contoso.eu-central-1.aws.clickhouse.cloud
      port: 9440
      username: analyst_ro
      password: ${CLICKHOUSE_PASSWORD}
      database: default
      secure: true

3. Write a pipeline.yml

Drop this into context/pipeline.yml:

# context/pipeline.yml
name: contoso_dbt_context
schedule: daily
start_date: "2016-01-01"
default_connections:
  google_cloud_platform: "contoso_dbt_bq"

The default_connections block makes the connection name implicit for every asset Bruin generates in the next step - you won't have to repeat connection: contoso_dbt_bq in 40 separate YAMLs. For non-BigQuery warehouses, use the matching key (postgres, redshift, clickhouse).

The pipeline never runs anything - but Bruin still treats it as a pipeline, which gives you bruin validate, lineage, and docs generation for free.

4. Test the connection

Confirm Bruin can reach the warehouse before going further:

bruin connections ping --config-file context/.bruin.yml contoso_dbt_bq

Expected output:

Successfully connected to 'contoso_dbt_bq'.

If you see an authentication error, run gcloud auth application-default login (BigQuery) or check your env vars (Postgres / Redshift / ClickHouse) and try again.

Gotcha - bruin connections test loads everything. It tests every connection in the loaded config, so a single broken connection breaks the test. Always pass --config-file context/.bruin.yml to scope it to this file.