Auto-merge (#16761)

lecoursen · mattpollard · myarb · web-flow · commit d20831c23f0c · 2020-12-15T21:41:17.000Z
* Add new article * Mention auto-merge in related articles * Add new article * Make intro inclusive * Add content for repo setting * Add versioning to reusable * Add procedures * Add gated features callout * Add permissions statements * Add conceptual content * Fix filename * Add missing step * Fix syntax * Add 💅 * Update permissions * Add 💅 * Add missing period * Add 💅 * Add 💅 * Add auto-merge to permissions articles * Fix permissions * Add 💅 * Let @mattpollard fix everything and take partial credit Co-authored-by: Matt Pollard <mattpollard@users.noreply.github.com> * Incorporate answers to questions * Add how to provide feedback * Update feedback link Co-authored-by: Matt Pollard <mattpollard@users.noreply.github.com> Co-authored-by: Melanie Yarbrough <11952755+myarb@users.noreply.github.com>
diff --git a/assets/images/help/pull_requests/allow-auto-merge-checkbox.png b/assets/images/help/pull_requests/allow-auto-merge-checkbox.png
diff --git a/assets/images/help/pull_requests/confirm-auto-merge-button.png b/assets/images/help/pull_requests/confirm-auto-merge-button.png
diff --git a/assets/images/help/pull_requests/disable-auto-merge-button.png b/assets/images/help/pull_requests/disable-auto-merge-button.png
diff --git a/assets/images/help/pull_requests/enable-auto-merge-button.png b/assets/images/help/pull_requests/enable-auto-merge-button.png
diff --git a/assets/images/help/pull_requests/enable-auto-merge-drop-down.png b/assets/images/help/pull_requests/enable-auto-merge-drop-down.png
diff --git a/assets/images/help/pull_requests/pull-request-information-fields.png b/assets/images/help/pull_requests/pull-request-information-fields.png
diff --git a/content/github/administering-a-repository/about-protected-branches.md b/content/github/administering-a-repository/about-protected-branches.md
@@ -11,12 +11,16 @@ versions:
   github-ae: '*'
 ---
 
+### About protected branches
+
 {% data reusables.pull_requests.about-protected-branches %} You can choose to enforce restrictions on how a pull request is merged into your repository.
 
 Repository owners and people with admin permissions for a repository can enforce certain workflows or requirements, before a collaborator can merge a branch in your repository by creating protected branch rules.
 
 {% data reusables.repositories.branch-rules-example %} For more information, see "[Configuring protected branches](/articles/configuring-protected-branches/)."
 
+{% data reusables.pull_requests.you-can-auto-merge %}
+
 ### Prioritization of protected branch rules
 
 If a repository has multiple protected branch rules that affect the same branches, the rules that include a specific branch name have the highest priority. If there is more than one protected branch rule that references the same specific branch name, then the branch rule created first will have higher priority.
diff --git a/content/github/administering-a-repository/configuring-pull-request-merges.md b/content/github/administering-a-repository/configuring-pull-request-merges.md
@@ -1,6 +1,6 @@
 ---
 title: Configuring pull request merges
-intro: 'You can configure pull request merges on {% data variables.product.product_location %} to match your workflow and preferences for managing Git history by enabling, disabling, or enforcing standard merge commits, squashed commits, or rebased commits on all pull requests in your repository.'
+intro: 'You can configure pull request merges on {% data variables.product.product_location %} to match your workflow and preferences for managing Git history.'
 mapTopic: true
 redirect_from:
   - /articles/configuring-pull-request-merges
diff --git a/content/github/administering-a-repository/index.md b/content/github/administering-a-repository/index.md
@@ -39,6 +39,7 @@ versions:
     {% link_in_list /about-merge-methods-on-github %}
     {% link_in_list /configuring-commit-squashing-for-pull-requests %}
     {% link_in_list /configuring-commit-rebasing-for-pull-requests %}
+    {% link_in_list /managing-auto-merge-for-pull-requests-in-your-repository %}
     {% link_in_list /managing-the-automatic-deletion-of-branches %}
 {% topic_link_in_list /defining-the-mergeability-of-pull-requests %}
     {% link_in_list /about-protected-branches %}
diff --git a/content/github/administering-a-repository/managing-auto-merge-for-pull-requests-in-your-repository.md b/content/github/administering-a-repository/managing-auto-merge-for-pull-requests-in-your-repository.md
@@ -0,0 +1,17 @@
+---
+title: Managing auto-merge for pull requests in your repository
+intro: "You can allow or disallow auto-merge for pull requests in your repository."
+product: '{% data reusables.gated-features.auto-merge %}'
+versions:
+  free-pro-team: '*'
+permissions: People with maintainer permissions can manage auto-merge for pull requests in a repository.
+---
+
+{% data reusables.pull_requests.auto-merge-release-phase %}
+
+If you allow auto-merge for pull requests in your repository, people can configure individual pull requests in the repository to merge automatically when all merge requirements are met. For more information, see "[Automatically merging a pull request](/github/collaborating-with-issues-and-pull-requests/automatically-merging-a-pull-request)."
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.repositories.sidebar-settings %}
+1. Under "Merge button", select or deselect **Allow auto-merge**.
+  ![Checkbox to allow or disallow auto-merge](/assets/images/help/pull_requests/allow-auto-merge-checkbox.png)
diff --git a/content/github/collaborating-with-issues-and-pull-requests/automatically-merging-a-pull-request.md b/content/github/collaborating-with-issues-and-pull-requests/automatically-merging-a-pull-request.md
@@ -0,0 +1,43 @@
+---
+title: Automatically merging a pull request
+intro: 'You can increase development velocity by enabling auto-merge for a pull request so that the pull request will merge automatically when all merge requirements are met.'
+product: '{% data reusables.gated-features.auto-merge %}'
+versions:
+  free-pro-team: '*'
+---
+
+{% data reusables.pull_requests.auto-merge-release-phase %}
+
+### About auto-merge
+
+If you enable auto-merge for a pull request, the pull request will merge automatically when all required reviews are met and status checks have passed. Auto-merge prevents you from waiting around for requirements to be met, so you can move on to other tasks.
+
+Before you can use auto-merge with a pull request, auto-merge must be enabled for the repository. For more information, see "[Managing auto-merge for pull requests in your repository](/github/administering-a-repository/managing-auto-merge-for-pull-requests-in-your-repository)."
+
+You can provide feedback about auto-merge by [contacting us](https://support.github.com/contact/feedback?category=prs-and-code-review&subject=Pull%20request%20auto-merge%20feedback).
+
+### Enabling auto-merge
+
+People with write permissions to a repository can enable auto-merge for a pull request.
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.repositories.sidebar-pr %}
+1. In the "Pull Requests" list, click the pull request you'd like to auto-merge.
+1. Optionally, to choose a merge method, select the **Enable auto-merge** drop-down menu, then click a merge method. For more information, see "[About pull request merges](/github/collaborating-with-issues-and-pull-requests/about-pull-request-merges)."
+  !["Enable auto-merge" drop-down menu](/assets/images/help/pull_requests/enable-auto-merge-drop-down.png)
+1. Click **Enable auto-merge**.
+  ![Button to enable auto-merge](/assets/images/help/pull_requests/enable-auto-merge-button.png)
+1. If you chose the merge or squash and merge methods, type a commit message and description and choose the email address you want to author the merge commit.
+  ![Fields to enter commit message and description and choose commit author email](/assets/images/help/pull_requests/pull-request-information-fields.png)
+1. Click **Confirm auto-merge**.
+  ![Button to confirm auto-merge](/assets/images/help/pull_requests/confirm-auto-merge-button.png)
+
+### Disabling auto-merge
+
+People with write permissions to a repository and pull request authors can disable auto-merge for a pull request.
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.repositories.sidebar-pr %}
+1. In the "Pull Requests" list, click the pull request you'd like to disable auto-merge for.
+1. In the merge box, click **Disable auto-merge**.
+  ![Button to disable auto-merge](/assets/images/help/pull_requests/disable-auto-merge-button.png)
diff --git a/content/github/collaborating-with-issues-and-pull-requests/index.md b/content/github/collaborating-with-issues-and-pull-requests/index.md
@@ -60,5 +60,6 @@ versions:
 {% topic_link_in_list /incorporating-changes-from-a-pull-request %}
     {% link_in_list /about-pull-request-merges %}
     {% link_in_list /merging-a-pull-request %}
+    {% link_in_list /automatically-merging-a-pull-request %}
     {% link_in_list /closing-a-pull-request %}
     {% link_in_list /reverting-a-pull-request %}
diff --git a/content/github/collaborating-with-issues-and-pull-requests/merging-a-pull-request.md b/content/github/collaborating-with-issues-and-pull-requests/merging-a-pull-request.md
@@ -14,6 +14,8 @@ versions:
 
 In a pull request, you propose that changes you've made on a head branch should be merged into a base branch. {% data reusables.pull_requests.about-protected-branches %} However, there may be restrictions on when you can merge a pull request into a specific branch. For example, you may only be able to merge a pull request into the default branch if required status checks are passing. For more information, see "[About protected branches](/github/administering-a-repository/about-protected-branches)."
 
+{% data reusables.pull_requests.you-can-auto-merge %}
+
 If the pull request has merge conflicts, or if you'd like to test the changes before merging, you can [check out the pull request locally](/articles/checking-out-pull-requests-locally) and merge it using the command line.
 
 You can't merge a draft pull request. For more information about draft pull requests, see "[About pull requests](/articles/about-pull-requests#draft-pull-requests)."
diff --git a/content/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization.md b/content/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization.md
@@ -60,7 +60,8 @@ In addition to managing organization-level settings, organization owners have ad
 | [Report abusive or spammy content](/articles/reporting-abuse-or-spam) | **X** | **X** | **X** | **X** | **X** |{% endif %}
 | Apply labels | | **X** | **X** | **X** | **X** |
 | Create, edit, delete labels | | | **X** | **X** | **X** |
-| Close, reopen, and assign all issues and pull requests | | **X** | **X** | **X** | **X** |
+| Close, reopen, and assign all issues and pull requests | | **X** | **X** | **X** | **X** |{% if currentVersion == "free-pro-team@latest" %}
+| [Enable and disable auto-merge on a pull request](/github/administering-a-repository/managing-auto-merge-for-pull-requests-in-your-repository) | | | **X** | **X** | **X** |{% endif %}
 | Apply milestones |  | **X** | **X** | **X** | **X** |
 | Mark [duplicate issues and pull requests](/articles/about-duplicate-issues-and-pull-requests)| | **X** | **X** | **X** | **X** |
 | Request [pull request reviews](/articles/requesting-a-pull-request-review) | | **X** | **X** | **X** | **X** |
diff --git a/content/github/setting-up-and-managing-your-github-user-account/permission-levels-for-a-user-account-repository.md b/content/github/setting-up-and-managing-your-github-user-account/permission-levels-for-a-user-account-repository.md
@@ -44,7 +44,8 @@ The repository owner has full control of the repository. In addition to the acti
 | Define code owners for the repository | "[About code owners](/github/creating-cloning-and-archiving-repositories/about-code-owners)" |
 | Archive the repository | "[About archiving repositories](/github/creating-cloning-and-archiving-repositories/about-archiving-repositories)" |{% if currentVersion == "free-pro-team@latest" %}
 | Create security advisories | "[About {% data variables.product.prodname_security_advisories %}](/github/managing-security-vulnerabilities/about-github-security-advisories)" |
-| Display a sponsor button | "[Displaying a sponsor button in your repository](/github/administering-a-repository/displaying-a-sponsor-button-in-your-repository)" |{% endif %}
+| Display a sponsor button | "[Displaying a sponsor button in your repository](/github/administering-a-repository/displaying-a-sponsor-button-in-your-repository)" |
+| Allow or disallow auto-merge for pull requests | "[Managing auto-merge for pull requests in your repository](/github/administering-a-repository/managing-auto-merge-for-pull-requests-in-your-repository)" | {% endif %}
 
 ### Collaborator access for a repository owned by a user account
 
@@ -66,7 +67,8 @@ Collaborators can also perform the following actions.
 | Manage labels for issues and pull requests in the repository | "[Labeling issues and pull requests](/github/managing-your-work-on-github/labeling-issues-and-pull-requests)" |
 | Manage milestones for issues and pull requests in the repository | "[Creating and editing milestones for issues and pull requests](/github/managing-your-work-on-github/creating-and-editing-milestones-for-issues-and-pull-requests)" |
 | Mark an issue or pull request in the repository as a duplicate | "[About duplicate issues and pull requests](/github/managing-your-work-on-github/about-duplicate-issues-and-pull-requests)" |
-| Create, merge, and close pull requests in the repository | "[Proposing changes to your work with pull requests](/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests)" |
+| Create, merge, and close pull requests in the repository | "[Proposing changes to your work with pull requests](/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests)" |{% if currentVersion == "free-pro-team@latest" %}
+| Enable and disable auto-merge for a pull request | "[Automatically merging a pull request](/github/collaborating-with-issues-and-pull-requests/automatically-merging-a-pull-request)"{% endif %}
 | Apply suggested changes to pull requests in the repository |"[Incorporating feedback in your pull request](/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request)" |
 | Create a pull request from a fork of the repository | "[Creating a pull request from a fork](/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork)" |
 | Submit a review on a pull request that affects the mergeability of the pull request | "[Reviewing proposed changes in a pull request](/github/collaborating-with-issues-and-pull-requests/reviewing-proposed-changes-in-a-pull-request)" |
diff --git a/data/reusables/gated-features/auto-merge.md b/data/reusables/gated-features/auto-merge.md
@@ -0,0 +1 @@
+Auto-merge for pull requests is available in public repositories with {% data variables.product.prodname_free_user %} and {% data variables.product.prodname_free_team %} for organizations, and in public and private repositories with {% data variables.product.prodname_pro %}, {% data variables.product.prodname_team %}, and {% data variables.product.prodname_ghe_cloud %}. {% if currentVersion == "free-pro-team@latest" %}{% data reusables.gated-features.more-info %}{% endif %}
diff --git a/data/reusables/pull_requests/auto-merge-release-phase.md b/data/reusables/pull_requests/auto-merge-release-phase.md
@@ -0,0 +1,5 @@
+{% note %}
+
+**Note:** Auto-merge for pull requests is currently in beta and subject to change.
+
+{% endnote %}
diff --git a/data/reusables/pull_requests/you-can-auto-merge.md b/data/reusables/pull_requests/you-can-auto-merge.md
@@ -0,0 +1,3 @@
+{% if currentVersion == "free-pro-team@latest" %}
+You can configure a pull request to merge automatically when all merge requirements are met. For more information, see "[Automatically merging a pull request](/github/collaborating-with-issues-and-pull-requests/automatically-merging-a-pull-request)."
+{% endif %}
