エンタープライズ版 Backlogを使いこなそう

Git Webフックとは、Backlogが管理しているGitリポジトリにpushされた際に、指定されたURL（サーバ）へHTTP POSTする機能です。

Webフックは、例えば以下の用途に用いることができます。

• CIビルドのトリガ
• バックアップの更新
• ステージング環境への最新版コードの反映
• その他外部システムとの連携

これらは、CIサーバに備わっているポーリング機能やcronなどで、定期的にGitリポジトリにアクセスすることでも代替可能です。ですが、ポーリングでは定期的にアクセスする仕組み上、pushされてから実際の処理が動くまでにタイムラグが発生することがあります。Webフックでは、pushされたタイミングで即座にHTTP通信が行われるため、タイムラグを無くして即座に処理を行うことができます。

Webフックの設定

Webフックはリポジトリごとに設定することができます。Gitリポジトリの作成、もしくはGitリポジトリの編集から、push時にPOSTする先のURLを指定してください。

注意事項

Webフックの指定先のURLは、Backlogのサーバからアクセスできるようにしておいてください。イントラネット内のサーバなど、BacklogからアクセスできないURLは指定することができません。同様の理由で、"192.168.x.x" などのプライベートネットワークを表すIPアドレスは指定することができません。

Webフック受信側の一時的なサーバダウン等に対応するため、サーバエラーとなった場合（POST時のHTTPステータスコードが5xx系だった場合）は数回リトライを試みます。

後述の通りコミットのメッセージやメールアドレスなどの情報を送信します。これらの情報を保護したい場合には、HTTPS の URL をご指定ください。

データ形式

Webフックでは、指定されたURLにpush時のデータをJSON形式で送信します。JSONデータのパラメータは "payload" のみです。"payload" の形式は以下の通りです。

{
  "before": push前のコミット,
  "after": push前のコミット,
  "ref": 参照
  "repository": {
    "url": リポジトリのURL,
    "name": リポジトリ名,
    "description": リポジトリの説明,
  },
  "commits": [{
    "id": コミットのID,
    "url": コミットのURL,
    "author": {
      "email": コミットした人のメールアドレス
      "name": コミットした人の名前
    },
    "message": コミットメッセージ,
    "timestamp": タイムスタンプ,
    "added": [ 追加されたファイル ],
    "removed": [ 削除されたファイル ],
    "modified": [ 修正されたファイル ],
  }]
}

サンプルデータは以下のようになります。

{
  "before": "5aef35982fb2d34e9d9d4502f6ede1072793222d",
  "after": "c0b8abaa6df37ea682454c25f2d602dffb5de6ed",
  "ref": "refs/heads/master"
  "repository": {
    "url": "https://demo.backlog.com/git/DORA/himitsu",
    "name": "himitsu",
    "description": "ひみつ道具を格納しているリポジトリ",
  },
  "commits": [
    {
      "id": "8e82fe274af30adbb378785628db509da1c969d1",
      "url": "https://demo.backlog.com/git/DORA/himitsu/commit/8e82fe274af30adbb378785628db509da1c969d1",
      "author": {
        "email": "nobi@example.com",
        "name": "nobi"
      },
      "message": "どこでも行けるドアを作成しました",
      "timestamp": "2013-04-01T14:57:17+09:00",
      "added": ["html/anywhere.html", "css/anywhere.css"]
    },
    {
      "id": "c0b8abaa6df37ea682454c25f2d602dffb5de6ed",
      "url": "https://demo.backlog.com/git/DORA/himitsu/commit/c0b8abaa6df37ea682454c25f2d602dffb5de6ed",
      "author": {
        "email": "gouda@example.com",
        "name": "gouda"
      },
      "message": "DORA-1 竹でできているヘリコプターが壊れました #fixed",
      "timestamp": "2013-04-01T18:22:10+09:00",
      "removed": ["html/take-copter.html"]
    },
  ],
}