IaC ワークフロー

SteadyCron の YAML マニフェストを採用・検証・プレビュー・適用する方法 — 初回エクスポートから CI/CD 自動化まで。

SteadyCron CLI はアカウントをテキストファイルに変換します。このファイルをバージョン管理し、 PR でレビューし、CI からデプロイすることができます。このページではワークフローの各コマンドを 説明します。

前提条件 {#prerequisites}

CLI のインストール

オプション 1 — .NET グローバルツール（推奨）

.NET 10 ランタイム が必要です。

dotnet tool install -g steadycron
steadycron --version

後でアップデートするには dotnet tool update -g steadycron を使用してください。

オプション 2 — 自己完結型バイナリ

ランタイム不要。リリースページ から 単一ファイルのバイナリをダウンロードしてください：

# Linux x64
curl -Lo steadycron https://github.com/steadycron/cli/releases/latest/download/steadycron-linux-x64
chmod +x steadycron && sudo mv steadycron /usr/local/bin/

Linux arm64、macOS、Windows 向けのバイナリも同じリリースページにあります。

認証

ダッシュボードの Settings → API keys で API キーを作成してください。変更を伴うコマンド （apply、sync、jobs create など）にはフルアクセスキーが必要です；export、 validate、plan は読み取り専用キーで動作します。

環境変数にキーを設定します：

export STEADYCRON_API_KEY=sc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

またはシェルセッション間で保持するために設定ファイルに保存します：

steadycron config set --api-key sc_...

接続を確認します：

steadycron config show --check

コマンド一覧

コマンド動作
steadycron export現在のアカウント状態をマニフェストにダンプ
steadycron validateマニフェストのスキーマエラーをチェック
steadycron plan変更内容をプレビュー — 書き込みなし
steadycron sync変更を適用（作成＋更新；削除なし）
steadycron apply変更を適用；--prune を追加すると削除も行う

ステップ 1 — エクスポート（既存アカウントの採用）

ダッシュボードにすでにジョブがある場合、export はそれらをマニフェストにまとめ、何も 失わずにコードとして管理できるようにします：

export STEADYCRON_API_KEY=sc_...
steadycron export --namespace production > manifests/production.yaml

エクスポートされたファイルはコミットしても安全です。API キー、webhook URL、その他のシークレットは ${VAR_NAME} プレースホルダーに置き換えられます — 実際の値は適用時に環境変数で提供します。 HTTP ジョブフィールド内のテンプレート変数（{{var}}）はそのまま保持されます。

ファイルを確認し、id のないジョブに値を追加してからコミットしてください。

ステップ 2 — バリデーション

適用前にマニフェストのスキーマエラーをチェックします：

steadycron validate manifests/production.yaml

成功時は 0、失敗時はエラーリストとともに 1 で終了します。すべての PR の事前チェックとして CI に組み込んでください。

ステップ 3 — プラン

plan は — terraform plan と同様の形式で — 何が変わるかを正確に表示します。何も書き込みません：

steadycron plan manifests/production.yaml

出力例：

  ~ weekly-digest       update  retries: 2 → 3
  + invoice-reminder    create  kind: http  schedule: 0 17 * * 5
  - old-report          (not in manifest — would be deleted with --prune)

  1 to create · 1 to update · 1 pending deletion

PR パイプラインでこれを使用し、すべてのプルリクエストにプラン差分をコメントとして追加できます。 自動的にこれを行う GitHub Action については CI/CD セットアップ を参照してください。

ステップ 4 — sync / apply

sync は新しいジョブを作成し、変更されたジョブを更新します。アカウントに存在するがマニフェストに ないジョブは削除しません：

steadycron sync manifests/production.yaml

管理されていないジョブ（ネームスペースにあるがファイルにないジョブ）も削除するには、 apply --prune を使用します：

steadycron apply --prune manifests/production.yaml

apply はトランザクション処理です。いずれかの操作が失敗した場合、バッチの残りは適用されず、 エラーは原因となった特定のリソースとともに報告されます。

ドライラン

sync または apply の呼び出しに --dry-run を渡すと、変更を加えずに何が起きるかを表示します — plan と同等ですが、スクリプト処理に便利です：

steadycron apply --prune --dry-run manifests/production.yaml

ネームスペースと所有権 {#namespaces}

ネームスペースは CLI が管理するリソースを限定します。ネームスペースがない場合、CLI はデフォルトの ネームスペースで動作し、--prune を安全に使用できません（マニフェストにないすべてのジョブ、 ダッシュボードで作成したジョブも含めて削除してしまいます）。

ネームスペースには環境名やチーム名を付けてください：

# manifests/production.yaml
namespace: production
jobs: [...]

# manifests/staging.yaml
namespace: staging
jobs: [...]

ダッシュボードには各ジョブが属するネームスペースが表示されます。ダッシュボードで作成されたリソース （ネームスペースなし）はデフォルトネームスペースに属し、ネームスペース付きの apply --prune では触れられません。

モノリポでの複数ネームスペース

ネームスペースごとに 1 つのマニフェストファイルを用意します：

manifests/
  production.yaml    # namespace: production
  staging.yaml       # namespace: staging
  workers.yaml       # namespace: workers-team

それぞれ独立して適用します：

steadycron apply --prune manifests/production.yaml
steadycron apply --prune manifests/staging.yaml

安定した ID と安全なリネーム

マニフェスト内のすべてのリソースには id フィールドがあります。これは安定した内部キーです — ジョブの name を変更しても、これは変わりません。

jobs:
  - id: nightly-backup         # ← 永久に安定
    name: Nightly database backup (prod)   # ← 自由にリネーム可能
    kind: heartbeat
    schedule: "0 2 * * *"

ハートビートで重要な理由： 各ハートビートチェックには内部 ID に紐付けられた固有の ping URL があります。ハートビートジョブをリネームしても、ping URL は保持されます — スクリプト、CI パイプライン、 監視インテグレーションを更新する必要はありません。

2 つのエントリが同じ id を持つ場合、validate はマニフェストを拒否します。

シークレットと変数 {#secrets}

シークレットはマニフェストに文字通り記載してはなりません。SteadyCron は 2 つの仕組みを提供します：

1. ${ENV_VAR_NAME} — CLI 環境変数置換

CLI は適用時にプロセス環境からこれらを読み取り、マニフェストを API に送信する前に置換します。 どのフィールドでも使用できます。

channels:
  - id: ops-slack
    name: Slack #ops
    kind: slack
    config:
      webhook_url: ${SLACK_WEBHOOK_URL}   # ← CLI が適用時に環境から読み取る

jobs:
  - id: invoice-job
    kind: http
    url: https://${API_HOST}/jobs/invoices
    headers:
      Authorization: Bearer ${INVOICE_API_KEY}

CI ではリポジトリのシークレットとして設定し、ジョブに渡してください：

# GitHub Actions
env:
  STEADYCRON_API_KEY: ${{ secrets.STEADYCRON_API_KEY }}
  SLACK_WEBHOOK_URL:  ${{ secrets.SLACK_WEBHOOK_URL }}
  INVOICE_API_KEY:    ${{ secrets.INVOICE_API_KEY }}

2. {{template_var}} — サーバーサイド置換

テンプレート変数は適用時ではなく、実行時に SteadyCron サーバーが解決します。HTTP ジョブの フィールド（url、headers、body）でのみ使用でき、実行ごとに変わる値やサーバーサイドで 計算される値に便利です。

jobs:
  - id: data-export
    kind: http
    url: https://api.myapp.com/export/{{date}}
    body: '{"run_id": "{{uuid}}"}'

steadycron export は両種類のプレースホルダーを自動的に出力します — エクスポートされた マニフェストは手動でのクリーンアップなしにそのままコミットしても安全です。