Setup

You need an HTTP library installed to use the Layer API. See code pane for details.

#in bash terminal
gem install bundler
bundle install faraday

#at top of file
require 'faraday'
require 'json'

#in bash terminal
pip install requests

#at top of file
import requests

#in bash terminal (ubuntu)
sudo apt-get update
sudo apt-get install -y curl ca-certificates

#other distributions - google "how to install curl"

//for javascript, we use use fetch()
//for nodejs, https://www.npmjs.com/package/node-fetch
//i.e., npm install --save node-fetch

CI Jobs

Layerfile runner objects

Each time you look at the dashboard for a run, you’re looking at a collection of layerfile runners. Each layerfile runner is created by a specific Layerfile, or by a Layerfile being retried.

CI jobs are a collection of Layerfile runners!

Example schema

{
    "repository_name": "layerci-example",
    "id": 1,
    "status": "SEE_RUNNERS",
    "status_change_time": "2000-01-01 01:23:45.123456 +0000 UTC",
    "calculated_status": "SUCCEEDED",
    "commit_sha": "9abc2ac68d52afe1a5a3fbc724d031af5a397204",
    "branch": "master",
    "merge_branch": "master",
    "run_start_reason": "Manual run created by API",
    "run_start_reason_url": ""
}

status vs. calculated_status

CI jobs themselves maintain an internal status which is either:

NEW for pending jobs
ERROR for jobs that have had some error while initializing (e.g., invalid layerfiles)
STARTING_RUNNERS for jobs which are in the process of starting runners
SEE_RUNNERS for jobs which have started runners. This status means you must look at the runners themselves to understand the status.

CI jobs also contain a status which is the calculated status of the whole job, looking at the runners. The calculated status is usually what you’ll use to determine the status of an entire run.

The calculated_status of a CI job is one of the following:

NEW for pending jobs
JOB_ERROR for jobs that have had an internal while initializing (e.g., internal errors in Layer occurred when starting this run)
BAD_LAYERFILE for jobs that had an invalid Layerfile
STARTING_RUNNERS means that runners are in the process of being started for this job.
FAILURE means that at least one runner failed (some instruction for that runner is red) - again, there can be multiple Layerfiles per repository and if either fails.
RUNNER_CANCELLED means that a user manually cancelled at least one runner
RUNNER_ERROR means that at least one runner had an internal error while running
RUNNING means that the runner itself is running
SUCCEEDED means that the runner succeeded

Get most recent CI job for a repository matching a search query

It’s often useful to get the most recent CI job given specific filters. This API endpoint allows for that.

require 'faraday'
require 'json'

# get the most recent failing jobs
res = Faraday.get 'https://layerci.com/api/v1/run/repo_name/search?search=status%3Asucceeded&layertoken=(your api key)'

res = JSON.parse(res.body)

import requests

# get the most recent failing job
my_token="(your API key)"
res = requests.get(
    f'https://layerci.com/api/v1/run/repo_name/search?search=status%3Asucceeded&layertoken={my_token}', 
).json()

# get the most recent failing job
my_token="(your API key)"
curl 'https://layerci.com/api/v1/run/repo_name/search?search=status%3Asucceeded&layertoken=${my_token}' | python -m json.tool

let apiKey="(your API key)"
fetch(
    'https://layerci.com/api/v1/run/repo_name/search?search=status%3Asucceeded&layertoken='+apiKey,
).then(res => res.json()).then(json => console.log(json))

Output:

{
    "status": "ok",
    "job": {
        "repository_name": "layerci-example",
        "id": 3,
        "status": "SEE_RUNNERS",
        "status_change_time": "2000-01-01 01:23:45.123456 +0000 UTC",
        "calculated_status": "SUCCEEDED",
        "commit_sha": "9abc2ac68d52afe1a5a3fbc724d031af5a397204",
        "branch": "master",
        "merge_branch": "master",
        "run_start_reason": "Manual run created by API",
        "run_start_reason_url": ""
    }
}

– or –

{
    "error": "There are no runs in layerdemo/layerci-example matching the given filters.",
    "status": "error"
}

The search query for /search and the main dashboard’s searchbar are the same, and can include:

natural text
“quoted exact text”
-minus -some -terms that should not appear in the author, commit body, or title of the commit.
repo:(the repository name) to match an exact repository name
branch:(the branch name) to match an exact (case sensitive) branch name
id:(the id) to match an exact run id
status:(status) to match a calculated status
running to match a run which is running
done to match a run which is not running
failed to match a run which has suffered a failure or error

Example query

text to find in commit body "exact text" -layer -ci repo:layer-example-repo branch:main id:10 status:running done running failed

Create a CI job for a given repository

Sometimes it’s useful to manually start LayerCI runs (for, e.g., deploying) This endpoint lets you do that.

The input to the POST is optional, but can contain:

branch=master to check out the “master” branch. If omitted, we use “master”
ref=9abc2ac68d52afe1a5a3fbc724d031af5a397204 to check out a specific commit. If omitted, we use “origin/master”
accept_buttons=true to accept any BUTTON instructions in the job (i.e., to deploy automatically)
skip_no_further_than=(CHECKPOINT name) to avoid skipping certain actions (e.g., deployment) - this lets you use Layer as a cheap lambda.
extra - extra data exposed in the run as API_EXTRA, useful for passing arbitrary data in

require 'faraday'
require 'json'

res = Faraday.post(
    'https://layerci.com/api/v1/run/repo_name?layertoken=(your api key)',
    {
        branch: 'master',
        ref: '9abc2ac68d52afe1a5a3fbc724d031af5a397204',
        accept_buttons: 'true',
        skip_no_further_than: 'run-and-deploy',
        extra: 'some extra data exposed as API_EXTRA variable',
    }.to_json
)

res = JSON.parse(res.body)

import requests

my_token="(your API key)"
res = requests.post(
    f'https://layerci.com/api/v1/run/repo_name?layertoken={my_token}',
    json={
        'branch': 'master',
        'ref': '9abc2ac68d52afe1a5a3fbc724d031af5a397204',
        'accept_buttons': 'true',
        'skip_no_further_than': 'run-and-deploy',
        'extra': 'some extra data exposed as API_EXTRA variable',
    },
).json()

my_token="(your API key)"
curl -X POST \
    -H 'Content-Type: application/json' \
    -d '{"branch": "master", \
         "ref": "9abc2ac68d52afe1a5a3fbc724d031af5a397204", \
         "accept_buttons": "true", \
         "skip_no_further_than": "run-and-deploy", \
         "extra": "some extra data exposed as API_EXTRA variable" \
        }' \
    "https://layerci.com/api/v1/run/repo_name?layertoken=${my_token}"

let apiKey="(your API key)"
fetch(
    'https://layerci.com/api/v1/run/repo_name?layertoken='+apiKey,
    {
        method: "POST",
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            'branch': 'master',
            'ref': '9abc2ac68d52afe1a5a3fbc724d031af5a397204',
            'accept_buttons': 'true',
            'skip_no_further_than': 'run-and-deploy',
            'extra': 'some extra data exposed as API_EXTRA variable',
        }),
    }
).then(res => res.json()).then(json => console.log(json))