Skip to content

Git designed for AI agents.

8.0 KB
Raw Blame
syntax = "proto3";

package gitaly;

import "lint.proto";
import "shared.proto";

option go_package = "github.com/feder-cr/git-ai/proto/go/gitalypb";

// HookService is a service which provides the implementation of a subset of
// Git hooks. These are typically invoked via the `gitaly-hooks` binary to
// ensure that the actual hook logic is executed in the context of the server.
service HookService {

  // PreReceiveHook ...
  rpc PreReceiveHook(stream PreReceiveHookRequest) returns (stream PreReceiveHookResponse) {
    option (op_type) = {
      op: ACCESSOR
    };
  }

  // PostReceiveHook ...
  rpc PostReceiveHook(stream PostReceiveHookRequest) returns  (stream PostReceiveHookResponse) {
    option (op_type) = {
      op: ACCESSOR
    };
  }

  // UpdateHook ...
  rpc UpdateHook(UpdateHookRequest) returns (stream UpdateHookResponse) {
    option (op_type) = {
      op: ACCESSOR
    };
  }

  // ReferenceTransactionHook ...
  rpc ReferenceTransactionHook(stream ReferenceTransactionHookRequest) returns (stream ReferenceTransactionHookResponse) {
    option (op_type) = {
      op: ACCESSOR
    };
  }

  // PackObjectsHookWithSidechannel is an optimized version of PackObjectsHook that uses
  // a unix socket side channel.
  rpc PackObjectsHookWithSidechannel(PackObjectsHookWithSidechannelRequest) returns (PackObjectsHookWithSidechannelResponse) {
    option (op_type) = {
      op: ACCESSOR
    };
  }

  // ReceiveReportHook is a hook invoked by git-receive-pack(1) after all reference
  // updates have been processed but before the status of the push is reported
  // to the client. A non-zero exit status turns every otherwise-successful ref
  // update into a failure, letting the durable object-store publish reject the
  // push before the client is told it succeeded.
  rpc ReceiveReportHook(stream ReceiveReportHookRequest) returns (stream ReceiveReportHookResponse) {
    option (op_type) = {
      op: MUTATOR
    };
  };

  // SignalPostReceiveReady signals that Praefect has completed transaction coordination
  // and the PostReceiveHook can proceed with calling Rails. This is used to prevent a
  // race condition where Rails is notified before all Gitaly replicas have applied the
  // write and before Praefect has updated its database for routing decisions.
  //
  // This RPC is called by Praefect after the request finalizer has completed (DB update
  // and replication job enqueueing). The transaction_id corresponds to the Praefect
  // transaction that was used to coordinate the write across replicas.
  rpc SignalPostReceiveReady(SignalPostReceiveReadyRequest) returns (SignalPostReceiveReadyResponse) {
    option (op_type) = {
      op: ACCESSOR
      scope_level: STORAGE
    };
  };
}

// PreReceiveHookRequest ...
message PreReceiveHookRequest {
  // repository ...
  Repository repository = 1 [(target_repository)=true];
  // environment_variables ...
  repeated string environment_variables = 2;
  // stdin ...
  bytes stdin = 4;
  // git_push_options ...
  repeated string git_push_options = 5;
}

// PreReceiveHookResponse ...
message PreReceiveHookResponse{
  // stdout ...
  bytes stdout = 1;
  // stderr ...
  bytes stderr = 2;
  // exit_status ...
  ExitStatus exit_status = 3;
}

// ReceiveReportHookRequest is the request for the ReceiveReportHook RPC.
message ReceiveReportHookRequest {
  // repository is the repository the hook operates on.
  Repository repository = 1 [(target_repository)=true];
  // environment_variables is the set of env variables to be passed to the RPC.
  repeated string environment_variables = 2;
  // stdin is a chunk of raw data which the hook receives (the successfully
  // updated refs, one per line).
  bytes stdin = 3;
  // git_push_options are the push options supplied by the client.
  repeated string git_push_options = 4;
}

// ReceiveReportHookResponse is the response for the ReceiveReportHook RPC.
message ReceiveReportHookResponse {
  // stdout is a chunk of raw data to be output to stdout of the hook.
  bytes stdout = 1;
  // stderr is a chunk of raw data to be output to stderr of the hook.
  bytes stderr = 2;
  // exit_status is the exit status the hook outputs, dictating the
  // success/failure of git-receive-pack(1).
  ExitStatus exit_status = 3;
}

// PostReceiveHookRequest ...
message PostReceiveHookRequest {
  // repository ...
  Repository repository = 1 [(target_repository)=true];
  // environment_variables ...
  repeated string environment_variables = 2;
  // stdin ...
  bytes stdin = 3;
  // git_push_options ...
  repeated string git_push_options = 4;
}

// PostReceiveHookResponse ...
message PostReceiveHookResponse{
  // stdout ...
  bytes stdout = 1;
  // stderr ...
  bytes stderr = 2;
  // exit_status ...
  ExitStatus exit_status = 3;
}

// UpdateHookRequest ...
message UpdateHookRequest {
  // repository ...
  Repository repository = 1 [(target_repository)=true];
  // environment_variables ...
  repeated string environment_variables = 2;
  // ref ...
  bytes ref = 3;
  // old_value ...
  string old_value = 4;
  // new_value ...
  string new_value = 5;
}

// UpdateHookResponse ...
message UpdateHookResponse{
  // stdout ...
  bytes stdout = 1;
  // stderr ...
  bytes stderr = 2;
  // exit_status ...
  ExitStatus exit_status = 3;
}

// ReferenceTransactionHookRequest ...
message ReferenceTransactionHookRequest {
  // State ...
  enum State {
    // PREPARED ...
    PREPARED = 0; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH
    // COMMITTED ...
    COMMITTED = 1; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
    // ABORTED ...
    ABORTED = 2; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
    // PREPARING ...
    PREPARING = 3; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
  }

  // repository ...
  Repository repository = 1 [(target_repository)=true];
  // environment_variables ...
  repeated string environment_variables = 2;
  // stdin ...
  bytes stdin = 3;
  // state ...
  State state = 4;
}

// ReferenceTransactionHookResponse ...
message ReferenceTransactionHookResponse {
  // stdout ...
  bytes stdout = 1;
  // stderr ...
  bytes stderr = 2;
  // exit_status ...
  ExitStatus exit_status = 3;
}

// PackObjectsHookWithSidechannelRequest ...
message PackObjectsHookWithSidechannelRequest {
  // repository ...
  Repository repository = 1 [(target_repository)=true];
  // args contains the arguments passed to the pack-objects hook, without the leading "git"
  repeated string args = 2;
  // gl_id is the user id of the initator of the fetch
  string gl_id = 3;
  // gl_username is the username of the initator of the fetch
  string gl_username = 5;
  // git_protocol is the protocol used for the fetch
  string git_protocol = 6;
  // remote_ip is the original IP of the initator of the fetch. This field is used as the key for
  // concurrency limiting before we trigger git-pack-objects command
  string remote_ip = 7;
  // environment_variables contains the environment variables passed to the hook invocation.
  repeated string environment_variables = 8;
}

// PackObjectsHookWithSidechannelResponse ...
message PackObjectsHookWithSidechannelResponse {
}

// SignalPostReceiveReadyRequest is the request for the SignalPostReceiveReady RPC.
message SignalPostReceiveReadyRequest {
  // storage_name is the name of the storage containing the repository.
  string storage_name = 1 [(storage)=true];
  // transaction_id is the Praefect transaction ID that identifies the write operation.
  // This corresponds to the transaction ID from the HooksPayload.Transaction.ID field.
  uint64 transaction_id = 2;
  // post_transaction_failed indicates that Praefect failed to complete post-transaction
  // work (database update and replication job enqueueing) after the transaction was
  // committed. When true, the PostReceiveHook should fail so that git-receive-pack
  // exits non-zero, preventing Rails from acting on a write that is not yet reflected
  // in Praefect's routing state.
  bool post_transaction_failed = 3;
}

// SignalPostReceiveReadyResponse is the response for the SignalPostReceiveReady RPC.
message SignalPostReceiveReadyResponse {
}