DocumentationCommerceCommerce on Cloud Infrastructure Guide

Manage branches with the CLI

Last update: Mon Feb 05 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Developer

To install the magento-cloud CLI, see the Cloud CLI reference. 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 projects. For information about the environment architecture, see Starter architecture or Pro architecture.

To manage the branches and environments with the Cloud Console, see Manage branches with the Cloud Console.

Use CLI commands

The magento-cloud CLI commands are similar to Git commands. You can use them to connect to your project and manage your environments. Although you can run the commands from any directory, it is recommended that you run them from a project directory. When run from a project directory, you can omit the -p <project-ID> parameter. See the Cloud CLI reference.

Clone the project

The following instructions use a combination of magento-cloud CLI commands and Git commands to clone your project to your local workstation. To see a full list of magento-cloud CLI commands, use the magento-cloud list command.

IMPORTANT
Some Git commands cannot complete an action in your Adobe Commerce on cloud infrastructure project. For example, you can create a branch using a Git command, but you cannot create and activate a new environment. You must create an environment using the magento-cloud environment:branch <branch-name> command for the environment to become active. Alternatively, you can use the Cloud Console to create active environments. See Cloud CLI reference.

To clone a project master environment:

  1. Log in to your local workstation with a file system owner account.

  2. Change to the web server or virtual host docroot directory.

  3. Log in using the magento-cloud CLI.

    code language-bash 
    magento-cloud login

  4. List your projects.

    code language-bash 
    magento-cloud project:list

  5. Clone a project.

    code language-bash 
    magento-cloud project:get <project-ID>

    When prompted, provide a directory name.

  6. Change to the magento2 directory.

  7. List available environments for the project.

    code language-bash 
    magento-cloud environment:list
    note important
    IMPORTANT
    The magento-cloud environment:list command displays environment hierarchies, whereas the git branch command does not.

  8. Fetch the remote branches.

    code language-bash 
    git fetch origin

  9. Pull updated code.

    code language-bash 
    git pull origin <environment-ID>
TIP
See Integrations for information about using Git-based hosting services with Adobe Commerce on cloud infrastructure.

Create a branch for development

After cloning your project and updating the Adobe Commerce administrator account configuration, you can branch for development. As stated earlier, you must create an environment using the magento-cloud environment:branch <branch-name> command or the Cloud Console for the environment to become active.

  • For Starter, consider creating a branch for staging, then create a development branch based on the staging branch.
  • For Pro, create development branches based on the Integration branch.

To create a development branch:

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

  2. Create an environment based on the branch recommended for your project workflow.

    code language-bash 
    magento-cloud branch <new-environment-name> integration

  3. Update dependencies.

    code language-bash 
    composer --no-ansi --no-interaction install --no-progress --prefer-dist --optimize-autoloader

  4. [optional] Create a backup of the environment.

Merge a branch

After completing development, merge this branch to the parent:

  1. Commit and push code changes:

    code language-bash 
    git add -A && git commit -m "Add message here"
    code language-bash 
    git push origin <branch-name>

  2. Merge with the parent environment:

    code language-bash 
    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.

WARNING
You cannot delete the master branch of any project.

You must be a project administrator, environment administrator, or Account Owner to perform this task. See Manage user access to Cloud projects.

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. On your local workstation, change to your project directory.

  2. Fetch updates from the remote server.

    code language-bash 
    git fetch

  3. Delete the environment branch.

    code language-bash 
    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.

    code language-bash 
    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.

    code language-terminal 
    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.

    code language-terminal 
    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.

    code language-terminal 
    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.
TIP
To activate an inactive environment, use the magento-cloud environment:activate command.

Interact with remote environments

After you set up SSH keys, you can connect from your local workspace to a remote environment and interact with your project services and modify settings.

05f2f56e-ac5d-4931-8cdb-764e60e16f26