> 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/creating-workflows.md).

# Creating Workflows

> **Related Guides and Examples:**
>
> * [Overview: Firefly Workflows and Guardrails](https://docs.firefly.ai/detailed-guides/workflows.md): High-level concepts and options.
> * [Integrating Existing CI/CD Pipelines with Firefly Workflows](https://docs.firefly.ai/integrations/workflows.md): For hybrid or external CI/CD integration.
> * [Creating Guardrail Rules in Firefly](https://docs.firefly.ai/detailed-guides/workflows/creating-guardrail-rules.md): How to define and enforce policies and best practices.
> * [Creating Projects](https://docs.firefly.ai/detailed-guides/workflows/creating-projects.md): How to create projects to group IaC orchestration resources and control access.
> * [Creating Variable Sets](https://docs.firefly.ai/detailed-guides/workflows/creating-variable-sets.md): Managing reusable variable collections.
> * [Cloud Credentials for Workflows](https://docs.firefly.ai/detailed-guides/workflows/cloud-credentials.md): Bind a workspace to the AWS or Azure Integration that holds its write credentials.
> * [SSH Private Module Access](https://docs.firefly.ai/detailed-guides/workflows/ssh-private-module-access.md): Configure SSH-based access to private Git repositories for Terraform modules.
> * [Triggering Workspace Deployment](https://docs.firefly.ai/detailed-guides/workflows/trigger-deploy.md): How to trigger a workspace deployment from the Firefly UI.
> * [Path Configurations (Change-Based Triggers)](https://docs.firefly.ai/detailed-guides/workflows/path-configurations.md): Trigger a workspace run when changes occur to files outside the workspace's configured working directory, including across repositories.
> * [Firefly Workflows Example Pipelines](https://github.com/gofireflyio/workflows-examples): Real-world pipeline and integration templates for Jenkins, GitHub Actions, and more.

Firefly Workflows offer a streamlined and powerful way to automate your Terraform, OpenTofu, and Terragrunt deployments directly within the Firefly platform. When you choose to create a new IaC pipeline with Firefly Runners, you leverage Firefly's fully managed infrastructure to execute your IaC operations (`plan` and `apply`). This approach provides built-in drift detection, policy guardrails, automatic logging, and a secure, scalable experience for your infrastructure deployments. For organizations with specific security or compliance needs, Firefly also supports self-hosted runners, allowing you to run workflows within your own environment while still benefiting from Firefly's orchestration and governance features.

This document provides a comprehensive guide to creating and configuring a new Firefly Runners-managed workflow.

## Introduction to Firefly Runners

Firefly Runners are ideal for:

* **Fully Managed IaC Operations**: Firefly handles the entire execution environment, eliminating the need to configure and maintain your own runners or complex pipeline scripts.
* **Built-in Drift Detection**: Automatic periodic scanning to detect infrastructure drift, configuration changes and deployment failures.
* **Policy Guardrails**: Integrated policy enforcement with automated checks and violations reporting.
* **Secure Execution**: Firefly provides a secure, isolated environment for running your Terraform/OpenTofu/Terragrunt operations.
* **Automated Logging**: Comprehensive logging and audit trails for all IaC operations.
* **VCS Integration**: Seamless integration with your Version Control System (VCS) like GitHub, GitLab, etc.
* **Flexible Runner Options**: Choose between managed runners for simplicity or self-hosted runners for enhanced security, compliance, and network control.

Each workflow in Firefly corresponds to a **Workspace**. A Workspace represents a specific IaC stack (a collection of Terraform/OpenTofu/Terragrunt files defining a set of resources) and its deployment configuration.

**Key Concepts for Firefly Runners:**

* **Workspace**: The core entity representing your IaC configuration, its associated VCS repository, variables, and run history.
* **Firefly Runners**: Firefly offers two types of runners for executing your IaC commands (`plan`, `apply`, and others):
  * **Managed Runners**: Firefly's fully managed, cloud-hosted infrastructure that securely runs your IaC operations without any setup or maintenance required on your end.
  * **Self-Hosted Runners**: For organizations with strict security, compliance, or network requirements, Firefly supports self-hosted runners. These allow you to run all IaC operations within your own environment or network, giving you full control over execution, networking, and data residency. Self-hosted runners are ideal when you need to keep sensitive credentials or resources within your own infrastructure.
* **VCS Integration**: Connects Firefly to your Git provider (e.g., GitHub) to trigger workflows based on code changes (pull requests, merges).
* **Pull Request (PR) Trigger**: Optionally, creating a PR in your connected repository automatically triggers a `plan` for the corresponding Workspace.
* **Merge Trigger**: Optionally, merging a PR into the Workspace's default branch automatically triggers a `apply` (or waits for manual approval, depending on Workspace settings).
* **Periodic Plans**: Optionally, scheduled drift detection that runs periodic `plan` operations to identify infrastructure changes and deployment failures. See [Periodic Plan Drift Detection](https://docs.firefly.ai/detailed-guides/workflows/periodic-plan-drift-detection.md).

## Prerequisites

Before creating a Firefly Runners workflow, ensure you have:

* An active Firefly account with appropriate permissions to create Workflows and Workspaces.
* Your Terraform, OpenTofu, or Terragrunt code hosted in a supported Version Control System (e.g., GitHub, GitLab, Azure DevOps, etc.).
* Your VCS provider integrated with Firefly. This is done at an organizational level within Firefly settings.
* Understanding of your IaC project structure (working directory, variable files, etc.).

## Creating a New Firefly Runners Workflow: Step-by-Step

Follow the wizard in the Firefly UI to create one or more workspaces with Firefly Runners. The wizard has four steps: **Project & source**, **Workspace details**, **Configuration** and **Review & create**. You can select several working directories in one pass, and each selected directory becomes its own workspace. A repository with 20 Terraform directories takes one trip through the wizard instead of 20.

**Procedure:**

### Step 1: Navigate to Workspaces

In the Firefly UI, click on **Workflows > Workspaces** from the main navigation menu.

### Step 2: Add New Workspace

Click on the **+ Workspace** button.

### Step 3: Choose Workflow Type

Select from the two available options:

#### Firefly Runners *Recommended*

Firefly will fully manage IaC operations using its execution engine, with built-in drift detection, policy guardrails, and automatic logging. This option supports both managed runners (Firefly's cloud infrastructure) and self-hosted runners (your own infrastructure) for maximum flexibility and security. You choose the runner type later, in the wizard's **Configuration** step.

If you haven't connected a Version Control System yet, Firefly asks you to connect one before you continue.

#### Integrate into an Existing IaC Pipeline

If you already have a CI pipeline for your IaC projects, Firefly can seamlessly integrate into it. By choosing this option, Firefly will help you add the necessary steps and configurations to your existing pipeline. See [Integrating Existing CI/CD Pipelines with Firefly Workflows](https://docs.firefly.ai/integrations/workflows.md).

> **Deprecated:** Generate third-party IaC pipeline option is deprecated. This option is no longer available. Please use the Firefly Runners option instead.

### Step 4: Project & Source

Choose the project for the new workspaces and the code they deploy.

**Project** (*Required*): Select the project the workspaces belong to. Firefly pre-selects the **Default Project**, or the first project your role lets you create workspaces in. Projects you can't create workspaces in are disabled.

#### Benefits of Project Assignment:

* **Access Control:** Limit workspace access to specific teams or users.
* **Variable Inheritance:** Automatically inherit project-level variables.
* **Resource Organization:** Group related workspaces together.

If the project, or a parent project it inherits from, has saved VCS settings, the wizard pre-fills the VCS integration and repository. You can change them.

**VCS Integration** (*Required*): Select your Version Control System provider from the available integrations. If you have only one integration, it's selected for you.

**Repository** (*Required*): Choose the repository containing your Infrastructure as Code files.

**Branch** (*Required*): Select the branch the workspaces run from. The repository's default branch is pre-selected. This branch is used for automatic deployments when changes are pushed to it, if configured in the execution settings. Changing the branch clears the selected working directories.

**Working Directory** (*Required*): Select the directory where your root infrastructure module is located, typically the folder with your `main.tf`, `variables.tf`, and `outputs.tf`. Choose it from a folder tree of the repository instead of typing a path:

* Expand a folder to see the folders inside it. The repository root appears as **/**.
* Each folder shows how many `.tf` files it contains, for example **6 .tf**, so you can see which directories hold IaC.
* A folder that already has a workspace is marked **Workspace exists** and can't be selected.
* If a selected folder has no `.tf` files, the wizard warns that it may not contain Terraform configuration files.

**Bulk creation:** Select one or more working directories. Each selected directory becomes its own workspace. Selecting a folder doesn't select the folders inside it. When you select more than one, the wizard confirms what will happen, for example: *2 directories selected — multiple workspaces will be created, one for each directory.*

Click **Next** to proceed to the workspace details.

### Step 5: Workspace Details

Name and describe the workspaces. What you see depends on how many working directories you selected.

**One working directory:**

* **Workspace name** (*Required*): Choose a clear, descriptive name that identifies your workspace's purpose and environment. Workspace names must be unique within your assigned project.
* **Description** (*Optional*): Add context about the workspace's purpose, team ownership, or infrastructure it manages.
* **Labels** (*Optional*): Use labels to categorize and filter workspaces across your organization.

**Several working directories:**

* **Naming pattern** (*Required*): Firefly names each workspace from this pattern. Use `{dir}` as a placeholder for each selected directory's name. The default is `{dir}`. For example, the pattern `{dir}-prod` names the workspace for `envs/network` as `network-prod`. `{dir}` is the last folder in the path, and the repository root becomes `root`.
* A preview lists every workspace that will be created, with its name and working directory. You can add an optional **Description** for each one.
* **Labels** (*Optional*): The labels apply to all the new workspaces.

Workspace names must start with a letter or digit, and can contain letters, digits and `_ : . / @ + , -`. If the pattern produces the same name for two directories, for example `apps/prod` and `services/prod` with the pattern `{dir}`, the wizard won't continue. Change the pattern so that every name is unique.

Click **Next** to proceed to the configuration.

### Step 6: Configuration

Configure how the workspaces run. The step has four sections: **IaC Engine**, **Variables Configuration**, **Execution Configuration** and **Runner Configuration**. Use the tabs at the top to jump to a section.

When you're creating several workspaces, this configuration applies to all of them. You can change the configuration of any individual workspace later from its edit page.

#### IaC Engine

**IaC Provisioning Engine** (*Required*): Select the Infrastructure as Code engine your project uses:

* **OpenTofu** (*Default*)
* **Terraform**
* **Terragrunt**

**Version** (*Required*): Select the version of your Infrastructure as Code tool that matches your project requirements. The newest version is selected by default. For Terragrunt, also select the Terragrunt version and the underlying engine and its version.

#### Variables Configuration (*Optional*)

Define the variables needed for your infrastructure deployment. Variables can be inherited from variable sets and project variables or defined specifically for this workspace.

**Variable Sets** (*Optional*): Attach existing variable sets to reuse common configurations across multiple workspaces.

#### What are Variable Sets?

* Pre-defined collections of variables that can be shared across workspaces.
* Ideal for common configurations like AWS regions, instance types, or team-specific settings.
* Can include both regular and sensitive variables.

> **Note:** Variable sets are managed separately in Firefly. If you need to create new variable sets, you can do so after workspace creation. Check the [Creating Variable Sets](https://docs.firefly.ai/detailed-guides/workflows/creating-variable-sets.md) guide for more information.

**Inline Variables** (*Optional*): Define variables specific to this workspace that supplement or override inherited variables.

* **Name:** Variable name.
* **Value:** Variable value.
* **Sensitive:** Mark sensitive values appropriately. If you mark a variable as sensitive, it will be encrypted and hidden from logs and the UI.
* **Environment Variable:** Export as environment variable. If you export a variable as an environment variable, it will be available to your workspace as an environment variable.

#### Loading Variables from Your Working Directory

Firefly can read the variables declared in your working directory and add them to the workspace for you, so you don't have to type each one by hand. This option isn't available when you're creating several workspaces at once. When variables are found, a banner appears above the variables list: **Found N variables in the working directory**. Click **Load Variables From Code** to add them. The same banner is available when you edit an existing workspace's variables.

**Prerequisites**

* The workspace runs on **Firefly Runners**.
* The IaC type is **Terraform**, **OpenTofu**, or **Terragrunt** (wrapping Terraform or OpenTofu).
* The workspace's **Default Branch** is `main` or `master`.
* The working directory declares at least one variable.

If any of these is not met, the banner does not appear.

**How it works**

Firefly indexes your repository asynchronously and keeps a snapshot of the variables declared in each directory. **Load Variables From Code** reads from this snapshot, not from the live repository, so a variable you committed very recently may not appear until the next indexing completes. Each loaded variable is labeled **Working directory (\<snapshot date>)** so you can see how current it is.

When you load variables:

* Each variable is added with its declared default as its value.
* Variables declared `sensitive = true` are added as sensitive.
* Variables with no default are added with an empty value. You must enter a value for each before you can continue. Firefly shows how many still need one.
* Variables that already exist in the workspace are skipped.

To undo, click **Remove Variables**. If you change the branch, working directory, or IaC type to one that is not supported, the loaded variables are removed automatically.

**Loaded variables are workspace variables**

After you load them, snapshot variables are treated exactly like inline variables you added yourself. You can edit, mark as sensitive, or delete them, and they follow the same [precedence](#variable-precedence) rules.

**When to use it**

A value set in Firefly always takes precedence over the default declared in your code. For a variable that already has a default in code, loading it is redundant unless you want to change the value for this workspace.

This is most useful for variables declared with **no default**, such as secrets and credentials. These must be supplied at runtime, and loading them gives you the full list to fill in.

> **Note:** Some variables with no default are supplied by Firefly at runtime, for example `aws_role_arn` and `aws_web_identity_token_file` when you use [AWS OIDC authentication](https://docs.firefly.ai/detailed-guides/oidc-provider/aws.md). If these are loaded, delete them from the list. A value you enter for them in Firefly overrides the value Firefly supplies. The same applies to cloud credentials for a workspace that is [bound to an Integration](https://docs.firefly.ai/detailed-guides/workflows/cloud-credentials.md): don't add them as variables.

#### Injecting a `.tfvars` File at Execution

If you want the workspace to load a specific `.tfvars` file during execution, use Terraform's native `TF_CLI_ARGS_plan` and/or `TF_CLI_ARGS_apply` environment variables. Firefly passes these to Terraform/OpenTofu, which then automatically appends them to the corresponding command.

Use the subcommand-scoped variables (`TF_CLI_ARGS_plan` / `TF_CLI_ARGS_apply`) rather than the global `TF_CLI_ARGS`. The global variable applies to *every* subcommand, including `terraform init`, which has no `-var-file` flag and would fail the run before `plan` even starts. To pass flags to `init`, such as `-backend-config`, use `TF_CLI_ARGS_init`, which applies only when the workspace uses its own backend. See [Backend Config Files](#backend-config-files).

To set this up, add an inline variable (or a [variable set](https://docs.firefly.ai/detailed-guides/workflows/creating-variable-sets.md) variable) with the following configuration:

* **Name:** `TF_CLI_ARGS_plan` and/or `TF_CLI_ARGS_apply`
* **Value:** `-var-file=<name>.tfvars`
* **Environment variable:** The **Environment variable** checkbox **must be checked** — otherwise the value is treated as a regular Terraform variable and the file will not be injected.

| Name                | Value                         | Environment variable |
| ------------------- | ----------------------------- | -------------------- |
| `TF_CLI_ARGS_plan`  | `-var-file=production.tfvars` | ✅ Checked            |
| `TF_CLI_ARGS_apply` | `-var-file=production.tfvars` | ✅ Checked            |

> **Notes:**
>
> * Set `TF_CLI_ARGS_plan` to inject the file during `plan`, and `TF_CLI_ARGS_apply` to inject it during `apply`. In most cases you should set both so the same variables are used across the full run.
> * The `.tfvars` file must exist in the workspace's working directory (it is read from your IaC repository).
> * Replace `<name>.tfvars` with the actual file name, for example `-var-file=production.tfvars`.

> ⚠️ **Don't set `TF_CLI_ARGS_apply` if the workspace runs destroys, or if it uses manual apply on the Terraform (not OpenTofu) engine.** In those cases `apply` runs against a saved plan file, and Terraform rejects `-var-file` with `Error: Can't set variables when applying a saved plan`. Use `TF_CLI_ARGS_plan` alone there — the variables captured during `plan` are already baked into the saved plan. (OpenTofu re-runs `apply` fresh, so setting `TF_CLI_ARGS_apply` is fine on the OpenTofu engine.)

#### Variable Precedence

When variables are defined in multiple places, Firefly follows this precedence order (highest to lowest):

* **Inline Variables** (this workspace)
* **Variable Sets** (attached to workspace)
* **Project Variables** (inherited from project)
* **Organization Variables** (inherited from organization)
* **Default Values** (defined in IaC code)

> **Note:** Cloud write credentials are the exception. When the workspace is bound to an AWS or Azure Integration, the credentials configured on the Integration take precedence over credentials from all of these sources. See [Cloud Credentials for Workflows](https://docs.firefly.ai/detailed-guides/workflows/cloud-credentials.md).

#### Execution Configuration

Configure when and how your workspace should execute infrastructure operations.

**Trigger Configuration:** Choose which events start a run. By default, only the pull request trigger is selected.

**Trigger plan on pull requests** (*Recommended*): Automatically run `plan` when a pull request into the workspace's branch includes changes in its working directory.

#### Benefits of the Pull Request Trigger:

* **Early Feedback:** See infrastructure changes before merging.
* **Code Review:** Review `plan` output alongside code changes.
* **Prevent Errors:** Catch issues before they reach production.
* **Compliance:** Ensure changes meet policy requirements.

#### What Happens when the Pull Request Trigger is enabled:

1. Developer opens a pull request.
2. Firefly automatically triggers a `plan` operation.
3. `plan` results are posted as PR comments.
4. Policy violations are flagged if any exist.
5. Reviewers can see infrastructure impact before approving.

**Trigger apply on branch update** (*For Production Workspaces*): Automatically run `apply` on every commit pushed to the workspace's branch that includes changes in its working directory, for example when a pull request is merged.

#### Benefits of the Apply Trigger:

* **Continuous Deployment:** Immediate infrastructure updates.
* **Consistency:** Ensures every merge results in deployment.
* **Reduced Manual Work:** Eliminates manual deployment steps.
* **Audit Trail:** Complete history of all changes.

#### What Happens when the Apply Trigger is enabled:

1. A pull request is merged, or a commit is pushed, into the workspace's branch.
2. Firefly automatically triggers an `apply` operation.
3. Infrastructure is updated according to the merged changes.
4. Notifications are sent to configured channels.

> **Caution:** Only enable auto-apply for well-tested workspaces. Consider manual approval for production environments.

**Trigger a run on specific conditions** (*Optional*): Use path configurations to declare additional file paths — inside or outside the workspace's working directory, and even in other connected repositories — that should trigger a run when modified. Useful for monorepos with shared modules and for workspaces that consume centralized variables or modules from another repository. See [Path Configurations (Change-Based Triggers)](https://docs.firefly.ai/detailed-guides/workflows/path-configurations.md) for the full guide.

**Trigger plan periodically** (*Optional*): Run `plan` automatically on a schedule to detect drift. In **Run plan every:**, choose **72**, **48**, **24** or **12** hours. The default is 72 hours. When a scheduled plan finds resources that were changed outside of code, the run ends with **PLAN COMPLETED · DRIFT DETECTED** and shows what drifted. See [Periodic Plan Drift Detection](https://docs.firefly.ai/detailed-guides/workflows/periodic-plan-drift-detection.md).

#### Benefits of Periodic Plans:

* **Early Detection:** Identify manual changes to your infrastructure or deployment failures.
* **Any Provider:** Detect drift on any resource Terraform or OpenTofu can plan.
* **Compliance:** Ensure infrastructure matches your code.
* **Monitoring:** Track deployment health over time.

#### Apply Approval

Choose how `apply` operations are handled:

**Automatic** (*Default*, *For Development/Staging*)

* Automatically applies changes after successful plan.
* Enables fully automated deployment pipeline.
* Suitable for development and staging environments.
* Reduces deployment time and manual intervention.

**Manual** (*Recommended for Production*)

* Requires manual approval within Firefly after plan generation.
* Provides an additional safety gate before infrastructure changes.
* Allows for final review of execution plan.
* Ideal for production environments and critical infrastructure.

#### Backend Configuration

Choose where the workspace keeps its state. This choice is available for Terraform and OpenTofu workspaces, and you can't change it after the workspace is created.

**Firefly Remote Backend** (*Default*): Firefly stores and locks the state for you, with no backend to set up. Firefly replaces the backend defined in your code, so [your own backend settings don't apply](https://docs.firefly.ai/detailed-guides/workflows/remote-state-management.md#variables-ignored-with-firefly-state). See [Remote State Management](https://docs.firefly.ai/detailed-guides/workflows/remote-state-management.md).

**My own backend**: Firefly runs `init` with the backend block from your code, for example an `s3` backend. You can add backend config files for it.

If your wizard shows an **Enable Firefly Remote Backend Configuration for this workspace** checkbox instead, select it to store state in Firefly, or leave it clear to use your own backend. This checkbox isn't selected by default.

#### Backend Config Files

Backend config files let one codebase serve several environments that keep their state in different places. Declare a partial backend in your code, keep each environment's settings in its own file, and create one workspace per environment:

```hcl
# backend.tf
terraform {
  backend "s3" {}
}
```

```hcl
# environments/prod.tfbackend
bucket = "acme-tfstate-prod"
key    = "network/terraform.tfstate"
region = "us-east-1"
```

With **My own backend** selected, add the environment's file under **Backend config files** (*Optional*):

* Enter a path relative to the workspace's working directory. For example, with the working directory `network` and the files in `environments/` at the repository root, enter `../environments/prod.tfbackend`. The path must stay inside the repository and can contain only letters, digits and `. _ - / @ +`.
* Firefly passes each file to `init` as `-backend-config=<path>` on every run, including periodic plans and destroys. When you add several files, later files override earlier ones for the same setting.
* If a file doesn't exist in the repository, the run fails at the **Init** step.
* Changing the files on an existing workspace points it at that state from the next run. Firefly doesn't migrate the existing state.

Firefly saves the files in the workspace environment variable `TF_CLI_ARGS_init`, for example `-backend-config=../environments/prod.tfbackend`. You can also set this variable yourself in **Variables** with **Environment variable** checked (Terraform reads `TF_CLI_ARGS` variables only from the environment, so **Variables** flags one saved without it), or through the [API](https://docs.firefly.ai/general-information/api/workflows.md#workspace-variables) with destination `env`. You can set it on a project or variable set to share it across workspaces. Each workspace then resolves the paths from its own working directory, and the files' settings override each workspace's backend block, so keep per-workspace settings such as `key` out of shared files.

> **Notes:**
>
> * The field edits `TF_CLI_ARGS_init` only when the workspace's own environment variable holds backend config file paths alone. If the variable is sensitive, comes from a project or variable set, overrides an inherited value, isn't an environment variable, or holds other settings, such as `-upgrade` or `-backend-config=key=value`, the field shows the value with an **Edit in Variables** link instead of editing it.
> * Keep credentials out of backend config files. Use your cloud provider's environment variables or [OIDC](https://docs.firefly.ai/detailed-guides/oidc-provider.md) instead.
> * Use `TF_CLI_ARGS_init`, not `TF_CLI_ARGS`, for backend settings. `TF_CLI_ARGS` applies to every command, and `plan` fails on `-backend-config`.

#### Runner Configuration

**Runner Type** (*Required*): Choose where the workspace's runs execute:

* **Managed by Firefly** (*Default*): Runs on Firefly's managed runners.
* **Self-hosted**: Runs on a [self-hosted runner pool](https://docs.firefly.ai/detailed-guides/workflows/creating-self-hosted-runner.md) in your environment. Select the **Runner Pool**. If the project has a runner pool, the workspace must use self-hosted runners.

**Integration** (*Optional*): Select the AWS account or Azure subscription Integration the workspace deploys to. Runs then authenticate with the write credentials configured on that Integration, which take precedence over credentials from variable sets, projects and the workspace's own OIDC settings. This option is available with managed runners only, and currently for AWS and Azure. Google Cloud support is under development. See [Cloud Credentials for Workflows](https://docs.firefly.ai/detailed-guides/workflows/cloud-credentials.md).

**Authentication Configuration** (*Optional*): For a workspace that isn't bound to an Integration, enable OIDC authentication so runners get short-lived credentials for AWS or Google Cloud instead of static keys. See [Authentication using OIDC Provider](https://docs.firefly.ai/detailed-guides/oidc-provider.md).

Click **Next** to review your choices.

### Step 7: Review & Create

Review the workspaces before Firefly creates them. The **Overview** shows the project, repository, branch, IaC engine, apply approval and runner. The list below it shows every workspace that will be created, with its working directory.

Click **Create workspace**, or **Create N workspaces** when you're creating several. Firefly creates the workspaces at the same time and shows each one's status: **Waiting**, **Creating…**, **Created** or **Failed**. You can't close the wizard while the workspaces are being created.

If some workspaces can't be created, the wizard shows why for each one. Click **Retry failed workspace**, or **Retry N failed workspaces**, to try the failed ones again. Or close the wizard to keep the workspaces that were created.

### Step 8: Completion

Congratulations! Your Firefly Runners workspaces have been successfully created and are ready to manage your infrastructure deployments. From the completion screen you can view your workspaces, add a guardrail or add a notification.

#### What Happens Next

**Immediate Actions:**

1. **Initial State Check:** Firefly automatically runs a baseline `plan` to establish your workspace's initial state.
2. **Configuration Verification:** Review your workspace dashboard to confirm all settings are correct.
3. **Integration Testing:** Your VCS integration is now active and will respond to pull requests and merges.

#### Recommended Next Steps

**1. Test Your Configuration**

* Create a test pull request to verify the PR trigger works.
* Review the generated `plan` output.
* Ensure all variables are correctly configured.

**2. Set Up Notifications**

* Configure notifications to your desired channels.
* Get alerted when plans fail or succeed.
* Keep stakeholders informed of infrastructure changes.

**3. Add Guardrails**

* Implement policy-as-code rules to enforce compliance.
* Set up cost controls and security policies.
* Prevent deployments of resources with no tags.

#### Quick Reference

**Your Workspace Configuration:**

* **Automatic Triggers:** Pull requests and merges will trigger IaC operations.
* **Drift Detection:** Periodic plans will monitor for configuration changes.
* **Security:** Sensitive variables are encrypted and redacted from logs.
* **Audit Trail:** Complete history of all infrastructure changes.

**Common Actions:**

* **Manual Deployment:** Use the *Deploy* button to run IaC operations manually.
* **Edit Variables:** Update workspace variables without recreating the workspace.
* **View Logs:** Access detailed execution logs for troubleshooting.
* **Manage Periodic Plans:** Adjust drift detection frequency from **Edit Workspace** as needed.

#### Additional Resources

* [Triggering Workspace Deployment](https://docs.firefly.ai/detailed-guides/workflows/trigger-deploy.md): How to trigger a workspace deployment from the Firefly UI.
* [Creating Guardrail Rules](https://docs.firefly.ai/detailed-guides/workflows/creating-guardrail-rules.md): How to define and enforce policies and best practices.
* [Creating Variable Sets](https://docs.firefly.ai/detailed-guides/workflows/creating-variable-sets.md): Managing reusable variable collections.
* [SSH Private Module Access](https://docs.firefly.ai/detailed-guides/workflows/ssh-private-module-access.md): Configure SSH-based access to private Git repositories for Terraform modules.
* [Creating Projects](https://docs.firefly.ai/detailed-guides/workflows/creating-projects.md): How to create projects to group IaC orchestration resources and control access.

## Managing Your Firefly Runners Workspace

After creation, you can manage your workspace through various actions:

### Edit Workspace

* Navigate to your workspace, in the actions menu click **Edit**.
* The wizard opens with the same steps used to create the workspace, and you can jump to any step. Some settings can't be changed: the project, the workspace name, the VCS integration, the repository and the choice between **Firefly Remote Backend** and **My own backend**. You can still change the branch and the working directory, and with your own backend, the [backend config files](#backend-config-files).
* Under **Runner Configuration > Integration**, you can bind the workspace to an AWS or Azure Integration, change the Integration, or clear the binding. See [Cloud Credentials for Workflows](https://docs.firefly.ai/detailed-guides/workflows/cloud-credentials.md).
* Click **Save changes** to save the changes.

### Edit Variables

* Navigate to your workspace, in the actions menu click **Edit Variables**.
* Attach variable sets or define inline variables specifically for this workspace. These variables will override any inherited ones.
* To add the variables declared in your code, click **Load Variables From Code**. See [Loading Variables from Your Working Directory](#loading-variables-from-your-working-directory).
* Click **Save** to save the changes.

### Set Periodic Plan

* Navigate to your workspace, in the actions menu click **Edit**.
* In the **Configuration** step, under **Execution Configuration**, select **Trigger plan periodically** and choose how often to run the plan. Clear it to stop the scheduled runs.
* Click **Save changes**. The workspace header shows the schedule, for example **Periodic plan · every 12 hours**. See [Periodic Plan Drift Detection](https://docs.firefly.ai/detailed-guides/workflows/periodic-plan-drift-detection.md).

### Deploy Workspace

* Navigate to your workspace, in the actions menu click **Deploy**.
* Trigger a `plan` and optionally an `apply` execution for the workspace using your selected branch and settings. You can also add additional CLI arguments for Terraform/OpenTofu/Terragrunt.
* Click **Deploy** to trigger the execution.

### Delete Workspace

* Navigate to your workspace, in the actions menu click **Delete**.
* Permanently delete this workspace from Firefly. You can optionally run a destroy before deletion to clean up infrastructure. This action cannot be undone.
* Click **Delete** to confirm the deletion.

## Best Practices

* **Workspace Organization:** Use descriptive names and labels for easy identification.
* **Variable Management:** Leverage variable sets for consistency across workspaces.
* **Security:** Always use sensitive variables for credentials and secrets. For AWS and Azure write credentials, prefer configuring them once on the [Integration](https://docs.firefly.ai/detailed-guides/workflows/cloud-credentials.md) instead of as variables.
* **Runner Selection:** Choose managed runners for simplicity, self-hosted for security/compliance requirements.
* **Monitoring:** Enable periodic plans for proactive drift detection and deployment failures.
* **Policy Enforcement:** Implement guardrails to maintain compliance.
* **Documentation:** Maintain clear descriptions and labels for team collaboration.

For hybrid or CI/CD integration, see the [Integrating Existing CI/CD Pipelines with Firefly Workflows](https://docs.firefly.ai/integrations/workflows.md) guide. For real-world pipeline examples, visit the [workflows-examples GitHub repository](https://github.com/gofireflyio/workflows-examples).

By following this guide, you can effectively create and manage Firefly Runners workflows, providing a fully integrated, scalable, and secure infrastructure automation experience.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.firefly.ai/detailed-guides/workflows/creating-workflows.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
