Referencia del manifiesto

El manifiesto v2 es la definición autorizada de su cuenta de SteadyCron. Un único archivo (o un directorio de archivos) declara cada job, canal de alerta, tag y variable que gestiona la CLI.

Estructura de nivel superior

namespace: my-app        # opcional — delimita la propiedad de IaC
variables:               # variables de plantilla del servidor (lista de objetos)
channels:                # definiciones de canales de alerta
tags:                    # definiciones de tags reutilizables
shaping:                 # límites de tasa
jobs:                    # jobs HTTP y checks de heartbeat
                         # las reglas de alerta se declaran por job bajo jobs[].rules

namespace

Una cadena que asigna un scope a todos los recursos de este manifiesto. La CLI solo gestiona (y con --prune, solo elimina) los recursos que pertenecen a este namespace — de modo que los jobs gestionados por IaC y los creados manualmente pueden coexistir de forma segura en la misma cuenta.

namespace: production

Si se omite namespace, se usa el namespace por defecto. Consulte Namespaces y propiedad para configuraciones de múltiples entornos.

jobs[]

Cada entrada es un job HTTP (kind: http) que llama a su endpoint según un calendario, o un check de heartbeat (kind: heartbeat) que espera un ping de su propio cron.

Campos comunes

Campo	Tipo	Requerido	Descripción
id	string	No	Clave de reconciliación estable. Cuando se define, los renombrados son seguros — el id nunca cambia, por lo que las URLs de ping de heartbeat se conservan. Recurre a name si está ausente.
name	string	Sí	Nombre de visualización en el dashboard y en los mensajes de alerta. Debe ser único en el manifiesto.
kind	http | heartbeat	No	Tipo de job. Por defecto: http.
schedule	string	Sí*	Expresión cron de cinco campos (minute hour dom month dow).
interval	integer	Sí*	Intervalo fijo en segundos (10–86400). Alternativa a schedule.
timezone	string	No	Nombre de zona horaria IANA, p. ej. Europe/Berlin. Por defecto: UTC.
paused	boolean	No	Crear o mantener el job en estado suspendido.
tags	string[]	No	Referencias de tags como cadenas "key:value", p. ej. ["env:prod", "team:backend"].
rules	object[]	No	Reglas de alerta por job. Véase Reglas de alerta.

*Se requiere exactamente uno de schedule o interval.

Campos de jobs HTTP

Campo	Tipo	Requerido	Descripción
method	string	No	Método HTTP. Uno de GET, POST, PUT, PATCH, DELETE. Por defecto: GET.
url	string	Sí	Endpoint a llamar. Admite marcadores ${ENV} (sustitución CLI) y {{template_var}} (servidor).
headers	object	No	Cabeceras de solicitud adicionales. Los valores admiten marcadores ${ENV}.
body	string	No	Cuerpo de la solicitud. Admite marcadores {{template_var}}.
timeout	integer	No	Tiempo de espera de la solicitud en segundos. Por defecto: 60.
retries	integer	No	Número de reintentos ante respuesta no-2xx o timeout. Por defecto: 0.
retry_backoff	integer	No	Segundos entre reintentos. Por defecto: 30.
retry_on_timeout	boolean	No	Contar los timeouts como fallos para los reintentos. Por defecto: true.
retry_on_status	integer[]	No	Códigos de estado HTTP que activan un reintento (100–599).
skip_if_running	boolean	No	Omitir la ejecución si la anterior todavía está activa. Por defecto: false.
misfire_policy	string	No	Comportamiento cuando se pierde una ejecución programada: do_nothing (por defecto) o fire_once_now.

Campos de checks de heartbeat

Campo	Tipo	Requerido	Descripción
grace	integer	No	Segundos a esperar tras el tiempo de ping esperado antes de alertar. Por defecto: 60.
stuck_run_detection	boolean	No	Alerta cuando una ejecución supera max_run_duration. Por defecto: true.
max_run_duration	integer	No	Duración máxima permitida de ejecución en segundos (60–86400).

channels[]

Canales de alerta referenciados por las reglas de job mediante su id o name.

Campo	Tipo	Requerido	Descripción
id	string	No	Clave de referencia estable usada en jobs[].rules[].channel.
name	string	Sí	Nombre legible mostrado en el dashboard y en los mensajes de alerta.
kind	string	Sí	Uno de slack, discord, email, telegram, webhook.
config	object	No	Configuración clave-valor específica del tipo. Use marcadores ${ENV} — nunca committe secrets reales.

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

Reglas de alerta {#alert-rules}

Las reglas de alerta se definen por job bajo jobs[].rules. Cada regla vincula un evento desencadenador con un canal de notificación.

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

Campo	Tipo	Requerido	Descripción
channel	string	Sí	id o name del canal a notificar.
trigger	string	Sí	Evento que activa la regla: on_failure, on_recovery, on_missed_heartbeat.
severity	string	No	Etiqueta de severidad enviada al canal (p. ej. p1, p2, p3).
params	object	No	Parámetros específicos del desencadenador.
dedup_window_seconds	integer	No	Ventana de deduplicación de alertas en segundos.

tags[]

Los tags agrupan jobs en el dashboard. Cada tag tiene una key y un value; los jobs los referencian como cadenas "key:value".

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

Referencia en un job: tags: ["env:prod", "team:backend"]

Campo	Tipo	Requerido	Descripción
id	string	No	Clave de referencia estable.
key	string	Sí	Categoría del tag (p. ej. env, team).
value	string	Sí	Valor del tag (p. ej. prod, backend).
color	string	No	Código de color hexadecimal para el dashboard.

variables

Variables de plantilla del servidor. Cada variable es un objeto con id, name y value. La CLI resuelve ${ENV_VAR} en value al aplicar; el servidor sustituye {{name}} en los campos HTTP del job al ejecutar. Los secrets nunca acaban en git.

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

Use {{digest_token}} en los campos HTTP url, headers o body.

Campo	Tipo	Requerido	Descripción
id	string	No	Clave de referencia estable.
name	string	Sí	Nombre de variable usado en sustituciones {{name}} del servidor.
value	string	No	Valor de la variable. Admite sustitución CLI ${ENV_VAR}.

shaping

El shaping de solicitudes controla la concurrencia y los límites de tasa para jobs HTTP — útil cuando muchos jobs se disparan en el mismo minuto y necesita distribuir la carga.

shaping:
  max_concurrent_jobs: 5
  max_jobs_per_minute: 30

Campo	Tipo	Descripción
max_concurrent_jobs	integer	Número máximo de jobs HTTP ejecutándose en paralelo.
max_jobs_per_minute	integer	Número máximo de ejecuciones de jobs HTTP por minuto.

Ejemplo completo

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

Secrets: dos mecanismos en paralelo

	${ENV_VAR_NAME}	{{template_var}}
Resuelto por	CLI al aplicar	Servidor al ejecutar
Funciona en	Cualquier campo	Solo url, headers, body de jobs HTTP
Úselo para	Claves de API, URLs de webhook, valores específicos del entorno	Valores dinámicos por ejecución
Exportado como	Marcador ${VAR}	Marcador {{var}}

steadycron export emite ambos tipos de marcadores de posición donde detecta un secret o una variable de plantilla, por lo que el manifiesto exportado es seguro para committear tal cual.