Perl Hackers Hub

第67回 GitHub APIによるチーム開発の効率化 ―基本操作から,GitHub Webhooksの活用まで(1)

この記事を読むのに必要な時間:およそ 4 分

本連載では第一線のPerlハッカーが回替わりで執筆していきます。今回のハッカーはtecklこと菅井茂樹さんで,テーマは「GitHub APIによるチーム開発の効率化」です。

本稿のコードは,執筆時点(2021年3月)の最新であるPerl 5.32.1で動作確認を行っています。サンプルコードはWEB+DB PRESS Vol.122のサポートサイトから入手できます。

チーム開発をもっと便利にするGitHub API

ソフトウェア開発にとって欠かせない存在となったGitHubですが,GitHub APIを使用することでさらに便利に活用できます。アイデアしだいで,普段手動で行っている操作を自動化したり,管理コストを削減したり,外部のツールと連携させたりと,チーム開発の効率化を行えます。

本稿では,このGitHub APIに焦点を当てます。みなさんが会社のGitHubの管理・運用を行うことになったケースを想定し,PerlのGitHub APIライブラリを用いてチーム開発をよりスムーズに進めるためのアイデアやテクニックを紹介します。

GitHub APIとは

GitHub APIとは,GitHubが提供するGitHub独自のAPIです。GitHub APIを使用すると,リポジトリの作成・編集,issueの取得・編集,Pull Requestの作成・編集,Gistの投稿,任意のコードの検索,Organization(組織)の管理など,ブラウザから可能な操作のほとんどを行えます。

GitHub APIの種類

2021年3月現在,GitHub APIにはv3 REST APIv4 GraphQL APIがあります。v4 GraphQL APIはAPIのエンドポイントが1つとなり,複数のリクエストを1回にまとめることができたり,必要な要素のみを取得できたりするなどの長所があります。一方でエラーハンドリングが難しく,初学者の学習コストがかかることも想定されます。v3 REST APIとv4 GraphQL APIではどちらも同じことを実現できますが,古くからあるREST APIのほうが気軽に組込みやすい方が多いと思いますので,本稿ではREST APIを用います。

GitHub Enterpriseの場合

GitHub Enterpriseという法人向けのGitHubを利用している方もいるでしょう。GitHub Enterpriseも,GitHub.comと同等のGitHub APIを備えています。GitHub Enterprise用のAPIのエンドポイントを合わせて指定することで利用できます。本稿の解説内容は,GitHub Enterpriseでも利用可能です。

GitHub API開発の準備

GitHub APIを使う準備を行いましょう。

OAuthトークンの取得

GitHub APIでは,オープンなリポジトリの操作には認証が不要です。プライベートなリポジトリの操作にはOAuthトークンによる認証が必要です。また,未認証の場合のリクエスト数は1時間あたり60件までですが,認証されたリクエストの場合は1時間あたり5,000件までと大幅に緩和されます。

OAuthトークンの取得には,GitHubのサイト上から「Settings」「Developer settings」「Personal access tokens」と遷移し,任意の名前でトークンを作成してください。この際,トークンに付与するスコープ(権限)を適切に選択してください。慣れないうちは,書き込み権限は付与せずに作成するほうがよいと思います。

GitHub APIクライアントのインストール

CPANにはPerlでGitHub APIを利用するためのクライアントがいくつも公開されています。代表的なのはPithubNet::GitHubです。どちらもほとんど同じことができますが,今回はオブジェクト指向で書きやすいPithubを使用します。Pithubはv3 REST APIのみの対応となるため,v4 GraphQL APIを使いたい場合はNet::GitHub::V4を利用するとよいでしょう。

Pithubは,cpanmコマンドでインストールできます。

$ cpanm Pithub
$ perl -MPithub -E 'say $Pithub::VERSION'
0.01036

これで,GitHub APIを利用するための準備が整いました。

GitHub APIの実用例

それでは,GitHub APIを利用してみましょう。前述したようにみなさんが会社のGitHubのOrganizationを運用している管理者だと想定して,いくつかの例を紹介します。

組織の公開リポジトリ一覧を取得する

たとえば運用しているOrganizationが,OSSOpen Source Software向けの公開リポジトリと,自社運用サービス向けのプライベートリポジトリの両方を扱っていたとします。これらのリポジトリの中から,公開リポジトリのみの一覧を取得するには次のようにします。

use strict;
use warnings;
use feature 'say';

use Pithub;

# 前節で取得したOAuthトークン
my $token = 'my_oauth_token';
my $pit = Pithub->new(
    token => $token,
);
my $result = $pit->repos->list( …(1)
    org => 'org_name_xxxxx',
    params => {
        type => 'public',
    },
);
while ( my $row = $result->next ) {
    say $row->{name};
}

これ以降に登場するコードでは,冒頭のuse Pithub;までは省略します

(1)$pit->reposとしている箇所は,GitHub APIドキュメントのRepositoriesに対応しています。このように,Pithubのメソッドと連動するモジュール名はGitHub APIの各リソースと対応しており,使用したいリソースから直感的にAPIリクエストを扱えます。この例ではリポジトリ名のみを出力していますが,ほかにもドキュメント内のレスポンスのサンプルにあるようなリポジトリの最終更新日(updated_at)やデフォルトブランチ名(default_branch⁠⁠,未解決のissueの件数(open_issues_count)などのリポジトリの固有情報を取得できます。

この程度であればブラウザ上での確認で十分ではないかと思われるかもしれませんが,後述するSlackなどの外部ツールと連携させることによって,公開リポジトリが作成されたタイミングでSlackなどの外部ツールに通知する,といったケースに活用できます。

なお,GitHub Enterpriseを利用している方は,次のように自身のGitHub Enterprise用のAPIのエンドポイントを追加で指定することで同じことが行えます。

my $pit = Pithub->new(
    token => $token,
    api_uri => 'https://example.com/api/v3/',
);

組織のメンバー一覧を取得する

たとえばみなさんのOrganizationにおいて,外部からの不正アクセスや不正ログインを防ぐため,GitHubの2要素認証を必須とすることになった状況を考えてみます。Organizationに所属しているメンバー一覧の中から,まだ2要素認証を設定していないメンバーの一覧を取得するには,次のようにします。

my $pit = Pithub->new(
    token => $token,
);
my $res = $pit->orgs->members->list( …(1)
    org => 'org_name_xxxxx',
    params => {
        filter => '2fa_disabled',
    },
);
my $members = $res->content;
for my $member (@{$members}) {
    say $member->{login};
}

(1)$pit->orgsとしている箇所は,GitHub APIドキュメントのOrganizationsに対応しています。

著者プロフィール

菅井茂樹(すがいいしげき)

SIerを経て2005年よりシーサー株式会社所属。ブログサービスを中心にPerlを使ったWeb開発に携わる。

最近ではレガシーなサービスのクラウド移行・インフラ構築・保守・運用を中心に行っている。趣味はラーメンの食べ歩きと旅行,ここ数年はキャンプにハマり中。

Twitter:@teckl