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.
# 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.
# 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. Required. SSH Public Key.
#sshPassphrase: # string. SSH Passphrase.
sshKeySecureFile: # string. Required. SSH Key.
# Install SSH Key v0
# Install an SSH key prior to a build or release.
- task: InstallSSHKey@0
inputs:
hostName: # string. Required. Known Hosts Entry.
sshPublicKey: # string. Required. SSH Public Key.
#sshPassphrase: # string. SSH Passphrase.
sshKeySecureFile: # string. Required. SSH Key.
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.
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.
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.
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
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:
Generate a key pair to use to authenticate access from GitHub to Azure DevOps:
In GitBash, run the following command:
ssh-keygen -t rsa
Enter a name for the SSH key pair. In our example, we use myKey.
(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:In Windows File Explorer, check your newly created key pair:
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
.Select Add deploy key.
In the Add new dialog box, enter a title, and then copy and paste the SSH key:
Select Add key.
Upload your private key to Azure DevOps:
In Azure DevOps, in the left menu, select Pipelines > Library.
Select Secure files > + Secure file:
Select Browse, and then select your private key:
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:
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 |
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 |