diff --git a/website/docs/reference/dbt-jinja-functions/packages.yml.md b/website/docs/reference/dbt-jinja-functions/packages.yml.md new file mode 100644 index 00000000000..dc405f1cc90 --- /dev/null +++ b/website/docs/reference/dbt-jinja-functions/packages.yml.md @@ -0,0 +1,62 @@ +--- +title: "About packages.yml context" +sidebar_label: "packages.yml context" +id: "packages.yml context" +description: "Use these context methods to configure dependencies in the packages.yml file." +--- + +The following context methods and variables are available when configuring a `packages.yml` file. + +**Available context methods:** +- [env_var](/reference/dbt-jinja-functions/env_var) + - Use `env_var()` in any dbt YAML file that supports Jinja. Only `packages.yml` and `profiles.yml` support environment variables for [secure values](/docs/build/dbt-tips#yaml-tips) (using the `DBT_ENV_SECRET_` prefix). +- [var](/reference/dbt-jinja-functions/var) (Note: only variables defined with `--vars` are available. Refer to [YAML tips](/docs/build/dbt-tips#yaml-tips) for more information) + +**Available context variables:** +- [builtins](/reference/dbt-jinja-functions/builtins) +- [dbt_version](/reference/dbt-jinja-functions/dbt_version) +- [target](/reference/dbt-jinja-functions/target) + +## Example usage + +The following examples show how to use the different context methods and variables in your `packages.yml`. + +Use `builtins` in your `packages.yml`: + +``` +packages: + - package: dbt-labs/dbt_utils + version: "{% if builtins is defined %}0.14.0{% else %}0.13.1{% endif %}" + +``` + +Use `env_var` in your `packages.yml`: + +``` +packages: + - package: dbt-labs/dbt_utils + version: "{{ env_var('DBT_UTILS_VERSION') }}" +``` + +Use `dbt_version` in your `packages.yml`: + +``` +packages: + - package: dbt-labs/dbt_utils + version: "{% if dbt_version is defined %}0.14.0{% else %}0.13.1{% endif %}" + +``` + +Use `target` in your `packages.yml`: + +``` + +packages: + - package: dbt-labs/dbt_utils + version: "{% if target.name == 'prod' %}0.14.0{% else %}0.13.1{% endif %}" + +``` + +## Related docs + +- [Packages](/docs/build/packages) \ No newline at end of file diff --git a/website/sidebars.js b/website/sidebars.js index 7b8a38496e5..451b139cc72 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -1533,7 +1533,7 @@ const sidebarSettings = { type: "generated-index", title: "dbt Jinja functions and context variables", description: - "In addition to the standard Jinja library, we've added additional functions and variables to the Jinja context that are useful when working with a dbt project.", + "In addition to the standard Jinja library, we've added additional functions and variables to the Jinja context that are useful when working with a dbt project. Note that dependencies.yml is not Jinja rendered and therefore does not support Jinja.", slug: "/reference/dbt-jinja-functions-context-variables", }, items: [ diff --git a/website/snippets/_packages_or_dependencies.md b/website/snippets/_packages_or_dependencies.md index 424bf84ca7d..375272cbd9b 100644 --- a/website/snippets/_packages_or_dependencies.md +++ b/website/snippets/_packages_or_dependencies.md @@ -35,7 +35,7 @@ Package dependencies allow you to add source code from someone else's dbt projec - If you only use packages like those from the [dbt Hub](https://hub.getdbt.com/), remain with `packages.yml`. - Use `packages.yml` when you want to download dbt packages, such as dbt projects, into your root or parent dbt project. Something to note is that it doesn't contribute to the dbt Mesh workflow. - Use `packages.yml` to include packages in your project's dependencies. This includes both public packages, such as those from the [dbt Hub](https://hub.getdbt.com/), and private packages. dbt now supports [native private packages](/docs/build/packages#native-private-packages). -- `packages.yml` supports Jinja rendering for historical reasons, allowing dynamic configurations. This can be useful if you need to insert values, like a [Git token method](/docs/build/packages#git-token-method) from an environment variable, into your package specifications. +- [`packages.yml` supports Jinja rendering](/docs/build/dbt-tips#yaml-tips) for historical reasons, allowing dynamic configurations. This can be useful if you need to insert values, like a [Git token method](/docs/build/packages#git-token-method) from an environment variable, into your package specifications. Previously, to use private Git repositories in dbt, you needed to use a workaround that involved embedding a Git token with Jinja. This is not ideal as it requires extra steps like creating a user and sharing a Git token. We’ve introduced support for [native private packages](/docs/build/packages#native-private-packages-) to address this.