Services /

Create build service

Creates a new build service.

Required permission

Project > Services > General > Create

Path parameters

projectId
string required
ID of the project

Request body

{object}

name
string required
The name of the service.
min length
3
max length
20
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+((-|\s)[a-zA-Z0-9]+)*)?$
description
string
A description of the service.
max length
200
pattern
^[a-zA-Z0-9.,?\s\\/'"()[\];`%^&*\-_:!]+$
billing
{object} required

deploymentPlan
string required
The ID of the deployment plan to use.
pattern
^[A-Za-z0-9-]+$

vcsData
{object} required

projectUrl
string required
URL of the Git repo to build.
projectType
string required
The VCS provider to use.
one of
bitbucket, gitlab, github, self-hosted
vcsId
string
If projectType is self-hosted, the ID of the self-hosted vcs to use.
pattern
^[A-Za-z0-9-]+\/[A-Za-z0-9-]+$

buildSettings
(multiple options) required

{object}

Build from a Dockerfile

dockerfile
{object}

buildEngine
string
Build engine to use. Defaults to recommended build engine kaniko
one of
kaniko, buildkit
dockerFilePath
string required
The file path of the Dockerfile.
pattern
^\/([a-zA-Z0-9-._]+\/)*[a-zA-Z0-9-._]+$
dockerWorkDir
string required
The working directory of the Dockerfile.
pattern
^\/([a-zA-Z0-9-._]+\/)*[a-zA-Z0-9-._]*$

{object}

Build from a Buildpack

buildpack
{object}

builder
string
Buildpack stack to use. Defaults to recommended stack HEROKU_20.
one of
HEROKU_20, HEROKU_18, GOOGLE_V1, CNB_ALPINE, CNB_BIONIC, PAKETO_TINY
buildpackLocators
[array]
Array of custom Buildpacks to use.

string
Url or registry identifier of custom Buildpack.

buildContext
string
The working directory to build in.
pattern
^\/([a-zA-Z0-9-._]+\/)*[a-zA-Z0-9-._]*$

buildConfiguration
{object}

branchRestrictions
[array]

string
pattern
^[a-zA-Z/*0-9-]*$

prRestrictions
[array]

string
pattern
^[a-zA-Z/*0-9-]*$

buildArguments
{object}
An object containing the build arguments to set for the service

Response body

{object}
Response object.

data
{object} required
Result data.

id
string required
Identifier for the service
appId
string required
Full identifier used for service deployment
name
string required
Service name
description
string
A short description of the service
projectId
string required
ID of the project that the service belongs to
createdAt
string required
The time the service was created.
disabledCI
boolean required
Whether Continuous Integration is disabled
disabledCD
boolean required
Whether Continuous Deployment is disabled
billing
{object} required

deploymentPlan
string required
ID of the billing plan used by this service

serviceType
string required
Type of the service (combined, build or deployment)
one of
combined, build, deployment
vcsData
{object}

projectUrl
string required
URL of the repository being built
projectType
string required
VCS provider for the repo being built
one of
bitbucket, gitlab, github, self-hosted
vcsId
string
ID of the self-hosted VCS, if applicable.
projectBranch
string
Branch of the repo being built
publicRepo
boolean
Whether the repo is being accessed without authentication.
dockerWorkDir
string required
Working directory used by the dockerfile
dockerFilePath
string required
File path of the Dockerfile

buildConfiguration
{object}

branchRestrictions
[array] required

string

prRestrictions
[array] required

string

buildEngineConfiguration
{object} required

builder
string
The build engine used.
one of
buildpack, kaniko, buildkit
buildpack
{object}

builder
string
The Buildpack stack used.
one of
HEROKU_20, HEROKU_18, GOOGLE_V1, CNB_ALPINE, CNB_BIONIC, PAKETO_TINY
buildpackLocators
[array]
Array of custom Buildpacks used.

string
Url or registry identifier of custom Buildpack.

API

CLI

JS Client

POST /v1/projects/{projectId}/services/build

Example request

Request body

curl

curl --header "Content-Type: application/json" \
  --header "Authorization: Bearer NORTHFLANK_API_TOKEN" \
  --request POST \
  --data '{"name":"Example Service","description":"A service description","billing":{"deploymentPlan":"nf-compute-20"},"vcsData":{"projectUrl":"https://github.com/northflank/gatsby-with-northflank","projectType":"github"},"buildSettings":{"dockerfile":{"buildEngine":"kaniko","dockerFilePath":"/Dockerfile","dockerWorkDir":"/"}},"buildConfiguration":{"branchRestrictions":["feature/*"],"prRestrictions":["feature/*"]},"buildArguments":{"ARGUMENT_1":"abcdef","ARGUMENT_2":"12345"}}' \
  https://api.northflank.com/v1/projects/{projectId}/services/build

Example response

200 OK

Details about the newly created service.

JSON

{
  "data": {
    "id": "example-service",
    "appId": "/example-user/default-project/example-service",
    "name": "Example Service",
    "description": "This is the service description",
    "projectId": "default-project",
    "createdAt": "2021-01-20T11:19:53.175Z",
    "disabledCI": false,
    "disabledCD": false,
    "billing": {
      "deploymentPlan": "nf-compute-20"
    },
    "serviceType": "build",
    "vcsData": {
      "projectUrl": "https://github.com/northflank/gatsby-with-northflank",
      "projectType": "github",
      "vcsId": "example-team/self-hosted-vcs",
      "projectBranch": "master",
      "publicRepo": false,
      "dockerWorkDir": "/",
      "dockerFilePath": "/Dockerfile"
    },
    "buildConfiguration": {
      "branchRestrictions": [
        "feature/*"
      ],
      "prRestrictions": [
        "feature/*"
      ]
    },
    "buildEngineConfiguration": {
      "builder": "buildpack",
      "buildpack": {
        "builder": "HEROKU_20",
        "buildpackLocators": [
          "https://buildpack-registry.heroku.com/cnb/mars/create-react-app"
        ]
      }
    }
  }
}

Example response

409 Conflict

There is already a service with the same derived identifier