Discord Webhook Notify

This sends a notification to discord using a webhook URL. It is written in JavaScript (ES) using the discord.js NPM package, so it will work with Windows, OS X, and Linux execution environments and anything else that runs NodeJS.

Status

Setup Instructions

Using this action involves the following steps, which assume you already have a Discord "server".

Create a Webhook on Discord

Login to Discord and create a new webhook. Assuming you have admin privileges for the server/channel, you can do this in Channel Settings or Server Settings, in both cases under the Integrations section. The webhook URL will look like a long URL with a big random-looking authentication token embedded in it. (This is what needs to be kept secret, otherwise anyone who gets it can endlessly spam the associated Discord channel.)

There is some Discord documentation about webhooks here. Note that webhooks do not require a Discord developer account. They are a simple, low-effort means of integration that doesn't require creating a Discord app or bot.

Add webhook URL to repository secrets

One you have generated a webhook url, use the GitHub web UI to add it to your repository.

Go into the Settings tab of your repo.
In the Settings tab page for a repository, select Secrets and variables->Actions on the left sidebar.
In the lower-right panel, select New repository secret. Make sure to use this and not something else like a repository variable.
Add a new Secret with the name DISCORD_WEBHOOK (or anything memorable) and the webhook URL as the value.

For more detail, including how to do this from the gh CLI tool, see the full documentation on adding repository secrets for GitHub Actions.

Add the action to workflow YAML

In your workflow YAML, set webhookUrl as follows: webhookUrl: ${{ secrets.DISCORD_WEBHOOK }}. If you used a different name, just use that name in place of DISCORD_WEBHOOK. (See full YAML examples below.)

You must set webhookUrl this way for each invocation of the action, because secrets are not passed to anything by default, only as parameters.

Version Usage Suggestions

I can't guarantee that any problems with this action will get fixed very quickly if there's an API-breaking change.
Because of this, consider forking this repo and referring to the action using your fork.
If you don't want to fork until necessary:
- Use rjstone/discord-webhook-notify@v2.x.x (or another specific tag after the @) if you want to guarantee use of a specific revision.
- Use rjstone/discord-webhook-notify@v2 if you want updates but nothing that should be backward-compatibility breaking. (If anything breaks compatibility it will be in v3+.)
- Don't use any v1.x.x as these have been broken by various changes over time and will no longer work properly.

Inputs

See the action.yml file for more exact details, and also see examples below this, but here's a quick summary.

`webhookUrl`

The webhook URL to use. This should be in a repository secret and the secret should be included here using ${{ secrets.DISCORD_WEBHOOK }} where DISCORD_WEBHOOK is whatever you named the secret.

`username`

"Username" to display in Discord for this notification. Not required since there's an identifiable default, but setting this is strongly suggested.

`avatarUrl`

URL to png of discord avatar to use. A basic default is provided, but setting this is strongly suggested. See the Discord documentation for image sizes and restrictions. If Discord doesn't like the image file or the URL for some reason then this will be silently ignored.

`content` / `text`

String to display as normal chat text after the username and above everything else. This may contain Discord style markdown and is otherwise the equivalent of whatever a user types as a normal chat message. There is a 2000 "character" (which might actually mean bytes, it isn't clear) limit.

content is the Discord API name for this field. text is a legacy alias kept for backward compatibility. If both are set, content wins and text is ignored (a warning is logged).

`flags`

A whitespace-separated list of MessageFlags. Supported values:

SuppressNotifications — prevent the message from triggering a "bleep" or other attention-grabbing attempt when received by the client
SuppressEmbeds — suppress automatic embeds (e.g. link previews)
IsComponentsV2 — opt into Discord Components V2 layout (only needed if you are using the newer component system via the raw components input)

Embed

Discord allows an "embed" in messages which looks sort of like an attachment. It doesn't actually have to contain images or links, but it has some properties for different elements.

The following settings are optional and are shortcuts for displaying information as an "embed".

`severity`

By default, embeds are used to express severity information. This is the severity level of the notification, either info, warn, error, or none. If none is specified then no embed will be added. If another option is specified then it will be used to set the defaults for fields in the embed. (You can still override these defaults though.)

`color`

Color of the gutter bar on the left side of the "embed" section, in the form #rrggbb (hex). Default determined by severity.

`title`

Title for the embed. Defaults to severity long terminology.

`thumbnailUrl`

URL of a small thumbnail image shown on the right side of the severity/easy embed. Default is no thumbnail.

`imageUrl`

URL of a large image attached to the severity/easy embed. Default is no image.

`description`

The first half of the text body of the embed. This defaults to showing only a few pieces of information from the context/environment, like the workflow name. (It used to show more but I got tired of keeping up with the API.) Override this if you do not want the default selection of information here. Note that this input may also contain Discord style markdown.

`details`

The second half of the text body of the embed. If you DO want the default information in description then just don't specify a description, and then specify additional details to append to the embed body using this details input. details defaults to empty, so if you specify a description then this input can just be ignored. Like description it can also contain Discord style markdown.

`footer`

String to display in the "footer" section of the embed. This defaults to showing the severity level.

`embeds` (experimental)

A string containing a YAML or JSON array of raw Discord embed objects. Because GitHub Actions inputs are strings, pass YAML with | or minified JSON. JSON is tried first, then YAML. Up to 10 embeds are sent (Discord's limit); extra entries are truncated with a warning.

If severity is not none, the generated "easy" embed is prepended to this list. See the Discord embed object docs.

Example (YAML):

  - name: Multi-embed notify
    uses: rjstone/discord-webhook-notify@v2
    with:
      webhookUrl: ${{ secrets.DISCORD_WEBHOOK }}
      embeds: |
        - title: First embed
          description: Hello
          color: 5814783
        - title: Second embed
          description: World

`components` (experimental)

A string containing a YAML or JSON array of raw Discord message components, passed through to the API with no validation. Not all component types work on webhooks (there is no bot/app to handle interactions). Link buttons in action rows are the usual safe choice. Use | for multi-line YAML.

See Discord message components.

Example (link button):

  - name: Notify with link button
    uses: rjstone/discord-webhook-notify@v2
    with:
      webhookUrl: ${{ secrets.DISCORD_WEBHOOK }}
      content: Build finished — open the run:
      components: |
        - type: 1
          components:
            - type: 2
              style: 5
              label: View run
              url: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}

"Advanced" Settings

These are usually not needed but could be useful for solving specific issues.

`processingOptions`

(experimental) Set to "percentDecode" if you want some inputs that are often multi-line strings to be run through "percent decoding" using decodeURIComponent(). This can be useful in cases where the output from another action should contain newlines, but won't be preserved by the Workflow system if it does. Right now, this is the only optional input processing.

`holddownTime`

If a webhook is called too soon after a previous webhook call, Discord's server API will return a rate limit exceeded error. This doesn't necessarily work exactly according to Discord's documentation because GitHub runners seem to use shared IP addresses, and also the rate limit is dynamic. However, a delay of 2-3 seconds (default) since the last webhook HTTP requests seems to usually be good enough. If for some reason it isn't you can increase this wait time.

`lockfileDir`

The directory where the lockfile used for saving last run time is stored. Default to the current directory but you can change it if it is in the way.

Example usage

Simple Usage Example

GitHub Actions are used in GitHub Workflows as a type of Step inside of a Job.

You can create notification for whatever if: conditions you want. There's no built-in handling based on reading the environment so you can run the action or skip it using any if: expression.

The following examples would go under jobs.<job_id>.steps (which is omitted in the examples to shorten them).

Using lots of defaults (not recommended), but still adding a message in the embed:

  - name: Test Success
    uses: rjstone/discord-webhook-notify@v2
    if: success()
    with:
        webhookUrl: ${{ secrets.DISCORD_WEBHOOK }}
        severity: info
        details: All tests passed!

Without any embed (content is preferred; text is still accepted as an alias):

  - name: Text Notify
    uses: rjstone/discord-webhook-notify@v2
    with:
      webhookUrl: ${{ secrets.DISCORD_WEBHOOK }}
      username: AwesomeSauce GitHub Repo Build Process
      avatarUrl: https://<some awesome domain>/<some awesome>.png
      content: |
          This is a text-only notification.
          * But it can contain (Discord) Markdown.

Minimal Full Custom Example

Something more fully customized, including optional thumbnail/image on the severity embed:

  - name: Test Custom
    uses: rjstone/discord-webhook-notify@v2
    with:
      webhookUrl: ${{ secrets.DISCORD_WEBHOOK }}
      username: Custom Bot Username
      avatarUrl: https://domain/images/custom.png
      content: Below this normal-looking message is an embed!
      severity: info # only to make sure the embed is added
      color: '#ff00aa'
      title: My Fancy Embed Title
      description: "This is a ***SuPeR custom*** description. I hope it looks good."
      # details: not needed because we overrode default description.
      footer: This embed was brought to you by the letter R and the number 4.
      thumbnailUrl: https://domain/images/thumb.png
      imageUrl: https://domain/images/banner.png

Raw embeds (experimental)

Pass a YAML (or JSON) array as a string. If severity is also set, the generated easy embed is prepended.

  - name: Multi-embed notify
    uses: rjstone/discord-webhook-notify@v2
    with:
      webhookUrl: ${{ secrets.DISCORD_WEBHOOK }}
      content: Build report
      embeds: |
        - title: Unit tests
          description: All green
          color: 5763719
        - title: Deploy
          description: Staging updated
          color: 3447003

Same thing as minified JSON (handy when the value comes from another step):

  - name: Multi-embed notify (JSON)
    uses: rjstone/discord-webhook-notify@v2
    with:
      webhookUrl: ${{ secrets.DISCORD_WEBHOOK }}
      embeds: '[{"title":"Unit tests","description":"All green","color":5763719}]'

Link button via components (experimental)

Webhook-safe pattern: an action row with a link button (style 5). Other component types often need a bot and will not work on plain webhooks.

  - name: Notify with link button
    uses: rjstone/discord-webhook-notify@v2
    with:
      webhookUrl: ${{ secrets.DISCORD_WEBHOOK }}
      content: Build finished — open the run:
      flags: SuppressNotifications
      components: |
        - type: 1
          components:
            - type: 2
              style: 5
              label: View run
              url: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}

Contributing

See CONTRIBUTING.md for development setup, branch/release notes, and PR expectations.

License

This project is licensed under the MIT License.

Name		Name	Last commit message	Last commit date
.github		.github
.vscode		.vscode
__fixtures__		__fixtures__
__tests__		__tests__
dist		dist
img		img
src		src
.gitignore		.gitignore
.node-version		.node-version
.prettierrc		.prettierrc
.yaml-lint.yml		.yaml-lint.yml
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
action.yml		action.yml
eslint.config.mjs		eslint.config.mjs
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
rollup.config.js		rollup.config.js
test.env		test.env

Latest commit

History

Folders and files

Repository files navigation

Discord Webhook Notify

Status

Setup Instructions

Create a Webhook on Discord

Add webhook URL to repository secrets

Add the action to workflow YAML

Version Usage Suggestions

Inputs

webhookUrl

username

avatarUrl

content / text

flags

Embed

severity

color

title

thumbnailUrl

imageUrl

description

details

footer

embeds (experimental)

components (experimental)

"Advanced" Settings

processingOptions

holddownTime

lockfileDir

Example usage

Simple Usage Example

Minimal Full Custom Example

Raw embeds (experimental)

Link button via components (experimental)

Contributing

License

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`webhookUrl`

`username`

`avatarUrl`

`content` / `text`

`flags`

`severity`

`color`

`title`

`thumbnailUrl`

`imageUrl`

`description`

`details`

`footer`

`embeds` (experimental)

`components` (experimental)

`processingOptions`

`holddownTime`

`lockfileDir`