> 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-projects.md).

# Creating Projects

> **Related Guides and Examples:**
>
> * [Overview: Firefly Workflows and Guardrails](https://docs.firefly.ai/detailed-guides/workflows.md): High-level concepts and options.
> * [Creating New Firefly Workflows](https://docs.firefly.ai/detailed-guides/workflows/creating-workflows.md): How to set up managed workflows.
> * [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 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): Configure AWS and Azure write credentials once on the Integration instead of in project variables.
> * [Triggering Workspace Deployment](https://docs.firefly.ai/detailed-guides/workflows/trigger-deploy.md): How to trigger a workspace deployment from the Firefly UI.

Firefly Projects are organizational units designed to group and manage related Infrastructure as Code (IaC) orchestration resources like workspaces, variable sets, and self-hosted runners. By establishing project hierarchies, you can maintain clear separation of environments, teams, and applications, while implementing robust access controls. Projects serve as the primary boundary for access control, resource organization, and operational management within Firefly Workflows, enabling teams to independently manage their infrastructure and providing a structured approach to organizing complex deployments across multiple environments. This document provides a comprehensive guide on how to create and configure Projects in Firefly Workflows.

**Key Benefits of Using Projects:**

* **Organizational Structure:** Group related workspaces, variables, and self-hosted runner pools by team, application, environment, or any logical boundary that matches your organization's needs.
* **Access Control:** Implement Role-Based Access Control (RBAC) to ensure users can only access resources within their assigned projects.
* **Resource Inheritance:** Leverage hierarchical variable inheritance and configuration sharing across project boundaries.
* **Operational Efficiency:** Set default configurations like drift detection schedules and notification settings at the project level.
* **Scalability:** Support complex organizational structures with up to 5 levels of project hierarchy.

## Project Structure and Hierarchy

Firefly Projects support a hierarchical structure that mirrors your organizational needs:

### Project Hierarchy Levels

1. **Organization Level (Root):**
   * The top-level container for all projects.
   * Contains global resources accessible across all projects.
   * Houses the default project that serves as the root directory.
2. **Project Level:**
   * First level of organization-specific groupings.
   * Examples: `/aws`, `/azure`, `/development`, `/production`.
3. **Sub-Project Levels (up to 5 total levels):**
   * Further subdivision of projects.
   * Examples: `/aws/production`, `/aws/production/frontend`, `/aws/production/frontend/web`.

### Project Components

Each project can contain:

* **Workspaces:** Terraform/OpenTofu/Terragrunt execution environments.
* **Variable Sets:** Reusable collections of configuration variables.
* **Runner Pools:** Self-hosted execution environments.
* **Users:** Team members with specific role assignments.
* **Sub-Projects:** Nested organizational units.

### Variable Inheritance

Projects follow a hierarchical variable inheritance model that distinguishes between direct variable assignment and variable set access:

#### Direct Variable Inheritance

* **Inheritance Flow:** Organization → Project → Sub-Project → Workspace.
* **Automatic Propagation:** When you set variables directly on a project, all underlying projects and workspaces automatically inherit those variables.
* **Precedence Rules:** Workspace variables override sub-project variables, which override project variables, which override organization variables.
* **Example:** If you set `AWS_REGION=us-east-1` on the `/aws` project, all sub-projects like `/aws/production` and `/aws/development`, as well as all workspaces within them, will automatically have access to this variable.

#### Variable Set Access Control

* **First-Level Assignment:** Variable set assignment to projects can only occur at the first level of the hierarchy.
* **Automatic Sub-Project Access:** When you assign a variable set to a project, all sub-projects and workspaces within them can consume that variable set.
* **Access-Based Assignment:** Assigning a variable set to a project is different from direct variable inheritance. It controls **who can view and use** that variable set.
* **User Scope:** Only users who have access to that project and its sub-projects can view and use the assigned variable set.
* **Selective Consumption:** Child resources can choose to consume variable sets from their parent projects, but the variable set must be accessible to the user performing the assignment.
* **Example:** If you assign a variable set called `aws-production-secrets` to the `/aws` project, only users with access to `/aws` and its sub-projects can view and use this variable set when creating workspaces or sub-projects.

#### User Access and Project Visibility

Access to projects is managed through **roles in Access Management**, not by assigning users directly to each project. A role can be scoped to specific projects and specific actions (**view, run, apply or manage state**), and the same permissions are enforced in the UI, the API and the Terraform CLI. See [Access Management (RBAC)](https://docs.firefly.ai/getting-started/access-management-rbac.md#workflows-permissions).

* **Sub-Project Access:** A role scoped to a project also covers the sub-projects and workspaces in it.
* **Default Project:** The Default Project is visible only to Admins and Viewers. If non-admin users work in Default Project workspaces, add the Default Project to their role.
* **Example:** A role scoped to the `/aws` project with the *Apply* action lets its members plan and apply in `/aws` and all its sub-projects, such as `/aws/production` and `/aws/development`, and nothing else.

## Creating a New Project: Step-by-Step

Follow the wizard in the Firefly UI to create a new Project.

**Procedure:**

U\[1. **Navigate to Projects & Variables:** \* In the Firefly UI, click on **Workflows** from the main navigation menu. \* Then, click on the **Projects & Variables** sub-section.

2. **Add New Project:**
   * Click on the **+ Create new project** button.
3. **Enter Project Details:**
   * **Name:**
     * Provide a unique name for your project (3-64 characters).
     * Use alphanumeric characters, hyphens, and underscores only.
     * The name must be unique within the selected parent directory.
     * *Example:* `aws-production`, `frontend-services`, `data-platform`.
   * **Description (Optional):**
     * Add a free-text explanation to help identify the project's purpose.
     * *Example:* "Production AWS infrastructure for customer-facing applications".
4. **Configure Project Hierarchy:**
   * **Parent Project (Optional):**
     * Select a parent project if this is a sub-project.
     * Projects can nest up to 5 levels deep.
     * Leave blank to create a root-level project.
     * *Example:* Select `/aws` as parent for a `/aws/production` sub-project.
5. **Configure Runner Pool:**
   * **Runner Pool (Optional):**
     * Please refer to the "Runner Pool Inheritance" section for more details.
     * Default: No runner pool assigned (workspaces use Firefly-managed runners)
     * Selection: Choose from available self-hosted runner pools in your organization
     * Inheritance: All workspaces and sub-projects inherit this runner pool assignment automatically
     * Leave empty if you want workspaces to use Firefly's managed runners or if you'll assign runner pools at the workspace level.
6. **Add Classification Labels:**
   * **Labels (Optional):**
     * Add tags to categorize or filter projects.
     * Use existing labels from the dropdown or create new ones.
     * *Example:* `environment:production`, `team:platform`, `cost-center:engineering`.
7. **Configure Version Control Access:**
   * **Version control (Optional):** Limit which code the project's workspaces can deploy. Choose one of:
     * **All integrations and repositories:** Workspaces in the project can use any connected VCS integration and any repository it can access, including ones added later. This is the default.
     * **Selected integrations and repositories:** Limit workspaces to specific VCS integrations. For each integration, either allow **every repository** in it or **pick individual repositories**.
   * The **Allowed repositories** field summarizes the selection, for example *1 integration · 1 with every repository*. When someone creates a workspace in the project, they can only choose from what's allowed.
   * **Why it matters:** RBAC decides *who* can work in a project; repository scoping decides *what* that project can deploy. Together they enforce least privilege on both people and code.
8. **Configure Periodic Plan for Drift Detection:**
   * **Set Default Periodic Plan (Optional):**
     * Enable automatic drift detection for all workspaces in this project.
     * **Simple Configuration:**
       * Check the box to enable periodic plans.
       * Set frequency: "Once every X hours" (e.g., 5 hours).
     * **Advanced Configuration:**
       * Click the rotation icon to convert to full cron expression.
       * Enter custom cron pattern (minimum frequency: hourly).
       * *Example:* `0 */5 * * *` for every 5 hours.
9. **Configure Project Variables:**
   * **Variable Set Selection (Optional):**
     * Choose one or more reusable variable sets to inherit.
     * Variable sets can be defined at organization or project level.
     * **Conflict Resolution:** If multiple variable sets contain the same variable name, you'll see a warning and must resolve the conflict.
   * **Custom Variables (Optional):**
     * Define project-specific variables that will be inherited by all child resources.
     * **Variable Properties:**
       * **Name:** The variable key (must be unique within the project).
       * **Value:** The variable value (can be overridden at workspace level).
       * **Sensitive:** Mark as sensitive to hide the value in logs and UI.
       * **Environment Variable:** Export as environment variable during execution.
   * **Cloud Credentials:** You don't need to put AWS or Azure write credentials in project variables. Configure them once on the [cloud Integration](https://docs.firefly.ai/detailed-guides/workflows/cloud-credentials.md) and bind workspaces to it. Those credentials take precedence over credentials from project variables and variable sets.
10. **Review and Create:** \* Carefully review all configured settings for your project. \* Ensure the hierarchy, user assignments, and variable configurations are correct. \* Click **Create** to create the project.

## Runner Pool Inheritance

When you assign a self-hosted runner pool to a project, all workspaces within that project and its sub-projects automatically use that runner pool for execution. Workspace-level runner assignments override project-level assignments. For detailed information on creating and managing runner pools, see [Creating a Self-Hosted Runner Pool](https://docs.firefly.ai/detailed-guides/workflows/creating-self-hosted-runner.md).

## After Creating a Project

* **Activation:** The project becomes active immediately and is available for workspace creation and resource assignment.
* **Workspace Creation:** When creating new workspaces, the project will appear in the project assignment dropdown.
* **Variable Inheritance:** All variables and variable sets configured at the project level will automatically be available to child resources.
* **Access Control:** Users whose roles are scoped to the project gain access to its resources according to the actions in their role.
* **Drift Detection:** If configured, automatic drift detection will begin running for all workspaces created within the project.

## Managing Projects

Once created, you can manage your projects through various operations:

### Viewing and Filtering Projects

* **Projects Sidebar:** The Workflows page has a Projects sidebar on the left where you can browse, search and switch between projects without leaving the page:
  * **Project tree:** Projects and sub-projects appear as a nested hierarchy (e.g. `infrastructure → Dev → dev-eu-env1`), with the workspace count next to every project and the total project count in the header.
  * **Search projects:** Jump straight to any project.
  * **Hide empty projects:** A toggle hides projects with no workspaces and shows how many are hidden.
  * **Create a project** right from the sidebar with the **+** button.
  * Selecting a project shows its workspaces in the main view, where you can create a **Workspace**, **Variable Set** or **Guardrail** in that project, and narrow the list with search and filters (Repository, CI Tool, Last Status and more).
* **Project List View:** The **Projects & Variables** page displays all projects you have access to.
* **Search and Filter:**
  * **Text Search:** Search by project name, description, or labels.
  * **Hierarchy Navigation:** Expand and collapse project hierarchies.
  * **Column Sorting:** Sort by name, user count, workspace count, or other attributes.

### Editing Projects

* **Basic Information:** Update name, description, parent project, and labels.
* **Access Management:** Control who can access the project through roles in [Access Management](https://docs.firefly.ai/getting-started/access-management-rbac.md#workflows-permissions).
* **Version Control Access:** Change which VCS integrations and repositories the project's workspaces may use.
* **Periodic Plan for Drift Detection:** Modify periodic plan schedules.
* **Variable Configuration:** Access through the *Edit Variables* option in the actions menu.

### Variable Management

* **Variable Sets:** Attach or detach variable sets from projects.
* **Custom Variables:** Add, modify, or remove project-specific variables.
* **Inheritance Tracking:** View variable origins and override indicators.
* **Conflict Resolution:** Resolve conflicts between variable sets with duplicate keys.

### Reassigning a Workspace to Another Project

You can move a workspace to a different project from the workspace's actions menu, without deleting and recreating it. Before anything moves, Firefly runs a pre-flight check so nothing breaks quietly after the move:

* **Variable changes:** Shows every variable that will be added, removed or changed by the target project's variable sets.
* **Runner pool and cloud provider changes:** Flagged clearly. You must tick a box to acknowledge them before the move goes through.
* **Blockers:** The move is stopped if a required variable set isn't assigned to the target project, or if a plan or apply is still running. Fix the issue, click **Recheck**, and continue.

### Deleting Projects

* **Empty projects only:** A project can be deleted only when it has no workspaces. If it still has workspaces, reassign them first — to the Default project or another project. Firefly never deletes workspaces automatically when a project is deleted.
* **Variable sets:** The delete dialog lists the variable sets that will be detached from the project.

## Examples of Project Structures

Here are some practical examples of how to organize projects:

### Environment-Based Organization

```
Organization
├── development/
│   ├── frontend/
│   └── backend/
├── staging/
│   ├── frontend/
│   └── backend/
└── production/
    ├── frontend/
    └── backend/
```

### Cloud Provider Organization

```
Organization
├── aws/
│   ├── production/
│   │   ├── us-east-1/
│   │   └── us-west-2/
│   └── development/
├── azure/
│   ├── production/
│   └── development/
└── gcp/
    ├── production/
    └── development/
```

### Team-Based Organization

```
Organization
├── platform-team/
│   ├── infrastructure/
│   └── monitoring/
├── frontend-team/
│   ├── web-apps/
│   └── mobile-apps/
└── data-team/
    ├── analytics/
    └── ml-pipelines/
```

## Best Practices for Creating Projects

* **Plan Your Hierarchy:** Design your project structure before creating projects. Consider your organization's structure, deployment patterns, and access control requirements.
* **Use Meaningful Names:** Choose descriptive names that clearly indicate the project's purpose and scope.
* **Leverage Labels:** Use consistent labeling conventions to enable effective filtering and organization.
* **Design Variable Inheritance:** Plan your variable inheritance strategy to minimize duplication and ensure consistency.
* **Start Simple:** Begin with a basic project structure and expand as your needs grow.
* **Document Your Structure:** Maintain documentation explaining your project hierarchy and naming conventions.
* **Regular Review:** Periodically review and optimize your project structure as your organization evolves.
* **Use Periodic Plan for Drift Detection Wisely:** Configure appropriate drift detection schedules that balance monitoring needs with resource consumption.
* **Consider Compliance:** Ensure your project structure supports any regulatory or compliance requirements.

## Project Permissions and RBAC

Understanding the Role-Based Access Control (RBAC) system is crucial for effective project management:

### Role Definitions

* **Viewer:**
  * Can view project assets and resources.
  * Cannot modify configurations or trigger deployments.
  * Suitable for stakeholders who need visibility without operational access.
* **Admin:**
  * Can create, update, and delete project resources.
  * Can manage workspaces, variable sets, and self-hosted runner pools.
  * Can assign users and modify project configurations.
  * Suitable for team leads and infrastructure operators.

### Permission Inheritance

* **Project Hierarchy:** Users with admin role in a project automatically have admin access to all sub-projects.
* **Resource Access:** Project membership determines access to workspaces, variable sets, and self-hosted runner pools within the project.
* **Global Access:** Some resources can be marked as global, making them accessible across all projects.

By thoughtfully creating and managing projects, you can build a scalable, secure, and well-organized infrastructure management system that grows with your organization's needs.


---

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