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.

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

{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

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

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