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]((-|\s)?[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.

    • runOnSourceChange

      string

      Configure when the job should be run if the source image changes.

      one of
      never, cd-promote, always
    • 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

        • cmdOverride

          string

          If set, the job runs a custom command rather than one defined in the Dockerfile.

        • entrypointOverride

          string

          If set, the job runs a custom entrypoint rather than one defined in the Dockerfile.

        • storage

          {object}
          • ephemeralStorage

            {object}
            • storageSize

              integer

              Ephemeral storage per container in MB

              one of
              1024, 5120, 10240, 20480
              min
              1024
              max
              20480
        • vcs

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

          • projectBranch

            string required

            The name of the branch to use.

        OR

      • {object}

        Deploy from an external image

        • cmdOverride

          string

          If set, the job runs a custom command rather than one defined in the Dockerfile.

        • entrypointOverride

          string

          If set, the job runs a custom entrypoint rather than one defined in the Dockerfile.

        • storage

          {object}
          • ephemeralStorage

            {object}
            • storageSize

              integer

              Ephemeral storage per container in MB

              one of
              1024, 5120, 10240, 20480
              min
              1024
              max
              20480
        • external

          {object} required
          • imagePath

            string required

            Image to be deployed. When not deploying from Dockerhub the URL must be specified.

            pattern
            ^(?:(?:https?:\/\/)?([a-zA-Z0-9\-]+\.[a-zA-Z0-9\.\-]+)(\/v1)?)?(?:\/)?([a-zA-Z/-9\.\-_]+)(?:\:([a-zA-Z/-9\.\-_\:]+)|\@([a-zA-Z/-9\.\-_\:]+))$
          • 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

        • cmdOverride

          string

          If set, the job runs a custom command rather than one defined in the Dockerfile.

        • entrypointOverride

          string

          If set, the job runs a custom entrypoint rather than one defined in the Dockerfile.

        • storage

          {object}
          • ephemeralStorage

            {object}
            • storageSize

              integer

              Ephemeral storage per container in MB

              one of
              1024, 5120, 10240, 20480
              min
              1024
              max
              20480
        • 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

          • buildId

            string

            ID of the build that should be deployed

        OR

      • {object}

        Choose later

      • buildConfiguration

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

      • buildSettings

        (multiple options)
        • {object}

          Build from a Dockerfile

          • dockerfile

            {object} required
            • buildEngine

              string

              Build engine to use. Defaults to recommended build engine kaniko

              one of
              kaniko, buildkit
            • useCache

              boolean

              Should intermediate image layers be cached? Only supported by Kaniko.

            • 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} required
            • 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, 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-._]*$
      • runtimeEnvironment

        {object}

        An object containing the runtime environment to set for the job. Keys must only contain letters and numbers separated with underscores, may not start with a number

        • runtimeFiles

          {object}

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

          • buildArguments

            {object}

            An object containing the build arguments to set for the job. Keys must only contain letters and numbers separated with underscores, may not start with a number

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

                • 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 job belongs to

                • createdAt

                  date 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
                  • selfHostedVcsId

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

                • buildEngineConfiguration

                  {object}
                  • buildEngine

                    string

                    The build engine used.

                    one of
                    buildpack, kaniko, buildkit
                  • buildpack

                    {object}

                    Details about Buildpack settings.

                    • builder

                      string

                      The Buildpack stack used.

                      one of
                      HEROKU_20, HEROKU_18, GOOGLE_V1, CNB_ALPINE, CNB_BIONIC, PAKETO_TINY, PAKETO_BASE, PAKETO_FULL
                    • buildpackLocators

                      [array]

                      Array of custom Buildpacks used.

                      • string

                        Url or registry identifier of custom Buildpack.

                  • kaniko

                    {object}

                    Details about Kaniko settings.

                    • useCache

                      boolean

                      Should intermediate image layers be cached?

                • 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

                  • docker

                    {object}

                    Details about the Docker overrides for this deployment.

                    • cmd

                      {object} required

                      Details about the CMD override for this deployment.

                      • enabled

                        boolean required

                        Whether the CMD override is enabled.

                      • value

                        string required

                        The CMD to run instead of the default if CMD override is enabled.

                    • entrypoint

                      {object} required

                      Details about the entrypoint override for this deployment.

                      • enabled

                        boolean required

                        Whether the entrypoint override is enabled.

                      • value

                        string required

                        The CMD to run instead of the default if entrypoint override is enabled.

                  • storage

                    {object}

                    Details about storage settings for this deployment.

                    • ephemeralStorage

                      {object}

                      Details about ephemeral storage settings for this deployment.

                      • storageSize

                        number required

                        Ephemeral storage per container in MB

                • 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
                  manual, cron
                • 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 Job","description":"A job description","billing":{"deploymentPlan":"nf-compute-20"},"backoffLimit":0,"runOnSourceChange":"never","activeDeadlineSeconds":600,"deployment":{"cmdOverride":"nginx -g","entrypointOverride":"/custom-entrypoint.sh","storage":{"ephemeralStorage":{"storageSize":1024}},"vcs":{"projectUrl":"https://github.com/northflank/gatsby-with-northflank","projectType":"github","accountLogin":"github-user","projectBranch":"master"}},"buildConfiguration":{"pathIgnoreRules":["README.md"]},"buildSettings":{"dockerfile":{"buildEngine":"kaniko","useCache":false,"dockerFilePath":"/Dockerfile","dockerWorkDir":"/"}},"runtimeEnvironment":{"variable1":"abcdef","variable2":"12345"},"runtimeFiles":{"/dir/fileName":{"data":"VGhpcyBpcyBhbiBleGFtcGxlIHdpdGggYSB0ZW1wbGF0ZWQgJHtOT0RFX0VOVn0gdmFyaWFibGU=","encoding":"utf-8"}},"buildArguments":{"variable1":"abcdef","variable2":"12345"},"buildFiles":{"/dir/fileName":{"data":"VGhpcyBpcyBhbiBleGFtcGxlIHdpdGggYSB0ZW1wbGF0ZWQgJHtOT0RFX0VOVn0gdmFyaWFibGU=","encoding":"utf-8"}}}' \
                http://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",
                    "selfHostedVcsId": "example-team/self-hosted-vcs",
                    "projectBranch": "master",
                    "publicRepo": false,
                    "dockerWorkDir": "/",
                    "dockerFilePath": "/Dockerfile"
                  },
                  "buildConfiguration": {
                    "pathIgnoreRules": [
                      "README.md"
                    ]
                  },
                  "buildEngineConfiguration": {
                    "buildEngine": "buildpack",
                    "buildpack": {
                      "builder": "HEROKU_20",
                      "buildpackLocators": [
                        "https://buildpack-registry.heroku.com/cnb/mars/create-react-app"
                      ]
                    },
                    "kaniko": {}
                  },
                  "disabledCI": false,
                  "disabledCD": false,
                  "deployment": {
                    "region": "europe-west",
                    "docker": {
                      "cmd": {
                        "enabled": true,
                        "value": "nginx -g"
                      },
                      "entrypoint": {
                        "enabled": true,
                        "value": "/docker-entrypoint.sh"
                      }
                    },
                    "storage": {
                      "ephemeralStorage": {
                        "storageSize": 1024
                      }
                    }
                  },
                  "billing": {
                    "deploymentPlan": "nf-compute-20"
                  },
                  "jobType": "manual",
                  "settings": {
                    "backoffLimit": 0,
                    "activeDeadlineSeconds": 600,
                    "cron": {}
                  },
                  "buildInitiated": true
                }
              }

              © 2022 Northflank Ltd. All rights reserved.