Git Tracker

git-tracker.delino.io で Git コミットの数値測定を追跡できます。Git Tracker は無料です。フォークのプルリクエストを含む、公開および非公開の GitHub リポジトリをサポートしています。ファイルサイズ、所要時間、スループット、件数、その他のスカラー測定に使用できます。

リポジトリを接続する

Delino アカウントでサインインし、個人または組織のスペースを選択します。
スペースの所有者に依頼し、そのスペースのグループを通じて Git Tracker の View、Edit、または Manage 権限を付与してもらいます。View では読み取りが許可されます。Edit ではアップロードと完了操作も許可されます。Manage ではさらに接続、トークン管理、完全削除が許可されます。
リポジトリに Git Tracker GitHub App をインストールします。
リポジトリを管理を開きます。owner/repository と、リポジトリ管理者アクセス権を持つ、連携済み GitHub アカウント用の GitHub アクセストークンを入力します。サービスは GitHub での権限を検証しますが、そのアクセストークンは保持しません。
リポジトリを接続します。Delino スペースの Owner/Admin 権限も必要です。リポジトリは一度に 1 つのスペースにのみ接続できます。Action および API 呼び出しに使用する接続 ID をリポジトリ管理画面からコピーします。接続解除後は、権限を持つ別のスペースが新しい接続 ID でそのリポジトリを接続できます。以前のスペースに保持された履歴は非公開のままです。

公開リポジトリの測定値は、サインインせずに読み取れます。非公開の測定値には、スペースのメンバーシップと Git Tracker の読み取り権限が必要です。スペースのアクセス権は、そのスペースに接続されているすべてのリポジトリに適用されます。

接続を解除するか App を削除すると、アップロードが停止し、保持されている履歴が非公開になります。権限を持つメンバーは引き続きその履歴を読み取れます。公開から非公開への変更が確認されると、履歴データも非公開になります。GitHub が現在の公開範囲を確認できない場合、Git Tracker は同期が成功するまで、最後に確認された公開範囲を維持します。

データセットを定義する

YAML 設定をリポジトリ内に保存します。ID は不変です。名前は履歴を失うことなく変更できます。1 行に含まれるすべての列は、一緒にアップロードする必要があります。

id: file-size
name: JavaScript file sizes
columns:
  - id: original
    name: Original size
    unit: B
    direction: lower
    absoluteThreshold: 1024
  - id: minified
    name: Minified size
    unit: B
    direction: lower
    percentageThreshold: 1
  - id: gzip
    name: Gzipped size
    unit: B
    direction: lower
    absoluteThreshold: 128
    percentageThreshold: 2

JSON の行をアップロードします。たとえば、SWC 形式のファイルサイズ表は次のようになります。

{
  "rows": [
    { "id": "jquery", "name": "jQuery", "values": { "original": 285314, "minified": 87533, "gzip": 30321 } },
    { "id": "three", "name": "Three.js", "values": { "original": 1321000, "minified": 675000, "gzip": 170000 } }
  ]
}

Action は、2 進浮動小数点への変換を行わず、JSON の小数表記をそのまま保持します。Direct Connect の呼び出し元は、"9007199254740993.0000000000000001" のように小数値を文字列として送信します。負数および有限小数がサポートされています。表示上の丸めがリグレッション判定を変えることはありません。

サポートされる単位は、B、kB、MB、GB、KiB、MiB、GiB、ns、μs、ms、s、count、%、unitless、および ops/s、B/s、kB/s、MB/s、GB/s、KiB/s、MiB/s、GiB/s です。互換性のある単位は比較前に変換されます。互換性のない種類は比較できません。たとえば、1048576 B は 1 MiB と表示されます。正確な値は表で引き続き確認できます。

方向は lower、higher、neutral です。中立の列ではリグレッションが発生することはありません。しきい値は、その列のすべての行に適用されます。絶対しきい値とパーセントしきい値の両方がある場合、いずれかを超えるとリグレッションになります。等しい場合はリグレッションではありません。しきい値がない場合、変更は表示されますが、リグレッションによる失敗は発生しません。悪化する方向の変更のみが判定されます。

変化率は (new - baseline) / abs(baseline) * 100 です。ベースラインがゼロの場合、変化率はありません。絶対しきい値による判定は引き続き可能ですが、パーセントのみのルールでは判定が保留されます。比較には、後から変更された設定ではなく、対象の実行に保存された設定が使用されます。

公式 GitHub Action を使用する

delinoio/apps/actions/git-tracker を、レビュー済みの完全なコミット SHA に固定します。以下のプレースホルダーを、Git Tracker の接続 ID、チェックアウトのリビジョン、Action のリビジョンに置き換えます。OIDC のために id-token: write を付与します。代わりにリポジトリアップロードトークンを使用することもできます。その場合は GitHub シークレットとして保存し、token を渡します。

permissions:
  contents: read
  id-token: write
jobs:
  measure:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@<reviewed-checkout-commit-sha>
      - run: ./measure.sh
      - uses: delinoio/apps/actions/git-tracker@<reviewed-action-commit-sha>
        with:
          repository-id: '019b0000-0000-7000-8000-000000000001'
          configuration: measurements.yaml
          measurements: measurements.json
          fail-on-regression: 'false'
  mark-as-done:
    needs: measure
    if: always()
    runs-on: ubuntu-latest
    steps:
      - uses: delinoio/apps/actions/git-tracker@<reviewed-action-commit-sha>
        with:
          operation: complete
          repository-id: '019b0000-0000-7000-8000-000000000001'

独立したジョブは、デフォルトの実行 ID である repository_id/run_id/run_attempt を共有し、互いに重複しない行をアップロードできます。再実行には新しい実行 ID を使用してください。Actions OIDC にはデフォルトの ID が必要です。カスタム実行 ID は、リポジトリトークンを使用する呼び出し元向けです。フォークからの OIDC アップロードは PR の head に限定され、ベースラインのオーバーライドを指定したり、上流の push 履歴へ書き込んだりすることはできません。

各アップロードジョブは、自身がアップロードした行のみを判定します。デフォルトでは、リグレッションは報告されますが CI は失敗しません。リグレッションが発生したときにそのジョブを失敗させるには、fail-on-regression: 'true' を設定します。比較対象がない場合は CI が失敗することはありません。完了ジョブは測定が終了したことだけを示します。CI の成功、失敗、キャンセルを送信することも、集約的なゲーティングを実行することもありません。すべてのジョブがスキップされた場合、空の完了操作も有効です。

ネットワークエラーと一時的な API 障害は、最大 3 回再試行されます。デフォルトでは、再試行後も失敗するとジョブが失敗します。代わりに警告を出して成功扱いにするには、warn-on-api-error: 'true' を設定します。PR コメントの失敗は警告のみです。保存済みデータを無効にしたり、それ自体で CI を失敗させたりすることはありません。Action は詳細リンクをログに記録し、Job Summary を書き込みます。

1 つの PR コメントに、その PR の最新コミットに対して最後に登録された実行の累積結果が反映されます。古い実行は引き続きウェブ上の履歴で確認できます。

Connect API を呼び出す

API のオリジンは https://git-tracker.api.delino.io です。Connect の JSON リクエストでは、Content-Type: application/json と Connect-Protocol-Version: 1 を使用します。管理者は、将来の有効期限が必須のリポジトリトークンを発行し、リポジトリ管理画面からそれらを失効させることができます。

curl --fail-with-body \
  'https://git-tracker.api.delino.io/gittracker.v1.GitTrackerService/Upload' \
  -H "Authorization: Bearer ${GIT_TRACKER_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H 'Connect-Protocol-Version: 1' \
  --data-binary @upload.json

upload.json には context、dataset、rows が含まれます。

{
  "context": {
    "repositoryId": "019b0000-0000-7000-8000-000000000001",
    "executionId": "my-historical-run",
    "commit": "0123456789012345678901234567890123456789",
    "branch": "main"
  },
  "dataset": {
    "id": "size",
    "name": "Size",
    "columns": [{ "id": "bytes", "name": "Bytes", "unit": "B", "direction": "DIRECTION_LOWER", "absoluteThreshold": "1024" }]
  },
  "rows": [{ "id": "bundle", "name": "Bundle", "values": { "bytes": "1048576" } }]
}

同じ context で /gittracker.v1.GitTrackerService/Complete を呼び出します。PR のアップロードでは pullRequest を含め、PR のベースブランチと head コミットを使用します。baselineCommit は、明示的な完全ベースライン SHA を選択します。過去のコミットには同じアップロード API を使用します。送信前に小数文字列を JavaScript の Number へ変換しないでください。

実行と比較のルール

最初のアップロードにより、その実行における各データセットの設定が固定されます。後から異なる設定を使用すると拒否されます。既存の行を同一の数値で繰り返し送信する操作は冪等です。競合する値は拒否されます。バッチはアトミックです。無効または競合する行がある場合、そのリクエストのデータは一切保存されません。

データは直ちに 測定中 として表示されます。完了後にのみ代表結果になります。コミットの代表結果は、リグレッションを含む実行も対象として、そのコミットについて最後に登録された完了済みの実行です。古い実行が遅れて完了しても、それより後に登録された完了済み実行を置き換えることはありません。完了操作を繰り返しても、完了時刻や順序は変更されません。

新たな測定データが保存されないまま 6 時間が経過すると、未完了の実行は中断状態になります。同一データの再送信では、このタイマーはリセットされません。完了済みおよび中断済みの実行では、それ以降のアップロードが拒否されます。中断済みの実行では完了操作も拒否されます。代わりに新しい実行を開始してください。データは削除するまで保持されます。

PR の自動比較では、最初のアップロード時にマージベースのコミットと、その代表となる完了済み実行が固定されます。ベースラインが存在しない場合、後からアップロードされても利用不可のままです。push の自動比較では、各行について第一親の祖先を個別にたどり、最初のアップロードの締め切り時点までに完了していた、測定済みの最も近い祖先を使用します。後続のジョブでも同じ締め切り時点が使用されます。表には、実際の各ソースコミットと実行が示されます。明示的なベースライン SHA による比較では、行単位の祖先フォールバックは使用されません。

ウェブサイトの 2 コミット比較では、選択したコミットの代表となる完了済み実行のみが使用されます。新しい行や列、欠落しているデータ、互換性のないデータは比較できず、リグレッションによる失敗を引き起こしません。削除されたベースラインデータは再構築されません。完了前に存在しない行は未収集として扱われ、完了後は欠落として扱われます。

グラフでは、第一親の順序でコミットが等間隔に配置されます。スキップされたコミットをまたいで、実際に測定された点同士を接続しますが、値を引き継いだり推測して生成したりすることはありません。データセット、ブランチ、列、項目、日付、コミット範囲で絞り込めます。正確な値と、キーボードでアクセス可能な実行リンクについては、データ表を使用してください。

削除とトラブルシューティング

管理者は、確認後にリポジトリの測定値、データセット、または 1 つの実行を完全に削除できます。ベースラインが削除された比較は利用できなくなります。Delcore がスペースの削除を確定すると、Git Tracker はそのスペースの接続、トークン、設定、履歴を削除します。

権限エラーが発生した場合は、選択しているスペースと現在の Git Tracker ロールを確認してください。アップロードの競合が発生した場合は、実行 ID、データセット設定、行の値が完全であることを確認してください。中断済みまたは完了済みの実行については、新しい実行 ID を使用してください。ネットワークまたはサーバーエラーの場合は再試行し、サポートを求める際に応答の相関 ID を保持しておいてください。公開レポートでは、トークン、認証情報、非公開の測定値を決して共有しないでください。

PR 実行の測定値は引き続き確認できますが、上流ブランチのグラフ上の点や自動ベースラインとしては使用されません。これにより、共有コミット SHA に対するベースラインブランチのデータや設定が、フォークの測定値によって置き換えられることを防ぎます。

#Git Tracker

#リポジトリを接続する

#データセットを定義する

#公式 GitHub Action を使用する

#Connect API を呼び出す

#実行と比較のルール