Harness Open Source

エントリポイントは cmd/gitness/main.go。kingpin ベースの CLI（cli/）が server / migrate / user / account / hooks / swagger を登録する。server は env を読み込んでから Google Wire が生成した巨大なインジェクタ（cmd/gitness/wire_gen.go）を呼び、ストア・git サービス・イベント・全コントローラ・レジストリ・パイプライン・Gitspaces を 1 つの System に組み立てる。

組み立て後は初回ブートストラップ（管理者ユーザーと内部呼び出し用のサービスプリンシパル作成）を行い、errgroup で HTTP サーバー、SSH サーバー、ジョブスケジューラ、CI ポーラー、メトリクス収集を並行起動する。停止は SIGINT/SIGTERM でグレースフルに行う。

Git 操作は libgit2 や go-git ではなく、OS の git コマンドを exec する方式で実装されている。層は 3 段。

サーバーサイドフックは同じバイナリ

リポジトリ作成時に、hooks/pre-receive と hooks/post-receive が gitness 実行ファイル自身へのシンボリックリンクとして張られる（update は性能上コメントアウト）。push のたびに次の往復が起きる。

ペイロード（リポジトリ ID、プリンシパル ID、リクエスト ID、操作種別、コールバック先 URL）は gob エンコード＋base64 で環境変数 GIT_HOOK_PAYLOAD 1 本に詰められる。cli/cli.go は起動時に argv を見てフック呼び出しだと判定すると hooks サブコマンドへ経路を切り替える。フック処理のタイムアウトは 3 分。

SSH 側

ssh/server.go は gliderlabs/ssh のサーバーで、許可コマンドを git-upload-pack / git-receive-pack / git-lfs-authenticate / git-lfs-transfer の 4 つに限定する。公開鍵認証は app/services/publickey が担い、その先は HTTP と同じリポジトリコントローラへ合流する。

CI は Drone のコードベースを依存ライブラリとして取り込む形で実装されている。ランナーは同一プロセス内で動き、ポーラーも HTTP ではなく in-process クライアント経由でジョブを受け取る。

2 つの YAML 方言

方言の判定は単純で、パイプラインファイルが ^spec: にマッチすれば v1 spec、しなければレガシー Drone YAML として扱う（app/pipeline/triggerer/trigger.go の isV1Yaml）。レガシー側は jsonnet / starlark のコンバータと lint を通り、DAG を組んでからステージ化される。

レジストリは registry ディレクトリ配下の別 Go モジュールで、ルート側の go.mod の replace でローカル参照されている。OCI distribution spec の適合テストがリポジトリに入っており、Makefile から ./gitness server を立てて走らせられる。

対応パッケージ形式

実装は registry/app/pkg の形式別ディレクトリに分かれる。ただし HELM は専用ディレクトリを持たず、Docker/OCI の経路で扱われる（docker のローカル・リモート実装がいずれも DOCKER と HELM を宣言する）。

レジストリの種類とディスパッチ

ハンドラの選択は (パッケージ形式, レジストリ種類) をキーにしたファクトリ（registry/app/pkg/base）で行われ、プロキシ有無とチェック有無のラッパーが被せられる。

ドライバのファクトリ構造は distribution/distribution を踏襲しており、OCI 側ハンドラは blob の resumable upload、manifest、tag 一覧、catalog、referrers（OCI 1.1）、トークン発行までカバーする。ガベージコレクタ（registry/gc）と隔離機構（quarantine）も別立てで用意されている。

Gitspaces は app/gitspace（orchestrator / infrastructure / scm / secret / logutil）と app/services/gitspace*、そしてインフラ抽象の infraprovider で構成される。API は app/api/controller/gitspace と infraprovider。

インフラプロバイダ

抽象インターフェイスは Provision / Find / Stop / CleanupInstanceResources / Deprovision / パラメータ検証などを備え、列挙型には docker、harness_gcp、harness_cloud、hybrid_vm_gcp、hybrid_vm_aws が並ぶ。ただしこの OSS ツリーで実装されているのは Docker だけで、ファクトリにも docker しか登録されない。Kubernetes プロバイダは含まれない。

イベント駆動で中断・再開する起動シーケンス

flowchart TD
  API["API: start gitspace"] --> ACT["app/services/gitspace
action_start"]
  ACT --> SCM["SCM 詳細取得
clone 認証 + devcontainer.json 解析"]
  SCM --> PORT["必要ポート算出
forwardPorts + IDE ポート"]
  PORT --> PROV["infra provisioner に
Provision イベントを投げて返る"]
  PROV -.->|"完了イベント"| RES["ResumeStartGitspace"]
  RES --> CONT["コンテナ orchestrator
作成・起動・features 解決"]
  CONT --> LC["lifecycle コマンド実行
postCreate / postStart"]
  LC --> SSHD["コンテナ内 sshd と IDE 準備"]
  SSHD -.->|"操作完了イベント"| FIN["FinishResumeStartGitspace"]

起動は同期的に完走せず、プロビジョニング完了とコンテナ操作完了がそれぞれイベントとして戻り、ResumeStartGitspace と FinishResumeStartGitspace が続きを引き受ける。停止・削除・クリーンアップも同じ形。状態は設定レベル（running / stopped / starting / stopping / cleaning / error / uninitialized）とインスタンスレベル（resetting、pending_cleanup などを含む 12 種）で二重管理される。

接続できる IDE

各 IDE は app/gitspace/orchestrator/ide の実装をファクトリで選ぶ。VS Code Web はアセットを同梱し、デスクトップ IDE と JetBrains Gateway はコンテナ内で起動する sshd に接続する。

主体（プリンシパル）は user / serviceaccount / service の 3 種。Admin フラグを持つプリンシパルは検査をバイパスする。内部処理は起動時に作られるシステム・パイプライン・Gitspace のサービスプリンシパルとして自分自身の API を呼ぶ。

リソースはネストしたスペース（パスで表現）の下に並ぶ。認可はリソースをスペースパスに写し、祖先方向にメンバーシップを辿って判定する。公開アクセス設定が先に評価され、次に管理者バイパス、最後にメンバーシップという順序。

権限は 56 個の文字列

権限は <リソース>_<動詞> 形式の文字列で、リポジトリ系だけでも repo_view / repo_create / repo_edit / repo_push / repo_review / repo_delete がある。レジストリ系は registry_* とアーティファクト操作系（artifacts_upload / artifacts_download / artifacts_delete / artifacts_quarantine）に分かれている。

検査の位置

認証（JWT の抽出と検証）はミドルウェアで常に試行されるが、強制はコントローラ側で行う。app/api/auth の CheckRepo、CheckSpace、CheckPipeline、CheckRegistry、CheckGitspace といったヘルパーを各コントローラが呼ぶ。トークンはヘッダの Bearer、HTTP Basic のパスワード、Cookie などから取り出す。git ルートではブラウザのセッショントークンをミドルウェアで弾く。

永続化は app/store/database.go に並ぶ約 60 のストアインターフェイスと、その実装（app/store/database、sqlx + squirrel）で構成される。プレースホルダは PostgreSQL 形式（$1）に固定されており、SQLite でもそのまま通す方針。

単体起動をやりやすくするため、分散化が必要な部品はすべて「インメモリ既定 + 外部バックエンド任意」の形で抽象化されている。Redis を入れれば同じインターフェイスのまま複数インスタンス構成に寄せられる。

フロントエンドは web ディレクトリの単一 yarn パッケージ（パッケージ名 codeui）。React 17 + webpack 5 で、Vite は使っていない。

i18n に i18next は使わず、YAML の文言ファイル（strings.en.yaml / strings.es.yaml）を独自フレームワークが読み、useStrings() と <String/> で参照する。型はビルド時に自動生成される。

1 つの webpack プロジェクトから 3 つのリモートを出力し、react / react-dom / react-router-dom / formik をバージョン固定の singleton として共有する。

レジストリ UI の合成方法は 2 通り

• OSS バイナリで動くモード: メインアプリのルーティングが lazy(() => import(...)) でレジストリアプリを読み込む。コード分割はされるがネットワーク越しではなく、同じ dist に同梱される。アダプタが matchPath、401 ハンドラ、トークン生成、ルート定義、ホスト側コンポーネントを注入する。
• プラットフォーム埋め込みモード: 同じコードを ./HAREnterpriseApp として federated module で公開し、親シェルがコンテキストを与える。API クライアントはインターセプタでヘッダと base URL を差し替えるため、レジストリ UI 自体は接続先を知らないまま動く。

Go バイナリは web/dist.go の go:embed dist/* でフロントエンドのビルド成果物を取り込む。dist は git 管理外なので、クリーンなチェックアウトでは make web-build（または Docker の web ステージ）が先に必要。make build は web-build に依存していない点に注意する。

# 手元でひととおり動かす
make dep && make tools          # wire, dbmate, goimports, protoc 系
cd web && yarn install && yarn build && cd ..
make build                      # wire 生成 → go build -o ./gitness
./gitness server .local.env     # http://localhost:3000

ビルドツールは実行時依存と分離され、go.tool.mod 側のモジュールとして go tool -modfile=go.tool.mod で呼ばれる。

公式イメージは 4 ステージ構成。node で web をビルド → golang-alpine で make dep・make tools の後にビルド成果物を web/dist へコピーして静的リンク（CGO_ENABLED=1、arm64 はクロスコンパイラを取得）→ CA 証明書ステージ → alpine/git ベースの最終イメージにバイナリだけを置く。バージョン情報は ldflags で埋め込まれる。

docker run -d \
  -p 3000:3000 -p 3022:3022 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /tmp/harness:/data \
  --name harness --restart always \
  harness/harness

Docker ソケットをマウントするのは、パイプラインの step と Gitspaces のコンテナをホストの Docker で動かすため。/data にはリポジトリ・SQLite・レジストリのブロブが入るので、名前付きボリュームかバインドマウントを当てないとコンテナ停止でデータが消える。

Kubernetes 向けには charts/gitness に Helm チャート（deployment / service / ingress / pvc / serviceaccount）がある。

• GitHub: harness/harness — 本体リポジトリ。main が開発ブランチ
• harness/harness の drone ブランチ — Drone のスナップショット
• Harness Open Source ドキュメント — 利用者向けガイド
• Docker Hub: harness/harness — 公開イメージ
• OCI Distribution Specification — レジストリの /v2/* が準拠する仕様
• Development Containers — Gitspaces が読む devcontainer.json の仕様
• google/wire — 起動時 DI に使われるコード生成ツール
• Drone — パイプライン実装の出自