Configuring Notifications

1. Using Slack Orb

Property	Description	Values	Notes
slack/notify	Sends build status to Slack	`slack/notify@x.y.z`	Use latest version from CircleCI registry

Example: Slack Notification Configuration

version: 2.1
orbs:
  slack: circleci/slack@4.10.0
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm test
      - slack/notify

Note: Ensure the Slack orb is configured with appropriate channel and build status settings in your CircleCI project settings.

2. Sending Email Notifications

Property	Value	Description
email	`enabled`	Enable or disable email notifications
email.to	`string`	Email address to send notifications to
email.from	`string`	Email address to send notifications from
email.subject	`string`	Subject line for email notifications

Example: Email Notification Configuration

notify:
  email:
    enabled: true
    to:
      - "dev@example.com"
      - "ops@example.com"
    from: "circleci@example.com"
    subject: "Build {{status}} - {{pipeline.number}}"

Note: Email notifications are sent via CircleCI's internal email service. Ensure that the email addresses are valid and properly configured in your project settings.

3. Using Webhook Notifications

Property	Values	Description
webhook.url	`https://example.com/webhook`	The URL to send the webhook payload to.
webhook.method	`POST`	HTTP method to use for sending the payload. Default is `POST`.
webhook.headers	`{}`	Optional custom headers to include in the webhook request.
webhook.payload	`json`	Format of the payload sent to the webhook. Default is JSON.

Example: Configuring Webhook Notification

version: 2.1
jobs:
  build:
    steps:
      - checkout
      - run: echo "Building..."
      - notify:
          webhook:
            url: https://example.com/webhook
            method: POST
            headers:
              Content-Type: application/json
            payload: |
              {
                "build": "success",
                "project": "my-project"
              }

Note: Webhook notifications are sent asynchronously and may not be received immediately.

4. Notifying on Failure

Example: Slack Notification on Build Failure

version: 2.1
jobs:
  build:
    steps:
      - checkout
      - run: echo "Building..."
      - store_artifacts:
          path: /tmp/build.log
      - slack/notify:
          channel: '#build-notifications'
          on_fail: true

Property	Description	Values
slack/notify	Slack notification step	`true` or `false`
channel	Slack channel to notify	`#build-notifications`
on_fail	Trigger only on failure	`true`

Note: Ensure the Slack integration is configured in your CircleCI project settings.

Example: Email Notification on Failure

version: 2.1
jobs:
  build:
    steps:
      - checkout
      - run: echo "Building..."
      - email/notify:
          recipients:
            - dev-team@example.com
          on_fail: true

Property	Description	Values
email/notify	Email notification step	`true` or `false`
recipients	List of email addresses	`[dev-team@example.com]`
on_fail	Trigger only on failure	`true`

5. Notifying on Success

Option	Values	Notes
on_success	`notify`	Send notification on job success
on_success	`ignore`	Do not send notification on job success

Example: Configuring Success Notification

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm test
      - notify:
          on_success: notify

Note: Success notifications are sent only if the job completes successfully and on_success is set to notify.

6. Using Custom Notifications

Example: Custom Notification Configuration

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm test
      - store_test_results:
          path: test-results
      - notify:
          custom:
            webhook_url: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
            message: "Build {{build_num}} completed successfully"

Property	Description	Values	Notes
notify.custom.webhook_url	URL of the webhook endpoint	`string`	Required for custom notifications
notify.custom.message	Message to send in the notification	`string`	Supports template variables like `{{build_num}}`
notify.custom.method	HTTP method to use for sending notification	`POST`, `GET`	Defaults to `POST`
notify.custom.headers	Custom headers to include in the request	`object`	Optional, used for authentication or custom data

Note: Template variables like {{build_num}}, {{status}}, and {{branch}} can be used in the message field to provide dynamic content.

Warning: Ensure that webhook URLs are securely stored and not exposed in public repositories.

Custom Notification Summary

Webhook URL must be valid and accessible
Message field supports dynamic templating
Headers can be used for authentication or custom metadata
Method defaults to POST but can be overridden

7. Configuring Chat Integrations

Integration	Channel/Service	Configuration	Notes
Slack	Slack Channel	`slack:` in config	Requires Slack app setup and bot token
Microsoft Teams	Teams Channel	`teams:` in config	Uses incoming webhook URL
Discord	Discord Channel	`discord:` in config	Uses webhook URL from Discord server settings

Example: Slack Integration

notifications:
  slack:
    channel: "#build-notifications"
    webhook_url: "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"

Example: Microsoft Teams Integration

notifications:
  teams:
    channel: "Build Notifications"
    webhook_url: "https://outlook.office.com/webhook/..."

Example: Discord Integration

notifications:
  discord:
    channel: "build-alerts"
    webhook_url: "https://discord.com/api/webhooks/..."

Note: All chat integrations require a valid webhook URL or bot token to function. Ensure permissions are correctly set for the integration service.

8. Setting Notification Preferences

Preference	Description	Values	Default
on_success	Send notification on successful build	`always`, `never`	`never`
on_fail	Send notification on failed build	`always`, `never`	`always`
on_start	Send notification when build starts	`always`, `never`	`never`
on_cancel	Send notification on canceled build	`always`, `never`	`never`

Example: Configuring Notification Preferences

version: 2.1
jobs:
  build:
    steps:
      - checkout
      - run: echo "Building..."
      - notify:
          on_success: always
          on_fail: always
          on_start: never
          on_cancel: never

9. Using Status Badges

Status badges provide a visual indicator of your build's current state, which can be embedded in README files, documentation, or project dashboards.

Badge Type	URL Format	Description	Usage Example
Build Status	`https://circleci.com/gh/<ORG>/<PROJECT>/tree/<BRANCH>.svg?style=shield`	Shows the current build status (success, failed, running)	`<img src="https://circleci.com/gh/yourorg/yourproject/tree/main.svg?style=shield" alt="Build Status">`
Workflow Status	`https://circleci.com/gh/<ORG>/<PROJECT>/workflows/<WORKFLOW_ID>.svg?style=shield`	Shows the status of a specific workflow	`<img src="https://circleci.com/gh/yourorg/yourproject/workflows/abc123.svg?style=shield" alt="Workflow Status">`

Example: Adding Build Badge to README

<img src="https://circleci.com/gh/yourorg/yourproject/tree/main.svg?style=shield" alt="Build Status">

Note: The ?style=shield parameter ensures the badge displays in a clean, standardized format.

10. Muting Notifications

Property	Values	Description
notifications.mute	`true`	Mutes all notifications for the project
notifications.mute	`false`	Enables notifications (default)

Example: Muting All Notifications

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm test

workflows:
  version: 2
  build-and-test:
    jobs:
      - build

notifications:
  mute: true