Magento 2.0.18 is the final 2.0.x release. After March 2018, Magento 2.0.x will no longer receive security patches, quality fixes, or documentation updates.
To maintain your site's performance, security, and PCI compliance, upgrade to the latest version of Magento.

GitHub integration

About the 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. Therefore, before you begin, make sure your project and environments are 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.

To set up the integration, you must obtain a GitHub token and a webhook. The following sections walk you through the process.

Generate a GitHub token

To perform this task, you must be a member of a group that can write 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 the git branch command does not.
  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}
    

    where

    <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: https://us.magento.cloud/api/projects/ov58dlacU2e/integrations/wO8a0eoamxwcg/hook
    
  3. Copy the Payload URL displayed by the command and continue with the next section.

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.

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