InstallSSHKey@0 - Install SSH key v0 task

Use this task in a pipeline to install an SSH key prior to a build or release step.

Syntax

# Install SSH key v0
# Install an SSH key prior to a build or deployment.
- task: InstallSSHKey@0
  inputs:
    knownHostsEntry: # string. Alias: hostName. Required. Known Hosts Entry. 
    #sshPublicKey: # string. SSH Public Key. 
    #sshPassphrase: # string. SSH Passphrase. 
    sshKeySecureFile: # string. Required. SSH Key. 
  # Advanced
    #addEntryToConfig: false # boolean. Add entry to SSH config. Default: false.
    #configHostAlias: # string. Required when addEntryToConfig = true. Alias. 
    #configHostname: # string. Required when addEntryToConfig = true. Host name. 
    #configUser: # string. Optional. Use when addEntryToConfig = true. User. 
    #configPort: # string. Optional. Use when addEntryToConfig = true. Port.

Inputs

knownHostsEntry - Known Hosts Entry
Input alias: hostName. string. Required.

Specifies the SSH key entry for the known_hosts file.

sshPublicKey - SSH Public Key
string.

Optional. Specifies the contents of the public SSH key.

sshPassphrase - SSH Passphrase
string.

Optional. Specifies the passphrase for the SSH key, if any.

sshKeySecureFile - SSH Key
string. Required.

Specifies the SSH key that was uploaded to Secure Files to install on the agent.

addEntryToConfig - Add entry to SSH config
boolean. Default value: false.

Optional. Adds an entry related to the key that was installed to the SSH config file. The key file will be available for all subsequent tasks.

configHostAlias - Alias
string. Required when addEntryToConfig = true.

Specifies the name of the SSH config entry.

configHostname - Host name
string. Required when addEntryToConfig = true.

Specifies the host name property of SSH config entry.

configUser - User
string. Optional. Use when addEntryToConfig = true.

Specifies the user name property of the SSH config entry.

configPort - Port
string. Optional. Use when addEntryToConfig = true.

Specifies the port of the SSH config entry.

Task control options

All tasks have control options in addition to their task inputs. For more information, see Control options and common task properties.

Output variables

None.

Remarks

Use this task in a pipeline to install an SSH key prior to a build or release step.

Note

This task required Git Bash for Windows on the agent.

Usage and best practices

If you install an SSH key in the hosted pools, in later steps in your pipeline, you can connect to a remote system in which the matching public key is already in place. For example, you can connect to a Git repository or to a VM in Azure.

We recommend that you don't pass in your public key as plain text to the task configuration. Instead, set a secret variable in your pipeline for the contents of your mykey.pub file. Then, call the variable in your pipeline definition as $(myPubKey). For the secret part of your key, use the Secure File library in Azure Pipelines.

To create your task, use the following example of a well-configured Install SSH Key task:

steps:
- task: InstallSSHKey@0
  displayName: 'Install an SSH key'
  inputs:
    knownHostsEntry: 'SHA256:1Hyr55tsxGifESBMc0s+2NtutnR/4+LOkVwrOGrIp8U johndoe@contoso'
    sshPublicKey: '$(myPubKey)'
    sshKeySecureFile: 'id_rsa'

Note

Your public key should be added to the repository\organization; otherwise, there will be access issues. For GitHub, follow the guide above. For Azure DevOps Services, use Add the public key to Azure DevOps Services/TFS.

Installing of multiple SSH keys in the same pipeline job

When using more than one key in the same pipeline job, the first one is used by default. To be able to use the desired key when establishing an SSH connection, you can use the Advanced section of the InstallSSHKey task to set the following parameters: addEntryToConfig, configHostAlias, configHostname, configUser, and configPort.

These parameters allow you to add a host to the SSH config file (for example, /root/.ssh/config for Linux) in order to use it in custom scripts via an alias.

After the build is completed, the task will attempt to restore the original SSH config file. If there was no SSH config file initially, then the host is removed from the agent.

An example of multiple SSH keys installation. The case with several GitHub repos and their own key for each one:

pool: <Some Agent Pool>

steps:
- task: InstallSSHKey@0
  inputs:
    knownHostsEntry: $(known_host)
    sshPublicKey: $(first_public_key)
    sshKeySecureFile: $(first_private_key)
    addEntryToConfig: true
    configHostAlias: <first-host-alias>
    configHostname: github.com
    configUser: git
  displayName: Install First Repo SSH Key

- task: InstallSSHKey@0
  inputs:
    knownHostsEntry: $(known_host)
    sshPublicKey: $(second_public_key)
    sshKeySecureFile: $(second_private_key)
    addEntryToConfig: true
    configHostAlias: <second-host-alias>
    configHostname: github.com
    configUser: git
  displayName: Install Second Repo SSH Key

- bash: git clone git@<first-host-alias>:<owner>/<first-repo>.git
  displayName: Clone First Repo

- bash: git clone git@<second-host-alias>:<owner>/<second-repo>.git
  displayName: Clone Second Repo

Related GitHub docs.

Examples

Example setup using GitHub

This section describes how to use a private GitHub repository with YAML from within Azure Pipelines.

If you have a repository that you don't want to expose to the open-source community, a common practice is to make the repository private. However, a CI/CD tool like Azure DevOps needs access to the repository if you want to use the tool to manage the repository. To give Azure DevOps access, you might need an SSH key to authenticate access to GitHub.

Here are the steps to use an SSH key to authenticate access to GitHub:

1. Generate a key pair to use to authenticate access from GitHub to Azure DevOps:

   1. In GitBash, run the following command:

      ssh-keygen -t rsa
      

   2. Enter a name for the SSH key pair. In our example, we use myKey.

      

   3. (Optional) You can enter a passphrase to encrypt your private key. This step is optional. Using a passphrase is more secure than not using one.

      

      ssh-keygen creates the SSH key pairs, and the following success message appears:

      

   4. In Windows File Explorer, check your newly created key pair:

      

2. Add the public key to the GitHub repository. (The public key ends in ".pub"). To do this, go the following URL in your browser: https://github.com/(organization-name)/(repository-name)/settings/keys.

   1. Select Add deploy key.

   2. In the Add new dialog box, enter a title, and then copy and paste the SSH key:

      

   3. Select Add key.

3. Upload your private key to Azure DevOps:

   1. In Azure DevOps, in the left menu, select Pipelines > Library.

      

   2. Select Secure files > + Secure file:

      

   3. Select Browse, and then select your private key:

      

4. Recover your "Known Hosts Entry". In GitBash, enter the following command:

   ssh-keyscan github.com
   

   Your "Known Hosts Entry" is the displayed value that doesn't begin with # in the GitBash results:

   

5. Create a YAML pipeline.

   To create a YAML pipeline, in the YAML definition, add the following task:

   - task: InstallSSHKey@0
    inputs:
      knownHostsEntry: #{Enter your Known Hosts Entry Here}
      sshPublicKey: #{Enter your Public key Here}
      sshKeySecureFile: #{Enter the name of your key in "Secure Files" Here}
   

The SSH keys are now installed, and you can proceed with the script to connect by using SSH, and not the default HTTPS.

Requirements

Requirement	Description
Pipeline types	YAML, Classic build, Classic release
Runs on	Agent, DeploymentGroup
Demands	None
Capabilities	This task does not satisfy any demands for subsequent tasks in the job.
Command restrictions	This task runs using the following command restrictions: restricted
Settable variables	This task has permission to set the following variables: SSH_AGENT_PID, SSH_AUTH_SOCK, INSTALL_SSH_KEY_CONFIG_LOCATION, INSTALL_SSH_KEY_KNOWN_HOSTS_LOCATION
Agent version	2.182.1 or greater
Task category	Utility