マニフェストリファレンス

SteadyCron v2 YAML マニフェストの完全なフィールドリファレンス — ジョブ、チャンネル、ルール、変数、タグ、ネームスペース。

v2 マニフェストは SteadyCron アカウントの正式な定義です。単一のファイル（またはファイルのディレクトリ）で、CLI が管理するすべてのジョブ、アラートチャンネル、タグ、変数を宣言します。

トップレベルの構造

namespace: my-app        # オプション — IaC の所有権を限定する
variables:               # サーバーサイドのテンプレート変数（オブジェクトのリスト）
channels:                # アラートチャンネルの定義
tags:                    # 再利用可能なタグ定義
shaping:                 # レート制限のヒント
jobs:                    # HTTP ジョブとハートビートチェック
                         # アラートルールは jobs[].rules の下でジョブごとに宣言する

`namespace`

このマニフェスト内のすべてのリソースにスコープを割り当てる文字列です。CLI はこのネームスペースに属するリソースのみを管理します（--prune の場合は削除も）— IaC 管理のジョブと手動作成のジョブが同じアカウントに安全に共存できます。

namespace: production

namespace を省略するとデフォルトのネームスペースが使用されます。マルチ環境の設定については ネームスペースと所有権 を参照してください。

`jobs[]`

各エントリはスケジュールに従ってエンドポイントを呼び出す HTTP ジョブ（kind: http）、または自身のクロンからの ping を待ち受けるハートビートチェック（kind: heartbeat）です。

共通フィールド

フィールド	型	必須	説明
`id`	string	いいえ	安定した調整キー。設定されている場合、リネームは安全です — `id` は変わらないため、ハートビートの ping URL が保持されます。未指定の場合は `name` にフォールバックします。
`name`	string	はい	ダッシュボードとアラートメッセージに表示される名前。マニフェスト内で一意である必要があります。
`kind`	`http` \| `heartbeat`	いいえ	ジョブの種類。デフォルト：`http`。
`schedule`	string	はい*	5 フィールドのクロン式（`minute hour dom month dow`）。
`interval`	integer	はい*	秒単位の固定間隔（10–86400）。`schedule` の代替。
`timezone`	string	いいえ	IANA タイムゾーン名。例：`Europe/Berlin`。デフォルト：UTC。
`paused`	boolean	いいえ	ジョブを一時停止状態で作成または維持する。
`tags`	string[]	いいえ	`"key:value"` 文字列としてのタグ参照、例：`["env:prod", "team:backend"]`。
`rules`	object[]	いいえ	ジョブごとのアラートルール。アラートルールを参照。

*schedule または interval のいずれか一方のみが必須です。

HTTP ジョブのフィールド

フィールド	型	必須	説明
`method`	string	いいえ	HTTP メソッド。`GET`、`POST`、`PUT`、`PATCH`、`DELETE` のいずれか。デフォルト：`GET`。
`url`	string	はい	呼び出すエンドポイント。`${ENV}`（CLI 置換）および `{{template_var}}`（サーバーサイド）プレースホルダーをサポート。
`headers`	object	いいえ	追加のリクエストヘッダー。値は `${ENV}` プレースホルダーをサポート。
`body`	string	いいえ	リクエストボディ。`{{template_var}}` プレースホルダーをサポート。
`timeout`	integer	いいえ	リクエストのタイムアウト（秒）。デフォルト：60。
`retries`	integer	いいえ	2xx 以外のレスポンスまたはタイムアウト時のリトライ回数。デフォルト：0。
`retry_backoff`	integer	いいえ	リトライ間の秒数。デフォルト：30。
`retry_on_timeout`	boolean	いいえ	タイムアウトをリトライのための失敗としてカウントする。デフォルト：`true`。
`retry_on_status`	integer[]	いいえ	リトライを引き起こす HTTP ステータスコード（100–599）。
`skip_if_running`	boolean	いいえ	前回の実行がまだアクティブな場合は実行をスキップする。デフォルト：`false`。
`misfire_policy`	string	いいえ	スケジュールされた実行が失われた場合の動作：`do_nothing`（デフォルト）または `fire_once_now`。

ハートビートチェックのフィールド

フィールド	型	必須	説明
`grace`	integer	いいえ	期待される ping 時刻の後、アラートを発する前に待機する秒数。デフォルト：60。
`stuck_run_detection`	boolean	いいえ	実行が `max_run_duration` を超えた場合にアラートを発する。デフォルト：`true`。
`max_run_duration`	integer	いいえ	許可される最大実行時間（秒）（60–86400）。

`channels[]`

id または name を通じてジョブルールが参照するアラートチャンネル。

フィールド	型	必須	説明
`id`	string	いいえ	`jobs[].rules[].channel` で使用する安定した参照キー。
`name`	string	はい	ダッシュボードとアラートメッセージに表示される人間が読める名前。
`kind`	string	はい	`slack`、`discord`、`email`、`telegram`、`webhook` のいずれか。
`config`	object	いいえ	種類固有のキーと値の設定。`${ENV}` プレースホルダーを使用してください — 実際のシークレットをコミットしないでください。

channels:
  - id: ops-slack
    name: Slack #ops
    kind: slack
    config:
      webhook_url: ${SLACK_WEBHOOK_URL}

アラートルール {#alert-rules}

アラートルールは jobs[].rules の下でジョブごとに定義されます。各ルールはトリガーイベントを通知チャンネルに結びつけます。

jobs:
  - id: weekly-digest
    name: Weekly digest email
    kind: http
    schedule: "0 9 * * 1"
    url: https://api.myapp.com/jobs/digest
    rules:
      - channel: ops-slack
        trigger: on_failure
        severity: p1
      - channel: ops-slack
        trigger: on_recovery

フィールド	型	必須	説明
`channel`	string	はい	通知するチャンネルの `id` または `name`。
`trigger`	string	はい	ルールを発火させるイベント：`on_failure`、`on_recovery`、`on_missed_heartbeat`。
`severity`	string	いいえ	チャンネルに転送される重要度ラベル（例：`p1`、`p2`、`p3`）。
`params`	object	いいえ	トリガー固有のパラメータ。
`dedup_window_seconds`	integer	いいえ	アラート重複排除ウィンドウ（秒）。

`tags[]`

タグはダッシュボードでジョブをグループ化します。各タグは key と value を持ち、ジョブは "key:value" 文字列としてそれらを参照します。

tags:
  - id: env-prod
    key: env
    value: prod
  - id: team-backend
    key: team
    value: backend

ジョブ参照：tags: ["env:prod", "team:backend"]

フィールド	型	必須	説明
`id`	string	いいえ	安定した参照キー。
`key`	string	はい	タグカテゴリ（例：`env`、`team`）。
`value`	string	はい	タグ値（例：`prod`、`backend`）。
`color`	string	いいえ	ダッシュボード用の 16 進数カラーコード。

`variables`

サーバーサイドのテンプレート変数。各変数は id、name、value を持つオブジェクトです。 CLI は適用時に value 内の ${ENV_VAR} を解決し、サーバーは実行時に HTTP ジョブフィールド内の {{name}} を置換します。シークレットが git に入ることはありません。

variables:
  - id: digest-token
    name: digest_token
    value: ${DIGEST_TOKEN}

HTTP の url、headers、または body フィールドで {{digest_token}} を使用してください。

フィールド	型	必須	説明
`id`	string	いいえ	安定した参照キー。
`name`	string	はい	サーバーサイドの `{{name}}` 置換で使用される変数名。
`value`	string	いいえ	変数の値。`${ENV_VAR}` CLI 置換をサポート。

`shaping`

リクエストシェーピングは HTTP ジョブの並行性とレート制限を制御します — 多くのジョブが同じ分に実行される場合に負荷を分散するのに便利です。

shaping:
  max_concurrent_jobs: 5
  max_jobs_per_minute: 30

フィールド	型	説明
`max_concurrent_jobs`	integer	並行して実行する HTTP ジョブの最大数。
`max_jobs_per_minute`	integer	1 分あたりの HTTP ジョブの最大実行数。

完全な例

namespace: production

variables:
  - id: digest-token
    name: digest_token
    value: ${DIGEST_TOKEN}

channels:
  - id: ops-slack
    name: Slack #ops
    kind: slack
    config:
      webhook_url: ${SLACK_WEBHOOK_URL}

tags:
  - id: env-prod
    key: env
    value: prod
  - id: team-backend
    key: team
    value: backend

jobs:
  - id: weekly-digest
    name: Weekly digest email
    kind: http
    method: POST
    url: https://api.myapp.com/jobs/digest
    schedule: "0 9 * * 1"
    timezone: Europe/Berlin
    timeout: 120
    retries: 3
    tags: ["env:prod", "team:backend"]
    rules:
      - channel: ops-slack
        trigger: on_failure
        severity: p1
      - channel: ops-slack
        trigger: on_recovery

  - id: nightly-backup
    name: Nightly DB backup
    kind: heartbeat
    schedule: "0 2 * * *"
    grace: 1800
    tags: ["env:prod"]
    rules:
      - channel: ops-slack
        trigger: on_missed_heartbeat
        severity: p1

シークレット：2 つの仕組みを並べて比較

	`${ENV_VAR_NAME}`	`{{template_var}}`
解決するもの	適用時の CLI	実行時のサーバー
使用できる場所	任意のフィールド	HTTP ジョブの `url`、`headers`、`body` のみ
使用対象	API キー、webhook URL、環境固有の値	実行ごとの動的な値
エクスポート形式	プレースホルダー `${VAR}`	プレースホルダー `{{var}}`

steadycron export はシークレットやテンプレート変数を検出した箇所に両種類のプレースホルダーを自動的に出力します。エクスポートされたマニフェストはそのままコミットしても安全です。