feature: adds merge queues docs CF-2398#2635
Conversation
|
Overall readability score: 54.12 (🟢 +0)
View detailed metrics🟢 - Shows an increase in readability
Averages:
View metric targets
|
There was a problem hiding this comment.
Pull request overview
Adds documentation for GitHub Merge Queues support, describing the required GitHub App permissions and how Codacy behaves when merge-queue checks are requested.
Changes:
- Add a new “Merge Queues” section to the GitHub integration docs.
- Document an additional GitHub App permission related to merge queues in the permissions reference table.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/repositories-configure/integrations/github-integration.md | Documents Merge Queues behavior and required GitHub App permission for the integration. |
| docs/getting-started/which-permissions-does-codacy-need-from-my-account.md | Adds “Merge Queues” to the list of required GitHub App permissions. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| <tr> | ||
| <td>Merge Queues</td> | ||
| <td>Read-Only</td> | ||
| <td>Codacy listens for `checks_requested` webhook events and responds accordingly.</td> | ||
| </tr> |
There was a problem hiding this comment.
The new “Merge Queues” permission is added under the Organization permissions section, but merge queues are a repository-level feature/permission in GitHub Apps. Also, checks_requested is typically an action within the merge queue webhook (not a standalone webhook event). Consider moving this row under repository permissions and clarifying the webhook name/action to avoid misleading customers.
|
|
||
|  | ||
|
|
||
| ## Merge Queues {: id="merge-queues"} |
There was a problem hiding this comment.
The new “Merge Queues” section is using an H2 (##) heading, but the other feature descriptions under “Configuring the GitHub integration” are H3 (###). This breaks the document hierarchy/TOC; consider making this a “### Merge queues” subsection (keeping the same anchor id if needed).
| ## Merge Queues {: id="merge-queues"} | |
| ### Merge queues {: id="merge-queues"} |
|
|
||
| ## Merge Queues {: id="merge-queues"} | ||
|
|
||
| To support this feature, our GitHub App requires **Merge Groups** permissions in order to listen to the `checks_requested` event. |
There was a problem hiding this comment.
This text says the GitHub App requires Merge Groups permissions, but elsewhere in the docs (permissions table) the permission is labeled “Merge Queues”. Please align the permission name/terminology so readers can find the correct GitHub App permission to grant.
| To support this feature, our GitHub App requires **Merge Groups** permissions in order to listen to the `checks_requested` event. | |
| To support this feature, our GitHub App requires the **Merge Queues** permission in order to listen to the `checks_requested` event. |
Up to standards ✅🟢 Issues
|
![codacy-production[bot]](https://avatars.githubusercontent.com/in/56611?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull Request Overview
While the PR successfully addresses the requirement to document GitHub Merge Queues support, there are two significant documentation errors that should be corrected before merging. First, the 'Merge groups' permission is incorrectly categorized as an 'Organization' permission when it is actually a 'Repository' permission; this will misdirect users during setup. Second, there is a naming inconsistency between 'Merge Queues' (used in the table) and 'Merge groups' (the official GitHub UI term). Codacy analysis shows the PR is otherwise up to standards.
About this PR
- There is a systemic terminology inconsistency: the permissions table uses 'Merge Queues', while the integration page and GitHub's UI use 'Merge Groups'. Additionally, the permission scope (Organization vs. Repository) is currently incorrect in the documentation.
Test suggestions
- Update the permissions table to include Merge Queues/Groups.
- Add a descriptive section to the GitHub Integration page about Merge Queues logic.
🗒️ Improve review quality by adding custom instructions
| <tr> | ||
| <td>Merge Queues</td> | ||
| <td>Read-Only</td> | ||
| <td>Codacy listens for `checks_requested` webhook events and responds accordingly.</td> | ||
| </tr> |
There was a problem hiding this comment.
🔴 HIGH RISK
This permission is a repository-level permission, but it is currently listed under the Organization permissions section (which begins at line 71). It should be moved to the repository permissions section (e.g., after 'Contents' at line 68) and renamed to Merge groups for consistency with the GitHub UI.
Try running the following prompt in your coding agent:
Move the new 'Merge Queues' table row to the repository permissions section (above 'Organization permissions'), rename the permission to 'Merge groups', and update the description to: 'Codacy listens for the
merge_groupevent and automatically reports a successful status check to the relevant commit.'
|
|
||
| ## Merge Queues {: id="merge-queues"} | ||
|
|
||
| To support this feature, our GitHub App requires **Merge Groups** permissions in order to listen to the `checks_requested` event. |
There was a problem hiding this comment.
🟡 MEDIUM RISK
Suggestion: The official GitHub permission name is Merge groups and the specific webhook event is merge_group (which contains the checks_requested action).
| To support this feature, our GitHub App requires **Merge Groups** permissions in order to listen to the `checks_requested` event. | |
| To support this feature, our GitHub App requires the **Merge groups** permission in order to listen to the `merge_group` event. |
pedrobpereira
force-pushed
the
feature/merge-queues-CF-2398
branch
from
b6113ba to
4db370f
Compare
pedrobpereira
force-pushed
the
feature/merge-queues-CF-2398
branch
from
4db370f to
28cd670
Compare
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| <td>Codacy retrieves repository contents to get installation access tokens when integrating with your repositories and clone them, and for code coverage analysis.<br/><strong>Codacy requests this permission since September 2023.</strong> Make sure an organization owner <a href="https://docs.github.com/en/apps/using-github-apps/reviewing-and-modifying-installed-github-apps">approves Codacy GitHub App updated permissions</a> on your GitHub organization.</td> | ||
| </tr> | ||
| <tr> | ||
| <td>Merge Groups</td> |
There was a problem hiding this comment.
For consistency with the other GitHub permission scope names in this table (for example, "Pull requests" and "Commit statuses" use sentence case), consider changing "Merge Groups" to "Merge groups".
| <td>Merge Groups</td> | |
| <td>Merge groups</td> |
| <tr> | ||
| <td>Merge Groups</td> | ||
| <td>Read-Only</td> | ||
| <td>Codacy listens for webhook events and responds to the `checks_requested` action accordingly.</td> |
There was a problem hiding this comment.
The description references the checks_requested action but doesn’t mention which webhook event it belongs to. Consider specifying the relevant GitHub event name (for example, the merge group event) so readers know where this action comes from and why this permission is needed.
| <td>Codacy listens for webhook events and responds to the `checks_requested` action accordingly.</td> | |
| <td>Codacy listens for the `merge_group` webhook event and responds to the `checks_requested` action accordingly.</td> |
| ## Merge Groups {: id="merge-groups"} | ||
|
|
||
| To support this feature, our GitHub App requires **Merge Groups** permissions to listen for and respond to the `checks_requested` action. | ||
|
|
||
| When this event is triggered, Codacy automatically sends a green status check to the relevant commit. The reasoning behind this is straightforward: by the time a PR enters the merge queue, it has already gone through Codacy's analysis — either receiving a green status or being manually bypassed. Since the PR was already unblocked before joining the queue, always responding with green is a safe and practical approach that keeps things moving without unnecessary friction. |
There was a problem hiding this comment.
This section uses both "Merge Groups" and "merge queue" terminology without defining the relationship between them, which can be confusing for readers (especially since the behavior described is about merge queue processing). Consider explicitly naming the GitHub feature (merge queues) and, if needed, clarifying that it relies on merge group events/permissions so the terminology is consistent.
| ## Merge Groups {: id="merge-groups"} | |
| To support this feature, our GitHub App requires **Merge Groups** permissions to listen for and respond to the `checks_requested` action. | |
| When this event is triggered, Codacy automatically sends a green status check to the relevant commit. The reasoning behind this is straightforward: by the time a PR enters the merge queue, it has already gone through Codacy's analysis — either receiving a green status or being manually bypassed. Since the PR was already unblocked before joining the queue, always responding with green is a safe and practical approach that keeps things moving without unnecessary friction. | |
| ## GitHub merge queues {: id="merge-groups"} | |
| To support GitHub **merge queues**, our GitHub App requires **Merge Groups** permissions so it can listen for and respond to the `checks_requested` action for merge group events. | |
| When a merge group event is triggered for a pull request in the merge queue, Codacy automatically sends a green status check to the relevant commit. By the time a pull request enters the merge queue, it has already gone through Codacy's analysis — either receiving a green status or being manually bypassed. Since the pull request was already unblocked before joining the queue, always responding with green is a safe and practical approach that keeps things moving without unnecessary friction. |
There was a problem hiding this comment.
Pull Request Overview
This PR successfully addresses the requirement to document GitHub Merge Queues and the necessary 'Merge groups' permissions. Codacy analysis indicates the changes are up to standards with no quality issues detected. The primary focus for final polish should be ensuring the 'Merge groups' permission is correctly categorized as a repository-level permission (as noted in previous comments) and maintaining consistent sentence-case formatting across all headings and tables.
Test suggestions
- Verify 'Merge Groups' permission is correctly listed as Read-Only in the permissions table.
- Verify the documentation explicitly mentions the 'checks_requested' webhook action.
- Verify the explanation for the automatic green status check is included in the GitHub integration guide.
🗒️ Improve review quality by adding custom instructions
|
|
||
|  | ||
|
|
||
| ## Merge Groups {: id="merge-groups"} |
There was a problem hiding this comment.
⚪ LOW RISK
Nitpick: Use sentence case for the heading to match the permission name and other documentation headings.
| ## Merge Groups {: id="merge-groups"} | |
| ## Merge groups {: id="merge-groups"} |
pedrobpereira
force-pushed
the
feature/merge-queues-CF-2398
branch
from
28cd670 to
ab016e7
Compare
There was a problem hiding this comment.
Pull Request Overview
This PR adds documentation for GitHub Merge Queues but contains major inaccuracies previously flagged that remain unaddressed. Specifically, the 'Merge groups' permission is incorrectly categorized under 'Organization permissions' instead of 'Repository permissions', and terminology is inconsistent ('Merge Queues' vs 'Merge Groups'). Additionally, the documentation fails to clearly explain the rationale for Codacy's 'always green' status checks for merge groups, using vague language that does not meet acceptance criteria. Codacy analysis is currently up to standards, but these documentation errors should prevent merging.
About this PR
- The PR description is empty and the submission checklist has not been completed. Please provide the required context and confirm that a self-review has been performed.
Test suggestions
- Verify the 'Merge groups' permission entry is correctly placed in the Repository Permissions section of the permissions documentation.
- Verify the clarity and accuracy of the explanation regarding 'always green' status checks for merge queues in the GitHub integration guide.
Prompt proposal for missing tests
Consider implementing these tests if applicable:
1. Verify the 'Merge groups' permission entry is correctly placed in the Repository Permissions section of the permissions documentation.
2. Verify the clarity and accuracy of the explanation regarding 'always green' status checks for merge queues in the GitHub integration guide.
🗒️ Improve review quality by adding custom instructions
👀 Live preview
live preview
🚧 To do