Creating a Javascript GitHub Action to Notify Slack

Alejandro González
Jan 18 · 4 min read
https://lab.github.com/githubtraining/github-actions:-writing-javascript-actions

When using a repository, it is helpful to know the status of the executed jobs. In our organization, we want to send this information to our communication tool (Slack). We achieve this by using GitHub Actions.

The GitHub documentation defines actions as follows:

GitHub actions are individual tasks that you can combine to create jobs and customize your workflow. You can create your own actions or use and customize actions shared by the GitHub community. (About Actions — GitHub Docs)

There are already actions created by the community. So, why would we want to implement them again?

When we needed the action, what we found in the marketplace didn’t meet our requirements. By creating our custom action we ensure two things: first, the information posted to Slack is exactly what we want and sensitive data is treated properly. Second, we can optimize the action to be the most performant for our use case.

Types of Actions

There are three types of actions: Docker container actions, JavaScript actions and Composite run steps actions.

Docker-based actions run GitHub Actions code inside Docker containers. This allows using specific versions of an operating system, dependencies and tools. This is an ideal option for actions that must run in a specific environment.

JavaScript actions can run directly on a GitHub runner. To ensure JavaScript actions are compatible with all GitHub runners, the code should be pure JavaScript.

Composite run steps actions allow you to combine many workflow run steps in one action. You can use this feature to bundle together many run commands into an Action.

Why did we chose a JavaScript Action?

We chose JavaScript instead of Docker container actions for the following advantages:

  • Docker container Actions must build the container on each run, which is time consuming. JavaScript Actions can run directly.
  • Docker container actions must use a Linux runner while JavaScript actions can be executed in any runner.

Likewise, there are also some drawbacks of using JavaScript Actions:

  • When using JavaScript actions, you are restricted to use just JavaScript. Docker container actions allow you to use any language or tool.
  • If you use libraries, you must include them in the repository (although not having to download the dependencies every time is what makes it faster).

First Version

A JavaScript GitHub Action has (at least) the following files:

  • action.yml: Metadata file to define the inputs, outputs and main entry point for your action. The .yaml extension is also valid for this file.
  • index.js: This file defines the behaviour of the action. In this case, a notification is sent to Slack with information about the GitHub event.

The code above sends a message to Slack indicating whether the GitHub event has been a success or a failure with its associated colour. The message is sent with the standard fetch method (using the node-fetch library), and structured using the Slack blocks API. In another of my stories, you can find a detailed explanation about the structure of the message and the fetch call.

To get the necessary information about the GitHub event, we use the Actions toolkit. The Actions toolkit is a collection of Node.js packages that help us to build JavaScript actions. In this case, we use the core package to get the action’s inputs.

Test the Action

To test the action we add a new workflow in the .github/workflows folder.

The action uses the following inputs:

  • job-status: Gets its value from the job object. This object contains information about the currently executing job.
  • channel: Slack channel name. Defined by the user.
  • slack-bot-token: Slack App Token. Provided using GitHub secrets.

Once the action has been defined and the workflow created, each time an event occurs in the repository, two notifications will be sent. One for success and one for failure. This way, we check that the notification works for both cases.

Failure and success messages.

The Complete Action

The action above barely provides any information about the GitHub event. For our organization, we have created a more complete action.

This version customizes the message according to three types of events: push, pull request and manual triggers. Most of the information about the event is collected using the event input and the Toolkit @actions/github package. event input gets its value from the github object, which contains information about the workflow run. The github package also provides an authenticated Octokit REST client that gives access to the GitHub API.

To get all the pull request information that we need, we use two different methods. Using the action’s inputs we get the names of the Pull Request’s related branches. Next, by using the Octokit REST client, we get the name of the Pull Request.

To use the Octokit REST client, you need a valid GitHub token. GitHub creates this token and stores it as a secret. To use it, you must reference it in your workflow file as an input.

With these improvements and properly structuring the message, we get notifications tailored to our needs.

Summing Up

By creating the action ourselves, we can customize it and adapt it to the specific uses of our organization. If one day we need to change the information, it will be easier than with a third party action.

Trabe

We are a development studio.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store