Intro

This page contains a reference for each directive which can appear in a Layerfile.

For a more introductory reference, see the documentation home

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

Build Environment variables

Some environment variables are dynamically set for the run and can be used in RUN directives. BUILD ENV allows you to rerun a step whenever one of those variables change.

BUILD ENV example

FROM vm/ubuntu:18.04
BUILD ENV LAYERCI_BRANCH
RUN echo "the current branch is: $LAYERCI_BRANCH"

CI

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

These CI variables are always true in LayerCI.

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

LAYERCI

LAYERCI=true

LAYERCI is always true in LayerCI 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.

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 LayerCI 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. It’s useful for authenticating LayerCI with other services on your behalf.

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.

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.

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

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