Path Configurations (Change-Based Triggers)

Related Guides:

• Creating New Firefly Workflows: How to create a workspace and set the working directory.

• Triggering Workspace Deployment: Manually triggering a deployment from the UI.

• Creating Guardrail Rules: 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).

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 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 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 — Workspace creation, working directory, and trigger basics.

• Triggering Workspace Deployment — Manually triggering a workspace from the UI.

• Integrating Version Control — Connecting a VCS provider so push events reach Firefly.

• Creating Guardrail Rules — Policies evaluated on every run, including those triggered by path configurations.