Enable SSH keys

Previous step

Install Magento prerequisites

The SSH protocol is designed to maintain a secure connection between two systems—in this case, your local working environment and your Magento Commerce Cloud Git project.

When initially setting up your local environment, you need to add the SSH keys to the following specific environments:

  • Starter: Add to Master (Production) and any environments you create by branching from Master
  • Pro: Add to Master Integration environment. After your Staging and Production environments are provisioned, you can add the SSH keys to those environments through the Project Web Interface or via SSH and CLI commands.

You must create an SSH key pair on every machine and workspace that requires access to Magento Commerce Cloud project source code and environments. The SSH keys allow you to connect to GitHub to manage source code and to connect to cloud servers without having to constantly supply your username and password.

You can add multiple SSH keys for each system or workspace that you use.

The SSH keys require the following:

For more information on SSH keys, see the following:

Locate an existing SSH key pair

An existing SSH key pair is typically located in the .ssh subdirectory of the user home directory. This folder is hidden and may not display in the File Manager or Finder if your system is not configured to display hidden files and folders.

To check for SSH keys:

  1. In the terminal, list the contents of your SSH directory.

    1
    
    ls ~/.ssh
    
  2. Review the output.

    If you have SSH keys, a directory listing is displayed similar to the following:

    1
    
    id_rsa  id_rsa.pub  known_hosts
    

If the directory does not exist or has no SSH key files, you must generate at least one SSH key and add it to your GitHub account. For instructions, see Generate a new SSH key in the GitHub documentation.

If you have at least one SSH key in your directory, add the key to your Magento and GitHub accounts:

Add a public SSH key to your Magento account

You can add SSH keys to your account in any of the following ways:

After you add a key, you must redeploy active Cloud environments to upload the key.

Add your SSH key using the CLI

To add an SSH key using the Magento Cloud CLI:

  1. Open a terminal application on your local workstation.

  2. If you have not done so already, log in (or switch to) the Magento file system owner to the server on which your SSH keys are located.

  3. Log in to your project:

    1
    
    magento-cloud login
    
  4. Add the key:

    1
    
    magento-cloud ssh-key:add ~/.ssh/id_rsa.pub
    

You can list and delete SSH keys using the Magento Cloud CLI commands ssh-key:list and ssh-key:delete.

Add your SSH key using the Project Web Interface

You must add your SSH public key to your account. After you add the key, you must redeploy all active environments on your account to install the key.

  • Starter: Add to Master (Production) and any environments you create by branching from Master
  • Pro: Add the key to the Staging, Production, and Integration environments

To add an SSH key using the Project Web interface:

  1. Get your public key.

    • In the terminal, navigate to the ~/.ssh directory.

    • Copy the contents of the public key file ~/.ssh/<keyname>.pub to the clipboard.

    If there are no SSH key files in the directory, you must create one. See Generate a new SSH key in the GitHub documentation.

  2. Login and access your project through the Project Web Interface.

  3. In your project, look for the No SSH key icon to the right of the command field. This icon is visible when the project does not contain an SSH key.

    No SSH key

  4. Click the icon to add the key.

    • Copy and paste the content of your public SSH key in the Public key field.

      Add SSH key

    • Follow the prompts on your screen to complete the task.

Add a key from the Cloud Account dashboard

You can add your SSH public key directly from the Cloud Account Settings page.

  1. Open your Cloud account page and log in if required.
  2. On the Cloud account dashboard, click the Account Settings tab.
  3. Under SSH keys, click Add a public key.

Update Cloud environments with a new SSH key

After you add an SSH key, redeploy each active Cloud environment to upload the new key.

Use the Magento Cloud CLI to redeploy the environment:

1
magento-cloud redeploy --project <project-name> --host <host-name> --environment <environment-name>

Set global Git variables

Set required global Git variables on the machine to commit or push to a Git branch. These variables set Git credentials for accessing your GitHub account.

To set variables, enter the following commands on every workspace:

1
git config --global user.name "<your name>"
1
git config --global user.email <your e-mail address>

For more information, see First-Time Git Setup

SSH access with MFA

Magento Commerce Cloud projects that have multi-factor authentication (MFA) enabled require all Magento Commerce Cloud accounts with SSH access to have two-factor authentication and to complete additional steps when using SSH to connect to GitHub or to project environments. See Enable MFA for SSH access.

Unable to access projects without MFA

If you authenticate to a project with multi-factor authentication (MFA) enabled, you might receive the following error when connecting to other projects that do not require MFA:

1
2
   ssh abcdef7uyxabce-master-7rqtabc--mymagento@ssh.us-3.magento.cloud
   abcdef7uyxabce-master-7rqtabc--mymagento@ssh.us-3.magento.cloud: Permission denied (publickey).

During the SSH certificate generation, the Magento Cloud CLI adds an additional SSH key to your local environment. That key will be used by default if your local SSH configuration does not include the SSH key for project access.

To add your SSH key to the local configuration:

  1. Create the config file if it does not exists.

    1
    
     touch ~/.ssh/config
    
  2. Add an IdentityFile configuration.

    1
    2
    
    Host *
      IdentityFile ~/.ssh/id_rsa
    

    You can specify multiple SSH keys by adding multiple IdentityFile entries to your configuration.

  3. Reload your SSH configuration to apply the changes.

    1
    
     source ~/.ssh/config
    

Next step

Set up the Magento file system owner