Create build service | Services | Northflank API docs
v1
ApplicationAPI & CLI
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
      39
      pattern
      ^[a-zA-Z]((-|\s)?[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\\/'"()[\];`%^&*\-_:!]+$

    • tags

      [array]

      An array of previously defined tags to help identify and group the resource.

      • string
        min length
        3
        max length
        39
        pattern
        ^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$

    • billing

      {object} required

      • deploymentPlan

        string

        The ID of the deployment plan to use. (Deprecated - use buildPlan for build resources instead.).

        pattern
        ^[A-Za-z0-9-]+$

      • buildPlan

        string

        The ID of the build plan to use.

        pattern
        ^[A-Za-z0-9-]+$

      • gpu

        {object}

        • enabled

          boolean

        • configuration

          {object}

          • gpuType

            string required

          • timesliced

            boolean

    • disabledCI

      boolean

      Whether CI (continuous integration) should be disabled.

    • vcsData

      {object} required

      • projectUrl

        string required

        URL of the Git repo to build.

        pattern
        ^(https:\/\/)?((www(\.[a-zA-Z0-9\-]{2,})+\.)?[a-zA-Z0-9\-]{2,})(\.([a-zA-Z0-9\-]{2,}))+(\/([a-zA-Z0-9\-._]{2,}))+?$

      • projectType

        string required

        The VCS provider to use.

        one of
        bitbucket, gitlab, github, self-hosted

      • selfHostedVcsId

        string

        If projectType is self-hosted, the ID of the self-hosted vcs to use.

        pattern
        ^[A-Za-z0-9-]+\/[A-Za-z0-9-]+$

      • accountLogin

        string

        By default, if you have multiple version control accounts of the same provider linked, Northflank will pick a linked account that has access to the repository. If accountLogin is provided, Northflank will instead use your linked account with that login name.

      • vcsLinkId

        string

        By default, if you have multiple version control accounts of the same provider linked, Northflank will pick a linked account that has access to the repository. If vcsLinkId is provided, Northflank will instead use your linked account with that ID.

        min length
        24
        max length
        24

    • buildSettings

      (multiple options: oneOf) required
      • {object}

        Build from a Dockerfile

        • storage

          {object}

          • ephemeralStorage

            {object}

            • storageSize

              integer

              Ephemeral storage per build in MB

              one of
              16384, 32768, 65536, 131072, 262144, 524288
              min
              16384
              max
              65536

        • dockerfile

          {object} required

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

          • useCache

            boolean

            Should intermediate image layers be cached?

        OR

      • {object}

        Build from a Buildpack

        • storage

          {object}

          • ephemeralStorage

            {object}

            • storageSize

              integer

              Ephemeral storage per build in MB

              one of
              16384, 32768, 65536, 131072, 262144, 524288
              min
              16384
              max
              65536

        • buildpack

          {object} required

          • builder

            string

            Buildpack stack to use. Defaults to recommended stack HEROKU_22.

            one of
            HEROKU_22, HEROKU_22_CLASSIC, HEROKU_20, HEROKU_18, GOOGLE_V1, CNB_ALPINE, CNB_BIONIC, PAKETO_TINY, PAKETO_BASE, PAKETO_FULL

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

          • useCache

            boolean

            Should build dependencies be cached?

    • buildConfiguration

      {object}

      • prRestrictions

        [array]

        An array of pull request build rules. Only supported for build services. Each commit belonging to a pull request on a branch that matches one of the provided build rules will be built automatically.

        • string

          A pull request build rule. Can contain * as a wildcard to match multiple branch names. For example, feature/* will build all commits from pull requests from branches that start with feature/.

          pattern
          ^[^?:@$~ [\]{}]*$

      • branchRestrictions

        [array]

        An array of branch build rules. Only supported for build services. Each commit belonging to a branch that matches one of the provided build rules will be built automatically.

        • string

          A branch build rule. Can contain * as a wildcard to match multiple branch names. For example, feature/* will build all commits from branches that start with feature/.

          pattern
          ^[^?:@$~ [\]{}]*$

      • pathIgnoreRules

        [array]

        An array of path ignore rules. A commit will only be built if a file has been changed that does not match any of the ignore rules. Path ignore rules follow .gitignore syntax.

        • string

          A path ignore rule, following .gitignore syntax. For example, *.md will ignore all files ending with .md.

          max length
          260

      • isAllowList

        boolean

        If true, the functionality of pathIgnoreRules will be inverted. A commit will only be built if a file has been changed that matches one or more of the rules in pathIgnoreRules.

      • ciIgnoreFlagsEnabled

        boolean

        If true, enables commit ignore flags. If a commit message contains one or more of the flags in ciIgnoreFlags, that commit will not be built.

      • ciIgnoreFlags

        [array]

        An array of commit ignore flags. If a commit message contains one or more of these flags, that commit will not be built. Defaults to ["[skip ci]", "[ci skip]", "[no ci]", "[skip nf]", "[nf skip]", "[northflank skip]", "[skip northflank]"]

        • string

          A commit ignore flag.

          max length
          72

      • dockerfileTarget

        string

        If your Dockerfile contains multiple build stages, you can specify the target stage by entering its name here.

      • dockerCredentials

        [array]
        • string

          The ID of the docker credentials to use.

          pattern
          ^[A-Za-z0-9-]+$

      • includeGitFolder

        boolean

        Include .git folder inside the build context

      • fullGitClone

        boolean

        Include the entire git history as part of the .git folder. Only relevant if "includeGitFolder" is set.

      • storage

        {object}

        • ephemeralStorage

          {object}

          • storageSize

            integer

            Ephemeral storage per build in MB

            one of
            16384, 32768, 65536, 131072, 262144, 524288
            min
            16384
            max
            65536

    • buildArguments

      {object}

      An object containing the build arguments to set for the service

      • buildFiles

        {object}

        Secret files as JSON object, encrypted at rest. File path must be absolute

      Response body

      • {object}

        Response object.

        • data

          {object} required

          Result data.

          • name

            string required

            The name of the service.

            min length
            3
            max length
            39
            pattern
            ^[a-zA-Z]((-|\s)?[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\\/'"()[\];`%^&*\-_:!]+$

          • tags

            [array]

            An array of previously defined tags to help identify and group the resource.

            • string
              min length
              3
              max length
              39
              pattern
              ^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$

          • billing

            {object} required

            • deploymentPlan

              string

              The ID of the deployment plan to use. (Deprecated - use buildPlan for build resources instead.).

              pattern
              ^[A-Za-z0-9-]+$

            • buildPlan

              string

              The ID of the build plan to use.

              pattern
              ^[A-Za-z0-9-]+$

            • gpu

              {object}

              • enabled

                boolean

              • configuration

                {object}

                • gpuType

                  string required

                • timesliced

                  boolean

          • disabledCI

            boolean

            Whether CI (continuous integration) should be disabled.

          • vcsData

            {object} required

            • projectUrl

              string required

              URL of the Git repo to build.

              pattern
              ^(https:\/\/)?((www(\.[a-zA-Z0-9\-]{2,})+\.)?[a-zA-Z0-9\-]{2,})(\.([a-zA-Z0-9\-]{2,}))+(\/([a-zA-Z0-9\-._]{2,}))+?$

            • projectType

              string required

              The VCS provider to use.

              one of
              bitbucket, gitlab, github, self-hosted

            • selfHostedVcsId

              string

              If projectType is self-hosted, the ID of the self-hosted vcs to use.

              pattern
              ^[A-Za-z0-9-]+\/[A-Za-z0-9-]+$

            • accountLogin

              string

              By default, if you have multiple version control accounts of the same provider linked, Northflank will pick a linked account that has access to the repository. If accountLogin is provided, Northflank will instead use your linked account with that login name.

            • vcsLinkId

              string

              By default, if you have multiple version control accounts of the same provider linked, Northflank will pick a linked account that has access to the repository. If vcsLinkId is provided, Northflank will instead use your linked account with that ID.

              min length
              24
              max length
              24

          • buildSettings

            (multiple options: oneOf) required
            • {object}

              Build from a Dockerfile

              • storage

                {object}

                • ephemeralStorage

                  {object}

                  • storageSize

                    integer

                    Ephemeral storage per build in MB

                    one of
                    16384, 32768, 65536, 131072, 262144, 524288
                    min
                    16384
                    max
                    65536

              • dockerfile

                {object} required

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

                • useCache

                  boolean

                  Should intermediate image layers be cached?

              OR

            • {object}

              Build from a Buildpack

              • storage

                {object}

                • ephemeralStorage

                  {object}

                  • storageSize

                    integer

                    Ephemeral storage per build in MB

                    one of
                    16384, 32768, 65536, 131072, 262144, 524288
                    min
                    16384
                    max
                    65536

              • buildpack

                {object} required

                • builder

                  string

                  Buildpack stack to use. Defaults to recommended stack HEROKU_22.

                  one of
                  HEROKU_22, HEROKU_22_CLASSIC, HEROKU_20, HEROKU_18, GOOGLE_V1, CNB_ALPINE, CNB_BIONIC, PAKETO_TINY, PAKETO_BASE, PAKETO_FULL

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

                • useCache

                  boolean

                  Should build dependencies be cached?

          • buildConfiguration

            {object}

            • prRestrictions

              [array]

              An array of pull request build rules. Only supported for build services. Each commit belonging to a pull request on a branch that matches one of the provided build rules will be built automatically.

              • string

                A pull request build rule. Can contain * as a wildcard to match multiple branch names. For example, feature/* will build all commits from pull requests from branches that start with feature/.

                pattern
                ^[^?:@$~ [\]{}]*$

            • branchRestrictions

              [array]

              An array of branch build rules. Only supported for build services. Each commit belonging to a branch that matches one of the provided build rules will be built automatically.

              • string

                A branch build rule. Can contain * as a wildcard to match multiple branch names. For example, feature/* will build all commits from branches that start with feature/.

                pattern
                ^[^?:@$~ [\]{}]*$

            • pathIgnoreRules

              [array]

              An array of path ignore rules. A commit will only be built if a file has been changed that does not match any of the ignore rules. Path ignore rules follow .gitignore syntax.

              • string

                A path ignore rule, following .gitignore syntax. For example, *.md will ignore all files ending with .md.

                max length
                260

            • isAllowList

              boolean

              If true, the functionality of pathIgnoreRules will be inverted. A commit will only be built if a file has been changed that matches one or more of the rules in pathIgnoreRules.

            • ciIgnoreFlagsEnabled

              boolean

              If true, enables commit ignore flags. If a commit message contains one or more of the flags in ciIgnoreFlags, that commit will not be built.

            • ciIgnoreFlags

              [array]

              An array of commit ignore flags. If a commit message contains one or more of these flags, that commit will not be built. Defaults to ["[skip ci]", "[ci skip]", "[no ci]", "[skip nf]", "[nf skip]", "[northflank skip]", "[skip northflank]"]

              • string

                A commit ignore flag.

                max length
                72

            • dockerfileTarget

              string

              If your Dockerfile contains multiple build stages, you can specify the target stage by entering its name here.

            • dockerCredentials

              [array]
              • string

                The ID of the docker credentials to use.

                pattern
                ^[A-Za-z0-9-]+$

            • includeGitFolder

              boolean

              Include .git folder inside the build context

            • fullGitClone

              boolean

              Include the entire git history as part of the .git folder. Only relevant if "includeGitFolder" is set.

            • storage

              {object}

              • ephemeralStorage

                {object}

                • storageSize

                  integer

                  Ephemeral storage per build in MB

                  one of
                  16384, 32768, 65536, 131072, 262144, 524288
                  min
                  16384
                  max
                  65536

          • buildArguments

            {object}

            An object containing the build arguments to set for the service

            • buildFiles

              {object}

              Secret files as JSON object, encrypted at rest. File path must be absolute

              • serviceType

                string required

                Type of the service (combined, build or deployment)

                one of
                build

              • id

                string required

                Identifier for the service

              • appId

                string required

                Full identifier used for service deployment

              • cluster

                {object}

                • id

                  required
                  one of
                  aws-cluster-id

                • name

                  required
                  one of
                  AWS Cluster Name

                • namespace

                  one of
                  ns-krbfnmxfv5x8-

              • createdAt

                string

                time of creation

              • updatedAt

                string

                time of update

              • status

                {object} required

                Details about the current service status.

                • build

                  {object}

                  Details about the status of the most recent build.

                  • status

                    string required

                    The current status of the build.

                    one of
                    QUEUED, PENDING, STARTING, CLONING, BUILDING, UPLOADING, ABORTED, FAILURE, SUBMISSION_FAILURE, SUCCESS, CRASHED

                  • lastTransitionTime

                    string

                    The timestamp of when the build reached this status.

          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","tags":["my-tag"],"billing":{"deploymentPlan":"nf-compute-20","buildPlan":"nf-compute-200-8"},"vcsData":{"projectUrl":"https://github.com/northflank/gatsby-with-northflank","projectType":"github","accountLogin":"github-user"},"buildSettings":{"storage":{"ephemeralStorage":{"storageSize":16384}},"dockerfile":{"buildEngine":"kaniko","dockerFilePath":"/Dockerfile","dockerWorkDir":"/","useCache":false}},"buildConfiguration":{"prRestrictions":["feature/*"],"branchRestrictions":["feature/*"],"pathIgnoreRules":["README.md"],"isAllowList":false,"ciIgnoreFlags":["[skip ci]"],"dockerCredentials":["example-docker-credential"],"storage":{"ephemeralStorage":{"storageSize":16384}}},"buildArguments":{"ARGUMENT_1":"abcdef","ARGUMENT_2":"12345"},"buildFiles":{"/dir/fileName":{"data":"VGhpcyBpcyBhbiBleGFtcGxlIHdpdGggYSB0ZW1wbGF0ZWQgJHtOT0RFX0VOVn0gdmFyaWFibGU=","encoding":"utf-8"}}}' \
  https://api.northflank.com/v1/projects/{projectId}/services/build

          Example response

          200 OK

          Details about the newly created service.

          JSON

          {
  "data": {
    "name": "Example Service",
    "description": "A service description",
    "tags": [
      "my-tag"
    ],
    "billing": {
      "deploymentPlan": "nf-compute-20",
      "buildPlan": "nf-compute-200-8"
    },
    "vcsData": {
      "projectUrl": "https://github.com/northflank/gatsby-with-northflank",
      "projectType": "github",
      "accountLogin": "github-user"
    },
    "buildSettings": {
      "storage": {
        "ephemeralStorage": {
          "storageSize": 16384
        }
      },
      "dockerfile": {
        "buildEngine": "kaniko",
        "dockerFilePath": "/Dockerfile",
        "dockerWorkDir": "/",
        "useCache": false
      }
    },
    "buildConfiguration": {
      "prRestrictions": [
        "feature/*"
      ],
      "branchRestrictions": [
        "feature/*"
      ],
      "pathIgnoreRules": [
        "README.md"
      ],
      "isAllowList": false,
      "ciIgnoreFlags": [
        "[skip ci]"
      ],
      "dockerCredentials": [
        "example-docker-credential"
      ],
      "storage": {
        "ephemeralStorage": {
          "storageSize": 16384
        }
      }
    },
    "buildArguments": {
      "ARGUMENT_1": "abcdef",
      "ARGUMENT_2": "12345"
    },
    "buildFiles": {
      "/dir/fileName": {
        "data": "VGhpcyBpcyBhbiBleGFtcGxlIHdpdGggYSB0ZW1wbGF0ZWQgJHtOT0RFX0VOVn0gdmFyaWFibGU=",
        "encoding": "utf-8"
      }
    },
    "serviceType": "build",
    "id": "example-service",
    "appId": "/example-user/default-project/example-service",
    "status": {
      "build": {
        "status": "SUCCESS",
        "lastTransitionTime": "2021-11-29T11:47:16.624Z"
      }
    }
  }
}

          Example response

          409 Conflict

          There is already a service with the same derived identifier

          © 2024 Northflank Ltd. All rights reserved.

          northflank.comTermsPrivacyfeedback@northflank.com