Skip to Content
OpenInspect
Automations

Create your first automation

Build a weekly scheduled automation that opens a dependency-update pull request, test it with Trigger Now, and read its run history.

Last reviewed View as MarkdownEdit on GitHubGive feedback

This tutorial walks you through a scheduled automation that opens a dependency-update pull request every Monday morning, then shows you how to test it and read the results.

Prerequisites

  • Both automations.create and sessions.create, granted by the built-in Member, Administrator, and Owner roles. Viewers cannot create automations. Custom roles need both permissions because the creator becomes the initial executor.
  • A repository the GitHub App can access. For a team automation, the owning team also needs a current repository grant; newly created teams have no grants until configured.
  • Current membership in the active team if you are creating a team-owned automation, including when you are a workspace Administrator or Owner.
  • At least one enabled model under Settings › Models that your chosen harness can run.

Open the create form

Open Automations in the sidebar and click Create Automation. If you would rather start from a pre-filled example, click Browse templates instead and choose one; the same form opens with fields already filled in (see Automation templates).

You can also start from a team's Automations tab. Choose the owning Team in the form, or Workspace (no team) if policy permits. Changing the team clears selected targets so you can choose from the new scope. Ownership cannot be changed after creation. If the workspace requires teams for new resources, select an active team you belong to. See Teams.

The Create Automation form with the trigger type picker, name, repository configuration, agent, model, and reasoning effort fields
Create Automation: choose a trigger type, name it, pick the repository, then the agent, model, and reasoning effort.

Choose the Schedule trigger

Under Trigger Type, select Schedule. The form adjusts to the trigger you pick: schedule triggers show a schedule and timezone, event triggers show an event type and conditions instead.

The trigger type cannot be changed after the automation is created.

Name it

Enter a Name of up to 200 characters, for example Weekly dependency updates. The name appears in the automations list and in every session this automation creates, prefixed with [Auto].

Pick one repository and a branch

Under Repository Configuration, select one repository. A Branch field appears; it defaults to the repository's default branch and is the branch each run checks out. Selecting a different repository resets the branch to that repository's default.

Schedule triggers also accept several repositories or environments. Leave that for later; see Multi-repository automations.

Choose the agent, model, and provider authentication

  • Agent: the harness that runs each session: OpenCode, Claude Agent, or Codex. It decides which models are listed below. See Agent harnesses.
  • Model: the model used on every run. Only models enabled under Settings › Models that the harness can run are listed.
  • Reasoning Effort: for models that support it, pick a level or leave Use model default.
  • Provider authentication: for each subscription-capable provider, either keep Use defaults when each run starts (the provider's configured unattended mode is resolved at run time) or pin a specific connected account or API-key mode. Pins survive model changes and apply only to future sessions. Anthropic account pins reach only Claude Agent automations; OpenCode uses the API key. See Provider accounts.

Write the instructions

Instructions is the prompt sent to the agent on every run (up to 15,000 characters). Write it the way you would write a normal session prompt: outcome, boundaries, and what "done" looks like.

Update this repository's dependencies.

1. Run the package manager's outdated check (for example `npm outdated`)
   and list minor and patch updates that are available.
2. Apply the minor and patch updates only. Do not apply major version
   bumps; list them in the PR description instead.
3. Run the project's test suite and typecheck. If something fails because
   of an update, revert that single package and note it in the PR.
4. Open one pull request titled "chore: weekly dependency updates" with
   a table of every package changed (old version, new version) and the
   list of skipped major updates.

If nothing is outdated, do not open a pull request.

See Writing prompts for the general pattern.

Set the schedule and timezone

Under Schedule, pick Weekly, choose Monday, and choose 9:00 AM. The picker shows a plain-language description of the schedule and a Next run preview beneath the controls.

Under Timezone, the form defaults to your browser's timezone. Change it if the schedule should follow a different region; "9:00" means 9:00 local time in the selected zone. Presets and custom cron expressions are covered in Schedules.

Save

Click Create Automation. You land on the automation's detail page, which shows the trigger, schedule, timezone, next run, and an empty Run History ("No runs yet.").

Test it with Trigger Now

Click Trigger Now on the detail page. A run starts immediately under your own authority, and the scheduled next run does not move. It can be rejected because a run is already active, you no longer qualify to execute it, or the team's grants changed. The full rules are in Schedules.

Read the run history

Each firing is one row in Run History with a status badge and duration. When you can read the linked session, its title and View session link are available. Click View session to open it, watch the agent, and review its diff and pull request. Older rows load with Load more.

Reading an automation does not grant access to all sessions it created. Run-history responses hide the session ID, title, and artifact summary when the linked session is not readable; the run row itself remains. History lists do not expose private sessions through an Owner's break-glass authority.

If a run fails, the failure reason appears under the row.

Pause, resume, edit, duplicate, or delete

  • Pause stops the automation from firing; Resume turns it back on and recalculates the next run from now. Both are available from the list and the detail page.
  • Edit changes the name, repository selection, branch, agent, model, instructions, schedule, and timezone. Changing the schedule or timezone recalculates the next run automatically. Editing the repository selection while a run is active does not affect that run; the next firing uses the new selection.
  • Duplicate on the detail page opens the create form filled in from this automation, named <name> (copy). Nothing is saved until you click Create Automation, and the copy starts with no run history, with you as its executor. An inbound webhook copy gets its own URL and a new API key. A Sentry copy asks for the Sentry client secret again and gets its own webhook URL; point a Sentry Custom Integration at that URL for the copy to receive alerts. If you cannot create automations in the source's team, the copy starts in your current scope and you choose its team and targets. Repositories or environments you cannot use are left out. A notice above the form says when either happens.
  • Delete asks for confirmation ("Delete automation?"), then stops all future runs. Existing run history and the sessions it created are preserved.

Ownership and execution

The owning team and executor are separate. Team ownership controls the resource's scope; the executor is the user whose authority scheduled and event-driven runs use. The creator is the initial executor. Workspace-owned automations have no owning team but still have an executor.

At run time, the executor must still be active and permitted to create sessions and use the targets. For team automations, they must belong to the active owning team and its grants must cover every target repository. Trigger Now checks the requester instead, including membership even for Administrators and Owners. Management authority alone is not execution authority.

New sessions inherit the automation's owning team and that team's default session visibility at launch. Workspace-owned automations create workspace-visible sessions. The person reading the automation must still pass each linked session's read checks; see Teams for visibility and deployment enforcement details.

Change the executor

Executor reassignment is currently API-only, not a control in the automation form. Ask an authorized team lead or workspace Administrator/Owner to reassign the executor to an active user who qualifies to launch the stored targets. This preserves the automation's ownership and history.

Troubleshooting

SymptomCauseFix
The Create Automation button stays disabledA required field is empty, the schedule is invalid, or no enabled model is compatible with the selected harnessFill in the name and instructions, check the cron picker's validation message, or enable a compatible model under Settings › Models
The repository you want is not in the pickerThe GitHub App cannot access it, or the selected team lacks a grantCheck installation access and the team's Repositories tab; see Teams
A scheduled firing is Skipped and the automation pauses immediatelyExecution authorization was denied: the executor lost access or team membership, the team was archived, or target grants are missingRestore the required access or ask an authorized lead/admin to reassign the executor through the API, then click Resume
Trigger Now is denied although you can edit the automationManagement access does not guarantee execution accessCheck your current team membership, session/target permissions, and the team's grants
A run has no session title or View session linkNo session was created, or you cannot read the linked sessionCheck the failure reason and session access; automation read access does not bypass session visibility
The badge says Degraded or the automation paused after failed runsRecent consecutive failures; three failures pause itOpen a failed run's View session, fix the cause, use Trigger Now to verify, then Resume

Next steps

On this page