Recipe Syntax
For documentation on legacy recipe syntaxes (i.e. v1 and v2, please reach out to support@devzero.io)
A recipe is a definition of a workspace. It consists of a base workspace configuration, and a set of steps to be executed. Let's look at a simple recipe:
Steps
Steps while optional are the core tool that you will use to configure your workspace and prepare it for work. Steps can be executed either during build time or launch time. This is accomplished by placing the steps in the corresponding section:
The file hello_launch
will get created during your workspace startup, while the file hello
will be created at build time.
You can most step you want between launch and build phases of the recipe. But keep in mind that doing more work during the launch of the container will make your workspace start slower.
At the moment we have following step types available:
Command
The bread and butter step, pretty much everything you need can be accomplished using this step.
You can have multiline commands, for example:
File
Creates a file with some content.
Paths are not using shell expansion, so you have to write out /home/devzero/projects rather than ~/projects
Directory
Creates a directory.
Same as with files path is not expanded, so ~ and environment variables will not be replaced with corresponding values
Apt Get
Installs apt packages.
We also support an easy way to add extra repositories, for example:
Or:
You can also specify components:
Git Clone
Clones a git repository.
Semantics for the directory are explained in git documentation.
Secrets and Environment variables
Commands often require either their environment to be set up correctly, or secrets to access private resources. Both of these can be managed on a per team or a per user basis.
System secrets are in the namespace
devzero
currently only one such secret existsdevzero.GITHUB_ACCESS_TOKEN
this token is populated using github account information for the user who is invoking the build
Environment variables
If you want to set a particular environment variable to some value you have to do it for each phase separatly. Phases being build
, launch
and runtime
.
Build time environment variables
Build time secrets can only come from team secrets or system (devzero) secrets. These environment variables will be available to any command executed within build phase, any values that make it into the final image will be part of it and will be available to anyone who launches the workspace.
Launch time environment variables
Launch time secrets can be sourced from both team and user secrets. These environment variables will be available to launch commands defined in the recipe. This does not include systemd units defined outside of the recipe (for example if you install docker or mysql, environment variables defined here will not be visible to startup scripts for these tools).
Runtime environment variables
Runtime environment variables will be present in any session (ssh, vscode, vscode terminal) started on the workspace.
Runtime environment variable customization is a bit special in that it supports Shell expansion (as opposed to build and launch environment variable settings). This is so you could configure development environment for your engineers more easily.
Customizing individual commands
You can provide environment variables to a single command only. The syntax for the variable is the same as for global ones for example:
The variable can come from both - the recipe or secrets registry.
Repository access
At the moment build time and launch time repository access can be controlled either automatically by using associated Github access credentials, or can be customized on a per step / per recipe basis. If you don't do any customization of the recipe, personal Github credentials for the user who triggered the build will be used during build time. But if the git-clone step is part of the recipe launch phase, we will use the credentials associated with the user who is starting the workspace.
Sometimes though it makes sense to use shared team secret as a way to control git access instead. You can do this by providing a code_clone_credentials
section in the recipe configuration section:
Currently we support two types of credentials: ssh-private-key
and github-token
. Credentials set in config will be used for all git operations during build
and launch
phases for all git-clone
steps.
You are also able to provide git credentials to an individual git step as follows:
Secrets as files
Sometimes a secret value (like an ssh key) is not very useful when it's stuck in an environment variable. To help you with this you can make sure the value is available as a file within a scope of a command, or as part of your workspace for example:
Will ensure that while executing git clone
command, the secret is available as /etc/gitconfig
Secrets mounted this way will only be available during the execution of the command, so they will not be part of the final workspace build. As opposed to files created using the file
step.
You can populate any file from secrets by using the standard file step:
Be careful using this during build phase, as you might embed secrets into the build, which usualy is not what you want.
Configuration
There are some more advanced configuration options for your workspace. These should be used with care, and most of the time you don't really need to change them.
Git clone root
By default all the repositories are cloned in /home/devzero
directory directly, but in some cases you might want your code to be cloned somewhere else like /home/devzero/projects
for example. To achieve that just add a config section with code_clone_root
set:
Code clone credentials
We already discussed default code clone credentials in the secrets section.
Volumes
Workspaces are based on docker containers, thus not everything is persisted across restarts. You can control which directories you want to persist by setting the volumes attribute in the config section:
These are the default volumes that are being persisted. Make sure to include at least /home/devzero
in the list when customizing it, otherwise your workspace might be completely ephemeral.
Secret interpolation language
Environment values and file contents are special in that you can embed secret values into them. The syntax is quite simple:
As you can see - the structure of the expression consists of 3 parts - source (at the moment only secret
is supported) namespace (user
, team
or devzero
) matching user secret registry, team registry, or system secrets like devzero.GITHUB_ACCESS_TOKEN
that comes from github account linked to your devzero account if present and secret name.
As we are using curly braces for variable interpolation, make sure you quote the strings properly:
Note: User secrets cannot be accessed during build time. However, all user secrets are automatically available as environment variables within each user's workspace.