Microsoft Teams Deploy Card

A comprehensive notification card in Microsoft Teams for your deployments.

Layouts

Complete

Cozy

Compact

Usage

Add MS_TEAMS_WEBHOOK_URI on your repository's configs on Settings > Secrets. It is the webhook URI of the dedicated Microsoft Teams channel for notification.

2) Add a new step on your workflow code below actions/checkout@v2:

name: MS Teams Deploy Card

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2
      # this is the new step
      - uses: toko-bifrost/ms-teams-deploy-card@master #  or "./" if in a local set-up
        if: always()
        with:
          github-token: ${{ github.token }}
          webhook-uri: ${{ secrets.MS_TEAMS_WEBHOOK_URI }}

Configurations

Main Configurations

Name	Required	Default	Description
`github-token`	`true`	None	This can be set to the following: - `${{ github.token }}` - `${{ secrets.GITHUB_TOKEN }}` - `${{ secrets.CUSTOM_TOKEN }}`
`webhook-uri`	`true`	None	The value of `MS_TEAMS_WEBHOOK_URI`
`card-layout-start`	`false`	`complete`	Card layout on *start* (i.e. `complete`, `cozy`, `compact`)
`card-layout-exit`	`false`	`compact`	Card layout on *exit* (i.e. `complete`, `cozy`, `compact`)
`show-on-start`	`false`	`true`	Show an MS Teams card upon *starting* this Github Actions job
`show-on-exit`	`false`	`true`	Show an MS Teams card upon *exiting* this Github Actions job, regardless if it's a successful or a failed exit
`show-on-failure`	`false`	`false`	Show an MS Teams card upon *exiting* this Github Actions job and status is `FAILURE`; This will override any boolean value of `show-on-exit`, e.g. with `show-on-exit=false` and `show-on-failure=true`, the notification card will still proceed upon job failure

Cozy and Complete Layout-specific Configurations

Name	Required	Default	Description
`environment`	`false`	None	Name of the environment, e.g. `development`, `production` (won't be included in the card if none)
`timezone`	`false`	`"UTC"`	A valid database timezone name, e.g. `Australia/Sydney`
`enable-view-status`	`false`	`true`	Enable an action to view the deployment status
`enable-review-diffs`	`false`	`true`	Enable an action to review commit diffs
`view-status-action-text`	`false`	`"View build/deploy status"`	Customize action text in viewing the deployment status
`review-diffs-action-text`	`false`	`"Review commit diffs"`	Customize action text in reviewing commit diffs
`custom-actions`	`false`	`null`	Add more actions; must be a YAML-parseable multiline string with `text` and `url` pairs

Complete Layout-specific Configurations

Name	Required	Default	Description
`custom-facts`	`false`	`null`	YAML-parseable multiline string defining a list of objects with `name` and `value` to display alongside existing facts. Only for `complete` layout.
`include-files`	`false`	`true`	Include the list of files when `layout` is set to `complete`
`allowed-file-len`	`false`	`7`	Allowed number of changed files to display, when `include-files` is set to `true`

Local Set-up

Clone this repository.
Install JS dependencies via yarn install or npm install.
Before pushing you changes, execute yarn ncc (or npm run ncc) to create a build on dist.
Do not remove the dist repository. Ever.
Check the Actions tab for the errors if there are any.

Known Issues

Avoid naming your secrets with the prefix GITHUB_ as secrets are being used as environment variables, and they are reserved for Github Actions' use only. Better stick with CI_GITHUB_TOKEN.
As this is still in development, always use the working latest version from the Releases, as they have more bug fixes and added features.
If you are going to set custom-facts (only for complete layout) and custom-actions (on both cozy and complete layout), look out for the pipe symbol (|). Github Actions only accept string, number, and boolean as parameters on job steps. To bypass this restriction and to instill YAML list formatting, we have to set it with a YAML-parseable multiline string containing a YAML list of objects with name and value on custom-facts, and text and url (i.e. must be a valid URI format) on custom-actions. If there is an error in YAML parsing, no custom facts/actions will be appended.

- uses: toko-bifrost/ms-teams-deploy-card@master
  with:
    github-token: ${{ github.token }}
    webhook-uri: ${{ secrets.MS_TEAMS_WEBHOOK_URI }}
    custom-facts: |
      - name: Custom Fact Name 1
        value: Custom Fact Value 1
      - name: Pull Request
        value: "http://example.com/${{ github.run_id }}"
    custom-actions: |
      - text: View PR
        url: "http://valid.uri.com"
      - text: View CI
        url: "http://example.com/${{ github.run_id }}"

Always set this job with if: always() when there are steps between actions/checkout@v2 and this job.
Status IN_PROGRESS upon job completion means you have set the jobs.<job_id>.name. It is encouraged to exclude setting the jobs.<job_id>.name. It is because GITHUB_JOB is set with jobs.<job_id>, and the Github API gives off the value of jobs.<job_id>.name, if set. Thus, there is no way to match the current job with the ones in the Github API upon post-job conclusion.
As much as possible, always set this Github action right after actions/checkout@v2 and before any job steps. The following diagram shows when this job if going to trigger if done the right way.

  job
    |-- actions/checkout@v2
      |-- ms-teams-deploy-card (fires notification of job initiation, if allowed)
        |-- step 1
        |...more steps
        |-- step N
      |-- post ms-teams-deploy-card
          * checks the conclusion based on the previous completed steps
          * fires notification if allowed in the settings
    |-- post actions/checkout@v2

toko-bifrost / ms-teams-deploy-card

readme

Microsoft Teams Deploy Card

Layouts

Complete

Cozy

Compact

Usage

Configurations

Main Configurations

Cozy and Complete Layout-specific Configurations

Complete Layout-specific Configurations

Local Set-up

Known Issues