Install SSH Key task

Azure Pipelines

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

YAML snippet

# Install SSH key
# Install an SSH key prior to a build or deployment
- task: InstallSSHKey@0
  inputs:
    knownHostsEntry: 
    sshPublicKey: 
    #sshPassphrase: # Optional
    sshKeySecureFile: 

Arguments

ArgumentDescription
Known Hosts Entry(Required) The entry for this SSH key for the known_hosts file.
SSH Public Key(Optional) The contents of the public SSH key.
SSH Passphrase(Optional) The passphrase for the SSH key, if any.
SSH Key (Secure File)(Required) Select the SSH key that was uploaded to Secure Files to install on the agent.
Control options

Prerequisites

  • GitBash for Windows

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 complete 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.

      Screenshot of the GitBash prompt to enter a name for your SSH key pair.

    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.

      Screenshot of the GitBash prompt to enter a passphrase for your SSH key pair.

      The SSH key pairs are created and the following success message appears:

      Screenshot of the GitBash message that shows that an SSH key pair was created.

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

      Screenshot of the key pair files in Windows File Explorer.

  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:

      Screenshot of the Add new dialog box.

    3. Select Add key.

  3. Upload your private key to Azure DevOps:

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

      Screenshot of the Azure Pipelines menu.

    2. Select Secure files > + Secure file:

      Screenshot of the Secure files menu.

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

      Screenshot of the Upload file dialog box and the Browse button.

  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:

    Screenshot of key search results in GitBash.

  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}
    

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

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'

Open source

This task is open source on GitHub. Feedback and contributions are welcome.