blob: 0f7c9618e686da922326038c11bc8e7cd9fca878 [file] [log] [blame]
// Copyright 2017 The LUCI Authors. All rights reserved.
// Use of this source code is governed under the Apache License, Version 2.0
// that can be found in the LICENSE file.
syntax = "proto3";
package srcman;
option go_package = "go.chromium.org/luci/common/proto/srcman";
// A Manifest attempts to make an accurate accounting of source/data directories
// during the execution of a LUCI task.
//
// These directories are primarily in the form of e.g. git checkouts of
// source, but also include things like isolated hashes and CIPD package
// deployments. In the future, other deployment forms may be supported (like
// other SCMs).
//
// The purpose of this manifest is so that other parts of the LUCI stack (e.g.
// Milo) can work with the descriptions of this deployed data as a first-class
// citizen. Initially this Manifest will be used to allow Milo to display diffs
// between jobs, but it will also be useful for tools and humans to get a
// record of exactly what data went into this LUCI task.
//
// Source Manifests can be emitted from recipes using the
// 'recipe_engine/source_manifest' module.
message Manifest {
// Version will increment on backwards-incompatible changes only. Backwards
// compatible changes will not alter this version number.
//
// Currently, the only valid version number is 0.
int32 version = 1;
message GitCheckout {
// The canonicalized URL of the original repo that is considered the “source
// of truth” for the source code.
//
// Ex.
// https://chromium.googlesource.com/chromium/tools/build
// https://chromium.googlesource.com/infra/luci/recipes-py
string repo_url = 1;
// If different from repo_url, this can be the URL of the repo that the source
// was actually fetched from (i.e. a mirror).
//
// If this is empty, it's presumed to be equal to repo_url.
//
// Ex.
// https://github.com/luci/recipes-py
string fetch_url = 2;
// The fully resolved revision (commit hash) of the source.
//
// This must always be a revision on the hosted repo (not any locally
// generated commit).
//
// Ex.
// 3617b0eea7ec74b8e731a23fed2f4070cbc284c4
string revision = 3;
// The ref that the task used to resolve/fetch the revision of the source
// (if any).
//
// This must always be a ref on the hosted repo (not any local alias
// like 'refs/remotes/...').
//
// This must always be an absolute ref (i.e. starts with 'refs/'). An
// example of a non-absolute ref would be 'master'.
//
// Ex.
// refs/heads/master
string fetch_ref = 4;
// If the checkout had a CL associated with it (i.e. a gerrit commit), this
// is the fully resolved revision (commit hash) of the CL. If there was no
// CL, this is empty. Typically the checkout application (e.g. bot_update)
// rebases this revision on top of the `revision` fetched above.
//
// If specified, this must always be a revision on the hosted repo (not any
// locally generated commit).
//
// Ex.
// 6b0b5c12443cfb93305f8d9e21f8d762c8dad9f0
string patch_revision = 5;
// If the checkout had a CL associated with it, this is the ref that the
// task used to fetch patch_revision. If `patch_revision` is supplied, this
// field is required. If there was no CL, this is empty.
//
// If specified, this must always be a ref on the hosted repo (not any local
// alias like 'refs/remotes/...').
//
// This must always be an absolute ref (i.e. starts with 'refs/').
//
// Ex.
// refs/changes/04/511804/4
string patch_fetch_ref = 6;
}
message CIPDPackage {
// The package pattern that was given to the CIPD client (if known).
//
// Ex.
// infra/tools/luci/led/${platform}
string package_pattern = 1;
// The fully resolved instance ID of the deployed package.
//
// Ex.
// 0cfafb3a705bd8f05f86c6444ff500397fbb711c
string instance_id = 2;
// The unresolved version ID of the deployed package (if known).
//
// Ex.
// git_revision:aaf3a2cfccc227b5141caa1b6b3502c9907d7420
// latest
string version = 3;
}
message Isolated {
// The namespace of the isolated document.
//
// Ex.
// default-gzip
string namespace = 1;
// The hash of the isolated document.
//
// Ex.
// 62a7df62ea122380afb306bb4d9cdac1bc7e9a96
string hash = 2;
}
// A Directory contains one or more descriptions of deployed artifacts. Note
// that due to the practical nature of jobs on bots, it may be the case that
// a given directory contains e.g. a git checkout and multiple cipd packages.
message Directory {
GitCheckout git_checkout = 1;
// The canonicalized hostname of the CIPD server which hosts the CIPD
// packages (if any). If no CIPD packages are in this Directory, this must
// be blank.
//
// Ex.
// chrome-infra-packages.appspot.com
string cipd_server_host = 2;
// Maps CIPD package name to CIPDPackage.
//
// Ex.
// "some/package/name": {...}
// "other/package": {...}
map<string, CIPDPackage> cipd_package = 4;
// The canonicalized hostname of the isolated server which hosts the
// isolated. If no Isolated objects are in this Directory, this must be
// blank.
//
// Ex.
// isolateserver.appspot.com
string isolated_server_host = 5;
// A list of all isolateds which have been installed in this directory.
repeated Isolated isolated = 6;
}
// Map of local file system directory path (with forward slashes) to
// a Directory message containing one or more deployments.
//
// The local path is relative to some job-specific root. This should be used
// for informational/display/organization purposes. In particular, think VERY
// CAREFULLY before you configure remote services/recipes to look for
// particular filesystem layouts here. For example, if you want to look for
// "the version of chromium/src checked out by the job", prefer to look for
// a Directory which checks out "chromium/src", as opposed to assuming this
// checkout lives in a top-level folder called "src". The reason for this is
// that jobs SHOULD reserve the right to do their checkouts in any way they
// please.
//
// If you feel like you need to make some service configuration which uses one
// of these local filesystem paths as a key, please consult with the Chrome
// Infrastructure team to see if there's a better alternative.
//
// Ex.
// "": {...} // root directory
// "src/third_party/something": {...}
map<string, Directory> directories = 2;
}
// Links to an externally stored Manifest proto.
message ManifestLink {
// The fully qualified url of the Manifest proto. It's expected that this is
// a binary logdog stream consisting of exactly one Manifest proto. For now
// this will always be the `logdog` uri scheme, though it's feasible to put
// other uri schemes here later.
//
// Ex.
// logdog://logs.chromium.org/infra/build/12345/+/some/path
string url = 1;
// The hash of the Manifest's raw binary form (i.e. the bytes at the end of
// `url`, without any interpretation or decoding). Milo will use this as an
// optimization; Manifests will be interned once into Milo's datastore.
// Future hashes which match will not be loaded from the url, but will be
// assumed to be identical. If the sha256 doesn't match the data at the URL,
// Milo may render this build with the wrong manifest.
//
// This is the raw sha256, so it must be exactly 32 bytes.
bytes sha256 = 2;
}