Important

circusdev maintains this fork of toshimaru/backlog-pr-link-action. Toshimaru archived the upstream project after v2.4.0. Use circusdev/backlog-pr-link-action for future fixes and releases.

backlog-pr-link-action

GitHub Actions: Link GitHub Pull Request to Backlog issue.

Prerequisite

• Backlog Premium plan (ref. Backlog Pricing)
• Create custom field named "Pull Request" in Backlog issue

Usage

# .github/workflows/backlog-pr-link.yml
name: 'Link PR to Backlog'

on:
  pull_request:
    types: [opened, edited]

jobs:
  backlog-pr-link:
    runs-on: ubuntu-latest
    steps:
      - uses: circusdev/backlog-pr-link-action@v2.5.0
        with:
          backlog-api-key: "${{ secrets.BACKLOG_API_KEY }}"
          backlog-host: "your-org.backlog.com"
          pr-link-template: "[{prTitle}]({link})"

Versioning and releases

Use circusdev/backlog-pr-link-action@v2 to receive compatible v2 updates. Pin @vX.Y.Z or a commit SHA when you need an immutable reference.

Release tags such as v2.5.0 are not moved after publication. The v2 major tag tracks the latest compatible v2 release.

Release PRs are managed by release-please. The release workflow builds and commits dist/ on release-please PRs, so normal pull requests should not edit dist/ directly. If this repository adds branch protection or required checks for release PRs, revisit whether release automation needs a GitHub App token or PAT instead of the default GITHUB_TOKEN.

Pull request link template

By default, this action writes a Markdown link to Backlog:

[Pull request title](https://github.com/owner/repo/pull/1)

Customize pr-link-template if you want another value. Set it to {link} to keep the URL-only behavior.

with:
  backlog-api-key: "${{ secrets.BACKLOG_API_KEY }}"
  backlog-host: "your-org.backlog.com"
  pr-link-template: "{link}"

Available placeholders:

Placeholder	Value
{prTitle}	Pull request title escaped for Markdown; falls back to the PR URL
{rawPrTitle}	Pull request title with whitespace normalized
{link}	Pull request URL

pr-link-template must include {link} and must be a single line. If your template renders Markdown, prefer {prTitle}. {rawPrTitle} writes the title as-is.

Tip

Avoiding unnecessary runs

If the pull request doesn't contain a Backlog URL, there's no need to run this action.

To avoid this situation, you can skip the job by using an if expression as follows:

# Run the job only when the pull request contains a Backlog URL
jobs:
  backlog-pr-link:
    runs-on: ubuntu-latest
    if: contains(github.event.pull_request.body, 'https://yourhost.backlog.com/')
    steps:
      - ...

How it works

• Check the pull request has a Backlog issue URL when it's opened or edited
• If it has the URL, link GitHub PR to Backlog issue

Setup

1. Create a custom field named Pull Request

• Custom Field: Pull Request
• Custom Field Type: Sentence

Image: Create a custom field

Reference

• [English] Setting Custom fields - Backlog Enterprise
• [Japanese] カスタム属性の設定方法 – Backlog ヘルプセンター

2. Generate Backlog API key

• Go to Backlog API Settings page
• Generate API key for the action

Image: Generate Backlog API key

Reference

• [English] API Settings – Backlog Help Center
• [Japanese] APIの設定 – Backlog ヘルプセンター

3. Set API key to GitHub Secret

• Go to GitHub Actions secrets page
• Add GitHub Repository secret
  • secret name: BACKLOG_API_KEY
  • secret value: {your-backlog-api-key}

Image: Set API key to GitHub Secret

Reference

• Encrypted secrets - GitHub Docs