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:

Log in to GitHub.
In your personal settings, on the Personal access tokens tab page, click Generate new token.
In the Token description field, enter a meaningful name.
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:
Click Generate token.
Copy the token to the clipboard.

Enable the GitHub integration

This section discusses how to enable the GitHub integration.

Get started

To get started:

Log in to your local development system, or switch to, the Magento file system owner.
Change to a directory to which the Magento file system owner has write access.
Enter the following command in a terminal to log in to your project:
```
magento-cloud login
```
List your projects. With the project ID, you can complete additional commands.
```
magento-cloud project:list
```
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>
```
Change to a project directory. For example, cd /var/www/html/magento2
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.
Fetch origin branches to get the latest code:
```
git fetch origin
```
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>
Pull any updated code to your local for the environment ID (which is the Git branch):
```
git pull origin <environment ID>
```

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:

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
```

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

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:

In your GitHub repository, click Settings as the following figure shows.
In the left navigation bar, click Webhooks & services.
In the right pane, click Add webhook as the following figure shows.
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:
Click Add webhook

Verify it works

To verify the integration works:

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

Edit this page on GitHub

Give us feedback