Notification behavior and mentions

Control how P4 Code Review sends Slack notifications and determines which users are notified.

This page explains:

  • When Slack notifications are sent.

  • How notifications are delivered.

  • How @mentions are resolved.

  • How direct message (DM) notifications work.

  • How the notify and notify_mentioned_only settings affect notification behaviour.

Overview

When review activity occurs,P4 Code Review generates a Slack notification based on the configured workspace settings.

Notifications can be delivered as:

  • Channel notifications.

  • Direct messages (DMs).

Notification behaviour is controlled by the Slack configuration for each workspace.

Notification triggers

Slack notifications are sent when the following events occur:

Event Description
Review created A new review is created.
Change committed A change is committed to a review.
Comment A comment is added, edited, or replied to.
State change A review is approved, rejected, updated, or moved to another review state.

These events determine when notifications are sent.

The configured notification settings determine how notifications are delivered and who receives them.

Notification types

Slack notifications are delivered in two ways:

Channel notifications (default)

By default, P4 Code Review posts notifications to the Slack channels configured for the workspace.

Channel notifications are typically used to:

  • Share review activity with a team.

  • Notify project channels.

  • Provide visibility into ongoing reviews.

Direct messages (DMs)

P4 Code Review can also send notifications directly to individual Slack users.

Direct messages are used when:

  • notify_mentioned_only is enabled.

  • One or more valid @mentions are present in the review content.

The notification is sent directly to the mentioned users instead of being posted to a channel.

@mentions in notifications

Slack notifications can include @mentions in two ways:

  1. Configured mentions (notify)

  2. Content-based mentions (typed directly in review content)

These mechanisms operate independently and serve different purposes.

Configured mentions (notify)

Use notify to add @mentions to the initial review notification only.

For example:

'notify' => [
    'author',
    'branch_default_reviewers'
],

Supported values

  • author - Review author.

  • branch_default_reviewers - Branch default reviewers, including groups.

  • branch_moderators - Branch moderators, including groups.

Behaviour

Configured mentions:

  • Applies only when the review is created.

  • Does not apply to:

    • Comments

    • Replies

    • Votes

    • State changes

  • Expands groups automatically, including nested groups.

  • Resolves users using email matching.

  • Ensure each Slack user is mentioned only once.

If a user cannot be resolved to a Slack account, the notification is still sent and the unresolved mention is skipped.

Content-based mentions

Users can add @mentions directly in review content.

Content-based mentions are supported in:

  • Review descriptions

  • Comments

  • Replies

  • State transition comments

Example:

Fixed authentication issue. @userA please review this change.

When notification processing occurs, P4 Code Review:

  • Parses @mentions from the content.

  • Attempts to resolve the users.

  • Applies notification behaviour based on the workspace configuration.

Content-based mentions can trigger direct message delivery when notify_mentioned_only is enabled.

Notify only mentioned users (notify_mentioned_only)

Use notify_mentioned_only to send notifications based on @mentions in content.

For example:

'notify_mentioned_only' => true,

Behaviour

When enabled:

If @mentions are present:

P4 Code Review:

  • Sends direct messages (DMs) to mentioned users.

  • Does not post a channel notification.

If no @mentions are present:

P4 Code Review sends a standard channel notification.

Applies to all events

This behaviour applies to:

  • Review creation.

  • Change commits.

  • Comments.

  • Replies.

  • Review state changes.

Important details

  • Only explicitly mentioned users receive DMs.

  • Duplicate mentions are ignored.

  • Users that cannot be resolved to Slack accounts are skipped.

  • If no @mentions are present, a channel notification is sent.

  • If @mentions are present but none can be resolved, P4 Code Review falls back to a channel notification.

Important: notify vs notify_mentioned_only

Although both settings involve @mentions, they perform different functions.

Key differences

notify

  • Adds @mentions to the initial review notification.

  • Applies only when a review is created.

  • Does not affect notification delivery.

  • Adds mentions to channel messages.

  • notify_mentioned_only

notify_mentioned_only

  • Changes how notifications are delivered.

  • Uses @mentions found in review content.

  • Applies to all notification events.

  • Sends notifications as direct messages when appropriate.

These settings can be used together or independently.

Event-based behaviour

Review created

When notify_mentioned_only is enabled:

  • If the review description contains @mentions, P4 Code Review sends direct messages (DMs) to the mentioned users only and does not post a channel notification.

  • If the review description does not contain any @mentions, P4 Code Review sends a channel notification.

When notify_mentioned_only is disabled:

  • P4 Code Review sends a channel notification.

  • If notify is configured, P4 Code Review @mentions the specified users (for example, the author or branch reviewers) in the initial review notification.

Comments and replies

When notify_mentioned_only is enabled:

  • If the comment contains @mentions, P4 Code Review sends direct messages (DMs) to the mentioned users only and does not post a channel notification.

  • If the comment does not contain any @mentions, P4 Code Review sends a channel notification.

When notify_mentioned_only is disabled:

  • P4 Code Review sends a channel notification.

  • P4 Code Review does not add notify @mentions to comments or replies.

State changes (approve, reject, needs revision)

When notify_mentioned_only is enabled:

  • If the state transition comment contains @mentions, P4 Code Review sends direct messages (DMs) to the mentioned users only.

  • If there are no @mentions in the transition comment, P4 Code Review sends a channel notification.

When notify_mentioned_only is disabled:

  • P4 Code Review sends a channel notification.

  • P4 Code Review does not add notify @mentions to state change notifications.

Worked examples

Example 1: Channel notification with configured mentions

Configuration:

'notify' => ['author'],
'notify_mentioned_only' => false,

Event: A review is created with no @mentions in the description.

Result:

  • P4 Code Review posts a notification to the configured channel.

  • The review author is @mentioned in the message.

Example 2: Direct message triggered by @mention

Configuration:

'notify_mentioned_only' => true,

Event: The review description includes:

@userA please review this change

Result:

  • P4 Code Review sends a direct message (DM) to userA.

  • P4 Code Review does not post a channel notification.

Example 3: Fallback to channel notification

Configuration:

'notify_mentioned_only' => true,

Event: A comment is added with no @mentions.

Result:

  • P4 Code Review posts a notification to the configured channel.

Example 4: Duplicate @mentions

Event: A comment includes:

@userA please review @userA again

Result:

  • P4 Code Review sends one direct message (DM) to userA.

  • Duplicate @mentions are ignored.

Example 5: Unresolved users

Event: A comment includes:

@userA @userB

Where:

  • userA is matched to a Slack user

  • userB cannot be matched to a Slack user

Result:

  • P4 Code Review sends a direct message (DM) to userA.

  • userB is skipped.

  • The notification is still delivered successfully.

Example 6: Mixed behaviour across workspaces

Configuration:

Workspace A

'notify_mentioned_only' => false,

Workspace B

'notify_mentioned_only' => true,

Event: A review description includes:

@userA please review

Result:

  • Workspace A posts a channel notification.

  • Workspace B sends a direct message (DM) to userA.