Tork Documentation

Tork jobs support dynamic values through inputs and sensitive data through secrets.

Inputs

Use the inputs block to define variables that can be referenced in tasks using the {{ inputs.key_name }} syntax.

Secrets

Use the secrets block for sensitive information. These values are automatically redacted in API responses. Reference them in tasks using the {{ secrets.key_name }} syntax.

Note: When passing secrets to a task's environment, use the expression language to map them to environment variables.

name: my job
inputs:
  source: https://example.com/path/to/video.mov
secrets:
  api_key: 1111-1111-1111-1111
tasks:
  - name: my task
    image: alpine:latest
    env:
      SOURCE_URL: '{{ inputs.source }}'
      API_KEY: '{{ secrets.api_key }}'
    run: curl -X POST -H "API_KEY: $API_KEY" http://example.com

A task is the fundamental unit of execution in Tork. When using the Docker runtime, each task runs in its own container. A task requires an image (the Docker image to use) and a run property (the script or command to execute).

To capture output from a task for use in subsequent tasks, write to the $TORK_OUTPUT environment variable. You can also assign a var name to the task to store its result in the job context.

name: hello job
tasks:
  - name: say hello
    var: task1
    image: ubuntu:mantic
    run: |
      echo -n hello world > $TORK_OUTPUT

You can configure Tork to notify external services when a job or task changes state using the webhooks block. You can use the if conditional to trigger webhooks only on specific states.

Supported events:

• job.StateChange
• task.StateChange

name: my job
webhooks:
  - url: http://example.com/my/webhook
    event: job.StateChange
    headers:
      my-header: somevalue
    if: "{{ job.State == 'COMPLETED' }}"
tasks:
  - name: my task
    image: alpine:latest
    run: echo hello world

Tork supports several mount types for providing storage to tasks:

• volume: A Docker volume (ephemeral, removed when the task ends).
• bind: A host path mounted into the container.
• tmpfs: An in-memory mount (Linux only).

pre and post tasks run on the same worker as the main task and share its mounts and networks.

name: mounts job
tasks:
  - name: convert the first 5 seconds of a video
    image: jrottenberg/ffmpeg:3.4-alpine
    run: ffmpeg -i /tmp/my_video.mov -t 5 /tmp/output.mp4
    mounts:
      - type: volume
        target: /tmp
    pre:
      - name: download the remote file
        image: alpine:3.18.3
        run: wget http://example.com/my_video.mov -O /tmp/my_video.mov

You can embed Tork into your own Go applications by importing the github.com/runabol/tork/cli and github.com/runabol/tork/conf packages. To start the engine, you must first load the configuration using conf.LoadConfig() and then execute the CLI instance using cli.New().Run().

package main

import (
	"fmt"
	"os"
	"github.com/runabol/tork/cli"
	"github.com/runabol/tork/conf"
)

func main() {
	if err := conf.LoadConfig(); err != nil {
		fmt.Println(err)
		os.Exit(1)
	}
	if err := cli.New().Run(); err != nil {
		fmt.Println(err)
		os.Exit(1)
	}
}

Tork uses the expr language for expressions. You can access several context namespaces: inputs, secrets, tasks, and job.

Use the if property on a task to perform conditional execution based on an expression.

name: conditional job
inputs:
  run: 'true'
tasks:
  - name: say something
    if: "{{ inputs.run == 'true' }}"
    image: ubuntu:mantic
    run: echo "this runs only when inputs.run is 'true'"

Tork supports scheduled jobs using standard cron syntax. To use this, submit your job definition to the /scheduled-jobs endpoint instead of the /jobs endpoint.

name: scheduled job test
schedule:
  cron: "0/5 * * * *"   # every 5 minutes
tasks:
  - name: my first task
    image: alpine:3.18.3
    run: echo -n hello world

Submit via API:

curl -s -X POST --data-binary @job.yaml \
  -H "Content-type: text/yaml" \
  http://localhost:8000/scheduled-jobs | jq .

You can pass data between tasks using the var property and the tasks context namespace. A task writes its result to $TORK_OUTPUT, and the next task can access it using the expression {{ tasks.<VAR_NAME> }}.

name: output and variables job
tasks:
  - name: populate a variable
    var: task1
    image: ubuntu:mantic
    run: echo -n "world" > "$TORK_OUTPUT"
  - name: say hello
    image: ubuntu:mantic
    env:
      NAME: '{{ tasks.task1 }}'
    run: echo -n hello $NAME

Tork can be configured using a config.toml file or environment variables.

Config File Locations:

1. Current directory
2. ~/tork/config.toml
3. /etc/tork/config.toml

You can override the config file location using the TORK_CONFIG environment variable.

Environment Variables: Use the prefix TORK_ followed by the property path with dots replaced by underscores (e.g., TORK_LOGGING_LEVEL=warn).

TORK_CONFIG=myconfig.toml ./tork run standalone

A Task in Tork exists in one of several states. You can use the TaskState type to track or filter tasks. The TaskStateActive slice identifies states where a task is still in progress or waiting to be processed.

Available States:

• CREATED
• PENDING
• SCHEDULED
• RUNNING
• CANCELLED
• STOPPED
• COMPLETED
• FAILED
• SKIPPED

Use the IsActive() method on a Task instance to check if it is currently in an active state (CREATED, PENDING, SCHEDULED, or RUNNING).

// Example checking if a task is active
if task.IsActive() {
    fmt.Println("Task is currently in progress or queued")
}