【チケット管理】GitHub IssuesとTrelloを完全に連携できるライブラリを作りました

概要

開発のチケット管理を効率的に行うために、GitHub Issuesを作成したらTrelloに自動でカードが作られるGitHub Actionsライブラリを作りました。
ポイントはIssue番号・タイトル・詳細に加えて、IssuesのAssignee⇆Trelloのメンバー、IssuesのLabels⇆Trelloのラベルを完全に連携できる点です。
設定の仕方までこの記事で説明しているので、ぜひ皆さんのリポジトリにも導入して使ってもらえたらと思います！
https://github.com/jessicazu/trello-github-actions

↑この内容でSubmit new issueをすると、数秒後、↓このようにカードが作られます。

背景

開発チームにチケット駆動開発を導入したかったのですが、GitHub Issueだけだとどうも全体が可視化しづらい。
そこで使い慣れていたTrelloと連携できたら無料だし最高だな〜と。
方法としてZapier等の自動化ツールを用いても連携はできるようですが、AssigneeとLabelsまで完全に対応させることはできません。
なので最近発表されたGitHub ActionsとTrello APIを使って、自作してみました！

GitHub Actionsとは

GitHubのリポジトリ内でのイベントをトリガーに、様々なアクションができるツールです。2018年に発表されました。
https://github.co.jp/features/actions
CIとの連携に使うと便利なようですね。

導入の手順

以下の流れで導入ができます。GitHub Actionsが初めての方にもわかるように1つずつ説明します。

1. GitHubのUsernameと、Trelloメンバーのユーザー名を同一にする
2. TrelloのAPIキー、APIトークンを取得する
3. TrelloのボードID、リストIDを取得する
4. GitHubリポジトリのSecretsに、2.と3.の値を設定する
5. GitHubリポジトリの.github/workflows以下にワークフローを作成する
6. Labelsを設定する

1. GitHubのUsernameと、Trelloメンバーのユーザー名を対応させる

AssigneeとTrelloメンバーを連携するためです。連携させたいユーザーは全員行ってください。
Trello側を変更する方が、影響が少ないと思います。
まずはGitHubのUsername(プロフィールページでのhttps://github.com/<ここ>)を確認。

1. Trelloを開き、右上の自分のアイコン→設定
2. 「プロフィールと公開範囲」タブ
3. 「ユーザー名」を、自分のGitHubのUsernameに変更して保存

2. TrelloのAPIキー、APIトークンを取得する

https://trello.com/app-key
こちらのページで取得ができます。トークンは、「手動でトークンを生成できます」をクリックして認証。

3. TrelloのボードID、リストIDを取得する

1. のユーザー名と、3. で取得したキーとトークンを用います。

ボードID取得

GETで以下にアクセス。
https://trello.com/1/members/<ユーザー名>/boards?key=<キー>&token=<トークン>&fields=name
この結果から、用いるボードを選んでそのIDをコピーしてください。

リストID取得

GETで以下にアクセス。
https://trello.com/1/boards/<↑のボードID>/lists?key=<キー>&token=<トークン>&fields=name
この結果から、カードを作成するリストを選んでそのIDをコピーしてください。
僕の場合はTo Doのリストを使っています。

4. GitHubリポジトリのSecretsに、2.と3.の値を設定する

連携させるリポジトリのSettingsから、SecretsにTrelloの情報を設定します。
Secretsはセキュアな環境変数で、ログ等にも表示されないようになっていて安心。

管理者でないと、Settingsは表示されないと思います。
名前は任意で良いのですが、キー、トークン、ボードID、リストIDが必要なので設定してください。
(画像では、Issueからカード作成以外にプルリクでカードを移動させるアクションも使っているため、複数のリストIDを設定しています。)

5. GitHubリポジトリの.github/workflows以下にワークフローを作成する

ここまでは前座で、このワークフロー作成が肝になります。
リポジトリの.github/workflows以下に、どのイベントをトリガーに、どのアクションを行うというワークフローの設定ファイルを作成することで、GitHub Actionsが機能します。
https://help.github.com/ja/actions/configuring-and-managing-workflows/configuring-a-workflow
https://help.github.com/ja/actions/reference/contexts-and-expression-syntax-for-github-actions

今回はIssue作成をトリガーにTrelloカード作成を行うので、以下のようなファイルを作ります。

.github/workflows/create_trello_card_when_issue_opened.yml

name: Create trello card when issue opened # GitHubに表示されるアクションの名前

on: # 何をトリガーにするか
  issues: # Issue
    types: [opened, reopened] # オープンと、リオープンをトリガーにする

jobs:
  create_trello_card_job: # ジョブのID
    runs-on: ubuntu-latest # ジョブを実行するマシン
    name: Create Trello Card # GitHubに表示されるジョブの名前
    steps: # ジョブ内のタスクをステップと呼ぶ
    - name: Call trello-github-actions # GitHubに表示されるステップの名前
      id: call-trello-github-actions # ステップの識別子
      uses: jessicazu/trello-github-actions@v1.0 # 実行するアクション。v1.0を指定してください
      with: # アクションに渡す入力パラメータ。Card作成のメソッドを指定している
        trello-action: create_card_when_issue_opened
      env: # アクションで用いる環境変数。Secretsに指定したTrelloの情報を設定する
        TRELLO_API_KEY: ${{ secrets.TRELLO_API_KEY }}
        TRELLO_API_TOKEN: ${{ secrets.TRELLO_API_TOKEN }}
        TRELLO_BOARD_ID: ${{ secrets.TRELLO_BOARD_ID }}
        TRELLO_LIST_ID: ${{ secrets.TRELLO_TO_DO_LIST_ID }} # To Doリストにカードを作成する

ここまでで、Issue作成するとカードが作成されるようになります。

6. Lablesの設定をする

GitHubのLabelsとTrelloのラベルを対応させると、さらに便利になります。
それぞれの名前に対応させているので、連携させたいラベルの名前を同一にしてください。
色も合わせれば完璧です。
Trelloは設定できるラベルの色が10色で決まっているため、Trelloラベルの色に合わせてGitHubラベルを作ると良いと思います。
参考までに、Trelloラベルのカラーコードを載せておきます。

緑：#61bd4f、黄色：#f2d600、オレンジ：#ff9f1b、赤：#d73a4a、紫：#c376e0、青：#0079bf、水色：#a2eeef、黄緑：#51e998、ピンク：#fe79cb、紺：#344563

以上で、手順は終了です。Issueを作って確認してみてください！

Pull Requestにも対応

この他に、プルリクをオープンorクローズ(マージ)するとリストを移動させるアクションも作成しました。
僕はオープンでDoingからReviewリストへ、マージでReviewからDoneリストへ移動するようにしています。

カードとプルリクの対応のさせ方として、プルリクの詳細に#{Issue番号}を探してIssue番号を取得し、移動元ボードからその番号でカードタイトルの検索をかけています。
なので、#{Issue番号}をプルリクの詳細に必ず含めるようにしてください。

ちなみにReviewerを指定すると、対応するTrelloメンバーをカードに登録するようにもなっています。

オープン

/.github/workflows/move_card_when_pull_request_opened.yml

name: Move trello card when pull request opened

on:
  pull_request:
    types: [opened, reopened]

jobs:
  move_card_when_pull_request_open:
    runs-on: ubuntu-latest
    name: Move Trello Card 
    steps:
    - name: Call trello-github-actions
      id: call-trello-github-actions
      uses: jessicazu/trello-github-actions@v1.0
      with:
        trello-action: move_card_when_pull_request_opened # オープンでカード移動アクション
      env:
        TRELLO_API_KEY: ${{ secrets.TRELLO_API_KEY }}
        TRELLO_API_TOKEN: ${{ secrets.TRELLO_API_TOKEN }}
        TRELLO_BOARD_ID: ${{ secrets.TRELLO_BOARD_ID }}
        TRELLO_DEPARTURE_LIST_ID: ${{ secrets.TRELLO_DOING_LIST_ID }} # カードの移動元となるリスト
        TRELLO_DESTINATION_LIST_ID: ${{ secrets.TRELLO_REVIEW_LIST_ID }} # カードの移動先となるリスト

マージ

/.github/workflows/move_card_when_pull_request_closed.yml

name: Move trello card when pull request closed

on:
  pull_request:
    types: closed
    branches:
      - master # ここではmasterへのマージを対応させています

jobs:
  move_card_when_pull_request_open:
    runs-on: ubuntu-latest
    name: Move Trello Card 
    steps:
    - name: Call trello-github-actions
      id: call-trello-github-actions
      uses: jessicazu/trello-github-actions@v1.0
      with:
        trello-action: move_card_when_pull_request_opened # マージでカード移動アクション
      env:
        TRELLO_API_KEY: ${{ secrets.TRELLO_API_KEY }}
        TRELLO_API_TOKEN: ${{ secrets.TRELLO_API_TOKEN }}
        TRELLO_BOARD_ID: ${{ secrets.TRELLO_BOARD_ID }}
        TRELLO_DEPARTURE_LIST_ID: ${{ secrets.TRELLO_REVIEW_LIST_ID }} # カードの移動元となるリスト
        TRELLO_DESTINATION_LIST_ID: ${{ secrets.TRELLO_DONE_LIST_ID }} # カードの移動先となるリスト

備考

上手く動かない、こんな機能も欲しい、など意見がありましたら、どしどしコメントしてやってください。

URL

今回作成したライブラリ：https://github.com/jessicazu/trello-github-actions
開発時参考にしたリファレンス
Trello API：https://developers.trello.com/reference/
GitHub API Event Types & Payloads：https://developer.github.com/v3/activity/events/types/#issuesevent
GitHub Actions JavaScript アクション：https://help.github.com/ja/actions/building-actions/creating-a-javascript-action