Run fails to retrieve remote module with "Permission denied (publickey). Fatal: Could Not Read from Remote Repository"

Problem

When performing a run in HCP Terraform or Terraform Enterprise, the run fails with the following error while attempting to retrieve a module from a Git repository over SSH.

Permission denied (publickey).
fatal: Could not read from remote repository.

Cause

HCP Terraform and Terraform Enterprise require PEM-encoded SSH private keys to access Git-based modules. This error occurs when an SSH key in a different format, such as the newer OpenSSH private key format, is used.

Solution

To resolve this issue, you must generate a new PEM-encoded SSH key and configure it in your organization and workspaces.

Step 1: Verify the SSH Key Format

Check the header of your existing private key file to determine its format. A PEM-encoded key begins with -----BEGIN RSA PRIVATE KEY-----.

Required PEM Format:

-----BEGIN RSA PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCjh2olhqcJBuLG
## ...
-----END RSA PRIVATE KEY-----

If the key header is -----BEGIN OPENSSH PRIVATE KEY-----, it is in the incorrect format and you must generate a new key.

Step 2: Generate a PEM-Encoded Key

Use the ssh-keygen command with the -m PEM flag to generate a new key pair in the required format. This command creates a private key file (service_terraform) and a public key file (service_terraform.pub).

$ ssh-keygen -t rsa -m PEM -f "/Users/your-username/.ssh/service_terraform" -C "service_terraform_hcp"

Step 3: Configure the New SSH Key

After generating the key pair, you need to configure the private key in your HCP Terraform or Terraform Enterprise organization and add the public key to your version control system (VCS) provider.

1. Add the private key to your organization. Follow the instructions to add the SSH private key in your organization's settings.
2. Add the public key to your VCS provider. Copy the contents of the public key file (service_terraform.pub) and add it as a deploy key in your Git repository settings.
3. Assign the key to workspaces. Ensure you assign the new SSH key to any workspaces that use the private module.
4. Queue a new run. After configuring the keys, queue a new run in the workspace to verify that Terraform can now successfully retrieve the module.

Additional Information

For more information, refer to the SSH Keys for Private Modules documentation.