Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.goldsky.com/llms.txt

Use this file to discover all available pages before exploring further.

The Compose App manifest is a YAML file that defines your app’s configuration. This is where you configure a list of tasks and other app-level concerns. Each task can be individually configured for things like retry behavior and HTTP trigger behavior, cron schedules and more.

​
App properties

PropertyTypeRequiredDescription
namestringYesUnique app identifier used for API calls. Must start with a lowercase letter, end with a letter or digit, and contain only lowercase letters, digits, and hyphens.
api_versionstringFor deployPins your app to a Compose runtime version. Required by goldsky compose deploy; optional for local dev. Use "stable" if unsure — see Release channels below.
secretsarray(string)NoNames of secrets you’ve set for this app (see Secrets)
envENVNoEnvironment-specific variables
tasksTasks[]YesList of tasks in your app (must contain at least one task)

​
Release channels

api_version pins your app to a Compose runtime version. You can use one of the release channels, or pin to a specific version:
  • "stable" — the current stable runtime. This is the recommended value for production apps.
  • "preview" — the latest pre-release runtime. Use this if you want early access to features that haven’t made it into stable yet. Expect more frequent changes.
  • A specific semver version (e.g. "0.3.0") — pin to an exact runtime version. Useful when you want full control over when your app picks up runtime changes. Do not include a v prefix. See the changelog for available versions.
If your manifest’s api_version is older than the CLI, goldsky compose deploy will warn you and prompt before continuing. Pass -f to skip the prompt.

​
Basic example

name: "my-app"
api_version: "stable"
secrets:
  - MY_SECRET
env:
  local:
    MY_VAR: "foo"
  cloud:
    MY_VAR: "bar"
tasks:
  - name: "price_fetcher"
    path: "./tasks/fetch_price.ts"
    triggers:
      - type: "cron"
        expression: "* * * * *" # Run every minute
      - type: "http"
        authentication: "auth_token"
    retry_config:
      max_attempts: 3
      initial_interval_ms: 1000
      backoff_factor: 2
  - name: "data_processor"
    path: "./tasks/process_data.ts"

​
ENV variables

You can set env variables in your manifest, which are injected into your task’s env context property. Env configuration is namespaced by environment, and only the values for the current environment are injected. Currently there are two environments: local, used when running your compose app locally, and cloud, used when your app is running after goldsky compose deploy — see the deploy guide for more. Values must be strings. For anything sensitive (API keys, private keys), use secrets instead.

​
Example

name: "my-app"
env:
  local:
    MY_VAR: "foo"
    ANOTHER_VAR: "bar"
  cloud:
    MY_VAR: "foo-prod"
    ANOTHER_VAR: "bar-prod"

​
Task configuration

Compose apps are made up of tasks, each task in the tasks array defines an executable unit of work and references a typescript file, see Task Authoring for more details. Tasks can be triggered by HTTP requests from your app, blockchain events, cron schedules, etc. See more about triggers below. Tasks can also trigger other tasks via the callTask context function within the task code. 
name: "my-app"
api_version: "stable"
tasks:
  - name: "unique_task_name" # Required: Unique identifier
    path: "./tasks/my_task.ts" # Required: Path to task file
    triggers:
      - type: "http"
        authentication: "auth_token"
      - type: "cron"
        expression: "*/5 * * * *" # Every 5 minutes
    retry_config: # Optional: Task-level retry settings
      max_attempts: 5
      initial_interval_ms: 2000
      backoff_factor: 1.5

​
Name validation

App names must start with a lowercase letter, end with a letter or digit, and contain only lowercase letters, digits, and hyphens (e.g. my-app-1). Task names must start with a letter (or underscore followed by a letter/digit) and contain only letters, digits, and underscores (e.g. fetch_prices, _internal_task).

​
Task properties

PropertyTypeRequiredDescription
namestringYesUnique task identifier used for API calls
pathstringYesFile path to the task module
triggersarray(object)NoList of triggers that will run the task. Each trigger type can only appear once per task.
retry_configobjectNoTask-level retry behavior

​
Triggers

Triggers are what runs your Compose tasks, these can be HTTP calls, onchain events, or cron jobs. For more information, see Triggers.

​
Example

triggers:
  - type: "cron"
    expression: "* * * * *" # Run every minute (standard cron expression)
  - type: "http"
    authentication: "auth_token"
If you provide no triggers in your manifest then tasks can only be executed by other tasks.

​
Retry configuration

retry_config:
  max_attempts: 3 # Maximum number of retry attempts
  initial_interval_ms: 1000 # Initial delay before first retry
  backoff_factor: 2 # Exponential backoff multiplier
When specifying retry_config, all three fields (max_attempts, initial_interval_ms, backoff_factor) are required. You cannot provide only some of them.
How retries work:
  • If a task fails, Compose waits initial_interval_ms before retrying
  • Each subsequent retry interval is multiplied by backoff_factor
  • Example with above config: 1000ms → 2000ms → 4000ms
  • After max_attempts failures, the task is marked as permanently failed
  • The default retry behaviour is 0 retries (1 attempt, no retries)

​
Manifest examples

​
Multi-chain oracle

name: "multi-chain-oracle"
api_version: "stable"
tasks:
  - name: "fetch_prices"
    path: "./tasks/fetch_crypto_prices.ts"
    retry_config:
      max_attempts: 5
      initial_interval_ms: 2000
      backoff_factor: 1.5

  - name: "update_ethereum_oracle"
    path: "./tasks/update_oracle.ts"
    triggers:
      - type: "cron"
        expression: "* * * * *" # Every minute
    retry_config:
      max_attempts: 3
      initial_interval_ms: 5000
      backoff_factor: 2

  - name: "update_polygon_oracle"
    path: "./tasks/update_oracle.ts"
    triggers:
      - type: "cron"
        expression: "* * * * *" # Every minute

​
Event processing pipeline

name: "event-processor"
api_version: "stable"
tasks:
  - name: "event_processing"
    path: "./tasks/process_events.ts"
    triggers:
      - type: "onchain_event"
        network: "base"
        contract: "0xb74de3F91e04d0920ff26Ac28956272E8d67404D"
        events:
          - "Transfer(address,address,uint256)"
    retry_config:
      max_attempts: 10
      initial_interval_ms: 1000
      backoff_factor: 1.2