Maklum balas Edit

Install SSH Key task

  • Artikel
  • 4 minit untuk dibaca

Azure DevOps Services

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: 
    #addEntryToConfig: # Optional
    #configHostAlias: # Optional
    #configHostname: # Optional
    #configUser: # Optional
    #configPort: # Optional

Arguments

Task control options

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.
Add Entry To Config(Optional) Add entry related to the key installed to the SSH config file. The key file will be available for all subsequent tasks.
Config Host Alias(Optional) Name of SSH config entry.
Config Host Name(Optional) Host name property of SSH config entry.
Config User(Optional) Username property of SSH config entry.
Config Port(Optional) Port of SSH config entry.

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'

Note

Your public key should be added to the repository\organization otherwise you'll get issue with the access. For GitHub please follow the guide above. For Azure DevOps Services please use the following guide: 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 further use it in custom scripts via alias. After build is completed, the task will attempt to restore the original SSH config file. If there was no SSH config file initially, it will just be 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.

Open source

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