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 you use a private GitHub repository.

This integration enables you to:

  • Create a new environment when you create a branch or opening a pull request on GitHub.
  • Rebuild the environment when you push new code to GitHub.
  • Delete the environment when you merge a pull request.

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

Generate a GitHub token

To perform this task, you must be a member of a group with write access to the GitHub repository. (In other words, you must be able to push to the repository.)

To generate a token:

  1. Log in to GitHub.
  2. In your personal settings, on the Personal access tokens tab page, click Generate new token.
  3. In the Token description field, enter a meaningful name.
  4. Select checkboxes corresponding to how you intend to use the token:

    • To integrate with public repositories, select public_repo
    • To integrate with your personal, private repositories, select repo
    • To integrate with your organization’s private repositories, select repo and read:org

    The following figure shows an example of creating a token that can be used to integrate with a private repository to which you have write access:

    Create a GitHub token for a private repository

  5. Click Generate token.
  6. Copy the token to the clipboard.

    Create a GitHub token for a private repository

Enable the GitHub integration

This section discusses how to enable the GitHub integration.

Get started

To get started:

  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>

Enable the integration

To enable the GitHub integration for your environment:

  1. Enable the integration:

    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> is your Magento Commerce (Cloud) project ID

    <your GitHub token> is the token you got in the preceding section

    --repository=USER/REPOSITORY is how you specify your personal, private GitHub repository

    --repository=ORGANIZATION/REPOSITORY is how you specify an organization repository

    --build-pull-requests is an optional parameter that instructs Magento Cloud to deploy after you merge a pull request (true by default)

    --fetch-branches is an optional parameter that causes Magento 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:

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

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

    magento-cloud integration:add --type=github --project=ov58dlacU2e --token=<token> --repository=Magento/teamrepo
  2. Enter the required information when prompted.

    Sample output:

    Created integration wp2f2thlmxwcg (type: github)
    Repository: myUserName/myrepo
    Build PRs: yes
    Fetch branches: yes
    Payload URL:
  3. Copy the Payload URL displayed by the command and continue with the next section.

Add the webhook

To add the webhook to your GitHub repository:

  1. In your GitHub repository, click Settings as the following figure shows.

    Go to your GitHub's account settings

  2. In the left navigation bar, click Webhooks & services.
  3. In the right pane, click Add webhook as the following figure shows.

    Add the webhook to your account

  4. Enter the following information:

    • Payload URL: Enter the URL displayed by the command in the preceding section.
    • Content type: Click application/json
    • Secret: Enter a verification secret.
    • Which events would you like to trigger this webhook?: Click Send me everything
    • Select the Active checkbox.

    The following figure shows an example:

    Add the webhook to your account

  5. Click Add webhook

Verify it works

To verify the integration works:

  1. Make a change in the GitHub repository with which you integrated.
  2. In the Magento Cloud CLI, pull the change to an environment.