common/proto/srcman/manifest.proto

// 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;
  }

  // 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;

    reserved 5, 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;
}