# Variable Resolution Rules

Source: https://www.jawsdeploy.net/guides/variable-resolution-rules

The most specific matching value wins: step, then target, then tag, then environment, then the project default, then the workspace.

When a variable has multiple values across scopes, Jaws Deploy resolves by **specificity**. The most specific matching scope wins.

## The specificity order

From most specific (highest priority) to least specific:

## First match in this list wins

- **Step-specific** value (scope: the deployment step currently running).
- **Target-specific** value (scope: exact target).
- **Tag-specific** value (scope: tag that the current target carries).
- **Environment-specific** value (scope: current environment).
- **Project-default** value (scope: project, no other constraints).
- **Workspace-level** value (scope: workspace, no other constraints).

## Step-scoped values

A variable value can be pinned to one or more **project steps** with a step filter. When that step runs, its value overrides everything else for the same variable, including a target-specific value, and no other step sees it. This is the most specific scope there is.

Reach for it when a single step needs a different value than the rest of the process: a longer command timeout for the migration step, a different path for the warm-up step, a feature flag flipped only while one step runs. The variable keeps its name, so you avoid inventing a parallel `ConnectionStringForMigrations` and remembering to use it in one place.

## Two matches at the same level

If two values match with the same specificity, the deployment fails instead of picking one. The usual cause is two tag-scoped values where the target carries both tags. Add another scope to one of the values, or change the tags so only one matches.

Scopes add up: a value scoped to an environment and a tag beats a value scoped to the tag alone, and any target-scoped value beats both.

## How a deployment resolves a variable

Target `web-prd-eu-01` is in environment `Production` with tags `role:web` and `region:eu`. The deployment process has a `Warm cache` step.

```
Variable: Cache.Endpoint

Defined values:
  - scope: project                            -> "localhost:6379"
  - scope: env=Production                     -> "prod-cache:6379"
  - scope: env=Production, tag=region:eu      -> "prod-cache-eu:6379"
  - scope: target=web-prd-eu-01               -> "override-cache:6379"
  - scope: step=Warm cache                    -> "warmups-cache-eu:6379"

Resolution for the 'Warm cache' step on web-prd-eu-01:
  -> "warmups-cache-eu:6379"   # the step value wins, even over the target value

Resolution for any other step on web-prd-eu-01:
  -> "override-cache:6379"     # target-specific wins

Resolution for deployment to web-prd-us-01 (no override):
  -> "prod-cache:6379"         # env wins (no tag match for region:eu)
```

## When to use each scope

Use the project default for sensible defaults and environments for most differences. Use tags for cross-cutting concerns such as region or role. Use a target scope only for one-off overrides, for example during an incident. If target-scoped values pile up, they probably belong on a tag. Use a step scope when one step needs a different value from the rest of the process. Keep these few, because a value only one step can see is easy to forget.