Enhance push event formatting and configurability

VladimirPal · VladimirPal · commit f021ee32f1f6 · 2025-03-27T17:52:16.000+07:00
- Add `push` configuration options to `GitHubRepoConnectionState` and
  `GitLabRepoConnectionState`, allowing customization of:
  - Commit display template (`md_bullets` or `html_dropdown`)
  - Maximum commits to display per push event
  - Whether to show commit body content
- Refactor `onPush` and `onGitLabPush` methods to use
  `FormatUtil.formatPushEventContent`, ensuring consistent commit formatting
- Improve Matrix event messages with enhanced formatting options, supporting
  collapsible commit lists in `html_dropdown` mode
- Apply improvements across GitHub and GitLab integrations
diff --git a/docs/usage/room_configuration/github_repo.md b/docs/usage/room_configuration/github_repo.md
@@ -41,6 +41,10 @@ This connection supports a few options which can be defined in the room state:
 |workflowRun.matchingBranch|Only report workflow runs if it matches this regex.|Regex string|*empty*|
 |workflowRun.includingWorkflows|Only report workflow runs with a matching workflow name.|Array of: String matching a workflow name|*empty*|
 |workflowRun.excludingWorkflows|Never report workflow runs with a matching workflow name.|Array of: String matching a workflow name|*empty*|
+|push|Configuration options for push events|`{ template: "md_bullets" \| "html_dropdown", maxCommits: number, showCommitBody: boolean }`|*empty*|
+|push.template|Defines the format of the message sent to the room for push events.|`"md_bullets"` \| `"html_dropdown"`|`"html_dropdown"`|
+|push.maxCommits|Specifies the maximum number of commits to display in the message.|Positive integer|`5`|
+|push.showCommitBody|Determines whether the commit message body (in addition to the commit title) should be included in the notification.|`true` \| `false`|`false`|
 
 
 [^1]: `ignoreHooks` is no longer accepted for new state events. Use `enableHooks` to explicitly state all events you want to see.
diff --git a/docs/usage/room_configuration/gitlab_project.md b/docs/usage/room_configuration/gitlab_project.md
@@ -30,6 +30,10 @@ This connection supports a few options which can be defined in the room state[^2
 |includeCommentBody|Include the body of a comment when notifying on merge requests|Boolean|false|
 |includingLabels|Only notify on issues matching these label names|Array of: String matching a label name|*empty*|
 |pushTagsRegex|Only mention pushed tags which match this regex|Regex string|*empty*|
+|push|Configuration options for push events|`{ template: "md_bullets" \| "html_dropdown", maxCommits: number, showCommitBody: boolean }`|*empty*|
+|push.template|Defines the format of the message sent to the room for push events.|`"md_bullets"` \| `"md_bullets"`|`"html_dropdown"`|
+|push.maxCommits|Specifies the maximum number of commits to display in the message.|Positive integer|`5`|
+|push.showCommitBody|Determines whether the commit message body (in addition to the commit title) should be included in the notification.|`true` \| `false`|`false`|
 
 
 [^1]: `ignoreHooks` is no longer accepted for new state events. Use `enableHooks` to explicitly state all events you want to see.
diff --git a/src/Connections/GithubRepo.ts b/src/Connections/GithubRepo.ts
@@ -64,7 +64,12 @@ export interface GitHubRepoConnectionOptions extends IConnectionState {
         matchingBranch?: string;
         includingWorkflows?: string[];
         excludingWorkflows?: string[];
-    }
+    };
+    push?: {
+        template?: "md_bullets" | "html_dropdown";
+        maxCommits?: number;
+        showCommitBody?: boolean;
+    };
 }
 
 export interface GitHubRepoConnectionState extends GitHubRepoConnectionOptions {
@@ -272,6 +277,15 @@ const ConnectionStateSchema = {
                 items: {type: "string"},
             },
         },
+    },
+    push: {
+        type: "object",
+        nullable: true,
+        properties: {
+            template: { type: "string", nullable: true, enum: ["md_bullets", "html_dropdown"] },
+            maxCommits: { type: "number", nullable: true },
+            showCommitBody: { type: "boolean", nullable: true }
+        }
     }
   },
   required: [
@@ -1332,8 +1346,33 @@ export class GitHubRepoConnection extends CommandConnection<GitHubRepoConnection
         if (this.hookFilter.shouldSkip('push')) {
             return;
         }
-    
-        const content = `**${event.sender.login}** pushed [${event.commits.length} commit${event.commits.length === 1 ? '' : 's'}](${event.compare}) to \`${event.ref}\` for ${event.repository.full_name}`;
+
+        const PUSH_MAX_COMMITS = 5;
+        const branchName = event.ref.replace("refs/heads/", "");
+        const commitsUrl = event.compare;
+        const branchUrl = `${event.repository.html_url}/tree/${branchName}`;
+
+        const { body, formatted_body } = FormatUtil.formatPushEventContent({
+            contributors: Object.values(event.commits.reduce((acc: Record<string, string>, commit) => {
+                acc[commit.author.name] = commit.author.name;
+                return acc;
+            }, {} as Record<string, string>)),
+            commits: event.commits.map(commit => ({
+                id: commit.id,
+                url: commit.url,
+                message: commit.message,
+                author: { name: commit.author.name },
+            })),
+            branchName,
+            branchUrl,
+            commitsUrl,
+            repoName: event.repository.full_name,
+            maxCommits: this.state.push?.maxCommits ?? PUSH_MAX_COMMITS,
+            shouldName: true,
+            template: this.state.push?.template ?? "html_dropdown",
+            showCommitBody: this.state.push?.showCommitBody,
+        });
+
         const eventContent: IPushEventContent = {
             ...FormatUtil.getPartialBodyForGithubRepo(event.repository),
             external_url: event.compare,
@@ -1344,8 +1383,8 @@ export class GitHubRepoConnection extends CommandConnection<GitHubRepoConnection
                 base_ref: event.base_ref,
             },
             msgtype: "m.notice",
-            body: content,
-            formatted_body: md.render(content),
+            body,
+            formatted_body,
             format: "org.matrix.custom.html",
         };
         await this.intent.sendEvent(this.roomId, eventContent);
diff --git a/src/Connections/GitlabRepo.ts b/src/Connections/GitlabRepo.ts
@@ -19,6 +19,7 @@ import { GitLabClient } from "../Gitlab/Client";
 import { IBridgeStorageProvider } from "../Stores/StorageProvider";
 import axios from "axios";
 import { GitLabGrantChecker } from "../Gitlab/GrantChecker";
+import { FormatUtil } from "../FormatUtil";
 
 export interface GitLabRepoConnectionState extends IConnectionState {
     instance: string;
@@ -33,6 +34,11 @@ export interface GitLabRepoConnectionState extends IConnectionState {
     pushTagsRegex?: string,
     includingLabels?: string[];
     excludingLabels?: string[];
+    push?: {
+        template?: "md_bullets" | "html_dropdown";
+        maxCommits?: number;
+        showCommitBody?: boolean;
+    };
 }
 
 interface ConnectionStateValidated extends GitLabRepoConnectionState {
@@ -149,6 +155,15 @@ const ConnectionStateSchema = {
             type: "boolean",
             nullable: true,
         },
+        push: {
+            type: "object",
+            nullable: true,
+            properties: {
+                template: { type: "string", nullable: true, enum: ["md_bullets", "html_dropdown"] },
+                maxCommits: { type: "number", nullable: true },
+                showCommitBody: { type: "boolean", nullable: true }
+            }
+        }
     },
     required: [
       "instance",
@@ -668,35 +683,36 @@ export class GitLabRepoConnection extends CommandConnection<GitLabRepoConnection
             return;
         }
         log.info(`onGitLabPush ${this.roomId} ${this.instance.url}/${this.path} ${event.after}`);
-        const branchname = event.ref.replace("refs/heads/", "");
-        const commitsurl = `${event.project.homepage}/-/commits/${branchname}`;
-        const branchurl = `${event.project.homepage}/-/tree/${branchname}`;
+        const branchName = event.ref.replace("refs/heads/", "");
+        const commitsUrl = `${event.project.homepage}/-/commits/${branchName}`;
+        const branchUrl = `${event.project.homepage}/-/tree/${branchName}`;
         const shouldName = !event.commits.every(c => c.author.email === event.user_email);
 
-        const tooManyCommits = event.total_commits_count > PUSH_MAX_COMMITS;
-        const displayedCommits = tooManyCommits ? 1 : Math.min(event.total_commits_count, PUSH_MAX_COMMITS);
-
-        // Take the top 5 commits. The array is ordered in reverse.
-        const commits = event.commits.reverse().slice(0,displayedCommits).map(commit => {
-            return `[\`${commit.id.slice(0,8)}\`](${event.project.homepage}/-/commit/${commit.id}) ${commit.title}${shouldName ? ` by ${commit.author.name}` : ""}`;
-        }).join('\n - ');
-
-        let content = `**${event.user_name}** pushed [${event.total_commits_count} commit${event.total_commits_count > 1 ? "s": ""}](${commitsurl})`
-        + ` to [\`${branchname}\`](${branchurl}) for ${event.project.path_with_namespace}`;
-
-        if (displayedCommits >= 2) {
-            content += `\n - ${commits}\n`;
-        } else if (displayedCommits === 1) {
-            content += `: ${commits}`;
-            if (tooManyCommits) {
-                content += `, and [${event.total_commits_count - 1} more](${commitsurl}) commits`;
-            }
-        }
+        const { body, formatted_body } = FormatUtil.formatPushEventContent({
+            contributors: Object.values(event.commits.reduce((acc: Record<string, string>, commit) => {
+                acc[commit.author.name] = commit.author.name;
+                return acc;
+            }, {} as Record<string, string>)),
+            commits: event.commits.map(commit => ({
+                id: commit.id,
+                url: commit.url,
+                message: commit.message,
+                author: { name: commit.author.name },
+            })),
+            branchName,
+            branchUrl,
+            commitsUrl,
+            repoName: event.repository.name,
+            maxCommits: this.state.push?.maxCommits ?? PUSH_MAX_COMMITS,
+            shouldName,
+            template: this.state.push?.template ?? "html_dropdown",
+            showCommitBody: this.state.push?.showCommitBody,
+        });
 
         await this.intent.sendEvent(this.roomId, {
             msgtype: "m.notice",
-            body: content,
-            formatted_body: md.render(content),
+            body,
+            formatted_body,
             format: "org.matrix.custom.html",
         });
     }
diff --git a/src/FormatUtil.ts b/src/FormatUtil.ts
@@ -1,8 +1,11 @@
 import { ProjectsListResponseData } from './github/Types';
 import { emojify } from "node-emoji";
+import markdown from "markdown-it";
 import { JiraIssue } from './jira/Types';
 import { formatLabels, getPartialBodyForJiraIssue, hashId, getPartialBodyForGithubIssue, getPartialBodyForGithubRepo, MinimalGitHubIssue } from "./libRs";
 
+const md = new markdown();
+
 interface IMinimalPR {
     html_url: string;
     id: number;
@@ -13,7 +16,6 @@ interface IMinimalPR {
     };
 }
 
-
 export interface ILabel {
     color?: string,
     name: string,
@@ -44,6 +46,140 @@ export class FormatUtil {
         return `${repo.html_url}`;
     }
 
+    public static formatPushEventContent({
+        contributors,
+        commits,
+        branchName,
+        branchUrl,
+        commitsUrl,
+        repoName,
+        maxCommits = 5,
+        shouldName = false,
+        template = "md_bullets",
+        showCommitBody = false,
+    }: {
+        contributors: string[];
+        commits: {
+            id: string;
+            url: string;
+            message: string;
+            author: { name: string };
+        }[];
+        branchName: string;
+        branchUrl: string;
+        commitsUrl: string;
+        repoName: string;
+        maxCommits?: number;
+        shouldName?: boolean;
+        template?: "md_bullets" | "html_dropdown";
+        showCommitBody?: boolean;
+    }) {
+        const tooManyCommits = commits.length > maxCommits;
+        const displayedCommits = Math.min(commits.length, maxCommits);
+        const separator = template === "md_bullets" ? "\n" : "<br>";
+        const multipleContributors = contributors.length > 1;
+
+        const formatCommitMessage = ({
+            commit,
+            showAuthor,
+        }: {
+            commit: typeof commits[0];
+            showAuthor: boolean;
+        }) => {
+            const { id, url, message, author } = commit;
+            const [title, ...body] = message.split("\n");
+            const authorInfo =
+                shouldName && showAuthor ? ` by \`${author.name}\`` : "";
+            const formattedBody =
+                showCommitBody && body.length
+                    ? `${separator}${body.join(separator)}`
+                    : "";
+            const commitId = id.slice(0, 8);
+
+            return template === "md_bullets"
+                ? `[\`${commitId}\`](${url}) ${title}${authorInfo}${formattedBody}`
+                : `- <a href="${url}"><code>${commitId}</code></a> ${title}${authorInfo}${formattedBody}`;
+        };
+
+        if (template === "html_dropdown") {
+            if (commits.length === 1) {
+                const singleCommitMessage = formatCommitMessage({
+                    commit: commits[0],
+                    showAuthor: false,
+                });
+
+                return {
+                    body: `**${contributors.join(", ")}** pushed 1 commit to [\`${branchName}\`](${branchUrl}) for ${repoName}: ${singleCommitMessage}`,
+                    formatted_body: `<b>${contributors.join(
+                        ", "
+                    )}</b> pushed 1 commit to <a href="${branchUrl}"><code>${branchName}</code></a>
+                    for ${repoName}: ${singleCommitMessage}`,
+                    format: "org.matrix.custom.html",
+                };
+            }
+
+            const commitList = commits
+                .slice(0, displayedCommits)
+                .map((commit) =>
+                    formatCommitMessage({
+                        commit,
+                        showAuthor: multipleContributors,
+                    })
+                )
+                .join("<hr>");
+
+            const extraCommits = tooManyCommits
+                ? `<br><br><a href="${commitsUrl}">and ${commits.length - displayedCommits} more commits</a>`
+                : "";
+
+            return {
+                body: `**${contributors.join(", ")}** pushed [${commits.length} commit${
+                    commits.length === 1 ? "" : "s"
+                }](${commitsUrl}) to [\`${branchName}\`](${branchUrl}) for ${repoName}`,
+                formatted_body: `
+                    <details>
+                        <summary><b>${contributors.join(", ")}</b> pushed
+                        <a href="${commitsUrl}">${commits.length} commit${
+                    commits.length === 1 ? "" : "s"
+                }</a> to <a href="${branchUrl}"><code>${branchName}</code></a> for ${repoName}
+                        </summary>
+                        <br>${commitList}${extraCommits}
+                    </details>
+                `,
+                format: "org.matrix.custom.html",
+            };
+        }
+
+        const commitMessages = commits
+            .slice(0, displayedCommits)
+            .map((commit) =>
+                formatCommitMessage({ commit, showAuthor: multipleContributors })
+            )
+            .join("\n - ");
+
+        let content = `**${contributors.join(", ")}** pushed [${commits.length} commit${
+            commits.length === 1 ? "" : "s"
+        }](${commitsUrl}) to [\`${branchName}\`](${branchUrl}) for ${repoName}`;
+
+        if (displayedCommits === 1) {
+            content += `: ${formatCommitMessage({
+                commit: commits[0],
+                showAuthor: false,
+            })}`;
+        } else if (displayedCommits > 1) {
+            content += `\n - ${commitMessages}\n`;
+        }
+
+        if (tooManyCommits) {
+            content += `\nand [${commits.length - displayedCommits} more](${commitsUrl}) commits`;
+        }
+
+        return {
+            body: content,
+            formatted_body: md.render(content),
+        };
+    }
+
     public static getPartialBodyForGithubRepo(repo: LooseMinimalGitHubRepo) {
         if (!repo.id || !repo.html_url || !repo.full_name) {
             throw Error('Missing keys in repo object');
