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
      54
      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
        1
        max length
        100
        pattern
        ^[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, azure

      • selfHostedVcsId

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

      • 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
      Build engine
      • {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?

          • buildkit

            {object}

            • useInternalCache

              boolean

            • internalCacheStorage

              number

        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
            54
            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
              1
              max length
              100
              pattern
              ^[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, azure

            • selfHostedVcsId

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

            • 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
            Build engine
            • {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?

                • buildkit

                  {object}

                  • useInternalCache

                    boolean

                  • internalCacheStorage

                    number

              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} required
                Cluster information

                • id

                  string required
                  The id of the cluster associated with this project.

                • name

                  string required
                  The name of the cluster associated with this project.

                • namespace

                  string
                  Namespace this resource is located within on the cluster.

                • loadBalancers

                  [array]
                  Load balancer DNS for the cluster.
                  • string

              • 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",
    "cluster": {
      "id": "nf-europe-west",
      "name": "nf-europe-west",
      "namespace": "ns-8zy2mcjh9zn2",
      "loadBalancers": [
        "lb.659200800000000000000000.northflank.com"
      ]
    },
    "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