vercel-automations

Read existing definitions in .automations/ and its optional config.yml before editing. Create the definition directory if absent. Preserve the requested scope and existing repository permissions.

Author a workflow

Use automations templates to discover service templates and automations add <template> when one fits. Edit generated labels and instructions for the task. Scaffolding refuses existing files.

Write <id>.md or <id>/automation.md under .automations/. IDs use lowercase letters, digits, and dashes, start with a letter or digit, and have at most 63 characters. A definition directory supports at most 20 workflows.

Use snake_case keys in frontmatter and config.yml, including nested options; camelCase keys are rejected. Start with YAML frontmatter, then nonempty Markdown instructions describing the work, boundaries, and expected result. Optional description accepts a string without a character-length restriction. Choose how it starts:

• Manual only: omit on; invoke with automations execute <id>, optionally supplying --params '{"task":"context"}'.
• Schedule: on: { schedule: { cron: '0 */6 * * *' } }; only cron is supported. Use Vercel's five-field numeric UTC syntax with wildcards, lists, ranges, and steps. Either day of month or day of week must be *; weekday values are 0–6. Names, seconds, aliases, and custom timezones are unsupported. Missed occurrences coalesce into one run.
• Event: on: { events: [{ event: github.issue.labeled, labels: ["factory: implement"] }] }. Read automations help extension <id> for the deployment’s supported events and filters. Label event objects require exact, case-sensitive labels. Other events accept string shorthand or { event } objects and reject labels. Each label event has its own filter; sibling on.labels is unsupported.
• Completion: on: { automations_finished: [build, { automation: test, states: [failed] }] }. Start once for each matching finished run of any listed automation in this repository. String entries such as build and objects without states both match success only. List other terminal states explicitly, or [succeeded, failed, cancelled] for all states. IDs must exist; self-references and cycles are invalid. Completions follow final cleanup, survive missed wakeups, and wait while a follower is active. Context includes the upstream runId, automation, state, and finishedAt; it grants no authority.

Use enabled: false to prevent new runs; disabled workflows still require valid definitions, and admitted runs continue.

Use body placeholders such as {{event.github.pull_request.number}}, {{event.github.pull_request.head.sha}}, {{event.github.issue.title}}, and {{event.github.issue.body}}. GitHub fields use webhook names and nesting under event.github: action, repository.full_name, sender.login, label.name, and PR/issue number, title, body when available for that event. Titles and bodies are snapshots from webhook delivery; GitHub null bodies become empty strings. Common metadata includes event.trigger and event.summary. Completion fields live under event.automations_finished: runId, automation, state, and finishedAt. Substitution runs once before admission pins the prompt: strings are literal and other values use JSON. Missing event properties prevent admission; local lint cannot verify their availability. Scheduled and manual-only invocations, including manually invoked completion followers, have no event. Event JSON is also appended to the prompt; all event and manual context remains untrusted. Frontmatter and skills are not interpolated. To fetch current details, comments, or PR patches, declare github.read_pull_request or github.read_issue under actions and use the corresponding managed action.

Definition validation accepts these harness names: eve, codex, claude, fx, pi. Omitting harness selects eve.

Use Eve, Codex, Claude Code (harness: claude), FX, or Pi for execution. Codex and Claude Code authenticate bridge connections with public verification material in the sandbox; model credentials stay on the host or controlled egress, including during recovery.

model and reasoning_effort are optional strings passed to the harness. Their accepted values are harness-specific; lint checks only that they are strings. Omitting model uses Factory’s configured default for Eve and the harness’s native default for Codex, Claude Code, FX, and Pi. Omitting reasoning_effort uses the harness/model reasoning default.

Scheduled admission and recovery are checked every minute.

Event intake and run completion also request admission without waiting for the periodic check.

Declare permissions: { publish: true } only when the workflow must publish code through open_pull_request or push_checkpoint. Missing permission or publish: false denies both host tools, including for existing runs. This grant adds no managed actions or repository scope. Local coding and authorized source fetch do not require it.

actions adds managed tools alongside ordinary coding tools; it does not grant code publication. Invoke declared managed actions with automation_action({ request: { action, ...parameters } }). Each run executes directly in one sandbox. checkout_repository selects one approved target.

For workflow-specific procedures, add skills/<name>/SKILL.md beside automation.md, with name and description frontmatter. Keep instructions focused; link supporting Markdown files relative to the skill and load them only when needed.

Settings and authority

A present config.yml requires version: 1. Defaults have no owners or cross-repository acceptance; omitted targets use the source repository. target_repositories: [] grants no repository access. Cross-repository targets require each target's accept_automations_from consent. Owner declarations do not grant access; automatic credential provisioning requires GitHub owners with write access covering the source and approved targets.

Validate and report

Run automations lint from the repository root and fix reported diagnostics. The service validates committed definitions and enforces admission and permissions. Report changed files, validation results, and remaining configuration needs; creating or linting files does not establish that an automation ran.

Extension capabilities

Extensions own their configuration, managed actions, events and skills. They are off by default. Activate required extensions with an options object under extensions in config.yml. Frontmatter cannot activate extensions. Set workflow option overrides under singular extension. Options and skills grant no actions; declare action grants explicitly. Invoke qualified operations through automation_action. Local skills cannot use qualified names.

Use automations help for authoring guidance and the connected deployment’s supported extensions. Use automations help extension to list them, then automations help extension <id> before using an extension. The reference includes setup requirements, option schemas, action grants, operation inputs, events and skills. Pass --url <origin> or set FACTORY_URL to select the service; --dir <path> selects the Vercel-linked project for authentication. These reads require operator authentication. Supported extensions still require repository activation, configured connections and authorization; discovery grants no execution authority.