Mention Committers On Build Failure by AmmarOFA · Pull Request #418 · jenkinsci/office-365-connector-plugin

AmmarOFA · 2025-12-16T15:41:30Z

Summary

How it Works / Idea

The goal of this feature is to allow Jenkins Office 365 Connector notifications to mention the users responsible for a build (committers or developers) in Microsoft Teams messages.

Workflow:

Collect User Information
- Jenkins gathers commit authors from the SCM (Git, SVN, etc.) associated with the build.
- If the commit author corresponds to a Jenkins user, their email is retrieved from Jenkins (hudson.model.User).
Format Mentions
- User emails are wrapped in <at>user@example.com</at> tags using TeamsMentionUtils.
- If no email is available, the user's full name is used as a fallback.
Conditional Mentions
- Mentions are sent only on build failures (controlled via mentionOnFailure).
Send Notification
- The Office 365 Connector sends the message/card to Teams.
- Teams (or the Power Automate / Teams workflow connector) parses the <at> tags and converts them into proper mention entities.

Summary Flow:

The changes include:

New Configurable Options:
- mentionOnFailure – Whether mentions are sent on build failures (default: true).
CardBuilder Updates:
- Added a new constructor with mentionCommitters and mentionOnFailure parameters.
- Updated createCompletedCard to conditionally add mentions based on these parameters.
- Ensured backward compatibility with the existing constructor.
FactsBuilder Updates:
- addCommitters now accepts a boolean to control mentions.
- Maintains old behavior with parameterless overloads.
- Users are de-duplicated, sorted, and mentions applied safely.
Webhook and Jelly Config Updates:
- Added mentionOnFailure properties to Webhook.
- Jelly UI updated to allow configuration of this new option.
Utility and Tests:
- Added TeamsMentionUtils to wrap emails in <at> tags for Teams mentions.
- Unit tests for TeamsMentionUtils to verify behavior for users with/without emails, and email formatting.

Testing done

Unit Tests:
- Added TeamsMentionUtilsTest to verify proper handling of user mentions and email formatting.
- Tests cover:
  - Users with valid email addresses
  - Users without email addresses
  - Null or empty email strings
Manual Verification:
- Triggered builds with different Webhook configurations:
  - With mentionOnFailure enabled/disabled.
  - Verified mentions appear correctly in Teams messages and only on failures when configured.
- Ensured backward compatibility:
  - Existing builds without the new parameters continue to work with the default behavior.

Related Issues / PRs

#55
#416

Submitter checklist

Make sure you are opening from a topic/feature/bugfix branch (right side) and not your main branch!
Ensure that the pull request title represents the desired changelog entry
Please describe what you did
Link to relevant issues in GitHub or Jira
Link to relevant pull requests, esp. upstream and downstream changes
Ensure you have provided tests that demonstrate the feature works or the issue is fixed

damianszczepanik · 2025-12-17T19:54:26Z

src/main/java/jenkins/plugins/office365connector/utils/TeamsMentionUtils.java

+
+    public static String mentionUser(User user) {
+    if (user == null) {
+        return "Unknown User";


Unknown User
or
Unknown user ?

damianszczepanik · 2025-12-17T19:58:41Z

src/main/java/jenkins/plugins/office365connector/utils/TeamsMentionUtils.java

+    if (user == null) {
+        return "Unknown User";
+    }
+    Mailer.UserProperty prop = user.getProperty(Mailer.UserProperty.class);


prop -> userProperty

damianszczepanik · 2025-12-17T20:03:42Z

src/main/java/jenkins/plugins/office365connector/utils/TeamsMentionUtils.java

+        return "<at>" + email + "</at>";
+    }
+
+    public static String mentionUser(User user) {


name of this method does not report your real intention but rather fallback scenario - I believe this is still mentionEmail

damianszczepanik · 2025-12-17T20:06:23Z

src/main/java/jenkins/plugins/office365connector/CardBuilder.java


        boolean isRepeatedFailure = isRepeatedFailure(previousResult, lastNotFailedBuild);
+
+        boolean shouldMention = (lastResult == Result.FAILURE || lastResult == Result.UNSTABLE || isRepeatedFailure) && mentionOnFailure;


if the current build is SUCCESS but the previous was FAILURE you are mentioning - was it your intention or you just want to provide more details only on failure?

damianszczepanik · 2025-12-17T20:13:44Z

src/main/resources/jenkins/plugins/office365connector/Webhook/config.jelly

                <f:checkbox/>
            </f:entry>
+
+            <f:entry title="Only Mention On Failure" field="mentionOnFailure">


Mention only when build has failed

damianszczepanik · 2025-12-17T20:16:06Z

src/main/java/jenkins/plugins/office365connector/FactsBuilder.java

        String joinedCommitters = authors.stream()
-                .map(User::getFullName)
-                .collect(Collectors.joining(", "));
+            .map(user -> mentionCommitters ? TeamsMentionUtils.mentionUser(user) : user.getFullName())


it complains here because you haven't extended examples in JSON file - same as for previous PR, please add it

damianszczepanik · 2025-12-17T20:24:03Z

src/main/java/jenkins/plugins/office365connector/CardBuilder.java

        factsBuilder.addRemarks();
-        factsBuilder.addCommitters();
-        factsBuilder.addDevelopers();
+        factsBuilder.addCommitters(mentionCommitters && shouldMention);


is it correct configuration if you set mentionCommiters to true and shouldMention to false?

Yes — committers are always displayed. The boolean only controls whether they’re mentioned. I’ll add clarification / rename to make that intent explicit. If I were to get rid of the mention developers toggle like I talk about here #418 (comment), then I wouldn't need a mentionCommitters toggle either as those would be the only people I'd mention. The only toggle would be shouldMention so that line would turn into

`factsBuilder.addCommitters(shouldMention);`

damianszczepanik · 2025-12-17T20:31:00Z

src/main/java/jenkins/plugins/office365connector/FactsBuilder.java

+        for (ChangeLogSet<ChangeLogSet.Entry> set : changeSets) {
+            for (ChangeLogSet.Entry entry : set) {
+                User author = entry.getAuthor();
+                if (author != null) {


this null checking is examined twice: here and above

damianszczepanik · 2025-12-17T20:40:08Z

src/main/java/jenkins/plugins/office365connector/CardBuilder.java

+    this.run = run;
+    this.isAdaptiveCards = isAdaptiveCards;
+    this.mentionCommitters = mentionCommitters;
+    this.mentionDevelopers = mentionDevelopers;


if you set commiters AND developers to true you will get committers list duplicated - is that correct?

committer is a subset of developers

The original intent was to allow some flexibility in terms of who you wanted to mention. Some people might want to mention Developers or Committers. Knowing that committers is essentially a blame list for who Jenkins thinks broke the build, it might make more sense to just have committers be mentioned and not developers? As far as I'm aware anyone's name in the developer section will show up in the committer section.

AmmarOFA · 2025-12-23T12:05:50Z

Currently on vacation, will come back to this in a week or so

damianszczepanik · 2026-01-13T19:12:19Z

src/main/java/jenkins/plugins/office365connector/CardBuilder.java


        Run previousBuild = run.getPreviousBuild();
-        Result previousResult = previousBuild != null ? previousBuild.getResult() : Result.SUCCESS;
+        Result previousResult = previousBuild != null ? previousBuild.getResult() : Result.SUCCESS; 


space at the end of the line - please clean up the files before pushing to code review

Will do, done.

damianszczepanik · 2026-01-13T19:16:57Z

src/main/java/jenkins/plugins/office365connector/FactsBuilder.java

-                .collect(Collectors.joining(", "));
+            .sorted(Comparator.comparing(User::getFullName))
+            .map(user -> mentionCommitters ? TeamsMentionUtils.mentionUserOrEmail(user) : user.getFullName())
+            .filter(StringUtils::isNotBlank) // remove nulls or empty strings


this does not filter out string Unknown user while IMO should

#418 (comment)

damianszczepanik · 2026-01-13T19:41:12Z

src/main/resources/jenkins/plugins/office365connector/Webhook/config.jelly

                <f:checkbox/>
            </f:entry>
+
+            <f:entry title="Mention Only When Build Has Failed" field="mentionOnFailure">


or is unstable - at least this is how I understand the code above

damianszczepanik · 2026-01-13T19:43:54Z

src/main/java/jenkins/plugins/office365connector/utils/TeamsMentionUtils.java

+    }
+
+    public static String mentionUserOrEmail(User user) {
+        if (user == null) {


when this condition is met on runtime?

You're right, double checked that getCulprits() never returns null Users based on Jenkins core behavior. Removed the null check from TeamsMentionUtils.mentionUserOrEmail() since it's only used on the list produced by getCulprits. Test functionality for this null check has been removed as well. If you think re-implementing it differently is of use, please let me know.

damianszczepanik · 2026-01-18T08:08:22Z

pom.xml

            <groupId>org.jenkins-ci.plugins</groupId>
            <artifactId>display-url-api</artifactId>
        </dependency>
+        <dependency>


do we need it?
it introduces security issue https://app.snyk.io/org/damianszczepanik/project/c78d3196-4d6a-4a74-a217-6f6bc5b2f6ac/pr-check/bbbd388e-00e1-4168-a972-a6579dd7772e

I was wondering what that was. I couldn't (and still can't) see the security issue provided by snyk. But Good point. Mailer is not strictly required for this plugin. I can remove the hard dependency and switch to runtime detection so mentions use email when Mailer is present, and fall back to usernames otherwise. Would that work?

Okay, surprised that work haha, I've set mailer to a test dependency now. Fallback behaviour will default if the mailer isn't there, but I needed to test integration. Looks good!

… so the users with extracted emails are tagged

…aults to true)

…velopers on started cards

…ed mention failure text in jelly.config

…d in the shouldMention boolean

…ld Has Failed'

…mentioning comitters on failures

…eIT test code

…ctedFileBuilder

…ions.json and mocking committers in sampleIT not developers

…nd making sure developer names are listed properly

…logset

…scm.getCulprits

AmmarOFA · 2026-02-17T00:25:39Z

Noticed the build was failing because of a banned import (commons.lang.StringUtils), specified lang3 in TeamsMentionUtils to be consistent with what we use in factsbuilder.java

damianszczepanik reviewed Dec 17, 2025

View reviewed changes

damianszczepanik force-pushed the email-@wrapping-toggle branch from fb7a821 to 7c72728 Compare January 13, 2026 19:09

damianszczepanik reviewed Jan 13, 2026

View reviewed changes

damianszczepanik requested changes Jan 18, 2026

View reviewed changes

AmmarOFA changed the title ~~Mention Committers/Developers On Build Failure~~ Mention Committers On Build Failure Jan 18, 2026

Ammar Zain added 24 commits February 9, 2026 23:24

added a toggle that will fetch user emails and wrap them in <at> tags…

c4ba289

… so the users with extracted emails are tagged

added mentionCommitters & mentionDevelopers to jelly.config

cd2741a

added updated constructor params to webhook notifier

2a963e2

removed extra space in factsbuilder

87a12ef

avoiding scope creep, only send mentions on failure notification (def…

835a66a

…aults to true)

got rid of extra constructor and added false defaults to commiters/de…

f58d20e

…velopers on started cards

removed unneeded commons-collection4 dependency

31cabd1

Mention failures now extend to unstable and repeated failures. Adjust…

086f973

…ed mention failure text in jelly.config

Mention failure value in jelly now matches value in webhook.java

229a30a

Naming & API clarity for TeamsMentionUtils & tests

a13fa70

repeated failure is not a result status therefore does not be include…

e9a9f38

…d in the shouldMention boolean

config.jelly webhook mention toggle now called 'Mention Only When Bui…

e3e6ff8

…ld Has Failed'

removed unnecessary null check in developer fetching

eeebccd

unnecessary space removed

6a082f9

fixed TeamsMentionUtils & FactsBuilder to use new method/variables names

d2ec4b3

conditional in metionUserOrEmail should use userProperty not prop

618cec8

updated test file variable name from prop to userProperty

0f3a39f

test now expects 'Unknown user'

55a8529

Removed mentioning developers functionality, now just one toggle for …

c61bc0d

…mentioning comitters on failures

added json testing for mention feature

f317ae2

removed extra space in WebhookBuilder

4f30cb2

fixed the name of testing json

96150ca

Json should use adaptivecard format not legacy message cards

3bee688

mention sampleIT test cannot use information provided in setup()

d880c3d

Ammar Zain and others added 15 commits February 9, 2026 23:24

manual changelogset config for getting emails in the test

d7ba528

added missing imports and extracted a helper method for cleaner sampl…

3b5e35c

…eIT test code

added helper class ChangeLogSetBuilder to sampleIT imports

06903bb

getFullName seems to return null, 0mocking user directly without Affe…

17a263a

…ctedFileBuilder

sorted committers in alphabetical order in completed-failed-with-ment…

baccf11

…ions.json and mocking committers in sampleIT not developers

added missing set and hashset imports

3ef6ae7

added developers to expected json output, ensuring committer order, a…

c19a73c

…nd making sure developer names are listed properly

coverting the sorted list into an array before passing it as a change…

08a3e32

…logset

now sorting committers in factbuilder

bb8a6c5

editing JSON format to match expected output

c32bf0b

more json editing

cd66404

updated config.jelly mention message to include unstable builds

ee28ab4

removed trailing space from line 79 in cardbuilder.java

6e18ccd

removed dead code null checks for committers list produced by runwith…

561ee5c

…scm.getCulprits

Mailer changed to a test dependency

5cacf78

damianszczepanik force-pushed the email-@wrapping-toggle branch from 3d9f5a5 to 5cacf78 Compare February 9, 2026 22:24

Specified lang3.StringUtils, lang(2) is a banned import

1efc85e

kikmon mentioned this pull request Mar 4, 2026

Question: mentions in teams #426

Open


		boolean isRepeatedFailure = isRepeatedFailure(previousResult, lastNotFailedBuild);

		boolean shouldMention = (lastResult == Result.FAILURE \|\| lastResult == Result.UNSTABLE \|\| isRepeatedFailure) && mentionOnFailure;

Uh oh!

Conversation

AmmarOFA commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

How it Works / Idea

Testing done

Related Issues / PRs

Submitter checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AmmarOFA commented Dec 23, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AmmarOFA Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AmmarOFA Jan 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AmmarOFA commented Feb 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

AmmarOFA commented Dec 16, 2025 •

edited

Loading

AmmarOFA Jan 13, 2026 •

edited

Loading

AmmarOFA Jan 18, 2026 •

edited

Loading