v1
Double column
API
CLI
JS Client

Jobs /

Create manual job

Creates a new manual job that only runs when initiated via the UI, CLI, API or JS client.

Required permission

Project > Jobs > General > Create

Path parameters

    • projectId

      string required

      ID of the project

Request body

  • {object}
    • name

      string required

      The name of the job.

      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 job.

      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-]+$
    • backoffLimit

      integer required

      The number of attempts to rerun a job before it is marked as failed.

    • activeDeadlineSeconds

      integer

      The maximum amount of time, in seconds, for a job to run before it is marked as failed.

      min
      1
    • deployment

      (multiple options)

      Where to deploy the job from.

      • {object}

        Deploy from version control

        • vcs

          {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-]+$
          • projectBranch

            string required

            The name of the branch to use.

        OR

      • {object}

        Deploy from an external image

        • external

          {object} required
          • imagePath

            string required

            Path of the external image excluding the hostname

          • credentials

            string

            ID of the saved credentials to use to access this external image.

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

        OR

      • {object}

        Deploy from a Northflank build service

        • internal

          {object} required
          • id

            string

            ID of the build service to deploy

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

            string

            Branch to deploy

          • buildSHA

            Commit SHA to deploy, or 'latest' to deploy the most recent commit

    • buildSettings

      (multiple options)
      • {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-._]*$
    • environment

      {object}

      An object containing the environment variables to set for the job.

      • buildArguments

        {object}

        An object containing the build arguments to set for the job.

      Response body

      • {object}

        Response object.

        • data

          {object} required

          Result data.

          • id

            string required

            Identifier for the job

          • appId

            string required

            Full identifier used for job deployment

          • name

            string required

            Job name

          • description

            string

            A short description of the job

          • projectId

            string required

            ID of the project that the service belongs to

          • createdAt

            string required

            The time the job was created.

          • 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

          • buildEngineConfiguration

            {object}
            • 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.

          • disabledCI

            boolean required

            Whether Continuous Integration is disabled

          • disabledCD

            boolean required

            Whether Continuous Deployment is disabled

          • deployment

            {object}
            • region

              string

              Region where this job is deployed and built

          • billing

            {object} required
            • deploymentPlan

              string required

              ID of the billing plan used by this job

          • jobType

            string required

            Type of the job (manual or cron)

            one of
            cron, manual
          • settings

            {object} required

            Job settings

            • backoffLimit

              integer required

              The number of attempts to rerun a job before it is marked as failed.

            • activeDeadlineSeconds

              integer required

              The maximum amount of time, in seconds, for a job to run before it is marked as failed.

              min
              1
            • cron

              {object}
            • buildInitiated

              boolean required

              Whether the job will be built immediately

        API
        CLI
        JS Client

        POST /v1/projects/{projectId}/jobs/manual

        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"},"backoffLimit":0,"activeDeadlineSeconds":600,"deployment":{"vcs":{"projectUrl":"https://github.com/northflank/gatsby-with-northflank","projectType":"github","projectBranch":"master"}},"buildSettings":{"dockerfile":{"buildEngine":"kaniko","dockerFilePath":"/Dockerfile","dockerWorkDir":"/"}},"environment":{"variable1":"abcdef","variable2":"12345"},"buildArguments":{"variable1":"abcdef","variable2":"12345"}}' \
          https://api.northflank.com/v1/projects/{projectId}/jobs/manual

        Example response

        200 OK

        Details about the newly created job.

        JSON

        {
          "data": {
            "id": "example-job",
            "appId": "/example-user/default-project/example-job",
            "name": "Example Job",
            "description": "This is the job description",
            "projectId": "default-project",
            "createdAt": "2021-01-20T11:19:53.175Z",
            "vcsData": {
              "projectUrl": "https://github.com/northflank/gatsby-with-northflank",
              "projectType": "github",
              "vcsId": "example-team/self-hosted-vcs",
              "projectBranch": "master",
              "publicRepo": false,
              "dockerWorkDir": "/",
              "dockerFilePath": "/Dockerfile"
            },
            "buildEngineConfiguration": {
              "builder": "buildpack",
              "buildpack": {
                "builder": "HEROKU_20",
                "buildpackLocators": [
                  "https://buildpack-registry.heroku.com/cnb/mars/create-react-app"
                ]
              }
            },
            "disabledCI": false,
            "disabledCD": false,
            "deployment": {
              "region": "europe-west"
            },
            "billing": {
              "deploymentPlan": "nf-compute-20"
            },
            "jobType": "manual",
            "settings": {
              "backoffLimit": 0,
              "activeDeadlineSeconds": 600,
              "cron": {}
            },
            "buildInitiated": true
          }
        }

        © 2021 Northflank Ltd. All rights reserved.