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

• GitLab: 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.

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 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:

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:

module "private_mod" {
  source = "git::ssh://[email protected]/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.