Backlog GitHub integration action

We made a custom GitHub action to integrate with Nulab's Backlog via GitHub events.

Backlog is nice to look and feel and easy to use for us. However, for some reason, it doesn't support GitHub integration. Our company uses repositories on the GitHub platform. So, GitHub integration has a profound effect on productivity.

Fortunately, GitHub provides an integration service named GitHub Actions. That makes various workflows via GitHub events, e.g.) making a Pull Request. Also, Nulab provides Backlog REST API. So It means we can achieve everything we want to do with GitHub Actions and Backlog REST API.

Repositories

The repository is here.

github.com/kazamori/backlog-github-integrat..

You can see the test repository and how it works for a quick look.

github.com/kazamori/test-gh-actions-repo

Usage

You must configure some tasks to use backlog-github-integration-action (referred to as "the custom action"). We explain them step by step.

Set Secrets for Backlog

Generate a new API Key for the custom action

Backlog doesn't provide any integration user accounts, we think. So, you may create a new user for integration use only on Backlog. In this article, we made an integration user named "lobster". A developer logs into lobster and generates API Key.

Configure Actoins secrets

Then, you create new Actions secrets in your GitHub repository. For example, Backlog API Key would be put into BACKLOG_API_KEY. Additionally, you have to set 2 secrets for Backlog: BACKLOG_FQDN and BACKLOG_PROJECT_KEY.

BACKLOG_FQDN="YOUR-SPACE.backlog.com"
BACKLOG_API_KEY="..."
BACKLOG_PROJECT_KEY="TEST"

See Encrypted secrets for more detail.

Create a workflow for a pull request in your repository.

Create .github/workflows/pull_request.yml. This is a trivial example.

name: Pull request

on:
  pull_request:
    types:
      - opened

jobs:
  pr-integration:
    runs-on: ubuntu-latest
    steps:
      - name: integrate the pull request with backlog
        if: ${{ github.event_name == 'pull_request' && github.event.action == 'opened' }}
        uses: kazamori/backlog-github-integration-action@main
        with:
          subcommand: "pull_request"
          args: "--repository ${{ github.repository }} --pr-number ${{ github.event.number }}"
        env:
          APP_LOCALE: "en_US"
          APP_LOG_LEVEL: "debug"
          BACKLOG_FQDN: ${{ secrets.BACKLOG_FQDN }}
          BACKLOG_API_KEY: ${{ secrets.BACKLOG_API_KEY }}
          BACKLOG_PROJECT_KEY: ${{ secrets.BACKLOG_PROJECT_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Confirm the custom action run

Create a branch, commit/push some changes, and create a new Pull Request. The custom actions will work if all configurations are valid.

You can see an actual example of our test repository to run workflows on GitHub actions.

github.com/kazamori/test-gh-actions-repo/ac..

After these workflows run, a user of BACKLOG_API_KEY will write the Description field and the issue comments. In the case of our test repository, lobster behaves them.

The link information would be below the previous Pull Request link when another Pull Request is made.

Conclusion

As you can see, our custom action is easy to use. Currently, the feature is Pull Request only.

But, we can provide more features depending on the developer's needs. We welcome to discuss them on our repository.

Edit 2022-04-30

Add a new feature: Commit integration.

Commits integrate with Backlog issue