Github Actions: Workflow 82 - Post Kanban board summary to team slack channel

The workflow 82-kanban-slack-update.yml was written by Ahsun Tariq as part of his research into the impact of reflection on Software Engineering Education. Phill Conrad also made contributions.

The purpose of the workflow is to provide the team with a summary of the state of the Kanban board at periodic intervals, showing the number of issues each team member has in the various columns of the Kanban board.

Installation

To install this in your project, you need to take several steps.

Step 1: Copy workflow

Copy the workflow file into your repo, in the .github/workflows directory.

Step 2: Configure Org to allow fine-grained personal access tokens

Go to the settings for the organization, and navigate to Personal Access Tokens / Settings

image

You can also use this link (editing the organization as needed):

Step 3: Create a fine-grained Personal Access Token (PAT)

Create a fine grained personal access token for the organization.

Under organizations, it should have read-only permission on projects.

Once you have the secret, keep the browser window open, since you’ll need this value in the next step, and once you navigate away from the window, the value is no longer available.

Step 4: Add Secret PAT to Organization Secrets

In a different web browser, navigate to your Organization Secrets, found here:

image

Or, use this link (editing to replace the organization):

Click New Organization Secret, and add the secret with the name PAT, and the value of the fine grained personal access token from the previous step.

Choose either All Repositories or select the repositorires to which this should be applied.

Step 5: Create a Slack bot user

To create a slack bot user, start here: https://api.slack.com/apps/

Instructions Screenshot
You’ll see this screen. Click Create New App. image
You’ll see this modal. Choose “From Scratch” image
For App Name, choose something like Kanban Board Update, and then select your Slack workspace, and click Create App image
That will take you to this screen. Now you need to look for OAuth and Permission in the left navigation image }
Click on this image
Scroll down to here image
Add these scopes: image
Then scroll back up to OAuth Tokens and click the Install button image
You’ll see a screen like this. Click Allow image
You’ll then be shown the OAuth Token value (redacted here). Leave this window open so that you can copy this value in the next step. image

Step 6: Copy OAuth token to org secrets as SLACK_BOT_USER_OAUTH_ACCESS_TOKEN

In a different web browser, navigate to your Organization Secrets, found here:

image

Or, use this link (editing to replace the organization):

Click New Organization Secret, and add the secret with the name SLACK_BOT_USER_OAUTH_ACCESS_TOKEN, and the value of the OAuth token from Slack from the previous step.

Choose either All Repositories or select the repositorires to which this should be applied.

Step 7: Update the TEAM_TO_CHANNEL environment variable

Now, you need to collect the Slack Channel Ids of each team channel. For example, if your teams are named f24-00, f24-01, f24-02`, you need to construct a JSON object that looks like this:

{ "f24-00" : "C08018C6ZUY", "f24-01" : "C07PYJKCWEL", "f24-02" : "C07P9QKLCSW" }

To obtain the channel numbers, you can right click on each team channel in Slack, and select View Channel Details:

image

The window that comes up has the channel id as the very bottom, with a widget you can click to copy it.

image

Assemble this JSON object; you’ll need it for the next step.

Step 8: Update the TEAM_TO_CHANNEL environment variable

Under the organization settings, find Secrets and Variables / Actions

image

On the page that comes up, choose the second tab, Variables:

Or, use this direct link (changing the organization name as needed):

Create a new variable called TEAM_TO_CHANNEL with the settings from the JSON object you created in the previous step.

Step 9: Update the ORG_NAME environment variable with your GitHub organization name.

Step 10: Update the END_DATE environment variable with the end date for the workflow to stop running the workflow forever.

Step 11: Update the COLUMNS environment variable with the column names in your project board.

Step 12: Update the branch name in the on section to match the branch you want to trigger the workflow on.

Step 13: Commit the changes to the main branch to trigger the workflow.

Step 14. The workflow will run and post the Kanban board status to the Slack channel associated with the team name.

Why does this only run on team repos and not legacy repos?

There is a bit of code in this workflow that’s worth explaining:

 if [[ "$OWNER" == "ucsb-cs156" ]]; then
            echo "This workflow should not run on repos in the ucsb-cs156 organization"
            echo "continue=false" >> "$GITHUB_OUTPUT"
 fi

To understand this code, some background is needed:

Long term, we maintain each of the legacy code projects in what we call “legacy code repos”

  • These are “the main repo for each project” or “the master repo for each project”—but we avoid those terms because they get confused with “main branch” or “master branch”.
  • So: we call them the legacy repos.

Those are maintained in the ucsb-cs156 organization. Examples include:

  • https://github.com/ucsb-cs156/proj-courses
  • https://github.com/ucsb-cs156/proj-dining
  • https://github.com/ucsb-cs156/proj-frontiers
  • https://github.com/ucsb-cs156/proj-rec

We use those as the starter code for the team repos, which have URLs such as these (examples are from S25):

  • https://github.com/ucsb-cs156-s25/proj-courses-s25-01
  • https://github.com/ucsb-cs156-s25/proj-courses-s25-02
  • https://github.com/ucsb-cs156-s25/proj-rec-s25-16

For workflows such as 82, the code starts out in the starter repo. For example, you can see workflow 82 in the legacy repo for dining here:

  • https://github.com/ucsb-cs156/proj-dining/blob/main/.github/workflows/82-kanban-slack-update.yml

And then it gets copied into team repos such as this one:

  • https://github.com/ucsb-cs156-s25/proj-dining-s25-08/blob/main/.github/workflows/82-kanban-slack-update.yml Same code! But different context.

In the context of the legacy repo, the code that checks the current organization kicks in, and if the organization is ucsb-cs156 the rest of the workflow is skipped.

But in the context of your team’s repo, that code does NOT kick in, so it runs.

This, along with the date restrictions, are how we keep the code when it would just be a waste of computer cycles.