builds

Creates, updates, deletes, gets or lists a builds resource.

Overview

Name	builds
Type	Resource
Id	netlify.builds.builds

Fields

The following fields are returned by SELECT queries:

list

Name	Datatype	Description
id	string
deploy_id	string
created_at	string (dateTime)
done	boolean
error	string
sha	string

get

Name	Datatype	Description
id	string
deploy_id	string
created_at	string (dateTime)
done	boolean
error	string
sha	string

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list	select	site_id	page, per_page
get	select	build_id
create	insert	site_id	branch, clear_cache, image, template_id, title	Runs a build for a site. The build will be scheduled to run at the first opportunity, but it might not start immediately if insufficient account build capacity is available.<br /><br />Files for build can be uploaded as a zipped site using one of these methods:<br />1. Set Content-Type to 'application/zip' and send the zip file as the raw request body<br />2. Set Content-Type to 'multipart/form-data' and include the zip file in the 'zip' field<br />
update_log	exec	build_id
notify_start	exec	build_id	buildbot_version, build_version, task_id

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
build_id	string
site_id	string
branch	string	If no branch is specified, it is treated as a production deploy If a branch IS specified and matches the main branch, it is also production If a branch is specified and doesn't match the main branch, it is a branch deploy
build_version	string
buildbot_version	string
clear_cache	boolean	Whether to clear the build cache before building
image	string	The build image tag to use for the build
page	integer (int32)
per_page	integer (int32)
task_id	string
template_id	string	The build template to use for the build
title	string	The title of the build

SELECT examples

list

OK

SELECT
id,
deploy_id,
created_at,
done,
error,
sha
FROM netlify.builds.builds
WHERE site_id = '{{ site_id }}' -- required
AND page = '{{ page }}'
AND per_page = '{{ per_page }}'
;

get

OK

SELECT
id,
deploy_id,
created_at,
done,
error,
sha
FROM netlify.builds.builds
WHERE build_id = '{{ build_id }}' -- required
;

INSERT examples

create

Runs a build for a site. The build will be scheduled to run at the first opportunity, but it might not start immediately if insufficient account build capacity is available.<br /><br />Files for build can be uploaded as a zipped site using one of these methods:<br />1. Set Content-Type to 'application/zip' and send the zip file as the raw request body<br />2. Set Content-Type to 'multipart/form-data' and include the zip file in the 'zip' field<br />

INSERT INTO netlify.builds.builds (
zip,
site_id,
branch,
clear_cache,
image,
template_id,
title
)
SELECT 
'{{ zip }}',
'{{ site_id }}',
'{{ branch }}',
'{{ clear_cache }}',
'{{ image }}',
'{{ template_id }}',
'{{ title }}'
RETURNING
id,
deploy_id,
created_at,
done,
error,
sha
;

Manifest

# Description fields are for documentation purposes
- name: builds
props:
  - name: site_id
    value: "{{ site_id }}"
    description: Required parameter for the builds resource.
  - name: zip
    value: "{{ zip }}"
    description: |
      A zip file containing the site files to build.
      Only used with Content-Type 'multipart/form-data'.
      Alternatively, set Content-Type to 'application/zip' and send the zip as the raw request body (no 'zip' parameter needed).
  - name: branch
    value: "{{ branch }}"
    description: If no branch is specified, it is treated as a production deploy If a branch IS specified and matches the main branch, it is also production If a branch is specified and doesn't match the main branch, it is a branch deploy
    description: If no branch is specified, it is treated as a production deploy If a branch IS specified and matches the main branch, it is also production If a branch is specified and doesn't match the main branch, it is a branch deploy
  - name: clear_cache
    value: {{ clear_cache }}
    description: Whether to clear the build cache before building
    description: Whether to clear the build cache before building
  - name: image
    value: "{{ image }}"
    description: The build image tag to use for the build
    description: The build image tag to use for the build
  - name: template_id
    value: "{{ template_id }}"
    description: The build template to use for the build
    description: The build template to use for the build
  - name: title
    value: "{{ title }}"
    description: The title of the build
    description: The title of the build

Lifecycle Methods

update_log

No content

EXEC netlify.builds.builds.update_log 
@build_id='{{ build_id }}' --required
;

notify_start

No content

EXEC netlify.builds.builds.notify_start 
@build_id='{{ build_id }}' --required, 
@buildbot_version='{{ buildbot_version }}', 
@build_version='{{ build_version }}', 
@task_id='{{ task_id }}'
;