Repositories

The repository is here.

• https://github.com/kazamori/backlog-github-integration-action

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

• https://github.com/kazamori/test-gh-actions-repo

Usage

Here we show only workflow YAML configuration. See the previous post if you need the entire configuration for a newbie to GitHub actions.

This workflow is including two features via pull_request event and push event. I guess that a user who is interested in our custom action wants to use both. We recommend making an independent workflow file since it's easy to maintain: what the workflow is and add/update a feature/configuration.

name: Backlog integration

on:
  pull_request:
    types:
      - opened
  push:
    branches:
      - main

jobs:
  backlog-integration:
    runs-on: ubuntu-latest
    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 }}
    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 }}"

      - name: integrate commits with backlog
        if: ${{ github.event_name == 'push' }}
        uses: kazamori/backlog-github-integration-action@main
        with:
          subcommand: "push"
          args: "--repository ${{ github.repository }} --pusher ${{ github.event.pusher.name }} --commits '${{ toJson(github.event.commits) }}'"

Commits integration is triggered by push event. After this workflow run, a user of BACKLOG_API_KEY will comment and can change the issue status by commits.

It's helpful to change the backlog issue status by a commit message.

• fix, fixes, fixed -> Resolved
• close, closes, closed -> Closed

For example, you can change the issue status like this.

fix TEST-1

closed TEST-1

Conclusion

As you can see, our custom action is easy to use. There are only a few features, though.

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

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.

• https://github.com/kazamori/backlog-github-integration-action

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

• https://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.

• https://github.com/kazamori/test-gh-actions-repo/actions

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