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

Enable the GitHub integration

This section discusses how to enable the GitHub integration.

  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>
    

To enable the GitHub integration:

  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

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.