diff --git a/rules/slack/_category.yml b/rules/slack/_category.yml new file mode 100644 index 0000000..7e94e9d --- /dev/null +++ b/rules/slack/_category.yml @@ -0,0 +1,4 @@ +name: "Slack Notifications" +slug: "slack" +description: "Automated Slack DM and channel notifications for PR/MR lifecycle events" +icon: "slack" diff --git a/rules/slack/pr-review-request.md b/rules/slack/pr-review-request.md new file mode 100644 index 0000000..b79a0d0 --- /dev/null +++ b/rules/slack/pr-review-request.md @@ -0,0 +1,119 @@ +--- +title: "Review Request Slack Notification" +description: "Send Slack DM to reviewers when they are assigned to a PR/MR" +slug: "pr_review_request_slack" +when: "PR/MR is opened with reviewers assigned, or reviewers are added to an existing PR/MR" +actions: "Send direct message via Slack to each assigned reviewer with PR/MR details" +integrations: "slack" +--- + +# Review Request Slack Notification + +Automatically notify reviewers via Slack direct message when they are assigned to review a pull request or merge request. + +## When to Use This + +Apply when: + +- PR/MR is opened with one or more reviewers already assigned +- New reviewer(s) added to an existing PR/MR (metadata update) +- Reviewer is a human user with a matching Slack account + +Do NOT apply for: + +- Draft pull requests or work-in-progress merge requests +- Reviewers who are bots or automated accounts +- PR/MR author assigning themselves as reviewer +- Reviewers who have already been notified for this PR/MR + +## How It Works + +1. **Detect review request event**: + - **On PR/MR open**: Check if reviewers are assigned in the initial request + - **On metadata update**: Detect newly added reviewers (compare before/after reviewer lists) + +2. **Filter reviewers to notify**: + - Exclude the PR/MR author (self-review) + - Exclude bot accounts + - Exclude reviewers already notified for this PR/MR (track via comments or metadata) + - Only include newly assigned reviewers on updates + +3. **Match reviewers to Slack users**: + - Get reviewer email from platform API + - Query Slack `users.lookupByEmail` endpoint + - If no match found, skip notification for that reviewer (fail gracefully) + +4. **Send Slack direct message to each reviewer**: + + **Message format**: + + ```md + 👀 Review requested on a pull request + + **[PR Title #123](https://github.com/owner/repo/pull/123)** + + Requested by @author-name + + > First 1-2 lines of PR description or commit message summary... + ``` + + **Include contextual details**: + - PR/MR title with link + - Author who requested the review + - Brief description snippet (first ~100 chars, if available) + - File count or change size indicator (e.g., "+150 / -30 lines") + +5. **Track notification sent**: + - Record that reviewer was notified to prevent duplicate DMs on subsequent updates + - Can use PR/MR comment metadata or external tracking + +6. **Handle errors gracefully**: + - Slack user not found: Log and skip (don't block workflow) + - Slack API errors: Log warning, do not fail the rule + - Rate limits: Queue for retry + +## Examples + +### Example 1: PR Opened with Reviewers + +``` +Event: PR #456 opened +Title: "Add user authentication flow" +Author: @alice +Reviewers: @bob, @carol + +Action: +- DM @bob: "👀 Review requested... [Add user authentication flow #456]..." +- DM @carol: "👀 Review requested... [Add user authentication flow #456]..." +``` + +### Example 2: Reviewer Added to Existing PR + +``` +Event: PR #456 updated (metadata change) +Before reviewers: [@bob] +After reviewers: [@bob, @dave] + +Action: +- DM @dave: "👀 Review requested..." +- Skip @bob (already notified) +``` + +### Example 3: Self-Review Filtered Out + +``` +Event: PR #789 opened +Author: @eve +Reviewers: @eve, @frank + +Action: +- Skip @eve (author cannot review own PR) +- DM @frank: "👀 Review requested..." +``` + +## Why This Matters + +- **Faster Review Turnaround**: Reviewers are notified immediately in Slack where they're already working, rather than relying on email or platform notifications +- **Reduced Review Latency**: Eliminates the "I didn't see the review request" problem that delays merges +- **Better Context Delivery**: DM includes enough context for reviewer to prioritize without opening the link first +- **Respects Attention**: Direct message ensures visibility without noisy channel posts diff --git a/rules/slack/ready-to-merge-notification.md b/rules/slack/ready-to-merge-notification.md new file mode 100644 index 0000000..f28d0db --- /dev/null +++ b/rules/slack/ready-to-merge-notification.md @@ -0,0 +1,137 @@ +--- +title: "Ready to Merge Slack Notification" +description: "Send Slack DM to PR/MR authors when all checks pass and their contribution is ready to merge" +slug: "ready_to_merge_slack" +when: "PR/MR becomes ready to merge (all checks pass, approvals met, no conflicts)" +actions: "Send direct message via Slack to PR/MR author with merge-ready status" +integrations: "slack" +--- + +# Ready to Merge Slack Notification + +Automatically notify pull request and merge request authors via Slack direct message when their contribution passes all required checks and is ready to merge. + +## When to Use This + +Apply when: + +- PR/MR status indicates ready to merge (all checks passed, approvals obtained, no conflicts) +- PR/MR is not in draft or work-in-progress state +- PR/MR author is a human user, not a bot + +Do NOT apply for: + +- Draft pull requests or work-in-progress merge requests +- PR/MRs created by bots (Dependabot, Renovate, automated CI accounts, etc.) +- Checks still pending or failing +- Merge conflicts present +- Required approvals not yet obtained + +## How It Works + +1. **Check platform-native merge readiness**: + - **GitHub**: Verify `mergeable_state == "clean"` via PR API + - Confirms all required checks passed, approvals obtained, branch up-to-date, no conflicts + - Automatically respects repository branch protection rules + - **GitLab**: Verify `merge_status == "can_be_merged"` via MR API + - Confirms pipeline passed, approvals met, no conflicts + - Automatically respects project merge request settings + + Using the platform's native merge status is more reliable than manually checking individual CI jobs and approval counts. + +2. **Verify exclusion conditions**: + - **Check if draft**: + - GitHub: `draft == true` + - GitLab: `draft == true` OR `work_in_progress == true` + - **Check if bot-created**: + - GitHub: `author.type == "Bot"` OR username matches `*[bot]` pattern + - GitLab: `author.bot == true` OR username matches bot patterns + - Common bot patterns: `dependabot`, `renovate`, `github-actions`, `gitlab-bot`, `snyk-bot` + + If any exclusion condition matches, skip this rule. + +3. **Check if author was already notified**: + - Track notifications sent per PR/MR to prevent duplicate messages + - Only notify once when transitioning to merge-ready state + +4. **Match PR/MR author to Slack user**: + - Get author email from platform API + - Query Slack `users.lookupByEmail` endpoint + - If no match found, skip notification (fail gracefully) + +5. **Send Slack direct message to author**: + + **Message format**: + + ```md + :white_check_mark: Your pull request is ready to merge! + + **[PR Title #123](https://github.com/owner/repo/pull/123)** + + :white_check_mark: All checks passed + :white_check_mark: Approved by 2 reviewers + ``` + + **Dynamic status details**: + - Show approval count if approvals were required + - Show check summary (e.g., "12 checks passed") + - Omit sections that aren't applicable + +6. **Handle errors gracefully**: + - Slack API unavailable: Log error, do not block PR/MR workflow + - Rate limits hit: Queue notification for retry + - User not found: Log and skip silently + +## Examples + +### Example 1: Standard Merge Ready + +``` +PR #456: "Add user authentication" +Author: @alice +Status: All 8 checks passed, 2 approvals, no conflicts + +Action: +- DM @alice: + ":white_check_mark: Your pull request is ready to merge! + [Add user authentication #456](link) + :white_check_mark: All checks passed + :white_check_mark: Approved by 2 reviewers" +``` + +### Example 2: Bot PR Skipped + +``` +PR #789: "Bump lodash from 4.17.20 to 4.17.21" +Author: dependabot[bot] +Status: Ready to merge + +Action: None (bot-authored) +``` + +### Example 3: Draft PR Skipped + +``` +PR #101: "WIP: Refactor database layer" +Author: @bob +Status: Draft, all checks passing + +Action: None (draft PR) +``` + +### Example 4: Still Has Failing Checks + +``` +PR #202: "Update payment flow" +Author: @carol +Status: 7/8 checks passed, 1 failing + +Action: None (not merge-ready) +``` + +## Why This Matters + +- **Faster Merge Cycles**: Authors are immediately notified when their work is ready, eliminating manual status checking +- **Reduced Context Switching**: Notification comes directly to Slack where developers work, rather than requiring platform tab monitoring +- **Improved Team Velocity**: Reduces the time between "ready to merge" and actual merge, keeping development momentum high +- **Better Developer Experience**: Clear, proactive communication reduces uncertainty about PR/MR status diff --git a/rules/slack/review-submitted-notification.md b/rules/slack/review-submitted-notification.md new file mode 100644 index 0000000..2d401f3 --- /dev/null +++ b/rules/slack/review-submitted-notification.md @@ -0,0 +1,176 @@ +--- +title: "Review Submitted Slack Notification" +description: "Send Slack DM to PR/MR authors when a reviewer submits their review" +slug: "review_submitted_slack" +when: "A reviewer submits a review (approved, changes requested, or commented)" +actions: "Send direct message via Slack to PR/MR author with review outcome and link" +integrations: "slack" +--- + +# Review Submitted Slack Notification + +Automatically notify pull request and merge request authors via Slack direct message when a reviewer completes and submits their review. + +## When to Use This + +Apply when: + +- A reviewer submits a review with a verdict (approved, changes requested, or comment-only) +- PR/MR author is a human user with a matching Slack account +- Review contains substantive feedback (not just an empty approval click) + +Do NOT apply for: + +- Draft pull requests or work-in-progress merge requests +- Reviews submitted by bots or automated accounts +- Author reviewing their own PR/MR (self-reviews) +- Inline comments without a formal review submission +- Duplicate notifications for the same review + +## How It Works + +1. **Detect review submission event**: + - **GitHub**: `pull_request_review` event with `action: submitted` + - **GitLab**: MR approval event or note event with review verdict + +2. **Extract review details**: + - **Review verdict**: + - GitHub: `APPROVED`, `CHANGES_REQUESTED`, or `COMMENTED` + - GitLab: Approval, unapproval, or comment-based review + - **Reviewer identity**: Username and email + - **Review body**: Summary comment if provided + +3. **Verify exclusion conditions**: + - Skip if reviewer is a bot + - Skip if reviewer is the PR/MR author (self-review) + - Skip if PR/MR is in draft state + - Skip if this exact review was already notified + +4. **Match PR/MR author to Slack user**: + - Get author email from platform API + - Query Slack `users.lookupByEmail` endpoint + - If no match found, skip notification (fail gracefully) + +5. **Send Slack direct message to author**: + + **Message format by verdict**: + + **Approved**: + ```md + :white_check_mark: @reviewer-name approved your pull request + + **[PR Title #123](https://github.com/owner/repo/pull/123)** + + > "Looks great! Nice work on the error handling." + ``` + + **Changes Requested**: + ```md + :arrows_counterclockwise: @reviewer-name requested changes on your pull request + + **[PR Title #123](https://github.com/owner/repo/pull/123)** + + > "A few suggestions on the API design, see inline comments." + ``` + + **Commented** (no verdict): + ```md + :speech_balloon: @reviewer-name left feedback on your pull request + + **[PR Title #123](https://github.com/owner/repo/pull/123)** + + > "Had some questions about the caching strategy." + ``` + + **Include review snippet**: + - Show first ~150 characters of review body if present + - Truncate with "..." if longer + - Omit quote block if review has no body text + +6. **Handle errors gracefully**: + - Slack user not found: Log and skip silently + - Slack API errors: Log warning, do not fail the rule + - Empty review body: Send notification without quote block + +## Examples + +### Example 1: Approval with Comment + +``` +Event: Review submitted on PR #456 +Reviewer: @bob +Verdict: APPROVED +Body: "LGTM! The refactoring really cleaned this up." +Author: @alice + +Action: +- DM @alice: + ":white_check_mark: @bob approved your pull request + [Add user authentication #456](link) + > 'LGTM! The refactoring really cleaned this up.'" +``` + +### Example 2: Changes Requested + +``` +Event: Review submitted on PR #456 +Reviewer: @carol +Verdict: CHANGES_REQUESTED +Body: "Please add error handling for the edge case on line 45." +Author: @alice + +Action: +- DM @alice: + ":arrows_counterclockwise: @carol requested changes on your pull request + [Add user authentication #456](link) + > 'Please add error handling for the edge case on line 45.'" +``` + +### Example 3: Comment-Only Review + +``` +Event: Review submitted on PR #789 +Reviewer: @dave +Verdict: COMMENTED +Body: "Curious about the performance implications here - have we benchmarked this?" +Author: @eve + +Action: +- DM @eve: + ":speech_balloon: @dave left feedback on your pull request + [Optimize database queries #789](link) + > 'Curious about the performance implications here - have we benchmarked this?'" +``` + +### Example 4: Self-Review Skipped + +``` +Event: Review submitted on PR #101 +Reviewer: @alice +Author: @alice + +Action: None (self-review) +``` + +### Example 5: Approval Without Body + +``` +Event: Review submitted on PR #202 +Reviewer: @frank +Verdict: APPROVED +Body: (empty) +Author: @grace + +Action: +- DM @grace: + ":white_check_mark: @frank approved your pull request + [Fix login bug #202](link)" +``` + +## Why This Matters + +- **Immediate Feedback Loop**: Authors know the moment feedback arrives, allowing them to address it while context is fresh +- **Faster Iteration Cycles**: No more checking GitHub/GitLab repeatedly to see if reviews came in +- **Clear Action Items**: The verdict emoji immediately signals whether author can merge or needs to make changes +- **Context Preservation**: Seeing the review summary in Slack helps authors prioritize which PRs need attention +- **Reduced Notification Fatigue**: Targets only the author rather than broadcasting to channels diff --git a/rules/slack/stale-pr-reminder.md b/rules/slack/stale-pr-reminder.md new file mode 100644 index 0000000..5cab132 --- /dev/null +++ b/rules/slack/stale-pr-reminder.md @@ -0,0 +1,150 @@ +--- +title: "Stale PR Review Reminder" +description: "Send Slack DM to reviewers when a PR/MR has been waiting for review too long" +slug: "stale_pr_reminder_slack" +when: "PR/MR has been open for a configurable number of days without review activity" +actions: "Send direct message via Slack to assigned reviewers reminding them to review" +integrations: "slack" +--- + +# Stale PR Review Reminder + +Automatically remind reviewers via Slack direct message when a pull request or merge request has been waiting for their review beyond a reasonable timeframe. + +## When to Use This + +Apply when: + +- PR/MR has been open for N days without review activity (default: 3 days) +- PR/MR has assigned reviewers who haven't submitted a review +- OR review requested changes but author has pushed new commits and is awaiting re-review + +Do NOT apply for: + +- Draft pull requests or work-in-progress merge requests +- PR/MRs with `on-hold`, `blocked`, or `do-not-merge` labels +- PR/MRs where all reviewers have already submitted reviews +- Weekends/holidays (calculate business days if possible) +- Reviewers who are currently OOO (if detectable via Slack status) + +## How It Works + +1. **Identify stale PR/MRs**: + - Calculate time since PR/MR was opened or since review was re-requested + - Check if threshold exceeded (default: 3 days) + - Verify PR/MR is still open and not in draft state + +2. **Determine reviewers to remind**: + - Get list of assigned reviewers + - Filter to those who have NOT submitted a review + - OR those whose review is outdated (requested changes, but new commits pushed since) + - Exclude reviewers who received a reminder within the last 24 hours + +3. **Check for blocking conditions**: + - Skip if PR/MR has blocking labels (`on-hold`, `blocked`, `waiting-on-author`, etc.) + - Skip if PR/MR has merge conflicts (author needs to resolve first) + - Skip if CI is failing (may indicate PR isn't ready) + +4. **Match reviewers to Slack users**: + - Get reviewer email from platform API + - Query Slack `users.lookupByEmail` endpoint + - Optionally check Slack status for OOO indicators + +5. **Send Slack direct message to each pending reviewer**: + + **Message format**: + + ```md + :wave: Friendly reminder: a PR is waiting for your review + + **[PR Title #123](https://github.com/owner/repo/pull/123)** + + Opened by @author-name • Waiting for 4 days + + +250 / -80 lines across 12 files + ``` + + **Contextual variations**: + + - **First reminder (3 days)**: + ``` + :wave: Friendly reminder: a PR is waiting for your review + ``` + + - **Second reminder (5+ days)**: + ``` + :hourglass: This PR has been waiting for review for 6 days + ``` + + - **After re-request (author addressed feedback)**: + ``` + :arrows_counterclockwise: @author-name addressed your feedback and is waiting for re-review + ``` + +6. **Track reminder sent**: + - Record timestamp of reminder per reviewer per PR/MR + - Prevent spamming same reviewer within 24-48 hours + +7. **Handle errors gracefully**: + - Slack user not found: Skip silently + - Slack API errors: Log and continue with other reviewers + +## Examples + +### Example 1: Initial Stale Reminder + +``` +PR #456: "Add payment processing" +Opened: 4 days ago +Reviewers: @bob (no review), @carol (no review) +CI: Passing +Labels: None blocking + +Action: +- DM @bob: ":wave: Friendly reminder... waiting for 4 days" +- DM @carol: ":wave: Friendly reminder... waiting for 4 days" +``` + +### Example 2: Re-Review Requested + +``` +PR #456: "Add payment processing" +Timeline: +- Day 1: PR opened, @bob assigned +- Day 2: @bob requests changes +- Day 3: @alice (author) pushes fixes +- Day 5: Still waiting + +Action: +- DM @bob: ":arrows_counterclockwise: @alice addressed your feedback and is waiting for re-review" +``` + +### Example 3: Blocked PR Skipped + +``` +PR #789: "Refactor auth system" +Opened: 5 days ago +Labels: ["blocked", "waiting-on-design"] +Reviewers: @dave (no review) + +Action: None (blocked label present) +``` + +### Example 4: Partial Review Complete + +``` +PR #101: "Update API endpoints" +Opened: 4 days ago +Reviewers: @eve (approved), @frank (no review) + +Action: +- Skip @eve (already reviewed) +- DM @frank: ":wave: Friendly reminder..." +``` + +## Why This Matters + +- **Reduces Review Bottlenecks**: Gentle nudges keep PRs moving without requiring authors to manually ping reviewers +- **Maintains Team Velocity**: Long-open PRs lead to merge conflicts and context loss; timely reviews prevent this +- **Respectful Reminders**: DMs are less intrusive than public channel pings while still ensuring visibility +- **Accounts for Real Workflows**: Tracks re-review requests separately so authors aren't left waiting after addressing feedback