# Module Registry

> **Note:** Module Registry is available on demand. Contact us to enable this feature for your organization.

## What is Module Registry?

The Module Registry is Firefly's Terraform Private Registry feature that allows you to centrally store, manage, and share Terraform modules across your organization. It provides a secure, private repository where your team can publish reusable infrastructure code modules and consume them directly in your Terraform configurations. This enables better collaboration, standardization, and governance of your infrastructure as code across all your projects.

## Importing a Module

Follow these steps to import a module into your private registry:

### Navigate to the Import Module feature

1. Click **IaC Explorer** in the left sidebar.
2. Click the **Modules** tab.
3. Click the **Import Module** button.

### Configure the module import

The import modal opens with the following fields:

* **Module name:** Enter the name under which the module will be stored in your registry
* **Provider type:** Select the cloud provider this module is associated with (e.g., AWS, Azure, GCP)
* **Version:** Enter the module version (e.g., 1.0.0)
* **VCS integration:** Select your version control system integration
* **Repository:** Select the repository that contains the module
* **Branch:** Select the branch to import from
* **Working directory (optional):** Specify the path within the repository where the module lives; defaults to `/` if left blank. You must choose the base module directory—if the module is nested under another directory layer, it will not work.

### Import the module

Once all values are valid, click the "Import" button.

### Verify the import

After clicking import, the modal will close and the module will appear in the modules table. Note that this action might take a few minutes to complete.

### Access the module call block

Click the + button next to your module in the table to reveal the module call block that you can use in your main.tf file.

## Auto-Discovery from Repository

In addition to [importing modules manually](#importing-a-module), you can configure your repositories to automatically publish modules to the Module Registry. By adding a `.firefly/config.yml` file to your module directory, Firefly detects and publishes the module whenever changes are pushed to your default branch.

Currently supported VCS providers:

* **GitHub**
* **GitLab**

### Set Up Auto-Discovery

1. In your module directory, create a `.firefly` folder with a `config.yml` file inside it.
2. Define the module metadata in `config.yml` (see [Configuration reference](#configuration-reference)).
3. Commit and push the changes to your `main` or `master` branch.
4. The module appears in **IaC Explorer > Modules** within a few minutes.

To publish a new version, update `module_version` in the config file and push again.

### Configuration Reference

**File path:** `.firefly/config.yml`

| Field            | Required | Description                                  | Default |
| ---------------- | -------- | -------------------------------------------- | ------- |
| `module_name`    | Yes      | The module name (for example, `vpc`)         | -       |
| `module_version` | Yes      | Semantic version (for example, `1.0.0`)      | -       |
| `provider`       | No       | Cloud provider (`aws`, `gcp`, `azure`, etc.) | `aws`   |

### Examples

#### Single module (minimal configuration)

Repository structure:

```
my-module/
├── .firefly/
│   └── config.yml
├── main.tf
├── variables.tf
└── outputs.tf
```

`.firefly/config.yml`:

```yaml
module_name: "vpc"
module_version: "1.0.0"
```

This publishes a module named `vpc` at version `1.0.0` with the default provider `aws`.

#### Single module (all fields)

`.firefly/config.yml`:

```yaml
module_name: "vpc"
module_version: "2.1.0"
provider: "gcp"
```

#### Multiple modules in one repository

You can publish multiple modules from a single repository by placing a `.firefly/config.yml` file in each module directory:

```
infra-modules/
├── modules/
│   ├── vpc/
│   │   ├── .firefly/
│   │   │   └── config.yml
│   │   ├── main.tf
│   │   └── variables.tf
│   └── security-group/
│       ├── .firefly/
│       │   └── config.yml
│       ├── main.tf
│       └── variables.tf
└── README.md
```

`modules/vpc/.firefly/config.yml`:

```yaml
module_name: "vpc"
module_version: "1.0.0"
provider: "aws"
```

`modules/security-group/.firefly/config.yml`:

```yaml
module_name: "security-group"
module_version: "1.2.0"
provider: "aws"
```

Each module is discovered and published independently.

## Credentials Setup

To import modules from Firefly's Terraform Private Registry, you'll need to configure authentication for your environment.

### Generate a JWT for the Module Registry

Before configuring your local or CI/CD environment, you need to create a JWT (JSON Web Token) that will be used to authenticate with the Terraform Private Registry.

#### Create an API key pair

1. In the Firefly web console, go to **Settings** and click **Access Management**.
2. Create an API key pair using either:
   * **Users** tab — Create a user API key (each user does this for their own access).
   * **Service Account** tab — Generate a key for the service account (recommended; assign only the permissions required for the registry).

#### Generate the JWT

Use your API key pair (Access Key and Secret Key) to generate a JWT via the Firefly API. For the request body and full details, see the [Authentication](https://docs.firefly.ai/general-information/api/auth#authentication) section.

When calling the login endpoint, you can optionally set a **`duration`** field to define how long the token is valid. If **`duration`** is omitted, the token does not expire.

You can use the Module Registry from Firefly in three ways: [**integrated CI**](#github-actions-setup) (e.g., GitHub Actions) [**Firefly runners**](#firefly-runners). Choose the setup below that matches your workflow. [**locally**](#local-setup) (on your machine)

### GitHub Actions Setup

When using Firefly's Module Registry in GitHub Actions workflows, you need to provide the authentication token during the Terraform initialization stage. This token allows Terraform to authenticate with the private registry and download the required modules.

Add the following step to your GitHub Actions workflow:

```yaml
- name: Terraform Init
  env:
    TF_TOKEN_api_firefly_ai: ${{ secrets.TF_CLOUD_TOKEN }}
  run: terraform init
```

Make sure to store your Firefly authentication token (generated in the previous step) as a GitHub secret (e.g., `TF_CLOUD_TOKEN`) in your repository settings.

### Firefly Runners

When running Terraform from a Firefly workspace (Firefly runners), provide the registry token as a workspace variable so that `terraform init` can authenticate with the private registry.

1. Open your workspace and go to **Variables Configuration** (in the workspace setup or **Edit Workspace Variables**).
2. Under **Variables**, add a new variable:
   * **Variable name:** `TF_TOKEN_api_firefly_ai`
   * **Variable value:** with the JWT generated in the [Generate a JWT for the Module Registry](#generate-a-jwt-for-the-module-registry) section above.
3. Enable **Sensitive value** and **Environment variable** so the token is available to Terraform and not displayed in logs.

### Local Setup

#### Configure Terraform credentials

In your `~/.terraform.d/credentials.tfrc.json` file, add the following configuration:

```json
{
 "credentials": {
  "api.firefly.ai": {
    "token": "<your-generated-token>"
  }
 }
}
```

Replace `<your-generated-token>` with the JWT generated in the [Generate a JWT for the Module Registry](#generate-a-jwt-for-the-module-registry) section above.

#### Use the module in your Terraform configuration

Once the setup is complete, you can reference modules from the registry using the standard module block syntax:

```hcl
module "example-module" {
  source  = "api.firefly.ai/firefly-authority/example-module/aws"
  version = "8.2.0"
}
```