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.

Use 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. See the Magento Cloud CLI reference.

Get started creating branches

To begin, create a new branch.

To get started with environment branches:

1. On your local workstation, change to your Cloud project directory.

2. Switch to the Magento file system owner.

3. Log in to your Magento project.

   1
   magento-cloud login
   

4. List your projects.

   1
   magento-cloud project:list
   

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

   1
   magento-cloud environment:list
   

   It is important to use the magento-cloud environment:list command because it displays environment hierarchies, whereas the git branch command does not.

6. Fetch origin branches to get the latest code.

   1
   git fetch origin
   

7. Checkout, or switch to, a specific branch and environment.

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

   Git commands only checkout the Git branch. The magento-cloud checkout command checks out the branch and switches to the active environment.

   You can create a new environment branch using the magento-cloud environment:branch <environment-name> <parent-environment-ID> command syntax. It may take some additional time to create and activate a new environment branch.

8. Use the environment ID to pull any updated code to your local. This is not necessary if the environment branch is new.

   1
   git pull origin <environment-ID>
   

9. (Optional) 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 Account 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. Delete the environment branch.

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

   Optionally, 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>
   

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 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.

Get IP address of Cloud instance

Use ping command for retrieving IP address for particular Cloud instance.

Example of usage:

1
ping integration-abcd123-abcd78910.us-3.magentosite.cloud

Sample response:

1
2
3
4
PING integration-abcd123-abcd78910.us-3.magentosite.cloud (34.210.133.187): 56 data bytes
Request timeout for icmp_seq 0
Request timeout for icmp_seq 1
Request timeout for icmp_seq 2

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
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.