View on GitHub

Introduction to Devfile

devfile v1

Devfile object Schema

This schema describes the structure of the devfile object

Abstract Extensible Status Identifiable Custom Properties Additional Properties Defined In
Can be instantiated Yes Experimental No Forbidden Forbidden  

Devfile object Properties

Property Type Required Nullable Defined by
apiVersion const Required No Devfile object (this schema)
attributes object Optional No Devfile object (this schema)
commands object[] Optional No Devfile object (this schema)
components object[] Optional No Devfile object (this schema)
metadata object Required No Devfile object (this schema)
projects object[] Optional No Devfile object (this schema)

apiVersion

Devfile API Version

apiVersion

The value of this property must be equal to:

"1.0.0"

attributes

attributes

attributes Type

object with following properties:

| Property | Type | Required | | ——– | —- | ——– |

commands

The Commands List

Description of the predefined commands to be available in workspace

commands

commands Type

Array type: object[]

All items must be of the type: object with following properties:

Property Type Required
actions array Required
attributes   Optional
name string Required
previewUrl object Optional

actions

The Command Actions List

List of the actions of given command. Now the only one command must be specified in list but there are plans to implement supporting multiple actions commands.

actions

actions Type

Array type: object[]

All items must be of the type: object with following properties:

Property Type Required
command string Optional
component string Optional
reference string Optional
referenceContent string Optional
type string Optional
workdir string Optional

command

The actual action command-line string

command

command Type

string

command Example
mvn package

component

Describes component to which given action relates

component

component Type

string

component Example
mvn - stack

reference

the path relative to the location of the devfile to the configuration file defining one or more actions in the editor-specific format

reference

reference Type

string

reference Example
../ide-config/launch.json

referenceContent

The content of the referenced configuration file that defines one or more actions in the editor-specific format

referenceContent

referenceContent Type

string

referenceContent Example
{
  "version": "2.0.0",
  "tasks": [
    {
      "type": "typescript",
      "tsconfig": "tsconfig.json",
      "problemMatcher": ["$tsc"],
      "group": {
        "kind": "build",
        "isDefault": true
      }
    }
  ]
}

type

Describes action type

type

type Type

string

type Example
exec

workdir

Working directory where the command should be executed

workdir

workdir Type

string

workdir Example
/projects/ginprs - petclinic

attributes

Additional command attributes

attributes

attributes Type

name

Describes the name of the command. Should be unique per commands set.

name

name Type

string

name Example
build

previewUrl

previewUrl

previewUrl Type

object with following properties:

Property Type Required
path string Optional
port number Required

path

path

path Type

string

port

port

port Type

number

components

The Components List

Description of the workspace components, such as editor and plugins

components

components Type

Array type: object[]

All items must be of the type: object with following properties:

Property Type Required Default
alias string Optional  
env array Optional  
mountSources boolean Optional "false"
type   Required  

alias

The name using which other places of this devfile (like commands) can refer to this component. This attribute is optional but must be unique in the devfile if specified.

alias

alias Type

string

alias Example
mvn - stack

env

The environment variables list that should be set to docker container

env

env Type

Array type: object[]

All items must be of the type: object with following properties:

Property Type Required
name string Required
value string Required

name

The Environment Variable Name

The environment variable name

name

name Type

string

value

The Environment Variable Value

The environment variable value

value

value Type

string

Describes environment variable

mountSources

Describes whether projects sources should be mount to the component. CHE_PROJECTS_ROOT environment variable should contains a path where projects sources are mount

mountSources

mountSources Type

boolean

type

Describes type of the component, e.g. whether it is an plugin or editor or other type

type

The value of this property must be equal to one of the known values below.

type Known Values
Value Description
cheEditor  
chePlugin  
kubernetes  
openshift  
dockerimage  
type Examples
chePlugin

cheEditor

kubernetes

openshift

dockerimage

metadata

metadata

metadata Type

object with following properties:

Property Type Required
generateName string Optional
name string Optional

generateName

Devfile Generate Name

Workspaces created from devfile, will use it as base and append random suffix. It’s used when name is not defined.

generateName

generateName Type

string

generateName Example
petclinic-

name

Devfile Name

The name of the devfile. Workspaces created from devfile, will inherit this name

name

name Type

string

name Example
petclinic - dev - environment

projects

The Projects List

Description of the projects, containing names and sources locations

projects

projects Type

Array type: object[]

All items must be of the type: object with following properties:

Property Type Required
clonePath string Optional
name string Required
source object Required

clonePath

The path relative to the root of the projects to which this project should be cloned into. This is a unix-style relative path (i.e. uses forward slashes). The path is invalid if it is absolute or tries to escape the project root through the usage of ‘..’. If not specified, defaults to the project name.

clonePath

clonePath Type

string

name

The Project Name

name

name Type

string

name Example
petclinic

source

The Project Source object

Describes the project’s source - type and location

source

source Type

object with following properties:

Property Type Required
branch string Optional
commitId string Optional
location string Required
sparseCheckoutDir string Optional
startPoint string Optional
tag string Optional
type string Required

branch

The name of the of the branch to check out after obtaining the source from the location. The branch has to already exist in the source otherwise the default branch is used. In case of git, this is also the name of the remote branch to push to.

branch

branch Type

string

branch Examples
master

feature - 42

commitId

The id of the commit to reset the checked out branch to. Note that this is equivalent to ‘startPoint’ and provided for convenience.

commitId

commitId Type

string

commitId Example
349d3ad

location

Project’s source location address. Should be URL for git and github located projects, or file:// for zip.

location

location Type

string

location Example
git@github.com:spring-projects/spring-petclinic.git

sparseCheckoutDir

Part of project to populate in the working directory.

sparseCheckoutDir

sparseCheckoutDir Type

string

sparseCheckoutDir Examples
/core/

core/

core

/wsmaster/che-core-api-workspace/

/d*

startPoint

The tag or commit id to reset the checked out branch to.

startPoint

startPoint Type

string

startPoint Examples
release / 4.2

349d3ad

v4.2.0

tag

The name of the tag to reset the checked out branch to. Note that this is equivalent to ‘startPoint’ and provided for convenience.

tag

tag Type

string

tag Example
v4.2.0

type

Project’s source type.

type

type Type

string

type Examples
git

github

zip