Intro

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

The BUILD ENV instruction tells the layerfile to rebuild when a variable changes.

Examples

Commonly used with $SUBDOMAIN to ensure each branch has the proper value:

BUILD ENV SUBDOMAIN
RUN echo "HOST=$SUBDOMAIN.mydomain.com" >> .env
RUN docker-compose up -d

Possible values

SUBDOMAIN

SUBDOMAIN=my-branch

The 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.

feat/add-some-dashboard-pages becomes add-some-dashboard-pages

Common use is to set HOST=$SUBDOMAIN.demo.example.com

DEPLOYMENT_HOST

DEPLOYMENT_HOST=job-5.demo.example.com

The 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

CI=true, IS_CI_MACHINE=true, CI_MACHINE=true, IN_CI_MACHINE=true, IN_CI=true

These CI variables are always true in Layer.

GIT_TAG

GIT_TAG=v1.0.0

GIT_TAG is the result of running git describe --always in the repository.

GIT_COMMIT

GIT_COMMIT=111122223333444455556666777788889999aaaa

GIT_COMMIT is the result of running git rev-parse HEAD in the repository.

GIT_COMMIT_TITLE

GIT_COMMIT_TITLE="[improvement] do something"

GIT_CLONE_USER

GIT_CLONE_USER=x-access-token:<token>

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

EXPOSE_WEBSITE_HOST=(uuid).cidemo.co

EXPOSE_WEBSITE_HOST is the hostname exposed by EXPOSE WEBSITE

It’s often used to link a frontend with a backend when running both with EXPOSE WEBSITE and RUN BACKGROUND

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

LAYERCI=true

LAYERCI is always true in Layer test runs.

LAYERCI_BRANCH

LAYERCI_BRANCH=staging

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

LAYERCI_JOB_ID=5

LAYERCI_JOB_ID always exists. It’s set to the ID of the current running job.

LAYERCI_PULL_REQUEST

LAYERCI_PULL_REQUEST=https://github.com/some/repo/pull_requests/5

LAYERCI_PULL_REQUEST may or may not exist. It’s a link to the pull request that triggered this pipeline.

LAYERCI_REPO_NAME

LAYERCI_REPO_NAME=somerepo

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

LAYERCI_REPO_OWNER=repoowner

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

LAYERCI_ORG_NAME=myorg

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

LAYERCI_RUNNER_ID=main-layerfile

LAYERCI_RUNNER_ID is the id of the current layerfile runner.

RETRY_INDEX

RETRY_INDEX=1

RETRY_INDEX is the current retry for the given runner (initially 1, then when retried once, 2, etc)

API_EXTRA

API_EXTRA=some data passed from API

API_EXTRA is optional data passed in when a run is started by the API.

BUTTON

BUTTON [message...]

The BUTTON instruction allows you to block the progress of a run until the button is pressed.

Examples

Commonly used for deployment: BUTTON would you like to deploy? followed by RUN ./deploy.sh would not deploy unless the button was pressed.

CACHE

CACHE [cached directories...]

The CACHE instruction makes specific files/directories be shared across runs, almost always as a performance improvement.

See the tuning performance documentation for more details.

Examples

Use CACHE /var/cache/apt to speed up RUN apt-get update
Use CACHE ~/.cache/go-build to speed up RUN go install
Use CACHE ~/.npm ~/.next/cache ~/.yarn/cache to speed up npm install and yarn install

Each Layer account gets a fixed amount of cache storage, and we periodically delete old or inactive caches.

CHECKPOINT

CHECKPOINT (name) or CHECKPOINT disabled

The 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.

Examples

Use CHECKPOINT disabled to disable checkpointing from that point onwards
Use CHECKPOINT deploy to create a checkpoint named “deploy”, which can be triggered as a lambda from our api
Use CHECKPOINT to expliticly take a checkpoint at a specific point (which happens automatically by default), or re-enable checkpointing after CHECKPOINT disabled

See the tuning performance documentation for more details.

COPY

COPY [files...] [destination]

The 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)

Examples

Use COPY . . to copy the directory containing the Layerfile to the current working directory (or /root if WORKDIR has not been used)
Use COPY package.json yarn.lock ./ to copy those two files to the current directory.
Use COPY / /root to copy the entire repository to /root in the runner.

ENV

ENV [key=value...] or BUILD ENV [key...]

The ENV instruction persistently sets environment variables in this Layerfile

Examples

ENV PATH=$GOPATH/bin:$PATH adds $GOPATH/bin to the existing path.
ENV CI=hello sets the variable $CI to the value hello.

EXPOSE WEBSITE

EXPOSE WEBSITE [location on runner] (path) (rewrite path)

The 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.

Additionally, the EXPOSE_WEBSITE_URL environment variable is available even before EXPOSE WEBSITE if you need to “bake” the path to the exposed website URL.

Examples

Use EXPOSE WEBSITE localhost:80 to expose the local webserver at port 80
Combine EXPOSE WEBSITE localhost:80 /api with 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

FROM [source]

The 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.

Examples

Use FROM vm/ubuntu:18.04 to use ubuntu:18.04 as the base.
Use FROM ../base to inherit from the file at ../base/Layerfile relative to the current Layerfile
Use FROM /base to inherit from the file at (repo root)/base/Layerfile)

MEMORY

MEMORY [number](K|M|G)

The 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.

Examples

Use MEMORY 2G to ensure at least 2 gigabytes of memory are available.

RUN

RUN (BACKGROUND|REPEATABLE) [command ...]

The 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.

Examples

RUN echo hello prints “hello” to the terminal
RUN BACKGROUND python3 -m http.server run python3 -m http.server persistently in the background.
RUN REPEATABLE docker build -t hello is a performance optimization, see tuning performance

SECRET ENV

SECRET ENV [secret name...]

The 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:

View of secrets page in Layer

Step 1: Navigate to the secrets tab in your Layer account.

View of dialogue box prompting secret creation in Layer

Step 2: Click ‘NEW’ in the top right corner. Follow the prompts to choose a secret name, value, and destination repository.

View of created secret in Layer

Step 3: All done!

Examples

Use SECRET ENV ENV_FILE to expose your dotfile env .env and then use RUN echo "$ENV_FILE" | base64 -d > ~/.env to 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.

View of Layer, highlighting the members tab within the settings menu

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.

View of how permissions are visible below a member’s name in Layer’s members tab

SETUP FILE

SETUP FILE [file ...]

The SETUP FILE instruction causes the contents of the given file to be sourced before every RUN command. This is equivalent to copy/pasting the contents of the file into the terminal before every RUN command.

A common use case is to set a lot of environment variables using an “.env” file, or specifying a custom “.bashrc” file.

Examples

Use SETUP FILE .env to run source (repository root)/.env before every RUN command.

SKIP REMAINING IF

SKIP REMAINING IF [KEY=VALUE]

The SKIP REMAINING IF instruction will cause remaining instructions in the Layerfile to be skipped if the condition is evaluated to true.

Multiple SKIP REMAINING IF instructions may be declared in one Layerfile.

Conditions may use any variable from BUILD ENV.

Conditions may use AND to group statements using logical AND.

Conditions may use != to evaluate statements are not true.

Examples

Use SKIP REMAINING IF LAYERCI_BRANCH!=master to skip execution on any branch that is not master.
Use 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”
Use SKIP REMAINING IF GIT_COMMIT_TITLE =~ "\[skip tests\]" would skip remaining actions if the commit title contained “[skip tests]”
Use SKIP REMAINING IF LAYERCI_BRANCH!=~^(master|dev)$ would skip remaining actions if the branch is anything besides master or dev

SPLIT

SPLIT [n]

The 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 and SPLIT_NUM environment variables automatically set. The former will be the index of the runner, and the latter will be the number of copies.

Examples

Use SPLIT 3 and three copies of the runner will have ENV SPLIT=0 SPLIT_NUM=3 and ENV SPLIT=1 SPLIT_NUM=3 and so on.

USER

USER [username]

The USER instruction allows you to run as a non-root user.

The user is added to the root group to circumvent permission denied errors.

Examples

Use USER www to run the remaining commands as the www user.

WAIT

WAIT [layerfile paths...]

The 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.

Examples

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

Advanced workflow graph example

Notice that deploy only occurs after all of the other layerfiles have succeeded.
This layerfile is available here

WORKDIR

WORKDIR [directory]

The WORKDIR instruction changes the location from which files are resolved in the runner.

Examples

Use WORKDIR /tmp to run commands in the /tmp directory within the runner.
Use WORKDIR hello to run commands in the (workdir)/hello directory within the runner.

Edit these docs