Skip to content

Automation Recipes

Automation recipes let you orchestrate approvals, notifications, and remediation steps without writing Ruby extensions. This guide covers authoring recipes with the in-app builder, previewing changes, and committing generated YAML to your definition repository using the PR helper.

Prerequisites

  • A project connected to a workflow definition repository (Settings → Workflow Repositories).
  • Permissions to update the project and to open pull requests in the connected GitHub repository.
  • Automation Recipes feature flag enabled for your organization (Starter plan or higher).

Generate a Recipe with the Builder

  1. Open the project and launch Automation Recipe Builder from the command palette (Cmd/Ctrl + K → automation:create) or the project settings card.
  2. Select the target workflow and provide the recipe metadata (key, name, trigger).
  3. Enter actions and optional conditions in JSON format. The builder normalizes the payload and validates required fields.
  4. (Optional) Provide an issue ID for the dry-run preview to see the actions rendered in the activity log.
  5. Click Validate to inspect the normalized payload, or Dry Run Preview to generate YAML.

Dry-run output includes: - Normalized JSON payload used by the runtime. - Generated YAML under model_version: "1.0" ready for your definition repo. - Preview information for approvals, notifications, and assignments the recipe would create.

Commit Using the PR Helper

When the builder detects a connected workflow repository, the footer exposes an Open PR Helper button (enabled after a successful dry run). Clicking the helper will:

  • Open a GitHub “Create new file” tab pointing at the configured branch and workflow path (for example, .kiket/workflows/default/automation_recipes/escalate_ops.yaml).
  • Pre-populate the file contents with the generated YAML and a commit message like Add automation recipe escalate_ops.

You can adjust filenames or branches before committing. Submit the change as a pull request to push the recipe through your existing review flow. Once merged, the next configuration sync will publish the automation.

Tip: If multiple repositories are connected, choose the target repo from the dropdown above the metadata summary before opening the helper.

File Layout & Naming

Automation recipes live under the workflow’s automation folder:

.kiket/
  workflows/
    <workflow_key>/
      automation_recipes/
        <recipe_key>.yaml

Keep recipe keys lower-case with underscores. The builder enforces this convention and mirrors the key in the generated filename.

Prebuilt Escalation Recipes

New projects automatically inherit three core automation recipes that live under storage/workflow_sources/defaults:

  • SLA Breach Escalation – fires when an issue is overdue and not in a final state. The recipe notifies project managers, reassigns to the team lead, and opens an approval to capture the recovery plan.
  • Silent Issue Follow-up – monitors active items that have not been updated or commented on within ~36–48 hours. The automation pings the current assignee and bubbles the work back to the lead if it is still unowned.
  • AI Risk Escalation – runs Vertex AI’s advisor to flag high-risk items (risk score ≥ 0.7) and routes an approval to managers with the generated summary.

Core recipes are stored for both Kanban and Scrum default workflows and appear in the Automation Recipes table with origin core. You can clone them via the builder to tweak thresholds or routing. Setting enabled: false in your definition repo disables a core recipe for a specific project.

Disable or Customize Recipes

  • Open Automation Recipe Builder in any project to view the existing recipe catalog. The new Existing Recipes table lists every synced recipe with its workflow and approval requirements.
  • Use the toggle next to each recipe to enable or disable it per project. Core recipes remain in the catalog (for audit history) even when disabled.
  • When you need to override a core rule, clone the YAML into your definition repo, adjust it, and set the original core recipe to disabled so only the customized variant runs.

Reviewing Automation Analytics

The Usage Dashboard now includes an Automation Runs card that aggregates:

  • Total automation executions in the current billing window.
  • Outcome breakdown (allow, pending, deny, error).
  • AI risk score averages and distribution (low, medium, high buckets).

Use this card to spot spikes in pending approvals, identify high-risk automations, and monitor plan consumption (e.g., Starter allocations vs. Professional limits).

Rate Limits & Guardrails

Automation runs now observe short-window rate limits in addition to monthly allocation caps:

  • Free: up to 10 automation runs every 10 minutes.
  • Starter: up to 120 automation runs every 5 minutes.
  • Professional: up to 500 automation runs every 5 minutes.
  • Enterprise: up to 2,000 automation runs every 5 minutes.

The runtime checks plan limits before recording an AutomationRun. When the limit is reached, the recipe is skipped with an informational activity entry and a warning is routed to org admins (in-app + email). The Usage Dashboard and /api/v1/ext/rate_limit endpoint both expose remaining quota. Rate-limit windows reset automatically; you can retry once the window refreshes or upgrade your plan for higher throughput.

Troubleshooting

  • PR helper disabled: Ensure at least one workflow repository is connected and active. Organization-level repositories are supported if no project-scoped repo exists.
  • No YAML generated: Run a dry run first; the helper only activates when fresh YAML is available.
  • Automation denied at runtime: Review the activity log entry for the automation run to inspect AI risk scores, approvals created, and notifications dispatched.
  • Exceeding plan limits: The Usage Dashboard card surfaces both monthly allocation status and the live short-window quota. If the runtime skips a recipe you will see an activity log note plus an admin warning; retry after the window resets or upgrade via Billing.
  • Existing organizations missing core recipes: Use the Sync Core Recipes action in the admin console (or kiket automation sync-core) to backfill the latest bundle across all projects, targeting specific organizations when needed.

Looking for an end-user overview? Visit the Automation Dashboard & Rate Limits guide for onboarding tips and the rate-limit FAQ.