Skip to content

Latest commit

 

History

History
221 lines (162 loc) · 6.83 KB

project-descriptor.md

File metadata and controls

221 lines (162 loc) · 6.83 KB
Raw

Project Descriptor

A project descriptor is a file that MAY contain configuration for apps, services, functions, and buildpacks. By default, the file SHOULD be named project.toml and located in the root directory of a project's repository. A platform SHOULD read the file to enrich the build process.

Table of Contents

Schema Version

This document specifies Project Descriptor Schema Version 0.2.

The Schema Version format follows the form of the Buildpack API Version:

  • MUST be in form . or , where is equivalent to .0
  • When is greater than 0 increments to SHALL exclusively indicate additive changes

Special Value Types

Top Level Tables

Non-_ Tables

All other tables besides _ will use reverse domains, i.e. buildpacks.io will be [io.buildpacks]. These tables can be optionally versioned with a schema version number using the schema-version field. All these tables are optional.

_

The TOML schema of the project section of the project descriptor:

[_]
schema-version = "<schema-version>"
id = "<string>" # machine readable
name = "<string>" # human readable
version = "<string>"
authors = ["<string>"]
documentation-url = "<uri>"
source-url = "<uri>"

[[_.licenses]]
type = "<string>"
uri = "<uri>"

[_.metadata]
# additional arbitrary keys allowed

The top-level _ table MAY contain configuration about the repository, including id and version. It MAY also include metadata about how it is authored, documented, and version controlled. It MUST contain schema-version to denote which schema version the descriptor is using.

[_]
schema-version = "<string>"
id = "<string>"
name = "<string>"
version = "<string>"
authors = ["<string>"]
documentation-url = "<uri>"
source-url = "<uri>"
  • schema-version - version identifier for the schema of the _ table and structure of the project descriptor file.
  • id - (optional) the machine readable identifier of the project (ex. "com.example.myservice")
  • name - (optional) the human readable name of the project (ex. "My Example Service")
  • version - (optional) and arbitrary string representing the version of the project
  • authors - (optional) the names and/or email addresses of the project's authors
  • documentation-url - (optional) a URL to the documentation for the project.
  • source-url - (optional) a URL to the source code for the project

_.licenses (optional)

This table MAY contain project licenses.

[[_.licenses]]
type = "<string>"
uri = "<uri>"
  • type - This MAY use the SPDX 2.1 license expression, but is not limited to identifiers in the SPDX Licenses List.
  • uri - If this project is using a nonstandard license, then this key MAY be specified in lieu of or in addition to type to point to the license.

_.metadata (optional)

This is a free form table for users to use as they see fit. The keys in this table are not validated.

[_.metadata.foo]
checksum = "a28a0d7772df1f918da2b1102da4ff35"

io.buildpacks (optional)

This is the Cloud Native Buildpacks' section of the project descriptor. The TOML schema is the following:

[io.buildpacks]
builder = "<string>"
include = ["<string>"]
exclude = ["<string>"]

[[io.buildpacks.group]]
id = "<string>"
version = "<string>"
uri = "<string>"

[[io.buildpacks.build.env]]
name = "<string>"
value = "<string>"

io.buildpacks.builder (optional)

This is the builder image to use (ex. "cnbs/sample-builder:bionic").

io.buildpacks.include (optional) and io.buildpacks.exclude (optional)

An optional list of files to include in the build (while excluding everything else): This MAY contain a list of files to include in the build (while excluding everything else):

[io.buildpacks]
include = [
    "cmd/",
    "go.mod",
    "go.sum",
    "*.go"
]

A list of files to exclude from the build (while including everything else):

[io.buildpacks]
exclude = [
    "spec/"
]

The .gitignore pattern is used in both cases. The exclude and include keys are mutually exclusive, and if both are present the Lifecycle will error out.

Any files that are excluded (either via include or exclude) MUST BE excluded before the build (i.e. not only excluded from the final image).

If both exclude and include are defined, the build process MUST result in an error.

io.buildpacks.group (optional)

This table MAY contain an array of buildpacks. The schema for this table is:

[[io.buildpacks.group]]
id = "<buildpack ID (optional)>"
version = "<buildpack version (optional default=latest)>"
uri = "<url or path to the buildpack (optional default=urn:buildpack:<id>)"

This defines the buildpacks that a platform should use on the repo.

Either an id or a uri MUST be included, but MUST NOT include both. If uri is provided, version MUST NOT be allowed.

io.buildpacks.env.build (optional)

This table MAY be used to set environment variables at build time, for example:

[[io.buildpacks.env.build]]
name = "JAVA_OPTS"
value = "-Xmx1g"

Example

[_]
id = "io.buildpacks.my-app"
version = "0.1"

[_.metadata]
cdn = "https://cdn.example.com"

[[_.metadata.assets]]
url = "https://cdn.example.com/assets/foo.jar"
checksum = "3b1b39893d8e34a6d0bd44095afcd5c4"

buzz = ["a", "b", "c"]

[io.buildpacks]
builder = "cnbs/sample-builder:bionic"
include = [
    "cmd/",
    "go.mod",
    "go.sum",
    "*.go"
]

[[io.buildpacks.group]]
id = "io.buildpacks/java"
version = "1.0"

[[io.buildpacks.gruop]]
id = "io.buildpacks/nodejs"
version = "1.0"