You need an HTTP library installed to use the webapp.io API. See code pane for details.
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!
status vs. calculated_status
CI jobs themselves maintain an internal status which is either:
NEWfor pending jobs
ERRORfor jobs that have had some error while initializing (e.g., invalid layerfiles)
STARTING_RUNNERSfor jobs which are in the process of starting runners
SEE_RUNNERSfor 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.
calculated_status of a CI job is one of the following:
NEWfor pending jobs
JOB_ERRORfor jobs that have had an internal while initializing (e.g., internal errors in webapp.io occurred when starting this run)
BAD_LAYERFILEfor jobs that had an invalid Layerfile
STARTING_RUNNERSmeans that runners are in the process of being started for this job.
FAILUREmeans 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_CANCELLEDmeans that a user manually cancelled at least one runner
RUNNER_ERRORmeans that at least one runner had an internal error while running
RUNNINGmeans that the runner itself is running
SUCCEEDEDmeans 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.
-- or --
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
runningto match a run which is running
doneto match a run which is not running
failedto match a run which has suffered a failure or error
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 webapp.io runs (for, e.g., deploying) This endpoint lets you do that.
The input to the POST is optional, but can contain:
branch=masterto check out the "master" branch. If omitted, we use "master"
ref=9abc2ac68d52afe1a5a3fbc724d031af5a397204to check out a specific commit. If omitted, we use "origin/master"
accept_buttons=trueto accept any BUTTON instructions in the job (i.e., to deploy automatically)
extra- extra data exposed in the run as API_EXTRA, useful for passing arbitrary data in
status can be one of
"error". If the latter exists, an
"error" value will be included with an explanation.