Skip to main content
Mapagam

Working with Notifications and Integrations

1. Configuring Email Notifications

Setting Value Description
email.enabled true Enable or disable email notifications
email.from "noreply@example.com" Sender email address
email.subject_template "[$CI_PROJECT_NAME] $CI_PIPELINE_STATUS" Template for email subject
email.to "team@example.com" Recipient email address or list

Example: Email Notification Configuration

notify:
  email:
    enabled: true
    from: "noreply@example.com"
    subject_template: "[$CI_PROJECT_NAME] $CI_PIPELINE_STATUS"
    to: "team@example.com"
Note: Email notifications require a configured SMTP server in GitLab settings.

2. Using Slack Notifications

Setting Value Description
notification_events push, merge, build Events that trigger Slack notifications
slack_url https://hooks.slack.com/services/... Slack webhook URL for incoming messages
slack_channel #ci-notifications Target Slack channel for messages

Example: Slack Notification Configuration

notify_slack:
  stage: notify
  script:
    - echo "Build completed"
  only:
    - main
  notifications:
    slack:
      url: $SLACK_WEBHOOK_URL
      channel: "#ci-notifications"
Note: Ensure SLACK_WEBHOOK_URL is set in your GitLab CI/CD variables.
Warning: Slack webhook URLs are sensitive and should never be exposed in public repositories.

3. Configuring Microsoft Teams Notifications

Setting Value Description
notification_events push, merge, build Events that trigger notifications
webhook_url https://outlook.office.com/webhook/... Microsoft Teams webhook URL
channel #gitlab-notifications Teams channel to send notifications to

Example: GitLab CI Configuration

notify_teams:
  stage: notify
  script:
    - echo "Sending notification to Microsoft Teams"
  only:
    - main
  notifications:
    teams:
      webhook_url: "https://outlook.office.com/webhook/..."
      channel: "#gitlab-notifications"
Note: Ensure the webhook URL is properly escaped and secured.

4. Using Discord Notifications

Setting Value Description
notification_events push, merge, build Events that trigger notifications
discord_webhook_url https://discord.com/api/webhooks/... Discord webhook URL to send notifications

Example: GitLab CI Configuration

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "push"

notify_discord:
  stage: notify
  script:
    - echo "Sending Discord notification"
  only:
    - main
  environment:
    name: production
  notifications:
    discord:
      webhook_url: "https://discord.com/api/webhooks/..."
      events:
        - push
        - merge
Note: Ensure the webhook URL has proper permissions and is not exposed in public repositories.

5. Implementing Custom Webhooks

Custom webhooks in GitLab CI/CD allow you to send build status, job details, and other events to external services or internal systems. These webhooks can be configured at various levels: project, group, or instance-wide.

Configuration Level Event Type Webhook URL Notes
Project push_events https://example.com/webhook Triggers on code pushes to any branch
Group job_events https://internal.service.com/gitlab Triggers on job completion in any project of the group
Instance pipeline_events https://monitoring.system.com/pipeline Triggers on pipeline creation or completion across all projects

Example: Setting up a Custom Webhook in GitLab CI

webhook_notification:
  stage: notify
  script:
    - |
      curl -X POST \
        -H "Content-Type: application/json" \
        -d '{"event_type":"pipeline","status":"success"}' \
        "https://example.com/webhook"
  only:
    - main
Note: Webhook payloads are sent as JSON and must be handled by the receiving service to parse and process the event data correctly.
Warning: Ensure that webhook URLs are secured and authenticated to prevent unauthorized access or abuse.

Key Considerations for Webhook Implementation

  • Use HTTPS endpoints to ensure secure transmission of data.
  • Implement retry logic in the receiving service to handle transient failures.
  • Validate incoming payloads to prevent injection attacks or malformed data.
  • Limit the number of concurrent webhook requests to avoid overwhelming external services.

6. Using ChatOps Integrations

Integration Supported Platforms Description Configuration
Slack Slack Send GitLab CI/CD pipeline notifications to Slack channels. 
# .gitlab-ci.yml
slack_notification:
  stage: notify
  script:
    - echo "Pipeline $CI_PIPELINE_ID finished with status $CI_PIPELINE_STATUS"
  only:
    - branches
Microsoft Teams Teams Send pipeline status updates to Microsoft Teams channels. 
# .gitlab-ci.yml
teams_notification:
  stage: notify
  script:
    - |
      curl -X POST \
        -H 'Content-Type: application/json' \
        -d '{"text":"Pipeline $CI_PIPELINE_ID finished with status $CI_PIPELINE_STATUS"}' \
        $TEAMS_WEBHOOK_URL
Discord Discord Send CI/CD notifications to Discord channels via webhooks. 
# .gitlab-ci.yml
discord_notification:
  stage: notify
  script:
    - |
      curl -X POST \
        -H 'Content-Type: application/json' \
        -d '{"content":"Pipeline $CI_PIPELINE_ID finished with status $CI_PIPELINE_STATUS"}' \
        $DISCORD_WEBHOOK_URL

Example: Slack Integration Setup

# 1. Create a Slack app and get the webhook URL
# 2. Add the webhook URL to GitLab CI/CD variables (e.g., SLACK_WEBHOOK_URL)
# 3. Use in .gitlab-ci.yml as shown above
Note: Ensure that the webhook URLs are stored securely in GitLab CI/CD variables to avoid exposing them in your configuration files.

ChatOps Integration Benefits

  • Real-time visibility into pipeline status.
  • Improved team collaboration through direct channel updates.
  • Customizable notification formats for different platforms.

7. Configuring Jira Integration

Setting Description Value
jira.integration.enabled Enables or disables the Jira integration true / false
jira.integration.url Base URL of the Jira instance https://your-jira-domain.atlassian.net
jira.integration.username Username for Jira API access user@example.com
jira.integration.token API token for Jira authentication your-jira-api-token

Example: GitLab CI/CD Configuration

variables:
  JIRA_INTEGRATION_ENABLED: "true"
  JIRA_INTEGRATION_URL: "https://your-jira-domain.atlassian.net"
  JIRA_INTEGRATION_USERNAME: "user@example.com"
  JIRA_INTEGRATION_TOKEN: "your-jira-api-token"
Note: Ensure the Jira API token has appropriate permissions to create and update issues.
Warning: Store sensitive credentials like JIRA_INTEGRATION_TOKEN in GitLab CI/CD variables or secrets to avoid exposing them in logs or configuration files.

8. Using PagerDuty Integration

Setting Description Value
pagerduty.enabled Enables or disables PagerDuty integration true or false
pagerduty.service_key PagerDuty service integration key <your-service-key>
pagerduty.event_type Event type to send to PagerDuty trigger, acknowledge, or resolve

Example: Configure PagerDuty Integration in .gitlab-ci.yml

pages:
  stage: deploy
  script:
    - echo "Deploying to production"
  only:
    - main
  notifications:
    pagerduty:
      enabled: true
      service_key: $PAGERDUTY_SERVICE_KEY
      event_type: trigger
Note: The PAGERDUTY_SERVICE_KEY should be set as a CI/CD variable in your GitLab project settings.

Integration Workflow

  • Configure the PagerDuty service key in GitLab CI/CD variables
  • Enable the integration in your job configuration
  • Set event type to trigger for alerting on job failures
  • Use acknowledge or resolve for status updates

9. Implementing Custom Notification Scripts

Custom notification scripts in GitLab CI/CD allow you to extend the built-in notification mechanisms with personalized logic. These scripts can be executed at various stages of a pipeline and are useful for sending notifications to external systems or custom channels.

Script Location Execution Context Description
.gitlab/custom-notifications.sh Runner context Script file located in the project root or a subdirectory, executed by the GitLab Runner.

Example: Custom Notification Script

#!/bin/bash
# .gitlab/custom-notifications.sh

if [ "$CI_JOB_STATUS" = "success" ]; then
  echo "Pipeline succeeded for branch $CI_COMMIT_REF_NAME"
  # Send to external service or Slack
else
  echo "Pipeline failed for branch $CI_COMMIT_REF_NAME"
  # Send failure alert
fi
Note: The script must be executable and reside in a location accessible to the GitLab Runner. Ensure proper permissions are set using chmod +x.

Key Points

  • Custom scripts can be triggered via GitLab CI/CD job hooks.
  • They support environment variables like CI_JOB_STATUS, CI_COMMIT_REF_NAME, and CI_PIPELINE_ID.
  • Scripts must be executable (chmod +x) to run in the GitLab Runner.
  • Use curl or similar tools to send notifications to external services like Slack, email, or webhooks.

10. Using GitLab API for Notifications

Resource Endpoint Description Method
Project Notifications /projects/:id/notifications Get project notification settings GET
Update Project Notifications /projects/:id/notifications Update project notification settings PUT
User Notifications /users/:id/notifications Get user notification settings GET
Update User Notifications /users/:id/notifications Update user notification settings PUT

Example: Get Project Notifications

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.example.com/api/v4/projects/1/notifications"

Example: Update Project Notifications

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{"level":"all","event_activities":["push","merge"]}' \
  "https://gitlab.example.com/api/v4/projects/1/notifications"
Note: The level can be all, participating, or off. The event_activities array specifies which events trigger notifications.

Was this article helpful?

Related Cheat Sheets