# SSH Private Module Access

This guide walks you through configuring SSH-based access to private Git repositories containing Terraform modules, so they can be consumed by Firefly workspaces.

## Prerequisites

* A private Git repository containing a valid Terraform module.
* Access to the repository settings to add deploy keys.
* A Firefly workspace where the module will be consumed.
* An SSH key pair (public + private key) already generated and available for use.

***

## Step 1: Create a Deployment Key

A deploy key is an SSH key that grants access to a **single repository**. GitHub attaches the public part of the key directly to the repository (not to a personal account), while the private part remains on your server/CI environment.

Deploy keys are **read-only by default**, but you can optionally grant write access when adding them to the repository.

> For full details, see the official guides:
>
> * **GitHub:** [Managing deploy keys](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys#deploy-keys)
> * **GitLab:** [Create a project deploy key](https://docs.gitlab.com/user/project/deploy_keys/#create-a-project-deploy-key)

### Important Considerations

* **One key per repository** — Each deploy key can only be used for a single repository. If you need to access multiple private module repos, generate a dedicated key pair for each one.
* **No passphrase by default** — Deploy keys are not protected by a passphrase, so if the key is compromised it can be used immediately. Store it securely.
* **Not linked to organization membership** — If the user who created the deploy key is removed from the repo, the key remains active.
* **No expiry date** — Deploy keys do not expire. Plan for periodic rotation.

***

## Step 2: Add the Public Key to the Repository

### GitHub

1. Navigate to the main page of the private module repository.
2. Go to **Settings** > **Deploy Keys** > **Add deploy key**.
3. In the **Title** field, provide a descriptive title (e.g., `firefly-workspace-module-access`).
4. In the **Key** field, paste the contents of `firefly_deploy_key.pub`.
5. **Do not** select "Allow write access" — read-only is sufficient for module fetching.
6. Click **Add key**.
7. Confirm the deploy key appears in the repository's Deploy Keys list.

> Deploy keys can also be created via the [GitHub REST API for deploy keys](https://docs.github.com/en/rest/deploy-keys).

### GitLab

1. Navigate to your project using the search bar at the top.
2. In the left sidebar, go to **Settings** > **Repository**.
3. Expand the **Deploy keys** section.
4. Click **Add new key**.
5. In the **Title** field, provide a descriptive title (e.g., `firefly-workspace-module-access`).
6. In the **Key** field, paste the contents of `firefly_deploy_key.pub`.
7. **Do not** select "Grant write permissions to this key" — read-only is sufficient for module fetching.
8. Optionally set an **Expiration date** for the key.
9. Click **Add key**.
10. Confirm the deploy key appears in the project's Deploy Keys list.

> Deploy keys can also be created via the [GitLab CLI](https://docs.gitlab.com/user/project/deploy_keys/#create-a-project-deploy-key) using `glab deploy-key add`.

***

## Step 3: Base64 Encode the Private Key

Encode the private key to base64 for safe storage as an environment variable:

```bash
cat firefly_deploy_key | base64 -w 0
```

Copy the resulting base64-encoded string. This value will be stored in Firefly in the next step.

***

## Step 4: Add the SSH Key as an Environment Variable in the Firefly Workspace

1. In the Firefly workspace, create a new environment variable with the following settings:

   | Field              | Value                                                                         |
   | ------------------ | ----------------------------------------------------------------------------- |
   | **Variable name**  | `SSH_PRIVATE_KEY`                                                             |
   | **Variable value** | The base64-encoded private key from Step 3                                    |
   | **Type**           | Environment Variable (not a Terraform variable)                               |
   | **Sensitive**      | Enabled — the value is write-only and will not be displayed in the UI or logs |
2. Confirm the variable appears in the workspace's variable list.

***

## Step 5: Configure Module Source

Push a Terraform configuration that references the private module via SSH:

```hcl
module "private_mod" {
  source = "git::ssh://git@github.com/org/private-module.git//subdir?ref=main"
}
```

The workspace will use the `SSH_PRIVATE_KEY` environment variable automatically during module initialization.

***

## Limitations

* **One SSH key per workspace** — Each workspace supports a single `SSH_PRIVATE_KEY` environment variable, which means only one private module repository can be accessed per workspace. If your Terraform configuration references multiple private modules from different repositories, they cannot all be served by the same SSH key.


---

# Agent Instructions: 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/ssh-private-module-access.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.