Configure SSH Keys Within FlexDeploy

SSH Key credentials support a private key file upload and an optional input for a passphrase. You will be able to download the public key based on the private key that is uploaded.

The private keys should be in OpenSSH format, not Putty PPK files. If using puttygen, please use the menu, conversions → export OpenSSH key.

Auto Import SSH Keys From File System

During server startup, FlexDeploy will look at the system user’s .ssh directory on the server’s file system and automatically create SSH Key credentials for any private key in that directory. It will ignore any file that is authorized_keys, known_hosts, and any file with the .pub extension. These credentials have the naming format Private key - <private key absolute path>. If a credential already exists with that name, then it will check the name of the file that is associated with the credential. If the name of the file matches the absolute path on the file system, then it will be ignored. Otherwise the SSH Key input value of the credential will be overwritten with the private key on the file system. If a credential does not exist with that name, then it will be created automatically. These credentials that are auto imported will need to have their passphrases manually configured from the Credentials screen. In the server logs, you can track the credentials that were created via the autoUploadPrivateKeyCredentials() method every time the server starts.

Note that if the underlying file was modified on the file system after it was already uploaded, then it would not be updated within FlexDeploy unless the credential file was changed, causing the credential SSH Key file to be overwritten. However, this auto-import feature is primarily to assist in auto creating credentials for SSH Keys after configuring FlexDeploy.

Referencing SSH Key Values As Properties

An SSH Key credential that is assigned to an encrypted property within FlexDeploy can be referenced for property replacement or groovy variables. In order to reference the private key, then only the property code can be used. If you want to access the passphrase, then attach the suffix _PASSPHRASE (case sensitive) to the property code.

For example, we have an encrypted property on this workflow with the code ENDPOINT_SSH_KEY.

We could have a step in our workflow to execute some sort of shell script that will make an SSH connection using the property configured on the project. Below is an example of referencing our property in a groovy script, but it would be similar for environment variables or property replacement within files. For accessing the private key then we would use the code ENDPOINT_SSH_KEY. For accessing the passphrase, then it would be ENDPOINT_SSH_KEY_PASSPHRASE. Note that if referencing the passphrase like this, it could fail if the actual value of the property during execution is not an SSH Key type credential.

Trouble Shooting SSH Key Credentials

Permission denied (publickey)

This error shows up when trying to connect to a GIT repository.

The most common reasons for this error happening are

• Public key is not uploaded to a user’s GIT account. Instructions on how to do this will vary by GIT provider, but here is a link on how to do it in GitHub: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account

• Passphrase is incorrect for connecting with the private key

• GIT URL could be incorrect

• Authenticating user may not have access to the repository in the GIT URL property

A couple of other reasons could be

• The system that is authenticating with GIT has an old version of OpenSSH (could use SHA-1 signing of keys) that does not support handling keys generated from a newer version (SHA-2 signature). This could result in a newer SHA-2 signed key trying to be accessed by an older version of OpenSSH that is only aware of SHA-1 signing. Additionally, most GIT providers will only accept SHA-2 signed keys. Please ensure that the OpenSSH version installed is 8.0+ on systems that will be performing GIT operations.

• The system that is authenticating with GIT is Windows-based and is running a version of OpenSSH that is less than 8.4. Please see the Executing On Windows Endpoint With Git Plugin section below.

Executing On Windows Endpoint With GIT Plugin

When executing GIT plugin operations on a Windows system, FlexDeploy uses the SSH_ASKPASS_REQUIRE environment variable to supply the passphrase of the private key. This environment variable was introduced in OpenSSH 8.4. For endpoints that are Windows based, it is recommended that the OpenSSH version should be 8.4+. If the version is <8.4, then trying to use SSH Keys with passphrases will not work when trying to connect to GIT repositories, and will result in an error that includes the message Permission denied (publickey). fatal: Could not read from remote repository. Please make sure you have the correct access rights and the repository exists. which could be misleading as there are many factors that will cause that error message. Note that this is not limited to just with the GIT plugin, as trying to make an SSH connection through a batch script within a workflow could result in a similar issue if trying to use the SSH_ASKPASS_REQUIRE environment variable.

Groovy Functions