# Path Configurations (Change-Based Triggers)

> **Related Guides:**
>
> * [Creating New Firefly Workflows](/detailed-guides/workflows/creating-workflows.md): How to create a workspace and set the working directory.
> * [Triggering Workspace Deployment](/detailed-guides/workflows/trigger-deploy.md): Manually triggering a deployment from the UI.
> * [Creating Guardrail Rules](/detailed-guides/workflows/creating-guardrail-rules.md): Policy enforcement applied to runs created by any trigger.

Every Firefly workspace is associated with a code repository and an optional **working directory** — the path within the repository where the workspace's IaC configuration lives. By default, a workspace runs only when files inside its working directory change.

**Path Configurations** extend that behavior by letting a workspace declare interest in additional file paths *outside* its working directory. When a push or pull request modifies any matching file, Firefly triggers a run on the workspace — even if no file inside the working directory itself changed.

This is especially useful for:

* **Monorepos**, where a single repository hosts many workspaces alongside shared Terraform modules and variable files.
* **Cross-repository module dependencies**, where a workspace consumes modules or configuration that live in a different repository entirely.
* **Centralized configuration**, where files such as `global.tfvars`, organization tag defaults, or compliance policies are maintained in one place and consumed by many workspaces.

## How Path Configurations Work

A workspace evaluates two sources of trigger paths on every incoming VCS event:

1. **Working directory** — the workspace's own root module path, set when the workspace is created. Any change to a file under this path triggers a run on the workspace.
2. **Path configurations** — one or more additional `{repository, path}` entries declared on the workspace. Any change to a file matched by an entry triggers a run on the workspace.

A match against **either** the working directory or any single path configuration is sufficient to trigger the run. Path configurations are **trigger-only**: when a run is triggered, the runner still executes from the workspace's working directory. The matched paths are only used to decide *whether* to trigger; they do not change *what* is executed.

### Run Type by Event

| VCS event                                                 | Resulting run                                   |
| --------------------------------------------------------- | ----------------------------------------------- |
| Push to the workspace's tracked branch                    | Tracked run (`plan` and, optionally, `apply`)   |
| Pull request opened or updated against the tracked branch | Proposed run (`plan` only — never auto-applies) |
| Push to any other branch                                  | No run                                          |

Standard workspace settings — *Run on Pull Request* and *Run on Merge* — still apply. A path configuration does not bypass those toggles; it simply broadens the set of file paths that count as a "change to this workspace".

## When to Use a Path Configuration

Use a path configuration when changes to files *outside* a workspace's working directory should still trigger a run on that workspace.

**Common scenarios:**

* The workspace consumes a shared Terraform module from another folder in the same repository (e.g., `modules/shared-vpc/`), and you want to re-plan the workspace whenever that module changes.
* The workspace reads from a centralized variables file (e.g., `config/global-settings.tfvars`) maintained outside the working directory.
* The workspace consumes a module hosted in a *different* repository entirely.
* You want a single change in a foundational file to trigger plans across many workspaces in a monorepo.

**When *****not***** to use a path configuration:**

* The path you want to watch is the working directory of *another* workspace in the same account. In that case, the right tool is a **workspace dependency** — Firefly will refuse to register a path configuration that overlaps another workspace's working directory and will direct you to use a dependency instead.
* You want to trigger the entire repository on every commit. Path configurations cannot point to the repository root.

## Path Pattern Syntax

A path configuration entry consists of:

* **VCS Repository** — the repository to watch. This can be the workspace's own repository or any other repository connected to your Firefly account through a VCS integration.
* **Path Pattern** — a single path within that repository.
* **Execution Type** — what to run when this entry matches (see [Execution Type per Entry](#execution-type-per-entry)).

Three pattern forms are supported:

| Pattern form           | Example                         | Matches                                                                                                                  |
| ---------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Directory prefix**   | `modules/shared-vpc`            | Any file at any depth under `modules/shared-vpc/` (e.g., `modules/shared-vpc/main.tf`, `modules/shared-vpc/nested/x.tf`) |
| **Exact file**         | `config/global-settings.tfvars` | Exactly that file path                                                                                                   |
| **Recursive wildcard** | `modules/**`                    | Any file at any depth under `modules/`                                                                                   |

Paths are relative to the repository root. A leading `/` is accepted but optional — `modules/shared-vpc` and `/modules/shared-vpc` are equivalent.

### Pattern Rules

* **Single-star wildcards are not supported.** A pattern containing a bare `*` (for example `config/*.tfvars`) is rejected. Use `**` for recursive matching, or specify a directory prefix.
* **Repository-root patterns are not allowed.** The values `""`, `"/"`, and `"**"` are rejected because they would match every file in the repository — equivalent to setting the workspace's working directory to the repository root. Path configurations must always point to a specific subdirectory, file, or sub-tree.
* **Multiple entries are supported.** A workspace can declare multiple path configuration entries; a match on **any** single entry triggers the run.

## Configuring Path Configurations from the UI

Path configurations are managed on the workspace itself, alongside the other trigger and execution settings.

### Step 1: Open the Workspace Trigger Settings

Navigate to **Workflows → Workspaces**, open the workspace, and click **Edit**. Path configurations appear under the workspace's trigger configuration.

### Step 2: Add a Path Configuration Entry

Click **Add New** and provide the four fields:

* **VCC** — pick an integration from the account's connected VCS integrations.
* **Repository** — pick an integration from the account's connected VCS integrations.
* **Path** — select the relevant repository that contains the directory you wish the workspace to track and execute a run.
* **Execution Type** — choose **Plan** or **Plan and Apply**.

You can add additional entries the same way. The UI initially caps the number of entries per workspace at **2** as a UX guardrail; the backend supports more.

### Step 3: Save

Click **Save**. Validation runs at submit time as well — if any entry is invalid, the entire save is rejected and the offending entry is highlighted.

To remove an entry, open the workspace edit form and click the **delete** icon next to the entry. To edit an entry, change its fields and save.

## Execution Type per Entry

Each path configuration entry declares its own **Execution Type**, which controls what happens when *that specific entry* matches a changed file:

| Execution Type     | Behavior on tracked run                                                                                         |
| ------------------ | --------------------------------------------------------------------------------------------------------------- |
| **Plan**           | The workspace runs `plan` only. The run never enters `apply`, regardless of the workspace's auto-apply setting. |
| **Plan and Apply** | The workspace follows the workspace's standard apply policy: auto-apply if enabled, manual approval if not.     |

Use `plan` for change-detection on files where an automatic apply would be undesirable (for example, a shared variables file that several teams modify), and `plan_and_apply` for paths whose changes should follow your normal deployment cadence.

### Multiple Matches in the Same Run

If a single commit modifies files matched by **more than one** path configuration entry on the same workspace, only one run is created and the **most permissive** execution type wins: `plan_and_apply` overrides `plan`. To enforce stricter behavior for a particular path, split the work across two workspaces with non-overlapping entries.

### Approval Gating

Whether a `plan_and_apply` run requires manual approval before applying is governed by the **workspace-level** apply rule:

* Workspaces with **Auto Apply** enabled apply automatically after a successful plan.
* Workspaces with **Manual Apply** require an explicit approval before `apply` proceeds.

Approval gating is intentionally a property of the workspace as a whole, not a per-entry setting. This keeps the workspace's run history coherent — every run on the workspace follows the same approval policy.

### Pull Request Behavior

A path configuration that matches on a pull request always produces a **proposed run** (plan only). The execution type of the matched entry does not change this — proposed runs never auto-apply, regardless of `executionType`.

## Validation and Conflicts

Path configurations are validated both as you type in the UI (inline feedback) and again on save. The same rules apply via the API.

| Rule                                                                        | Result if violated                                                                                                                                                                                                                                        |
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Path is empty, missing, or contains only `/` or `**`                        | Rejected — a path configuration must point to a specific subdirectory, file, or sub-tree (not the repository root).                                                                                                                                       |
| Pattern contains a single-star (`*`) wildcard                               | Rejected — only `**` recursive wildcards and directory/file paths are supported.                                                                                                                                                                          |
| VCS repository is not connected to the account                              | Rejected — the selected repository must belong to a VCS integration the account can access.                                                                                                                                                               |
| Path matches the working directory of another workspace in the same account | Rejected — Firefly suggests using a [workspace dependency](/detailed-guides/workflows/creating-workflows.md) instead, since a change to a path that *is* another workspace's root is more naturally expressed as "trigger that workspace, then this one". |
| Duplicate `{repository, path}` entries within the same workspace            | Deduplicated automatically.                                                                                                                                                                                                                               |

When the validator rejects an entry, the message identifies the offending field and, where relevant, the conflicting workspace by name so you can navigate directly to it.

## Run Titles for Path-Triggered Runs

Runs that fire because of a path configuration match carry a self-describing title in the workspace's run history, so you can see at a glance *why* a given run was created without opening it.

```
Triggered by Path Configuration trigger - <integration>:<repo>:<path>
```

When more than one entry matched, all matching entries are listed, comma-separated:

```
Triggered by Path Configuration trigger - Github:org/infra-modules:modules/shared-vpc, Github:org/infra-modules:config/global.tfvars
```

Runs triggered by changes to the workspace's own working directory keep their existing commit-message title.

## Multi-Workspace Behavior

In a monorepo with many workspaces, a single commit can match the working directories or path configurations of several workspaces simultaneously. In that case Firefly creates one run per matching workspace, and runs that are independent of each other execute in parallel on the assigned runner pool.

## VCS Provider Support

Path configurations work transparently with all supported VCS integrations:

* GitHub (and GitHub Enterprise)
* GitLab
* Bitbucket
* Azure DevOps

No VCS-specific configuration is required — webhook delivery, push/PR detection, and commit-status reporting all behave the same as for working-directory-triggered runs. See [Integrating Version Control](/integrations/version-control.md) for integration setup.

## Examples

### Example 1: Shared Module in a Monorepo

A workspace `prod-networking` lives at `terraform/prod/networking/` and consumes a module at `modules/shared-vpc/` in the same repository.

| Field                                  | Value                                       |
| -------------------------------------- | ------------------------------------------- |
| Working Directory                      | `terraform/prod/networking`                 |
| Path Configuration #1 — Repository     | `org/prod` (the workspace's own repository) |
| Path Configuration #1 — Path           | `modules/shared-vpc`                        |
| Path Configuration #1 — Execution Type | `plan_and_apply`                            |

A push that modifies `terraform/prod/networking/main.tf` triggers a run because of the working directory. A push that modifies `modules/shared-vpc/main.tf` also triggers a run, because of the path configuration.

### Example 2: Cross-Repository Module Consumer

The same `prod-networking` workspace also consumes a module from a different repository, `org/infra-modules`, on the same VCS integration.

| Field                                  | Value                       |
| -------------------------------------- | --------------------------- |
| Working Directory                      | `terraform/prod/networking` |
| Path Configuration #1 — Repository     | `org/prod`                  |
| Path Configuration #1 — Path           | `modules/shared-vpc`        |
| Path Configuration #1 — Execution Type | `plan_and_apply`            |
| Path Configuration #2 — Repository     | `org/infra-modules`         |
| Path Configuration #2 — Path           | `modules/shared-vpc/**`     |
| Path Configuration #2 — Execution Type | `plan_and_apply`            |

A change in either repository now triggers `prod-networking`. The runner still operates from `terraform/prod/networking` in `org/prod`; the cross-repository entry only acts as a trigger.

### Example 3: Plan-Only Watch on a Variables File

The workspace watches a centralized variables file, but you want a human to review any change before applying.

| Field                               | Value                    |
| ----------------------------------- | ------------------------ |
| Path Configuration — Repository     | `org/platform-config`    |
| Path Configuration — Path           | `defaults/global.tfvars` |
| Path Configuration — Execution Type | `plan`                   |

A change to `defaults/global.tfvars` triggers a `plan`-only run. The workspace's own `apply` cadence is unaffected — apply still runs on changes to the working directory or to entries declared with `plan_and_apply`.

## Limitations

* A workspace can have up to **2** path configuration entries.
* Path configurations are trigger-only. They do not modify the working directory, alter what files the runner sees, or pass values into the run.
* Patterns must point to a path below the repository root. To trigger on every change in a repository, set the workspace's working directory to the repository root instead.
* Single-star (`*`) wildcards are not supported in MVP. Use `**` for recursive matching or a directory/file path.

## Related Guides

* [Creating New Firefly Workflows](/detailed-guides/workflows/creating-workflows.md) — Workspace creation, working directory, and trigger basics.
* [Triggering Workspace Deployment](/detailed-guides/workflows/trigger-deploy.md) — Manually triggering a workspace from the UI.
* [Integrating Version Control](/integrations/version-control.md) — Connecting a VCS provider so push and pull-request events reach Firefly.
* [Creating Guardrail Rules](/detailed-guides/workflows/creating-guardrail-rules.md) — Policies evaluated on every run, including those triggered by path configurations.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.firefly.ai/detailed-guides/workflows/path-configurations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.