> For the complete documentation index, see [llms.txt](https://docs.firefly.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.firefly.ai/detailed-guides/workflows/path-configurations.md).

# 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 — including paths in *different* repositories. When a push modifies any matching file, Firefly triggers a run on the workspace, even if no file inside the workspace's own working directory 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 push 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 push that modifies 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 in the workspace's own repository. The matched paths are only used to decide *whether* to trigger; they do not change *what* is executed.

### Run Type by Event

| VCS event                                                 | Working directory match                       | Path configuration match                       |
| --------------------------------------------------------- | --------------------------------------------- | ---------------------------------------------- |
| Push to the workspace's tracked branch                    | Tracked run (plan and, optionally, apply)     | Tracked run (plan and, optionally, apply)      |
| Pull request opened or updated against the tracked branch | Proposed run (plan only — never auto-applies) | **No run** — path configurations are push-only |
| Push to any other branch                                  | No run                                        | No run                                         |

Path configurations fire on **push events only**. A pull request that changes a path matched by a path configuration does not create a run — this keeps proposed-run noise out of dependent workspaces and reserves PR-time plans for the workspace whose own working directory is being edited. To get plan feedback on a pull request that touches a shared module, work through the workspace that owns that module's working directory (or open the PR against that workspace's repository directly).

A path configuration does not change *how* a run applies. Whether a path-triggered run auto-applies or waits for manual approval is governed by the workspace's existing **Auto Apply** / **Manual Apply** setting, exactly as for a working-directory-driven run. A path configuration only broadens the set of file paths that count as a "change to this workspace" on a push.

### Cross-Repository Triggers

When a path configuration points at a repository other than the workspace's own (a **cross-repository** entry), the trigger is still scoped to the workspace's own repository:

* The run executes against the workspace's **own repository** at the workspace's **default branch** — never the source repository or the source push's branch. The cross-repository entry acts purely as a trigger.
* Downstream check-run and PR-comment dispatch target the workspace's own repository, using the workspace's VCS integration credentials.
* The run's **Triggered By** card identifies the cross-repository entry that fired the trigger, so you can trace the run back to its source push.

This means a single push to a shared-module repository can fan out to many tracked-branch runs across many workspaces in many other repositories — each running its own `plan` (and optionally `apply`) from its own working directory.

## 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.
* You want pull-request-time feedback on the path. Path configurations do not fire on PR events.

## 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. The repository is identified by `<integration-id>:<owner/repo-name>`, so repositories with the same `owner/repo-name` reached through different VCS integrations remain distinct.
* **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.
* **Pattern matching is precise.** The matcher honors the literal pattern, including underscores and percent signs — those are *not* treated as wildcards.

## 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 Path Configuration** and provide the three fields:

* **VCS Repository** — pick a repository from the account's connected VCS integrations. The picker shows the integration name alongside the repository slug (e.g., `Github : org/infra-modules`) so repositories with the same `owner/repo-name` accessed through different integrations remain distinct.
* **Path Pattern** — enter a directory prefix, exact file, or recursive wildcard pattern. Inline validation flags the entry the moment it would be rejected on save (e.g., a single-star wildcard, an empty path, or a path that conflicts with another workspace's working directory).
* **Execution Type** — choose **Plan** or **Plan and Apply**.

You can add additional entries the same way, up to a maximum of **2** entries per workspace.

### 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 on a push:

| 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.

## 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.

## The "Triggered By" Run Card

Runs that fire because of a path configuration show a **Triggered By** summary in the run's details, so you can see at a glance *why* a given run was created. The summary captures:

* **Trigger type** — `path-config` for runs triggered by a path configuration entry; `push` or `pull-request` for runs triggered by the workspace's own working directory.
* **Triggered at** — the timestamp at which the trigger was evaluated and the run created.
* **Matched entries** — the `{repository, path}` entries that drove the trigger. When more than one entry matched in the same commit, all of them appear.

This makes it easy to trace a cross-repository run back to the upstream change that caused it. Runs triggered by changes to the workspace's own working directory show the `push` or `pull-request` trigger type with no matched entries.

## Multi-Workspace Behavior

In a monorepo (or across many repositories) a single push 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

This includes **cross-VCS** triggers — a workspace on GitHub can declare a path configuration against a GitLab repository, and a push on the GitLab side triggers a run on the GitHub workspace using the GitHub integration's credentials. No VCS-specific configuration is required — webhook delivery, push 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. A pull request that modifies `modules/shared-vpc/main.tf` does **not** trigger `prod-networking` — to get PR-time feedback on the shared module, work through whichever workspace owns `modules/shared-vpc` as its working directory.

### 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 push to either repository now triggers `prod-networking`. The runner still clones `org/prod` at `prod-networking`'s default branch — the cross-repository entry only acts as a trigger, never as a source for the clone.

### 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 push that changes `defaults/global.tfvars` triggers a `plan`-only run on the workspace. 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 **push-only**. Pull-request events on a path-configuration-matched file do not create runs.
* Path configurations are **trigger-only**. They do not modify the working directory, alter what files the runner sees, or pass values into the run.
* Cross-repository runs always clone the **workspace's own repository at its default branch** — there is no option to clone the source repository, and the source push's branch is not used.
* 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 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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.