共用方式為

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.

Inputs

sshPublicKey - SSH Public Key
string. Required.

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.


hostName - Known Hosts Entry
string. Required.

Specifies the SSH key entry for the known_hosts file.


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.

      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.

      ssh-keygen creates the SSH key pairs, 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}

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 Any
Settable variables Any
Agent version 2.117.0 or greater
Task category Utility