This page contains a reference for each directive which can appear in a Layerfile.
For a more introductory reference, see the documentation home
BUILD ENV instruction tells the layerfile to rebuild when a variable changes.
- Commonly used with
$SUBDOMAINto ensure each branch has the proper value:
BUILD ENV SUBDOMAIN RUN echo "HOST=$SUBDOMAIN.mydomain.com" >> .env RUN docker-compose up -d
SUBDOMAIN variable is often used to set the
HOST variable for webservers.
It is a cleaned up version of the
$LAYERCI_BRANCH variable, acceptable for use in a URL.
Common use is to set
DEPLOYMENT_HOST variable is set if a deployment exists for your run.
It’s often used to tell a webserver where it is being hosted.
If there are multiple deployments, a single one is returned.
CI variables are always
true in Layer.
GIT_TAG is the result of running
git describe --always in the repository.
GIT_COMMIT is the result of running
git rev-parse HEAD in the repository.
GIT_COMMIT_TITLE="[improvement] do something"
GIT_CLONE_URL is a token which can be used to clone this repository.
git clone https://[email protected]/org/repo.git
EXPOSE_WEBSITE_HOST is the hostname exposed by
It’s often used to link a frontend with a backend when running both with
EXPOSE WEBSITE and
You can even reference this before
EXPOSE WEBSITE is ever used, but the URL is only live after the run passes.
Note: Unavailable for use by BUILD ENV
LAYERCI is always
true in Layer test runs.
LAYERCI_BRANCH is included if this commit was to a specific branch in the repository.
LAYERCI_BRANCH is not included if this job is running due to an external pull request.
LAYERCI_JOB_ID always exists. It’s set to the ID of the current running job.
LAYERCI_PULL_REQUEST may or may not exist. It’s a link to the pull request that triggered this pipeline.
LAYERCI_REPO_NAME is the name of the repository. If the repository is at github.com/a/b, this would be “b”
LAYERCI_REPO_OWNER is the name of the owner of this repository. If the repository is at github.com/a/b, this would be “a”
LAYERCI_ORG_NAME is the name of the current organization. If the dashboard is at layerci.com/myorg, this would be “myorg”
LAYERCI_RUNNER_ID is the id of the current layerfile runner.
RETRY_INDEX is the current retry for the given runner (initially 1, then when retried once, 2, etc)
API_EXTRA=some data passed from API
API_EXTRA is optional data passed in when a run is started by the API.
CACHE [cached directories...]
CACHE instruction makes specific files/directories be shared across runs, almost always as a performance improvement.
See the tuning performance documentation for more details.
CACHE /var/cache/aptto speed up
RUN apt-get update
CACHE ~/.cache/go-buildto speed up
RUN go install
CACHE ~/.npm ~/.next/cache ~/.yarn/cacheto speed up
Each Layer account gets a fixed amount of cache storage, and we periodically delete old or inactive caches.
CHECKPOINT (name) or
CHECKPOINT instruction allows you to control exactly when Layer will take snapshots of the pipeline.
On future runs, if no files or instructions have changed since the snapshot was taken, the runner will restore the snapshot instead of repeating work.
CHECKPOINT is not usually required, it’s advised not to use it unless you are using the API or there is measurable performance benefit to doing so.
CHECKPOINT disabledto disable checkpointing from that point onwards
CHECKPOINT deployto create a checkpoint named “deploy”, which can be triggered as a lambda from our api
CHECKPOINTto expliticly take a checkpoint at a specific point (which happens automatically by default), or re-enable checkpointing after
See the tuning performance documentation for more details.
COPY [files...] [destination]
COPY instruction moves files from your repository to the runner.
Files can be: - relative (to the layerfile location for sources, and WORKDIR location, or /root if not specified for destination) - absolute (from the root of the repository for sources, and filesystem root for destination)
COPY . .to copy the directory containing the Layerfile to the current working directory (or /root if WORKDIR has not been used)
COPY package.json yarn.lock ./to copy those two files to the current directory.
COPY / /rootto copy the entire repository to /root in the runner.
ENV [key=value...] or
BUILD ENV [key...]
ENV instruction persistently sets environment variables in this Layerfile
$GOPATH/binto the existing path.
ENV CI=hellosets the variable
$CIto the value
EXPOSE WEBSITE [location on runner] (path) (rewrite path)
EXPOSE WEBSITE instruction creates a persistent link to view a webserver running at a specific port in the Layerfile. It’s especially useful for sharing changes with non-technical stakeholders or running manual QA/review.
EXPOSE_WEBSITE_URL environment variable is available even before
EXPOSE WEBSITE if you need to “bake” the path to the exposed website URL.
EXPOSE WEBSITE localhost:80to expose the local webserver at port 80
EXPOSE WEBSITE localhost:80 /apiwith
EXPOSE WEBSITE localhost:3000 /to route all requests that start with /api to port 80 in the runner, and all other requests to port 3000.
FROM instruction tells Layer what base to use to run tests from.
There can only be one
FROM line in a Layerfile, and it must always be the first directive in the Layerfile.
For now, only
FROM vm/ubuntu:18.04 is allowed as a top level, but inheriting from other Layerfiles is possible.
FROM vm/ubuntu:18.04to use ubuntu:18.04 as the base.
FROM ../baseto inherit from the file at
../base/Layerfilerelative to the current Layerfile
FROM /baseto inherit from the file at
MEMORY instruction allows you to reserve memory before you need it.
In particular, languages like
nodejs might require memory to be available before they are used.
We’ll automatically add memory as it’s requested, adding memory with
MEMORY will decrease snapshot speed.
There’s a limit to an additional
4G of memory added at once.
MEMORY 2Gto ensure at least 2 gigabytes of memory are available.
RUN (BACKGROUND|REPEATABLE) [command ...]
RUN instruction runs the given script, and fails the entire Layerfile if the given command fails.
For example, you might use
RUN echo "the directory is $(pwd)" to print your current directory.
RUN echo helloprints “hello” to the terminal
RUN BACKGROUND python3 -m http.serverrun
python3 -m http.serverpersistently in the background.
RUN REPEATABLE docker build -t hellois a performance optimization, see tuning performance
SECRET ENV [secret name...]
SECRET ENV instruction adds values from secrets to the runner’s environment.
Secrets are useful for storing sensitive information. They can hold passwords, API keys, or other private credentials. For security reasons, it is good practice to not keep this information within source code. Managing private data using secrets allows easy authentication with other services on your behalf.
Layer has a secrets manager built into the platform. This makes entering and editing secrets as simple as 1, 2, 3:
Step 1: Navigate to the secrets tab in your Layer account.
Step 2: Click ‘NEW’ in the top right corner. Follow the prompts to choose a secret name, value, and destination repository.
Step 3: All done!
SECRET ENV ENV_FILEto expose your dotfile env
.envand then use
RUN echo "$ENV_FILE" | base64 -d > ~/.envto decode the uploaded env file to the specific location.
Who can create secrets?
Only owners of an organization’s Layer account can create and edit secrets. Permissions can be edited in the members tab, which can be found in the settings dropdown menu. The members tab displays all users in an organization.
Click on the name of a user to display their permissions. Only users with owner-level access can create secrets. An organization’s owner(s) can edit permissions for other users.
SETUP FILE [file ...]
SETUP FILE instruction causes the contents of the given file to be sourced before every
This is equivalent to copy/pasting the contents of the file into the terminal before every
A common use case is to set a lot of environment variables using an “.env” file, or specifying a custom “.bashrc” file.
SETUP FILE .envto run
source (repository root)/.envbefore every
SKIP REMAINING IF
SKIP REMAINING IF [KEY=VALUE]
SKIP REMAINING IF instruction will cause remaining instructions in the Layerfile to be skipped if the condition is evaluated to true.
SKIP REMAINING IF instructions may be declared in one Layerfile.
Conditions may use any variable from
Conditions may use
AND to group statements using logical AND.
Conditions may use
!= to evaluate statements are not true.
SKIP REMAINING IF LAYERCI_BRANCH!=masterto skip execution on any branch that is not master.
SKIP REMAINING IF LAYERCI_BRANCH!=master AND LAYERCI_REPO_NAME !=~ "web"would skip remaining actions if the branch is not master, and the repository name is not “web”
SKIP REMAINING IF GIT_COMMIT_TITLE =~ "\[skip tests\]"would skip remaining actions if the commit title contained “[skip tests]”
SKIP REMAINING IF LAYERCI_BRANCH!=~^(master|dev)$would skip remaining actions if the branch is anything besides
SPLIT instruction causes the runner to duplicate its entire state a number of times at a specific point.
Each copy of the runner will have
SPLIT_NUM environment variables automatically set.
The former will be the index of the runner, and the latter will be the number of copies.
SPLIT 3and three copies of the runner will have
ENV SPLIT=0 SPLIT_NUM=3and
ENV SPLIT=1 SPLIT_NUM=3and so on.
USER instruction allows you to run as a non-root user.
The user is added to the
root group to circumvent permission denied errors.
USER wwwto run the remaining commands as the
WAIT [layerfile paths...]
WAIT instruction allows you to make one step require other steps to succeed before running.
It’s especially useful for conditional actions like executing notifications, deployment, and CI/CD.
Continuous deployment with WAIT
# at deploy/Layerfile FROM vm/ubuntu:18.04 # Wait for the layerfiles at /unit-tests/Layerfile and /acceptance-tests/Layerfile WAIT /unit-tests /acceptance-tests RUN ./notify-slack.sh RUN ./deploy.sh
Conditional deployment with WAIT and BUTTON
# at deploy/Layerfile FROM vm/ubuntu:18.04 # Wait for the layerfiles at /unit-tests/Layerfile and /acceptance-tests/Layerfile WAIT /unit-tests /acceptance-tests RUN ./notify-slack.sh BUTTON deploy? RUN ./deploy.sh
What the job view will look like with WAIT
- Notice that deploy only occurs after all of the other layerfiles have succeeded.
- This layerfile is available here
WORKDIR instruction changes the location from which files are resolved in the runner.
WORKDIR /tmpto run commands in the
/tmpdirectory within the runner.
WORKDIR helloto run commands in the
(workdir)/hellodirectory within the runner.