GitHub の GraphQL API Explorer を使って自分の活動の振り返りをする

Jul 24, 2020 ( Feb 11, 2022 更新 )

要約

  • GitHub での PR 作成とレビュー履歴を参考にやったことを振り返る
  • 社の期末振り返りを書くのにも便利

GitHub での活動を振り返る

みなさん、定期的に自分の活動を振り返っていますか。 定期的な目標設定と振り返りを個人的にしている方もいるでしょうし、あるいは職場で必須となっている方もいるでしょう。 ソフトウェアエンジニアの中には GitHub を使って OSS 活動をされている方、職場のソースコード管理やコミュニケーションツールとして活用されている方がいるかと思います。

私の職場では、期初の目標設定、期末の振り返りが必須となっています。また、社内の開発のコミュニケーションは GitHub で行っています。 この振り返りを書くとき、何も考えないでやろうとすると、どうも抽象的な内容になってしまいます。

具体的にどんなタスクをどのようなアプローチで行ったか、またスピードはどうか。全体としての生産性はどうか。 それを具体的にあらわすには、実際にコードへの変更や、開発上発生したコミュニケーションの内容(例えば、コードレビューなど)を読み返してみるのが一つの手です。

まず、それらを活用するために、この記事で GitHub 上の活動履歴を簡単に取得する方法を紹介します。

GitHub の GraphQL API Explorer を使う

GitHub の 活動履歴をさかのぼりたい時、 Web UI からたどっていくというやり方もできるでしょう。 しかし、このやり方だと

  • 取得できる情報にたどり着くまでに何回もページ遷移する必要がある
  • データの流用が難しい
    • Web UI からデータを取得すると(画面上のテキストをページごとにコピーするなど)、あとから加工できる形にするには手間がかかる

という問題があります。

GitHub は、 GraphQL API Explorer という、 GitHub の GraphQL API1 を簡単に実行できるツールを公開しています。 これを使って、自分の必要な情報だけを簡単に、かつ加工のしやすい JSON 形式で取得することができます。

使い方

公式ドキュメントも用意されていますので、そちらを見るのもよいかと思います。 以下に、私の使い方を書いていきます。

まずはおもむろに GraphQL API Explorer へアクセスします。

graphql-01

左側の入力フォームが、 GraphQL のクエリを入力する場所です。 初期状態では、単純に field が入力された状態になっています。 クエリは、

  • viewer query が設定
    • viewer は User object を返却する
  • User の login (アカウント名) を取得するように設定

という内容となっています。

このツールは、 field 等をクリックすると右側のパネルで API ドキュメントを参照できます。 取得する object で何の fields が取得できるか入力しながらすぐにわかるのでめちゃくちゃ便利です。

graphql-02

これを利用して、自分の取得したいものを query を使って書いていきます。

クエリをつくる

私は

  • ある organization 内の PR

かつ

  • ある一定期間内に自身が作成した PR
  • ある一定期間内に自身がレビューした PR

を取得したかったので、以下のようなクエリを作成しました。 $me のような、 query variables がありますが、後述しますので今は無視してください。

query ($me: String!, $orgId: ID!, $from: DateTime!, $to: DateTime!, $count: Int!) {
  user(login: $me) {
    contributionsCollection(from: $from, to: $to, organizationID: $orgId) {
      pullRequestContributions(last: $count, orderBy: {direction: ASC}) {
        totalCount
        pageInfo {
          hasNextPage
          hasPreviousPage
        }
        nodes {
          pullRequest {
            title
            url
            reviewDecision
            latestReviews(last: 100) {
              nodes {
                author {
                  login
                }
              }
            }
            createdAt
            closedAt
          }
        }
      }
      pullRequestReviewContributions(last: 100, orderBy: {direction: ASC}) {
        totalCount
        pageInfo {
          hasNextPage
          hasPreviousPage
        }
        nodes {
          pullRequestReview {
            url
            pullRequest {
              title
              url
              author {
                login
              }
            }
            submittedAt
          }
        }
      }
    }
  }
}

variables は以下のようになります。

{
  "me": "mookjp", // 自分のアカウント名
  "orgId": "XXX", // org の node_id
  "from":  "2021-12-01T00:00:00+09:00",
  "to":  "2021-12-31T24:59:59+09:00",
  "count": 100
}

※ 2020-10-04: 自分が作成した PR のレビュワーを取得できるように編集

このようなクエリを作成するのはかなり面倒そうですが、 object 以下の field は適当な文字列をエディタ上で入力すると補完・サジェストされます。

また、この API Explorer のエディタの Explorer ボタンをクリックすると、エディタの左側に object, field の一覧とチェックボックスが表示されます。 これを使ってポチポチ好きな項目を選んでいくだけで簡単にクエリが作成できてしまいます。

graphql-03

変数設定

上記のクエリには $me などといった query variables が使われています。 この内容も、エディタ上で指定することができます。

はじめにクエリ側で変数を記入してから、下の query variables というフォームに移動して JSON を入力します。こちらも補完がききます。

graphql-04

前述した PR を取得するクエリでは、

  • アカウント名 - $me
  • 日付 - $from, $to
  • organization ID - $orgId

を変更できるようにしています。

organization ID を取得するには、 GitHub にログインした状態で以下の URL にアクセスすればよいです。

https://api.github.com/orgs/{organization name}

レスポンス JSON の、 node_id を organization ID として使うことができます。

jq で整形する

ここまでで、 GitHub 上の欲しい情報を取得することはできました。 結果は JSON なので、必要であればこの結果をコピーして

pbpaste | jq # ... jq コマンド

のように加工することができます。

jq の整形の例

私は JSON の構造を

  • prs - 自分が作成した PR
    • total
    • data
      • title
      • url
      • createdAt
      • closedAt
  • reviews - 自分が作成した PR 以外で自分がレビューしているもの
    • total
    • data
      • title
      • url
      • author
      • submittedAt

としたかったので、以下のように jq で整形しました。

pbpaste | jq '.data.user.contributionsCollection | {"prs": {"data":[.pullRequestContributions.nodes[].pullRequest]}, "reviews": {"data": [.pullRequestReviewContributions.nodes[].pullRequestReview | select((.pullRequest.author.login != "mookjp") and .pullRequest.author.login != "github-actions") ]} } | {"prs": {"total": .prs.data | length, "data": [.prs.data] }, "reviews": {"total": .reviews.data | length, "data": [.reviews.data[] | {"title": .pullRequest.title, "url": .pullRequest.url, "author": .pullRequest.author.login, "submittedAt": .submittedAt} ]} }' > output.json

reviews には、自分の作成した PR を含めたくないため select で弾いています。 また、他にも PR の中には、 Github Actions で作られたものもあったので同様に select を使って除外しています。

所感

今回、あまりに振り返りを書くのが面倒だったのがきっかけで GitHub API Explorer を見つけて利用してみたのですがなかなか便利でした。 今後も職場での振り返りに使えそうですし、自分個人の活動の振り返りにも使えそうです。 クエリ例など、よかったら参考にしてみてください。

今後は、 JIRA とか Slack とかでも一定期間内の活動をうまく抽出して振り返りに使いたいなとも考えています。

  1. GraphQL 自体については、この記事では詳しく説明しません。公式サイトにわかりやすい説明があるので、そちらを参照してみてください。 ↩︎

Return to top