GitHub integration

The GitHub integration enables you to manage your Magento Commerce Cloud environments directly from your GitHub repository. The integration manages content already in GitHub and synchronizes it with Magento Commerce. Before you begin, your project and environments must be in a GitHub repository.

We strongly recommend using a private repository for your Magento Commerce Cloud project to protect any proprietary information or development work, such as extensions and sensitive configurations.

This integration enables you to:

• Create a new environment when you create a branch
• Redeploy the environment when you merge a pull request
• Delete the environment when you delete the branch

You must obtain a GitHub token and a webhook to continue the process.

Generate a GitHub token

You must be a member of a group with write-access to the GitHub repository, so that you can push to the repository. See GitHub: Create.

Prepare your repository

You need to clone your Magento Commerce Cloud project from an existing environment and migrate the project branches to a new, empty GitHub repository, preserving the same branch names. It is critical to retain an identical Git tree, so that you do not lose any existing environments or branches in your Magento Commerce Cloud project.

1. From the terminal, log in to your Magento Commerce Cloud project.

   1
   magento-cloud login
   

2. List your projects and copy the project ID.

   1
   magento-cloud project:list
   

3. Clone the project to your local environment.

   1
   magento-cloud project:get <project-ID>
   

4. Add your GitHub repository as a remote.

   1
   git remote add origin git@github.com:<user-name>/<repo-name>.git
   

5. Delete the default magento remote.

   1
   git remote remove magento
   

6. Verify that you added the GitHub remote correctly.

   1
   git remote -v
   

   You should see the following:

   1
   2
   origin git@github.com:<user-name>/<repo-name>.git (fetch)
   origin git@github.com:<user-name>/<repo-name>.git (push)
   

7. Push the project files to your new GitHub repository. Remember to keep all branch names the same.

   1
   git push -u origin master
   

   If you are starting with a new GitHub repository, you may have to use the -f option, because the remote repository does not match your local copy.

8. Verify that your GitHub repository contains all of your project files.

Enable the GitHub integration

The following enables the GitHub integration and provides a Payload URL to use when creating a webhook.

The following command overwrites all code in your Magento Commerce Cloud project with code from your GitHub repository. This includes all branches, including the Production branch. This action happens instantly and cannot be undone. As a best practice, it is very important to clone all of your branches from your Magento Commerce Cloud project and push them to your GitHub repository before adding the GitHub integration.

To enable the GitHub integration:

1. Enable the integration.

   1
   magento-cloud integration:add --type=github --project=<project-ID> --token=<your-GitHub-token> {--repository=USER/REPOSITORY | --repository=ORGANIZATION/REPOSITORY} [--build-pull-requests={true|false} --fetch-branches={true|false}
   

   • <project-ID>—Your Magento Commerce Cloud project ID
   • <your-GitHub-token>—The personal access token you generated for GitHub
   • --repository=USER/REPOSITORY—Your personal GitHub repository name
   • --repository=ORGANIZATION/REPOSITORY—The organization repository name
   • --build-pull-requests—An optional parameter that instructs Magento Commerce Cloud to deploy after you merge a pull request (true by default)
   • --fetch-branches—An optional parameter that causes Magento Commerce Cloud to track branches and deploy after you update a branch (true by default)

   Example 1: Enable the GitHub integration for a personal, private repository:

   1
   magento-cloud integration:add --type=github --project=ov58dlacU2e --token=<token> --repository=myUserName/myrepo
   

   Example 2: Enable the GitHub integration for an organization repository:

   1
   magento-cloud integration:add --type=github --project=ov58dlacU2e --token=<token> --repository=Magento/teamrepo
   

2. Enter the required information when prompted.

3. Copy the Payload URL displayed by the return output.

   1
   2
   3
   4
   5
   Created integration wp2f2thlmxwcg (type: github)
   Repository: myUserName/myrepo
   Build PRs: yes
   Fetch branches: yes
   Payload URL: https://us.magento.cloud/api/projects/ov58dlacU2e/integrations/wO8a0eoamxwcg/hook
   

Add the webhook in GitHub

In order to communicate events—such as a push—with your Cloud Git server, you need to create a webhook for your GitHub repository:

1. In your GitHub repository, click the Settings tab.

2. In the left navigation bar, click Webhooks.

3. In the Webhooks pane, click Add webhook.

4. In the Webhooks/Add webhook form, edit the following fields:

   • Payload URL: Enter the URL returned when you enabled the GitHub integration.
   • Content type: Choose application/json from the list.
   • Secret: Enter a verification secret.
   • Which events would you like to trigger this webhook?: Select Send me everything.
   • Select the Active checkbox.

5. Click Add webhook.

Test the integration

To verify the integration works, make a change in the GitHub repository and use the magento-cloud CLI to pull the change into the local environment.