Manage branches with the CLI

When managing with your environment, you will tend to use the Magento CLI and SSH into the system. You should have the Magento CLI installed and SSH keys set up. For detailed information on the environment architecture, see Starter or Pro architecture information.

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

Common Magento CLI commands

The following Magento CLI commands can be run from any directory and run best from a project directory. When run from a project directory, you can omit the -p <project ID> parameter. These commands are meant to be used to manage integration environments. You may notice these commands are similar to Git commands. The magento-cloud versions directly connect with Magento Git, the Magento ECE project, and provide Git features.

All commands are shown with required options only. Get help for any magento-cloud command by appending --help.

git commit --allow-empty -m "redeploy" && git push <branch name>
Push an empty commit to force a redeployment. Some actions, like adding a user for example, don’t result in deployment.
magento-cloud login
Log in to the project.
magento-cloud project:get <project ID> <directory> -e <environment ID>
Clone a project to a directory. To clone the master environment, omit -e <environment ID>.
magento-cloud environment:list -p <project ID>
List the environments in the current project (that is, the project that corresponds to the directory in which you run the command).
magento-cloud environment:branch <name> <parent branch>
Create a new branch with a name and an ID. This information corresponds to the environment.

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.

magento-cloud environment:checkout <environment ID>
Check out an existing environment.
magento-cloud environment:merge -p <project ID> -e <environment ID>
Merge changes in this environment with its parent.
magento-cloud environment:synchronize -p <project ID> -e <environment ID> {code|data}
Synchronize (that is, git pull) code and/or data from the parent to this environment.
magento-cloud variable:list
List variables in this environment.
magento-cloud variable:set <name> <value>
Set a value for an environment variable in this environment.

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

Get started creating branches

To begin, you’ll need a branch to work in.

  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:

    magento-cloud login
  4. List your projects. With the project ID, you can complete additional commands.

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

    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.

    magento-cloud environment:list

    magento-cloud environment:list displays environment hierarchies whereas git branch displays does not. If you have any nested environments, use magento-cloud environment:list to see the full list.

  8. Fetch origin branches to get the latest code:

    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.

    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):

    git pull origin <environment ID>
  11. Create a snapshot of the environment as a backup:

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

Merge a branch

After completing development, you can merge this branch to the parent. The following instructions provide an example.

  1. Complete code in your local branch.
  2. Add, commit, and push your change to the environment:

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

    Where <branch name> is the Git name of the environment (that is, the environment ID).

  3. Merge with the parent environment:

    magento-cloud environment:merge <environment ID>

    For example,

    magento-cloud environment:merge master

Optionally delete the environment

Before you delete an environment, make sure you don’t need it anymore. You cannot recover a deleted environment later.

You cannot delete the master environment of any project.

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

This section discusses how to optionally delete an environment in the following ways:

  • Make the environment inactive but let it remain in the project
  • Delete the environment entirely and remove it from the project

To delete a environment:

  1. Log in to your project if you haven’t already done so.
  2. Fetch branches from the origin server.

    git fetch origin
  3. To delete the branch entirely (removing it from the project), check out the branch.

    magento-cloud environment:checkout <environment ID>
  4. Delete the environment:

    magento-cloud environment:delete <environment ID>

    For example, to delete the deleteme environment:

    magento-cloud environment:delete deleteme

    To delete more than one environment:

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

    For additional options, see the command-line help:

    magento-cloud environment:delete --help
  5. Answer the prompt:

     Are you sure you want to delete the remote Git branch deleteme? [Y/n]

    A Y answer makes the branch inactive but leaves it in the project.

  6. Answer the prompt:

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

    A Y answer completely removes the branch from the project.

Wait for the environment to delete.

To activate the environment later, 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 in the future. Prior to any future change, all affected customers will receive ample warning.

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

Outbound IP addresses Inbound IP addresses
US Region EU Region US Region EU Region

Interact with environments via CLI

After setting up your set up SSH, you can interact with services and modify settings through your local to a remote environment.

The following steps provide an example of accessing a database:

  1. SSH to the integration environment.

    magento-cloud ssh
  2. Find the database login information:

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

    Sample output follows:

          [0] => stdClass Object
               [username] => user
               [password] =>
               [ip] =>
               [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:

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