v1
Double column
API
CLI
JS Client

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-._]*$

        OR

      • {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

    © 2021 Northflank Ltd. All rights reserved.