Preset Tasks¶

Overview¶

Preset Tasks let you instantiate versioned, ready-made task scripts from a catalog repository hosted on GitHub. Instead of writing a script from scratch, you pick a preset from the catalog, provide the required config and secrets, and JustIAM creates the scheduled task with the script snapshotted from that version.

Key properties:

The script is immutable for a given version — use Upgrade to move to a newer release.
Config values and secrets are stored separately from the snapshot and can be updated at any time without upgrading.
Every preset task runs as a normal preset-type scheduled task, benefiting from the same run history, cron scheduling, and manual triggering as any other task.

Preset Sources¶

A Preset Source is a catalog URL — a GitHub raw content prefix — that JustIAM fetches manifests from.

Official source¶

A built-in source is always available. It points to the official JustIAM preset catalog and does not require authentication.

Custom sources¶

Custom catalog repositories can be added in Infrastructure → Preset Sources (requires the preset_sources.manage permission) or via the API:

POST /api/v1/preset-sources
Content-Type: application/json

{
  "name": "Internal Catalog",
  "url": "https://raw.githubusercontent.com/acme/idp-presets/main",
  "auth_type": "github_token",
  "secrets": {
    "token": "<github-pat>"
  }
}

auth_type values:

Value	Description	Required secret keys
`none`	Public repository — no credentials needed	—
`github_token`	Personal access token	`token`
`github_app`	GitHub App installation — full JWT flow	`github_app_client_id`, `github_app_installation_id`, `github_app_private_key`
`github_app`	GitHub App — pre-generated installation token (fallback)	`installation_token`

For github_app, if github_app_client_id, github_app_installation_id, and github_app_private_key are all provided, JustIAM generates a short-lived RS256 JWT and exchanges it for an installation access token automatically. Alternatively, provide only installation_token for a simpler but less automatic setup.

Signature verification¶

To protect against tampered or hijacked catalog files, a preset source can be pinned to a minisign public key. When a public key is registered, JustIAM verifies the integrity of every downloaded file before caching or executing it.

How it works:

The catalog publisher generates a keypair once and signs a checksums.txt file (SHA-256 hashes of all catalog files) on every release.
The public key is registered in JustIAM when adding or editing the preset source.
On every cache refresh or on-demand fetch, JustIAM downloads checksums.txt and checksums.txt.minisig, verifies the Ed25519 signature, then checks the SHA-256 of each downloaded file.
Any mismatch (tampered file, wrong key, missing entry) causes the entire source to be rejected — it is never cached or executed.

Publisher workflow (per release):

# One-time keypair generation
minisign -G -p catalog.pub -s catalog.key

# After any change to catalog files
sha256sum catalog.json $(find presets -name '*.yaml' | sort) > checksums.txt
minisign -S -s catalog.key -m checksums.txt

# Commit catalog.json, presets/, checksums.txt, checksums.txt.minisig
# Keep catalog.key offline / in a secrets manager

Registering the key via API:

POST /api/v1/preset-sources
Content-Type: application/json

{
  "name": "Signed Internal Catalog",
  "url": "https://raw.githubusercontent.com/acme/idp-presets/main",
  "auth_type": "github_token",
  "public_key": "untrusted comment: minisign public key\nRWSxxxxxx...",
  "secrets": { "token": "<github-pat>" }
}

Leave public_key empty (or omit it) to skip verification — useful for internal sources or during initial setup. It is strongly recommended to set a public key for all 3rd-party sources.

Official JustIAM catalog: The built-in JustIAM Official Presets source is pre-configured with its public key and is verified out of the box — no action required.

UI indicator: The preset sources list shows a signed badge next to sources that have a public key configured, and an unsigned badge for those that do not.

Warning

Sources without a public_key run any script in the catalog without integrity checking. Always set a public key for sources you do not control.

Cache refresh¶

JustIAM caches catalog manifests locally. The built-in preset_cache_refresh task runs hourly to keep the cache up to date. You can also trigger a manual refresh:

POST /api/v1/preset-sources/{id}/refresh

Each refresh (both scheduled and manual) clears all stale entries for the source before repopulating, so versions removed from the catalog are immediately evicted and will no longer appear in the preset picker.

Catalog format¶

A catalog repository must expose:

An index file at <url>/catalog.json listing all available presets and versions.
Per-preset manifests at <url>/presets/<preset-id>/<version>.yaml.

Manifest structure¶

id: datadog-teams-sync
name: "Datadog Teams Sync"
description: "Keeps Datadog teams in sync with JustIAM app mappings."
version: v1.0.0

schedule:
  type: cron
  default_cron: "0 * * * *"
  timeout_secs: 120

config:
  - key: dd_endpoint
    description: "Datadog API base URL (e.g. https://api.datadoghq.eu)"
    required: true
  - key: justiam_app_id
    description: "UUID of the JustIAM application whose mappings to sync"
    required: true
  - key: variable_name
    description: "App mapping variable to use (e.g. teams)"
    required: true

secrets:
  - key: dd_api_key
    description: "Datadog API key"
  - key: dd_app_key
    description: "Datadog application key"

script: |
  package task
  // ... script body

Creating a preset task¶

Scheduling¶

The schedule_type field controls how the task is triggered:

Value	Behaviour
`cron` (default)	Runs on the schedule defined by `cron_expr` or the manifest's `default_cron`
`once`	Not scheduled — triggered manually or by an Event Action

Leave schedule_type empty to inherit the value from the preset manifest.

Overlap policy¶

The overlap_policy field controls what happens when a trigger fires while a run is already active.

Value	Behaviour
`allow` (default)	New run starts immediately — concurrent runs are allowed
`skip`	Trigger is dropped; a `cancelled` history entry records the reason
`queue`	Trigger is queued and runs in FIFO order after the active run finishes
`replace`	Active run is cancelled and a new run starts; cancelled run appears in history

Leave overlap_policy empty to inherit the value from the preset manifest. Many catalog presets (e.g. Datadog sync) default to queue to prevent concurrent sync conflicts.

Via API¶

POST /api/v1/preset-tasks
Content-Type: application/json

{
  "name": "acme-datadog-teams-sync",
  "source_id": "<preset-source-uuid>",
  "preset_id": "datadog-teams-sync",
  "version": "v1.0.0",
  "cron_expr": "",
  "overlap_policy": "queue",
  "enabled": true,
  "config": {
    "dd_endpoint": "https://api.datadoghq.eu",
    "justiam_app_id": "<app-uuid>",
    "variable_name": "teams"
  },
  "secrets": {
    "dd_api_key": "...",
    "dd_app_key": "..."
  }
}

cron_expr is optional — leave blank to use the preset's default_cron.

Via Terraform¶

resource "justiam_preset_task" "dd_teams_sync" {
  name           = "acme-datadog-teams-sync"
  source_id      = justiam_preset_source.internal.id
  preset_id      = "datadog-teams-sync"
  version        = "v1.0.0"
  overlap_policy = "queue"
  enabled        = true

  config = {
    dd_endpoint    = "https://api.datadoghq.eu"
    justiam_app_id = justiam_application.datadog.id
    variable_name  = "teams"
  }

  secrets = {
    dd_api_key = var.dd_api_key
    dd_app_key = var.dd_app_key
  }
}

Updating config and secrets¶

Config and secrets can be changed without touching the pinned script version:

PUT /api/v1/preset-tasks/{id}
Content-Type: application/json

{
  "config": {
    "variable_name": "datadog_team"
  }
}

Only the keys you include are replaced. Omit config or secrets to leave them unchanged.

Upgrading the version¶

To update the script to a newer catalog version:

POST /api/v1/preset-tasks/{id}/upgrade
Content-Type: application/json

{ "version": "v1.2.0" }

The server fetches the new manifest, updates the underlying task's script, and re-snapshots the manifest. Config and secrets are not affected.

In Terraform, simply change the version attribute — the provider calls the upgrade endpoint automatically.

Required permissions¶

Action	Permission
View / list preset tasks and sources	`tasks.manage`
Create / update / delete sources, refresh catalog	`preset_sources.manage`
Create / update / delete / upgrade preset tasks	`tasks.manage`

The preset_sources.manage permission is granted to the built-in Super Admin role. Custom roles can be configured in Settings → Admin Roles.

Managing preset tasks¶

Action	API
List preset tasks	`GET /api/v1/preset-tasks`
Get preset task	`GET /api/v1/preset-tasks/{id}`
Update (name, cron, config, secrets)	`PUT /api/v1/preset-tasks/{id}`
Upgrade script version	`POST /api/v1/preset-tasks/{id}/upgrade`
Delete	`DELETE /api/v1/preset-tasks/{id}`
List sources	`GET /api/v1/preset-sources`
Create source	`POST /api/v1/preset-sources`
Update source	`PUT /api/v1/preset-sources/{id}`
Delete source	`DELETE /api/v1/preset-sources/{id}`
Refresh source cache	`POST /api/v1/preset-sources/{id}/refresh`

Built-in tasks¶

Task	Default schedule	Description
`preset_cache_refresh`	`0 * * * *` (hourly)	Refreshes the local catalog and manifest cache for all sources

This task is seeded automatically and cannot be deleted, but its schedule can be changed.