Manage branches with the CLI

After you install the Magento Cloud CLI and set up SSH keys for remote access to your Cloud infrastructure, you can use Magento Cloud CLI commands to manage the environments for your Magento Commerce Cloud projects. For information about the environment architecture, see Starter architecture or Pro architecture.

To manage the branches and environments with the Project Web Interface, see Manage branches with the Project Web Interface.

Common Magento Cloud CLI commands

Magento Cloud CLI commands are very similar to Git commands. You can use them to connect to your Magento Commerce Cloud project and manage your Magento Commerce Cloud environments. Although you can run the commands from any directory, we recommend that you run them from a project directory. When run from a project directory, you can omit the -p <project-ID> parameter.

The following list of commonly used Magento Cloud CLI commands includes required options only. Use the --help option with any command to get more detailed information.

For a full list of commands, see the Magento Cloud CLI reference.

The environment name is different from the environment ID only if you use spaces or capital letters in the environment name. An environment ID consists of all lowercase letters, numbers, and allowed symbols. Capital letters in an environment name are converted to lowercase in the ID; spaces in an environment name are converted to dashes. An environment name cannot include characters reserved for your Linux shell or for regular expressions. Forbidden characters include curly braces ({ }), parentheses, asterisk (*), angle brackets (< >), ampersand (&), percent (%), and other characters.

Get started creating branches

To begin, create a new branch.

1. Log in to your local development system, or switch to, the Magento file system owner.
2. Change to a directory to which the Magento file system owner has write access.

3. Enter the following command in a terminal to log in to your project:

   1
   magento-cloud login
   

4. List your projects. With the project ID, you can complete additional commands.

   1
   magento-cloud project:list
   

5. If necessary, clone the project to your local. You should have cloned when setting up your local development workspace.

   1
   magento-cloud project:get <project ID>
   

6. Change to a project directory. For example, cd /var/www/html/magento2

7. List environments in the project. Every environment includes an active Git branch of your code, database, environment variables, configurations, and services.

   1
   magento-cloud environment:list
   

   magento-cloud environment:list—displays environment hierarchies whereas the git branch command does not.

8. Fetch origin branches to get the latest code:

   1
   git fetch origin
   

9. Check out, or switch to, a specific branch and environment. Git commands only checkout the Git branch. The Magento Cloud command also switches to the active environment.

   1
   magento-cloud environment:checkout <environment ID>
   

   To create a new environment, use magento-cloud environment:branch <environment name> <parent environment ID>

10. Pull any updated code to your local for the environment ID (which is the Git branch):

    1
    git pull origin <environment ID>
    

11. Create a snapshot of the environment as a backup:

    1
    magento-cloud snapshot:create -e <environment ID>
    

Merge a branch

After completing development, you can merge this branch to the parent:

1. Complete code in your local branch.

2. Add, commit, and push changes to the environment.

   1
   git add -A && git commit -m "Commit message" && git push origin <branch-name>
   

3. Merge with the parent environment:

   1
   magento-cloud environment:merge <environment-ID>
   

Delete an environment

Only delete an environment if you are certain that you no longer need it. You cannot recover an environment after you delete it.

You cannot delete the master environment of any project.

You must be a project administrator, environment administrator, or Project Owner to perform this task.

When you delete an environment, the environment is set to inactive. The code is still available in the Git branch, but no longer contains the services or the database. To delete the environment completely, you must also delete the corresponding remote Git branch.

To delete an environment:

1. Open a terminal and navigate to your project.

2. Fetch updates from the remote server.

   1
   git fetch
   

3. Checkout the environment branch.

   1
   magento-cloud environment:checkout <environment-ID>
   

4. Respond to the prompts to delete the local environment and the corresponding remote environment.

   1
   2
   The environment <environment-ID> is currently active: deleting it will delete all associated data.
   Are you sure you want to delete the environment <environment-ID>? [Y/n]
   

   Deleting the environment places it in an inactive state.

   1
   Delete the remote Git branch too? [Y/n]
   

   Deleting the remote Git branch removes the environment from the project.

5. Wait for the environment to delete.

   1
   2
   3
   4
   5
   6
   7
   8
   Deleting environment <environment-ID>
   Waiting for the activity...
     Deleting environment <project-id>-<environment-ID>-xxxxxx
       
     [============================]  1 min (complete)
   Activity ID succeeded
   Deleted remote Git branch <environment-ID>
   Run git fetch --prune to remove deleted branches from your local cache.
   

To delete more than one environment:

You can delete more than one environment at a time by adding multiple environment IDs to the delete command.

1
magento-cloud environment:delete <environment-1-ID> <environment-2-ID>

To activate an inactive environment, use the magento-cloud environment:activate command.

Integration environment IP addresses

The following table lists incoming and outgoing IP addresses used by Magento Commerce Cloud Integration environments. These IP addresses are stable, but might change. We always notify customers before making any IP address changes.

If you have a corporate firewall that blocks outgoing SSH connections, you can add the inbound IP addresses to your whitelist.

Interact with environments via the Magento Cloud CLI

After you setup SSH keys, you can connect from your local workspace to a remote environment and use Magento Cloud CLI commands to interact with your Magento Commerce Cloud project services and modify settings.

The following steps provide an example of accessing a database:

1. SSH to the integration environment.

   1
   magento-cloud ssh
   

2. Find the database login information:

   1
   php -r 'print_r(json_decode(base64_decode($_ENV["MAGENTO_CLOUD_RELATIONSHIPS"]))->database);'
   

   Sample output follows:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   Array
    (
         [0] => stdClass Object
           (
              [username] => user
              [password] =>
              [ip] => 192.0.2.60
              [host] => database.internal
              [query] => stdClass Object
                 (
                   [is_master] => 1
                 )
              [path] => main
              [scheme] => mysql
              [port] => 3306
           )
       )
   

3. Use the following command to connect to the database:

   1
   mysql --host=<host> --user='<database username>' --password='<user password>' --port='<port>' --database='<path>'
   

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
2
3
cd <project directory>
magento-cloud project:list
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.