SSH and sFTP

SSH, or Secure Shell, is a common protocol used to securely log into remote servers and systems. You will typically use SSH to access your environments directly to enter CLI commands for managing your branching, creating variables, and much more. We also support sFTP (Secure FTP) using your SSH public key.

To use SSH, you need to:

  • Generate your SSH public and private keys
  • Add your SSH public key to your remote server either through CLI commands or the Project Web Interface
  • Use Magento Cloud CLI or Git commands to SSH to an environment

You create an SSH key pair including a public and private key:

  • The public key is safe to provide for accessing a site, SSH, and sFTP.
  • The private key should remain private on your workspace that you use for remote accessing environments. Never share your private key. Do not add it to a ticket, copy it to a chat, or attach it to emails.

How SSH keys work

When you enter an SSH command to connect your client to the remote host, the host and your workspace begin tests back and forth to verify and allow access. These tests use the public and private keys you generated. Your entered command initiates SSH key authentication to request access to the server, indicating the public key to use. The server checks for authorized keys in its list for your public key. When found, it generates a message string and encrypts it with the public key the host has for you. Your system receives the message, decrypts it using your local private key, and merges the message with a session ID. Your system generates an MD5 of the message and session ID, sending it back to the host. If everything checks out, this passes the connection test and completes full SSH access to the host.

You must create an SSH key pair on every machine and workspace that requires access to Cloud for Adobe Commerce 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

Cloud for Adobe Commerce projects that have multi-factor authentication (MFA) enabled require all Cloud for Adobe Commerce 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.

SSH to an environment

You can connect using SSH in any of the following ways:

SSH using Magento Cloud CLI

Magento Cloud CLI commands can only be used in environments with the software installed. These environments include:

  • Starter environments
  • Pro Integration environments

To SSH to an environment using the Magento Cloud command line:

  1. Log in to the project:

    1
    
    magento-cloud login
    
  2. List the project IDs:

    1
    
    magento-cloud project:list
    
  3. List the environments in that project:

    1
    
    magento-cloud environment:list -p <project ID>
    
  4. SSH to the environment:

    1
    
    magento-cloud ssh -p <project ID> -e <environment ID>
    

Locate the SSH command in the Project Web Interface

You can locate the SSH command for all Starter environments and Pro Integration environments through the Project Web Interface.

To copy the SSH command:

  1. Log in to the Project Web Interface.
  2. Select an environment or branch to access.
  3. Click Access Site.

    Find the SSH URL using the Web Interface

  4. Click the clipboard button to copy the full SSH command to the clipboard.
  5. Enter the command in a terminal window to SSH.

Example SSH command:

1
ssh abcdefg123abc-smith-a12b34c--mymagento@ssh.us-2.magento.cloud

SSH commands for Pro Staging and Production

You can not use the Magento Cloud CLI to log in with SSH to the Pro Staging and Production environments, which are not added into the Project Web Interface. You can log in with SSH to those environments and use Linux/Unix commands for managing the system.

With your SSH keys added to those servers, you can use a terminal application, the SSH command, and the URL to access the server.

For the URLs, see the following:

  • Staging: ssh <project ID>_stg@<project ID>.ent.magento.cloud
  • Production: ssh <project ID>@<project ID>.ent.magento.cloud

For example, to log in to the Staging environment, use the following command: ssh abcdefghij_stg@abcdefghij.ent.magento.cloud. For production: ssh abcdefghij@abcdefghij.ent.magento.cloud

SSH tunneling

You can also use SSH tunneling to connect to a service from your local development environment as if the service were local. Before tunneling, you need to have SSH configured.

Use a terminal application to log in and issue commands.

1
magento-cloud login

First, you may want to check if any tunnels are already open using the following command:

1
magento-cloud tunnel:list

To build a tunnel, you must know the name of the app to which to tunnel. Use the following commands to list those applications:

1
cd <project directory>
1
magento-cloud project:list
1
magento-cloud apps

For information on the command, you can enter magento-cloud apps --help.

Set up the SSH tunnel

Use the following command:

1
magento-cloud tunnel:open -e <environment ID> --app <app name>

For example, to open a tunnel to the sprint5 branch in a project with an app named mymagento, enter

1
magento-cloud tunnel:open -e sprint5 --app mymagento

Messages similar to the following display:

1
2
3
4
5
6
7
8
SSH tunnel opened on port 30003 to relationship: solr
SSH tunnel opened on port 30004 to relationship: redis
SSH tunnel opened on port 30005 to relationship: database
Logs are written to: /home/magento_user/.magento/tunnels.log

List tunnels with: magento-cloud tunnels
View tunnel details with: magento-cloud tunnel:info
Close tunnels with: magento-cloud tunnel:close

Get tunnel information

To display information about your tunnel, enter:

1
magento-cloud tunnel:info -e <environment ID>

Connect to services

Now you can connect to services as if they were running locally.

For example, to connect to the database, use the following command:

1
mysql --host=127.0.0.1 --user='<database username>' --pass='<user password>' --database='<name>' --port='<port>'

Details about the service display if you use the magento-cloud tunnel:info command.

sFTP to environments

Typically, you want to use SSH for secure access to your environments and migrate files with rsync commands. We also support accessing your environments using sFTP (secure FTP) with SSH authentication.

You need the following requirements to sFTP into cloud environments:

  • You need to use a client that supports SSH key authentication for sFTP and use your SSH public key.
  • Your public SSH key must be added to the target environment. For Starter environments and Pro Integration environments, you can add it through the Project Web Interface. For Pro Staging and Production, you must enter a Support ticket with your public key attached. Never provide your private SSH key.

When configuring sFTP, use the information from your SSH access environment command (<project-id>-<environment-id>--<app-name>@ssh<cloud-host>) and the following information:

  • Username: All content before the @ in your SSH access destination.
  • Password: You do not need a password for sFTP. sFTP access uses the SSH key based authentication.
  • Host: All content after the @ in your SSH access.
  • Port: 22, which is the default SSH port.
  • SSH Private Key: If necessary, provide the location of your private key to the sFTP client. By default, private keys are stored in the ~/.ssh directory.

Depending on the client, you may need to enter additional options and setup to complete SSH authentication for sFTP. Review the documentation for your selected client.

For Starter environments and Pro Integration environments, you may also want to consider adding a mount for access to a specific directory. You would add the mount to your .magento.app.yaml file. For a list of writable directories, see Project structure. This mount point will only work in those environments.

For Pro Staging and Production environments, you need to enter a Support ticket to request sFTP access in those environments. We can then create a mount point and provide access to the specific pub/media folder.