gitpod/components/content-service-api/initializer.proto

syntax = "proto3";

package contentservice;

option go_package = "github.com/gitpod-io/gitpod/content-service/api";

// WorkspaceInitializer specifies how a workspace is to be initialized
message WorkspaceInitializer {
    oneof spec {
        EmptyInitializer empty = 1;
        GitInitializer git = 2;
        SnapshotInitializer snapshot = 3;
        PrebuildInitializer prebuild = 4;
    }
}

message EmptyInitializer { }

message GitInitializer {
    // remote_uri is the Git remote origin
    string remote_uri = 1;

    // upstream_Remote_uri is the fork upstream of a repository
	string upstream_Remote_uri = 2;

    // the target mode determines what gets checked out
    CloneTargetMode target_mode = 3;

	// the value for the clone target mode - use depends on the target mode
	string clone_taget = 4;

	// a path relative to the workspace root in which the code will be checked out to
	string checkout_location = 5;

    // config specifies the Git configuration for this workspace
    GitConfig config = 6;
}

// CloneTargetMode is the target state in which we want to leave a GitWorkspace
enum CloneTargetMode {
    // REMOTE_HEAD has the local WS point at the remote branch head
	REMOTE_HEAD = 0;

	// REMOTE_COMMIT has the local WS point at a specific commit
	REMOTE_COMMIT = 1;

	// REMOTE_BRANCH has the local WS point at a remote branch
	REMOTE_BRANCH = 2;

	// LOCAL_BRANCH creates a local branch in the workspace
	LOCAL_BRANCH = 3;
}

message GitConfig {
    // custom config values to be set on clone provided through `.gitpod.yml`
	map<string, string> custom_config = 1;

	// authentication method
	GitAuthMethod authentication = 2;

    // auth_user is the username used to authenticate the clone
	string auth_user = 3;

	// auth_password is the password used to authenticate the clone (can also be an API token)
    string auth_password = 4;

    // auth_ots is a URL where one can download the authentication secret (<username>:<password>)
    // using a GET request.
    string auth_ots = 5;
}

// GitAuthMethod is the means of authentication used during clone
enum GitAuthMethod {
    // NO_AUTH disables authentication during clone
    NO_AUTH = 0;

    // BASIC_AUTH uses HTTP basic auth during clone (fails if repo is not cloned through http)
    BASIC_AUTH = 1;

    // BASIC_AUTH_OTS uses HTTP basic auth during the clone with the secrets coming from the OTS URL.
    // Fails if either the OTS download or the clone fail.
    BASIC_AUTH_OTS = 2;
}

message SnapshotInitializer {
    // name of the snapshot to restore
    string snapshot = 1;
}

// A prebuild initializer combines snapshots with Git: first we try the snapshot, then apply the Git clone target.
// If restoring the snapshot fails, we fall back to a regular Git initializer.
message PrebuildInitializer {
    SnapshotInitializer prebuild = 1;
    GitInitializer git = 2;
}

// GitStatus describes the current Git working copy status, akin to a combination of "git status" and "git branch"
message GitStatus {
    // branch is branch we're currently on
    string branch = 1;

    // latest_commit is the most recent commit on the current branch
    string latest_commit = 2;

    // uncommited_files is the number of uncommitted files, possibly truncated
    repeated string uncommited_files = 3;

    // the total number of uncommited files
    int64 total_uncommited_files = 6;

    // untracked_files is the number of untracked files in the workspace, possibly truncated
    repeated string untracked_files = 4;

    // the total number of untracked files
    int64 total_untracked_files = 7;

    // unpushed_commits is the number of unpushed changes in the workspace, possibly truncated
    repeated string unpushed_commits = 5;

    // the total number of unpushed changes
    int64 total_unpushed_commits = 8;
}