magento · hguthrie · Mar 1, 2019 · Feb 28, 2019 · Feb 28, 2019 · Mar 1, 2019
diff --git a/common/images/cloud_github-acct-settings.png b/common/images/cloud_github-acct-settings.png
diff --git a/common/images/cloud_github-acct-webhook.png b/common/images/cloud_github-acct-webhook.png
diff --git a/common/images/cloud_github-acct-webhook2.png b/common/images/cloud_github-acct-webhook2.png
diff --git a/guides/v2.0/cloud/project/project-integrate-github.md b/guides/v2.0/cloud/project/project-integrate-github.md
@@ -98,29 +98,25 @@ To enable the GitHub integration for your environment:
 
 5.	Copy the Payload {% glossarytooltip a05c59d3-77b9-47d0-92a1-2cbffe3f8622 %}URL{% endglossarytooltip %} displayed by the command and continue with the next section.
 
-## Add the webhook {#cloud-int-gh-hook}
+## Add the webhook in GitHub
 
-To add the webhook to your GitHub repository:
+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 **Settings** as the following figure shows.
+1.  In your GitHub repository, click the **Settings** tab.
 
-	![Go to your GitHub's account settings]({{ site.baseurl }}/common/images/cloud_github-acct-settings.png){:width="650px"}
-2.	In the left navigation bar, click **Webhooks & services**.
-3.	In the right pane, click **Add webhook** as the following figure shows.
+1.  In the left navigation bar, click **Webhooks**.
 
-	![Add the webhook to your account]({{ site.baseurl }}/common/images/cloud_github-acct-webhook.png){:width="650px"}
-4.	Enter the following information:
+1.  In the _Webhooks_ pane, click **Add webhook**.
 
-	*	**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.
+1.  In the _Webhooks/Add webhook_ form, edit the following fields:
 
-	The following figure shows an example:
+    -  **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.
 
-	![Add the webhook to your account]({{ site.baseurl }}/common/images/cloud_github-acct-webhook2.png){:width="650px"}
-5.	Click **Add webhook**
+1.  Click **Add webhook**.
 
 ## Verify it works {#cloud-int-gh-verify}
 

diff --git a/guides/v2.1/cloud/integrations/bitbucket-integration.md b/guides/v2.1/cloud/integrations/bitbucket-integration.md
@@ -22,7 +22,7 @@ Before you enable the integration, you must have the following:
 
 ## Prepare your repository
 
-You need to clone your {{site.data.var.ece}} project from an existing environment and migrate the project branches to a new, empty Bitbucket repository, preserving the same branch names.  It is **critical** to retain an identical Git tree, so that you do not lose any existing environments or branches in your {{site.data.var.ece}} project.
+You need to clone your {{site.data.var.ece}} project from an existing environment and migrate the project branches to a new, empty Bitbucket repository, preserving the same branch names. It is **critical** to retain an identical Git tree, so that you do not lose any existing environments or branches in your {{site.data.var.ece}} project.
 
 1.  From the terminal, log in to your {{site.data.var.ece}} project.
 

diff --git a/guides/v2.1/cloud/integrations/github-integration.md b/guides/v2.1/cloud/integrations/github-integration.md
@@ -22,78 +22,131 @@ You must obtain a GitHub token and a webhook to continue the process.
 
 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](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/).
 
-## Enable the GitHub integration
+## Prepare your repository
 
-This section discusses how to enable the GitHub integration.
+You need to clone your {{site.data.var.ece}} project from an existing environment and migrate the project branches to a new, empty GitHub repository, preserving the same branch names. It is **critical** to retain an identical Git tree, so that you do not lose any existing environments or branches in your {{site.data.var.ece}} project.
 
-{% include cloud/cli-get-started.md %}
+1.  From the terminal, log in to your {{site.data.var.ece}} project.
 
-#### To enable the GitHub integration:
+    ```bash
+    magento-cloud login
+    ```
+
+1.  List your projects and copy the project ID.
+
+    ```bash
+    magento-cloud project:list
+    ```
+
+1.  Clone the project to your local environment.
+
+    ```bash
+    magento-cloud project:get <project-ID>
+    ```
+
+1.  Add your GitHub repository as a remote.
+
+    ```bash
+    git remote add origin git@github.com:<user-name>/<repo-name>.git
+    ```
+
+1.  Delete the default `magento` remote.
 
-1.	Enable the integration:
+    ```bash
+    git remote remove magento
+    ```
 
-		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}
+1.  Verify that you added the GitHub remote correctly.
 
-	where
+    ```bash
+    git remote -v
+    ```
 
-	`<project ID>` is your {{site.data.var.ece}} project ID
+    You should see the following:
 
-	`<your GitHub token>` is the token you got in the preceding section
+    ```terminal
+    origin git@github.com:<user-name>/<repo-name>.git (fetch)
+    origin git@github.com:<user-name>/<repo-name>.git (push)
+    ```
+    {: .no-copy}
 
-	`--repository=USER/REPOSITORY` is how you specify your personal, private GitHub repository
+1.  Push the project files to your new GitHub repository. Remember to keep all branch names the same.
 
-	`--repository=ORGANIZATION/REPOSITORY` is how you specify an organization repository
+    ```bash
+    git push -u origin master
+    ```
+
+    If you are starting with a new GitHub repository, you may have to use the `-f` option, because the remote repository does not match your local copy.
+
+1.  Verify that your GitHub repository contains all of your project files.
+
+## Enable the GitHub integration
+
+The following enables the GitHub integration and provides a Payload URL to use when creating a webhook.
+
+{: .bs-callout .bs-callout-warning}
+The following command overwrites _all_ code in your {{site.data.var.ece}} project with code from your GitHub repository. This includes all branches, including the Production branch. This action happens instantly and cannot be undone. As a best practice, it is very important to clone all of your branches from your {{site.data.var.ece}} project and push them to your GitHub repository **before** adding the GitHub integration.
+
+#### To enable the GitHub integration:
 
-	`--build-pull-requests` is an optional parameter that instructs Magento Cloud to deploy after you merge a pull request (`true` by default)
+1.  Enable the integration.
 
-	`--fetch-branches` is an optional parameter that causes Magento Cloud to track branches and deploy after you update a branch (`true` by default)
+    ```bash
+    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}
+    ```
 
-	**Example 1**: Enable the GitHub integration for a personal, private repository:
+    -   `<project-ID>`—Your {{site.data.var.ece}} project ID
+    -   `<your-GitHub-token>`—The personal access token you generated for GitHub
+    -   `--repository=USER/REPOSITORY`—Your personal GitHub repository name
+    -   `--repository=ORGANIZATION/REPOSITORY`—The organization repository name
+    -   `--build-pull-requests`—An _optional_ parameter that instructs {{site.data.var.ece}} to deploy after you merge a pull request (`true` by default)
+    -   `--fetch-branches`—An _optional_ parameter that causes {{site.data.var.ece}} to track branches and deploy after you update a branch (`true` by default)
 
-		magento-cloud integration:add --type=github --project=ov58dlacU2e --token=<token> --repository=myUserName/myrepo
+    **Example 1**: Enable the GitHub integration for a personal, private repository:
 
-	**Example 2**: Enable the GitHub integration for an organization repository:
+    ```bash
+    magento-cloud integration:add --type=github --project=ov58dlacU2e --token=<token> --repository=myUserName/myrepo
+    ```
 
-		magento-cloud integration:add --type=github --project=ov58dlacU2e --token=<token> --repository=Magento/teamrepo
-6.	Enter the required information when prompted.
+    **Example 2**: Enable the GitHub integration for an organization repository:
 
-	Sample output:
+    ```bash
+    magento-cloud integration:add --type=github --project=ov58dlacU2e --token=<token> --repository=Magento/teamrepo
+    ```
 
-		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
+1.  Enter the required information when prompted.
 
-5.	Copy the Payload {% glossarytooltip a05c59d3-77b9-47d0-92a1-2cbffe3f8622 %}URL{% endglossarytooltip %} displayed by the command and continue with the next section.
+1.  Copy the **Payload URL** displayed by the return output.
 
-## Add the webhook {#cloud-int-gh-hook}
+    ```terminal
+    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
+    ```
+    {: .no-copy}
 
-To add the webhook to your GitHub repository:
+## Add the webhook in GitHub
 
-1.	In your GitHub repository, click **Settings** as the following figure shows.
+In order to communicate events—such as a push—with your Cloud Git server, you need to create a webhook for your GitHub repository:
 
-	![Go to your GitHub's account settings]({{ site.baseurl }}/common/images/cloud_github-acct-settings.png){:width="650px"}
-2.	In the left navigation bar, click **Webhooks & services**.
-3.	In the right pane, click **Add webhook** as the following figure shows.
+1.  In your GitHub repository, click the **Settings** tab.
 
-	![Add the webhook to your account]({{ site.baseurl }}/common/images/cloud_github-acct-webhook.png){:width="650px"}
-4.	Enter the following information:
+1.  In the left navigation bar, click **Webhooks**.
 
-	*	**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.
+1.  In the _Webhooks_ pane, click **Add webhook**.
 
-	The following figure shows an example:
+1.  In the _Webhooks/Add webhook_ form, edit the following fields:
 
-	![Add the webhook to your account]({{ site.baseurl }}/common/images/cloud_github-acct-webhook2.png){:width="650px"}
-5.	Click **Add webhook**
+    -  **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.
 
-## Verify it works {#cloud-int-gh-verify}
+1.  Click **Add webhook**.
 
-To verify the integration works:
+## Test the integration
 
-1.	Make a change in the GitHub repository with which you integrated.
-2.	In the Magento Cloud CLI, pull the change to an environment.
+To verify the integration works, make a change in the GitHub repository and use the magento-cloud CLI to pull the change into the local environment.