Anatomy of a workflow: Deep dive into our Github issues to Slack template
Contents
Introduction
Trigger.dev makes it easy to create workflows in code.
This workflow allows you to receive real-time updates from GitHub to Slack. This is useful for keeping track of any issues raised in your repositories. As an open source platform this is especially important to us, and we use this workflow internally to keep track of any issues raised in our repos.
Can’t I just make this myself?
Kind of.
You can create alerts from GitHub to Slack using Slack’s webhooks system. This requires some technical knowledge and much more setup time, with a limited scope of events to choose from. You have no control over how the events appear in your Slack channel, and no way of interacting back and forth between the services.
So why would I use Trigger.dev?
Our GitHub and Slack integrations mean setup, authentication and customization becomes trivial. With our 5 minute installation you can create a fully customizable workflow directly in code. We also give you access to a much larger range of events and much richer Slack messages using the Slack Block Kit (which is awesome). You can then customize and extend the workflow to fit your needs.
Installation and setup in 5 minutes using Trigger.dev
In this example I will show you how to create a brand new project using our template.
To start, simply navigate to our templates page, and select the Post to Slack when a GitHub issue is created or modified template.
Grab this code and run it in your terminal of choice to create a new GitHub issues to Slack project using this template.
npx [email protected] github-issues-to-slack
Follow the steps in our CLI, adding your development API key from your account if want to use a specific organization. Use your development key for local development, and live for production:
Then change directory to the new folder you just made.
You now have a project you can test. Navigate to index.ts , and update "triggerdotdev/github-issues-to-slack"; to a repo of your choice, and either create a new Slack channel called “github-issues” in your workspace, or update channelName: "github-issues" to another channel you would like to use. It’s that simple.
import { Trigger } from "@trigger.dev/sdk";
import * as github from "@trigger.dev/github";
import * as slack from "@trigger.dev/slack";
// Change "triggerdotdev/github-issues-to-slack" to the repo you want to track e.g. "yourorg/yourrepo"
const repo =
process.env.GITHUB_REPOSITORY ?? "triggerdotdev/github-issues-to-slack";
new Trigger({
// Give your Trigger a stable ID
id: "github-issues-to-slack",
name: "Posts to Slack when a GitHub Issue is created or modified",
// This will register a webhook with the repo
// and trigger whenever a new issue is created or modified
on: github.events.issueEvent({
repo,
}),
// The run function will get called once per "issue" event
// See https://docs.trigger.dev/integrations/apis/github/events/issues
run: async (event, ctx) => {
// Posts a new message to the "github-issues" slack channel.
// See https://docs.trigger.dev/integrations/apis/slack/actions/post-message
// If the channel is private, you'll need to add the Trigger.dev bot to the channel first.
const response = await slack.postMessage("send-to-slack", {
channelName: "github-issues",
// If you include blocks, this text will be used in any notifications.
text: `GitHub issue, *${event.issue.title}* has been *${event.action}*. `,
// Blocks allow you to create richly formatted messages.
// See https://api.slack.com/tools/block-kit-builder
blocks: [
{
type: "section",
text: {
type: "mrkdwn",
text: `GitHub issue, *${event.issue.title}* has been *${event.action}*.`,
},
accessory: {
type: "button",
text: {
type: "plain_text",
text: "View Issue",
emoji: true,
},
value: "View Issue",
url: event.issue.html_url,
action_id: "button-action",
},
},
],
});
},
}).listen();
Once you’re happy with the repo and Slack channel names, use the command npm run dev , and you should get a message in the console with a link to your dashboard:
Tap 'View on dashboard' and you’ll be taken to our web app, where you will see a new workflow.
As you can see, there is a warning symbol next to the GitHub logo. This is because you haven’t authenticated GitHub for this organisation yet. To do this, simply click on the workflow, and click the ‘Connect to GitHub’ button.
A window will pop asking you to authorize GitHub access. Once authorized, you can try your workflow. Navigate to your specified GitHub repo, and create or update an issue:
Once you have done that, refresh your workflow overview page and you will see your workflow run update. The workflow should have tried to post the update to Slack, but it does not have Slack authentication yet.
To authenticate, simply click the ‘Connect to Slack’ button, choose your workspace, and you will be authenticated 🔥:
Once connected, the workflow will run immediately, and voila 🧑🍳💋 - an issue has been created and posted to Slack!
Now for the fun part...
Customizing a workflow template
After successfully running your workflow, you can either update your API key to live and deploy your workflow using Render or another service (our cloud offering is coming soon!). Or you can dive into customization 🦄!
Customizing the data received from the GitHub API
In our template, the name of the issue, “A test issue”, and its status, “opened”, are shown. The code for this is, *${event.issue.title}* and *${event.action}*:
text: `GitHub issue, *${event.issue.title}* has been *${event.action}*. `,
NB: Wrapping the code in * symbols here means that this text is bold. Slack uses a special version of markdown called mrkdown which we will be using.
These are just two of the possible properties you can access from the GitHub API. You can use any of the fields provided by GitHub for a specific event or action and simply add them to your workflow.
Other available variables
As well as Issue Comments, there are plenty of other fields that are easily accessible from the GitHub integration. Here are some examples of the types of information you can access:
- Issues: When an issue is opened, closed or edited.
- New Star: When someone stars your repo.
- PR Review Comments: When comments are added or changed on a pull request review.
- PR Reviews: When a pull request is reviewed or commented on.
- Pull Requests: When a pull request is opened, closed, merged or edited.
- Pushes: When code is pushed to a repo.
By mixing and matching these fields, you can get the exact information you need from actions and events in your GitHub repos.
Slack - customizing the channel
In the template the GitHub issue and action are posted to the public “send-to-slack” channel. This can of course be changed to any channel you wish. If the channel is private all you need to do is add the Trigger.dev bot to the channel for it to work.
// Posts a new message to the "github-issues" slack channel.
// See https://docs.trigger.dev/integrations/apis/slack/actions/post-message
// If the channel is private, you'll need to add the Trigger.dev bot to the channel first.
const response = await slack.postMessage("send-to-slack",
Customizing the Slack message with the Slack Block Kit
We support rich Slack messages, and strongly encourage our users to create rich and interactive Slack messages in their workflows.
To do this, the best way is to build blocks using the Slack Block Kit builder, and then copy the code to use in your workflow.
The block kit builder can be used to create interactive messages and notifications that allow users to take actions directly from Slack, such as merging pull requests or resolving issues.
We recommend starting with a template and then customizing it depending on your use case. It is easy to create a rich Slack post your team can easily pick up.
This can be really useful if you want to create workflows like a ticket triaging system, or a simple CRON job which posts to a specific Slack channel with a status report once a day, etc.
Customizing the Slack message using the Slack API
In this example we have added more detail: it is a Slack message with issue number, issue title, comment and whether it has been created / modified.
The code:
const response = await slack.postMessage("send-to-slack", {
channelName: "github-issues",
// If you include blocks, this text will be used in any notifications.
text: `GitHub issue #*${event.issue.number}* , *${event.issue.title}* with the comment *${event.issue.body}* has been *${event.action}*.`,
// Blocks allow you to create richly formatted messages.
// See https://api.slack.com/tools/block-kit-builder
blocks: [
{
type: "section",
text: {
type: "mrkdwn",
text: `GitHub issue #*${event.issue.number}*, *${event.issue.title}* with the comment *${event.issue.body}* has been *${event.action}*.`,
},
accessory: {
type: "button",
text: {
type: "plain_text",
text: "View Issue",
emoji: true,
},
value: "View Issue",
url: event.issue.html_url,
action_id: "button-action",
},
},
],
});
But that's just the tip of the iceberg. If you want to make the block even better, you can! In this example you have the issue information as well as information about the user who created the issue, including their username, profile picture and a link to their profile:
The code:
const response = await slack.postMessage("send-to-slack", {
channelName: "github-issues",
// If you include blocks, this text will be used in any notifications.
text: `⚠️ GitHub issue #*${event.issue.number}*, *${event.issue.title}* "_${event.issue.body}_" has been created by ${event.issue.user.login}.`,
// Blocks allow you to create richly formatted messages.
// See https://api.slack.com/tools/block-kit-builder
blocks: [
{
type: "section",
text: {
type: "mrkdwn",
text: `⚠️ GitHub issue #*${event.issue.number}*, *${event.issue.title}*\n "_${event.issue.body}_" \n has been created by ${event.issue.user.login}.`,
},
accessory: {
type: "image",
image_url: event.issue.user.avatar_url,
alt_text: "User Avatar",
},
},
{
type: "divider",
},
{
type: "actions",
elements: [
{
type: "button",
text: {
type: "plain_text",
text: "View issue",
emoji: true,
},
value: "View issue",
url: event.issue.html_url,
},
{
type: "button",
text: {
type: "plain_text",
text: "View user profile",
emoji: true,
},
value: "View user profile",
url: event.issue.user.html_url,
},
],
},
],
});
},
These are just a couple of ways of spicing up your Slack posts. Keep experimenting and let the community know if you come up with anything cool.
Workflow inspiration
There are many different workflows you could create using using our Slack and GitHub integrations. here are some other examples:
- Send a message to a Slack channel when a pull request is opened or closed in a GitHub repository.
- Send a notification to a Slack channel when a new branch is created in a GitHub repository.
- Post a message in a Slack channel when a pull request is approved or merged in a GitHub repository.
- Send a notification to a Slack channel when a GitHub repository's code is changed by a specific user.
- Post a message in a Slack channel when a GitHub repository's code review is requested.
Get in touch!
We are always happy to help our users build any workflow they need. If you would like help building a workflow using our Slack / GitHub integrations please either book a meeting with us here:
Call us about a workflow you'd like to build
or use our workflow request form here:
We hope you enjoyed this post and we look forward to seeing what you build with our Slack and GitHub integrations!