GitHub integration

About the GitHub integration

The GitHub integration enables you to manage your Magento Enterprise Cloud Edition environments directly from your GitHub repository. The integration manages content already in GitHub and synchronizes it with Magento Enterprise Cloud Edition. 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 check boxes 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 machine, or switch to, the Magento file system owner.
  2. Change to a directory to which the Magento file system owner has write access, such as the web server docroot.
  3. Log in to your project:

    magento-cloud login
    
  4. List your projects:

    magento-cloud project:list
    
  5. If necessary, clone a project.

    magento-cloud project:get <project ID>
    

    Typically, you should clone the project in the web server’s docroot or a Virtual Host docroot.

  6. Change to a project directory.

    For example, cd /var/www/html/magento2

  7. List environments in the project:

    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.

  8. Fetch origin branches:

    git fetch origin
    
  9. Check out an environment:

    magento-cloud environment:checkout <environment ID>
    

    To create a new environment, use magento-cloud environment:branch <environment name> <parent environment ID>

  10. Pull updated code:

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

    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 Enterprise Cloud Edition 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

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 check box.

    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.