How to Use Discord Webhooks for GitLab Pipeline Notifications

You want GitLab to send pipeline status updates directly into a Discord channel. Webhooks let GitLab push messages to Discord automatically when a pipeline succeeds, fails, or is blocked. This article explains how to create a Discord webhook URL, configure GitLab to use it, and customize the notification format.

What Discord Webhooks Do for GitLab Pipelines

A Discord webhook is a simple HTTP endpoint that accepts JSON data and posts it as a message in a specific channel. GitLab sends a POST request to that endpoint every time a pipeline event occurs — for example, when a pipeline starts, succeeds, fails, or is canceled.

The webhook integration requires no bot or custom code. You only need a Discord webhook URL and the GitLab project webhook settings. GitLab sends a default payload, but you can override it with a custom message using the Discord webhook format.

Before you begin, confirm you have the following:

• Manage Webhook permission in the Discord server (or ask a server admin to create the webhook)
• At least Maintainer role in the GitLab project
• GitLab pipeline already configured and running

Steps to Configure a Discord Webhook for GitLab Pipeline Notifications

Follow these steps to connect GitLab to Discord. The process has two parts: creating the webhook in Discord and adding it to GitLab.

Create a Webhook in Discord

1. Open Server Settings
   Right-click the Discord server name in the channel list and select Server Settings. If you do not see this option, you lack the Manage Server permission.
2. Go to Integrations
   In the left sidebar, click Integrations. Then click the Webhooks tab if it is not already selected.
3. Create a new webhook
   Click the Create Webhook button. A new webhook entry appears.
4. Name the webhook and select a channel
   Give the webhook a name such as “GitLab Pipeline Notifications.” Choose the Discord channel where you want messages to appear. You can also change the avatar by clicking the default icon.
5. Copy the webhook URL
   Click the Copy Webhook URL button. Store this URL securely — anyone with this URL can post messages to the selected channel.
6. Save changes
   Click Save to confirm the webhook.

Add the Webhook to GitLab

1. Open GitLab project settings
   Go to your GitLab project, then navigate to Settings > Webhooks in the left sidebar.
2. Paste the Discord webhook URL
   In the URL field, paste the webhook URL you copied from Discord.
3. Set the trigger events
   Under Trigger, check at least the following events:
   – Pipeline events
   – Job events (optional, for per-job notifications)
4. Enable SSL verification
   Leave Enable SSL verification checked. Discord requires HTTPS connections.
5. Add a custom webhook name (optional)
   In the Description field, type a label like “Discord pipeline alerts” for your own reference.
6. Test the webhook
   Click the Test button and select Push events or Pipeline events. GitLab sends a test payload to Discord. If the test fails, check that the URL is correct and that the channel still exists.
7. Save the webhook
   Click Add webhook. The webhook appears in the list with a green checkmark if it is active.

Customizing the Notification Message

GitLab sends a default JSON payload that Discord interprets as a simple text message. To display rich embeds with pipeline status, commit details, and branch names, you must create a custom payload using Discord’s webhook format.

GitLab allows you to override the payload with a custom JSON body. Go to Settings > Webhooks, click Edit on your webhook, and expand the Custom webhook template section. Paste a JSON object that follows the Discord embed structure.

Here is an example custom payload for a pipeline notification:

{
  "embeds": [{
    "title": "Pipeline #{object_attributes.id}",
    "url": "${object_attributes.url}",
    "color": "${object_attributes.status == 'success' ? 3066993 : 15158332}",
    "fields": [
      {"name": "Project", "value": "${project.path_with_namespace}", "inline": true},
      {"name": "Branch", "value": "${object_attributes.ref}", "inline": true},
      {"name": "Status", "value": "${object_attributes.status}", "inline": true},
      {"name": "Commit", "value": "${commit.message}"}
    ],
    "timestamp": "${object_attributes.created_at}"
  }]
}

The variables inside ${} are GitLab placeholders that are replaced with real data at runtime. You can use any variable from the GitLab webhook payload — the full list is in GitLab’s webhook events documentation.

To test your custom payload, click the Test button and select Pipeline events. Check the Discord channel to see if the embed appears correctly. Adjust the JSON syntax if the message is empty or shows raw text.

Common Issues and How to Avoid Them

Webhook Test Succeeds but Pipeline Events Do Not Send

If the manual test works but real pipeline events do not trigger, the webhook URL may be correct but the pipeline events are not being generated. Verify that your GitLab CI/CD pipeline actually runs. Also check that you selected Pipeline events under Trigger, not just Push events. Go to Settings > Webhooks, click Edit on your webhook, and confirm the checkboxes.

Discord Shows Raw JSON Instead of an Embed

This happens when the custom payload is invalid JSON or does not follow Discord’s embed structure. Use a JSON validator to check the syntax. Common mistakes include missing commas, double quotes inside the JSON, or using single quotes instead of double quotes. Copy the example payload above and replace only the variable placeholders.

Webhook URL Changes After Server Settings Are Modified

Discord webhook URLs remain stable unless the webhook is deleted or the server owner regenerates the URL. If you delete and recreate a webhook, you must update the URL in GitLab. To avoid downtime, keep the old webhook active while testing a new one, then remove the old webhook after confirming the new one works.

Discord Webhook vs GitLab Native Notifications

Feature	Discord Webhook	GitLab Email Notification
Setup complexity	Requires webhook URL and GitLab webhook config	Built into GitLab, uses user email preferences
Message format	Rich embeds with custom fields, colors, and mentions	Plain text email
Delivery speed	Near real-time	Depends on email server latency
Channel targeting	Posts to a single Discord channel per webhook	Delivered to individual email inboxes
Customization	Full control via JSON payload	Limited to GitLab notification templates

You can now send GitLab pipeline status updates to any Discord channel using webhooks. Start by creating a webhook in Discord, then configure it in GitLab under Settings > Webhooks. For richer notifications, replace the default payload with a custom JSON embed that shows pipeline ID, branch, status, and commit details. As an advanced step, use GitLab CI/CD variables to dynamically set the webhook URL for different environments such as staging and production.