Create a GitHub Bot for the new Issues Project beta with Boomerang Flow

GitHub recently launched a beta of the new Issues Project Planning and it is pretty amazing. However, as always, there is a lot you will want to automate including making sure all new issues get added to your project board.

Enter Boomerang Flow, a no-code workflow editor with a visually beautiful drag and drop interface. In a previous post, I walked through sending a CloudEvent from GitHub to Boomerang Flow using GitHub Actions and we will build on this to trigger our new Bot using the Boomerang Action

Your Workflow Automation (a.k.a your Bot)

For this step, I used Flowabl, a managed instance of Boomerang Flow with a free tier, out of ease and simplicity. However, as Boomerang Flow is 100% open source you can also run your own.

One thing to note, as the new GitHub Issues Projects are in beta we rely on the GitHub GraphQL API under the covers. For you as an end-user, you will be able to just drag and drop the task onto the designer.

1. Navigate to the Workflows screen, personal or team, and click on Add Workflow

2. Enter a creative name and choose an icon and click ‘create’

3. In the workflow designer, you want to expand the GitHub category in the left palette and select the ‘Add Issue to Project’ task.

4. Drag the lines between the Start -> Task -> End

5. Switch to the Parameters tab and create a new parameter called ‘issuedId’ and map this to an Event Payload of $.issue.node_id .

This is one of the great features of Boomerang Flow, if a Workflow receives an event, you can map the payload of the event automatically to a parameter and access that specific value.

5. Retrieve the Projects node ID that you need in the next step. It’s not easily accessible and you will need to run a curl command.

Replace the <token> <organization_name> and <project_number> in the curl command. The project number can be found in the URL of the project i.e. https://github.com/orgs/sample/projects/5

curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token <token>' \
--header 'GraphQL-Features: projects_next_graphql' \
--data '{"query":"query{organization(login: \"<organization_name>\") {projectNext(number: <project_number>){id}}}"}'

This will all return a number like PN_aaBBA12340xAA

6. Click the pencil on the task and fill in the modal. For this, you will need

• Token: a Personal Access Token with org:write scope
• Project Node ID: from above
• Issue ID: set the value to $(params.issueId) . This references the Workflow Parameter created in the prior step, which in turn is referencing a value from the GitHub Event that will trigger this workflow.

🎉 Congratulations. The workflow is now all set up!

Setting Up GitHub Actions to Trigger the Workflow

Now we need to create the GitHub Action that will send the event through to Boomerang Flow and trigger our ‘Bot’ to update the Project.

1. In your repository navigate to the Actions tab

2. Select ‘set up a workflow yourself’ or if you already have workflows you can click the ‘new workflow’ button.

3. Once the new workflow editor is loaded, in the right-hand Marketplace pane, search for Boomerang and select the Action titled ‘Boomerang Flow Run Workflow’

4. Follow the instructions to copy it into your workflow and edit as follows. I recommend using secrets for sensitive information such as the Workflow ID and Workflow Token.

name: Issue Bot
on:
  issues:
    types: [ opened ]
jobs:
  bot:
    runs-on: ubuntu-latest
    steps:
    - name: Boomerang Flow Run Workflow
      uses: boomerang-io/flow.action@v0.6.4
      with:
        # The Boomerang Flow event URL and context
        url: ${{ secrets.FLOWABL_URL }}
        # The security token as part of your workflow
        token: ${{ secrets.FLOWABL_TOKEN }}
        # The ID of the workflow you wish to execute
        workflowId: ${{ secrets.FLOWABL_WORKFLOW_ID }}
        # The custom topic entered into your worlflow configuration
        topic: NewIssue
        # The JSON payload to send with the event
        payload: ${{ toJson(github.event) }}

This will create a GitHub Action that on newly opened issues sends a CloudEvent to trigger a Boomerang Flow Workflow.

Let the magic begin

Now in the repository, you created the GitHub Action in, create a GitHub Issue.

You can check on its progress in two places

1. Under the Actions tab, you should have seen the Action go through and send a CloudEvent to Boomerang Flow

2. In Boomerang Flow you should have seen the Activity generate and be able to dive into the detail

Next Steps

There are really exciting and powerful workflow features that you can use to extend and enhance GitHub Issues with Boomerang Flow. You could;

• Review the contents of the issue and assign them to different projects based on the content.
• Add labels to the issue as appropriate
• Ensure there are assignees on the Issue
• Alert the maintainers of items that need triage using the Boomerang Flow Actions

Show your support

Thanks for reading! If you made it this far, show your support if this helped you:
- ⭐️ the GitHub project
- 💬 Follow Tyson (the author) and Boomerang on Twitter
- ☁️ Install the project on your own Kubernetes cluster
- 🙏 Join us and help contribute

✨ A special thanks to Flowabl for providing a free tier for a managed instance of Boomerang Flow.