Send message to MS Teams (webhook)

Send message to Teams

JavaScript GitHub action to send message to channel(s) in Microsoft Teams using webhook URL(s)

Send a one line message
Additional configuration enables title, status and actor name labels, title background color, buttons that re-direct to run and commit URLs

Usage

Add incoming webhook URL for Teams in GitHub secrets
To send a minimal message, add the following in your workflow YAML

E.g.,

steps:
  - uses: neonidian/teams-notify-build-status@v3
    with:
      webhookUrl: ${{ secrets.TEAMS_INCOMING_WEBHOOK_URL }}   # Secret name is "TEAMS_INCOMING_WEBHOOK_URL"
      message: Workflow run passed !!

All features:
- Send to multiple channels by specifying multiple webhook URLs
- Display title header
- Display actor label(GitHub user ID who triggered the workflow)
- Display status label
- Display title background color
- Enable 'View run' and 'View commit' buttons

E.g.,

steps:
  - uses: neonidian/teams-notify-build-status@v3
    with:
      webhookUrl: |                                         # Send to multiple channels in MS Teams
        ${{ secrets.TEAMS_INCOMING_WEBHOOK_URL_1 }}
        ${{ secrets.TEAMS_INCOMING_WEBHOOK_URL_2 }}
      title: Unit Tests                                      # Specify a title header
      titleBackgroundColor: ${{ steps.unitTest.outcome }}    # Specify title background color. 'unitTest' is the ID of a step
      status: ${{ steps.unitTest.outcome }}                  # Specify what should be displayed in the status label
      message: >-
        Unit tests have been run for version ${{ steps.versioning.outputs.semver }}       # 'versioning' is the ID of the steps that creates versioning
    env:                                                     # Enable actor labels and buttons using environment variables
      SHOULD_DISPLAY_ACTOR_LABEL: true
      SHOULD_DISPLAY_VIEW_RUN_BUTTON: true
      SHOULD_DISPLAY_VIEW_COMMIT_BUTTON: true

See the actions tab in your GitHub repository for runs of this action! 🚀

Inputs and environment variables

Inputs

#	Input ID	Required	Description
1	webhookUrl	Yes	Teams webhook URL(s). If more than 1 webhook URL, use YAML multi-line strings
2	message	Yes	Message to be sent
3	title	No	Title of the card (displays at the top with a larger text)
4	titleBackgroundColor	No	Background color of the title section. Allowed values: 'success', 'green', 'failure', 'red', 'cancelled', 'yellow', 'skipped', 'blue' success, failure, cancelled, skipped can be used dynamically in the workflow using job or step context. E.g., `${{ job.status }}` or `${{ steps.<step_id>.outcome }}` See GitHub docs for more info
5	status	No	Status of a step or a job, or a custom text

Environment variables

#	Environment variable	Allowed values	Default value	Description
1	SHOULD_DISPLAY_VIEW_RUN_BUTTON	'true' or 'false'	false	Clicking on this button redirects to the attempt of the workflow run page in GitHub
2	SHOULD_DISPLAY_VIEW_COMMIT_BUTTON	'true' or 'false'	false	Clicking on this button redirects to SHA commit page in GitHub
3	SHOULD_DISPLAY_ACTOR_LABEL	'true' or 'false'	false	Label to display the username of the workflow initiator

Examples

Send message only when the job is not successful, set status label and display only the 'View Run' button

steps:
  - uses: neonidian/teams-notify-build-status@v3
    if: ${{ !success() }}        # For other statuses, see https://docs.github.com/en/actions/learn-github-actions/expressions#status-check-functions
    with:
      webhookUrl: ${{ secrets.TEAMS_INCOMING_WEBHOOK_URL }}
      message: >-
        Failed to publish artifact version ${{ steps.versioning.outputs.semver }}
      status: Failure
    env:
      SHOULD_DISPLAY_VIEW_RUN_BUTTON: true

Send message only if some jobs have failed, provide status input, title containing link to repository, enable 'View run' and 'View commit' buttons, display actor label by setting the environment variables to true

steps:
  - uses: neonidian/teams-notify-build-status@v3
    needs: [ unitTests, systemTests ]          # IDs of jobs
    if: ${{ job.status == 'failure' }}       # Same as 'failure()'
    with:
      webhookUrl: ${{ secrets.TEAMS_INCOMING_WEBHOOK_URL }}
      title: >-
        [Repository link](${{ github.server_url }}/${{ github.repository }})
      message: Test run failed
      status: ${{ job.status }}
    env:
      SHOULD_DISPLAY_VIEW_RUN_BUTTON: true
      SHOULD_DISPLAY_VIEW_COMMIT_BUTTON: true
      SHOULD_DISPLAY_ACTOR_LABEL: true

Always send a message even if previous steps have been failed, cancelled or skipped, enable 'View commit' button, display title background color based on the current status of the job.

steps:
  - uses: neonidian/teams-notify-build-status@v3
    if: always()
    with:
      webhookUrl: |
       ${{ secrets.TEAMS_INCOMING_WEBHOOK_URL_1 }}
       ${{ secrets.TEAMS_INCOMING_WEBHOOK_URL_2 }}
       ${{ secrets.TEAMS_INCOMING_WEBHOOK_URL_3 }}
      message: Workflow has been run
      titleBackgroundColor: ${{ job.status }}
    env:
      SHOULD_DISPLAY_VIEW_COMMIT_BUTTON: true

Tools used

Adaptive cards interface of Teams has been used for UI
Actions HTTP client JS library from Actions toolkit has been used for HTTP communication
GitHub data for constructing workflow run URL, commit URL etc. are fetched via the default GitHub environment variables

Features

Minimal payload size: Less than 200 KB
Uses JavaScript GitHub action. So containers are not needed to run this action

Sample screenshots (Dark mode enabled in Teams)

status = "failure", "View run" and "View commit" buttons enabled
status = "skipped", "View run" and "View commit" buttons are not enabled
No status input provided, title = "Only with title and view run button" with "View Run" button enabled
status = "skipped", only "View run" is enabled
status = "cancelled", only "View commit" button enabled
Status = "BUILD SUCCESSFUL" which is a custom status not defined in GitHub statuses. Font colour is set to default in case of custom status
titleBackgroundColor = "failure", view run button enabled
title and status inputs provided, titleBackgroundColor = "yellow", view run and view commit buttons enabled
Environment variable SHOULD_DISPLAY_ACTOR_LABEL set to true; set title
Mobile device screenshot (iOS)