n8vDocs

Automations

Create recurring tasks that run based on specific events

Automations are saved prompts that run automatically in response to a trigger. We currently support the following trigger types:

  • Schedule: these run automatically at a specified frequency. Either daily, weekly, monthly, weekdays only, or custom weekly (e.g., Tuesdays and Wednesdays)
  • GitHub Pull Request: these run automatically in response to pull requests being opened or updated
  • GitHub Issue: these run automatically in response to GitHub issues being opened
  • GitHub Mention: these allow you to customize the behavior when @n8v-io is mentioned in pull requests, issues, or comments
  • Manual: these run on-demand when you explicitly trigger them
  • Webhook: these run when another service (CI, n8n, Zapier, a script) calls the automation's URL (details)

Examples

Tasks you run regularly on a predictable schedule:

  • Writing release notes based on recent commits
  • Daily summaries of commits to a repo
  • Identifying and cleaning up dead code
  • Reviewing external tickets to decide which tasks to start next
  • Rebasing long-running branches onto the default branch
  • Identifying and addressing stale PRs

Tasks that run automatically when pull requests are created or updated:

  • Automated code review when PRs are opened
  • Updating documentation based on code changes
  • Identify and flag subtle bugs in the PR to help the code reviewer review the PR more efficiently

Tasks that run automatically when issues are created:

  • Triaging and labeling new issues
  • Creating initial investigation tasks for bug reports
  • Assigning issues to appropriate team members
  • Linking related issues and pull requests

Tasks that run when @n8v-io is mentioned in pull requests, issues, or comments:

  • Addressing specific comments
  • Ask questions about code changes
  • Fixing test failures

Tasks you run regularly, but not on a set schedule:

  • Standardized code reviews before merging PRs
  • Debugging and root cause analysis based on a bug report
  • Updating dependencies
  • Well-defined migrations
  • Generating tests for new features
  • Updating documentation based on recent commits

Creating an Automation

Navigate to Automations from the sidebar

Click Create Automation
Enter a name for your automation
Choose the trigger type
Decide on the configuration for the trigger (e.g., for a scheduled automation, set the schedule frequency)
Choose an agent task or an enabled Workflow Graph, then configure its prompt or graph

Optional: expand Recurring follow-up to continue each generated task on completion or on its own schedule

Click Create to save your automation

Recurring follow-ups

Recurring follow-ups keep the task created by an automation moving after its first run:

  • On completion sends your follow-up after each completed run. You can also continue after errors and request timeouts; this stops automatically after three consecutive failures.
  • On schedule sends the follow-up at the selected frequency and timezone, independently of the automation's trigger schedule.
  • Ends can be set to never, a future date, or a maximum number of runs.

A recurring task must remain active. Enabling recurrence therefore turns off Create task in archive and PR/issue Auto-archive on completion options. You can edit or disable the recurring follow-up later from the automation or the generated task.

Running Automations

All automations can be run manually to test them out. This can be helpful for tweaking and refining the prompt to make sure that it does what you want it to do.

An agent-task Automation creates a task that appears in your task list. A Workflow Graph Automation starts a durable graph run instead; each task node still appears normally and is linked from the graph run.

To see all of the past runs and tasks created by an Automation, click on it from Automations. This is helpful for ensuring your Automations are completing as expected.

Workflow Graph actions

Manual and scheduled automations can start an enabled Workflow Graph. The graph and automation must target the same repository and branch. Graph actions use the graph's versioned nodes and routing instead of an automation prompt, and each trigger creates a new graph run without a placeholder task.

Webhook trigger

Webhook automations are in early access and may not be enabled for your account yet.

A webhook automation gives other systems a URL that starts a task. The automation decides the repository, branch, model and prompt. The caller only adds context.

Create an automation with the Webhook trigger, pick the repository, branch and model, and write the prompt
Optional: turn on Let callers choose the branch if requests should pick the base branch
Save, open the automation, and click Create token. Copy it right away: n8v stores only a hash and cannot show it again
Store the token as a secret in the calling system, for example N8V_WEBHOOK_TOKEN
Click Send test request to check the endpoint and token from the page. It sends a dry run, so no task starts
Send a request from your system. The automation page listens while you set up and shows the first call as soon as it arrives

The automation page walks you through these steps and has ready-to-copy examples for cURL, GitHub Actions and JavaScript, filled in with your endpoint.

curl -sS --fail-with-body --retry 3 --retry-max-time 120 \
  -X POST https://n8v.online/api/webhooks/automations/<automation-id> \
  -H "Authorization: Bearer $N8V_WEBHOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -d '{"message":"Build failed on main","context":{"run":"https://ci.example.com/runs/42"}}'

-sS hides the progress meter so CI logs stay clean but still prints errors. --fail-with-body makes curl exit with an error on any 4xx or 5xx and still print the reason, so a CI step fails visibly instead of passing. --retry 3 retries timeouts, 429, 500 and 503, honouring Retry-After, and --retry-max-time 120 stops it from waiting out a long Retry-After (the hourly limit can ask for up to an hour). The key is generated once per command, so every retry carries the same key and at most one task starts. On curl older than 7.76, use --fail instead of --fail-with-body.

From GitHub Actions, add a step at the end of a job. It runs only when an earlier step failed:

- name: Hand the failure to n8v
  if: failure()
  env:
    N8V_WEBHOOK_TOKEN: ${{ secrets.N8V_WEBHOOK_TOKEN }}
    RUN: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
    SHA: ${{ github.sha }}
  run: |
    jq -n --arg run "$RUN" --arg sha "$SHA" \
      '{message: "CI failed", context: {run: $run, commit: $sha}}' |
    curl -sS --fail-with-body --retry 3 --retry-max-time 120 \
      -X POST https://n8v.online/api/webhooks/automations/<automation-id> \
      -H "Authorization: Bearer $N8V_WEBHOOK_TOKEN" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: ${{ github.run_id }}-${{ github.run_attempt }}" \
      --data-binary @-

jq (preinstalled on GitHub-hosted runners) builds the body from environment variables, so quotes or newlines in a value can never break the JSON. The key is tied to the run attempt: if several matrix jobs fail in one run, they share it, the first one starts the task and the others get the same task back, so every step stays green. A manual re-run starts a fresh task.

Check that it worked. Until the first successful call, the automation page shows each attempt as it arrives, with the reason if it was refused. After that it shows Recent calls: the last 20 calls that carried a valid token, kept for 7 days. Each row leads with what happened (for example Task started or Branch feat/x does not exist), then the start of message, the status code and a link to the task. Duplicates with the same Idempotency-Key fold into the call that started the task, and a burst of rate-limited retries shows as one entry. Calls with a missing or wrong token are never listed, so outside noise cannot push real calls out: if your caller gets 401 and nothing appears, check the token.

Inspect a call. Click a row to see the request body, user agent and Idempotency-Key, and the response that was sent back. Fields named like credentials (password, token, apiKey, clientSecret and similar) and known token formats (GitHub, Slack, AWS, JWTs, n8v webhook tokens) are replaced with [redacted], bodies are shown up to 16 KB, and the Authorization header is never stored. Copy as cURL resends the exact body with your token from $N8V_WEBHOOK_TOKEN; it is offered only when nothing was redacted or cut.

The body is optional JSON with these fields. Any other field is rejected.

FieldTypeDescription
messagestringShort note added to the prompt, up to 20,000 characters
contextanyJSON data added to the prompt, such as a failing job, an alert or a ticket
branchstringBase branch for this task. Only accepted when Let callers choose the branch is on
dryRunbooltrue checks the request and starts nothing; see below

The whole body can be up to 64 KB. A successful call returns 202 with the task:

{ "taskId": "…", "url": "https://n8v.online/task/…" }
StatusMeaning
202Task started
200Same Idempotency-Key as an earlier call; returns that call's task. A duplicate that arrives while the first call is still starting waits for it, up to 5 seconds. Also a passed dry run
400Invalid body, branch name or Idempotency-Key, or context nested deeper than 32 levels
401Missing or wrong token, or no such webhook automation. Carries WWW-Authenticate: Bearer
403Webhooks are not enabled for the account
409The automation is disabled, or a call with the same Idempotency-Key was still running after 5 seconds
413Body larger than 64 KB. Checked after the token, so a request with a wrong token gets 401
422The task could not start, for example the branch does not exist or the plan has no automation runs left. error says why. Also returned when an Idempotency-Key is reused with a different body
429More than 30 calls per minute for this automation, or 120 per hour across your webhooks; see Retry-After
503Briefly unavailable. Retry after the seconds in Retry-After; no task was started

Dry runs. Send "dryRun": true to check a request without starting a task, for example when wiring up a new CI job. The endpoint runs every check it does for a real call (token, account, whether the automation is on, rate limits, body and branch rules) and answers 200 with {"dryRun": true, "valid": true}, or with the same error a real call would get. A dry run does not check the repository itself, so a branch that does not exist is only reported by a real call. It never uses up an Idempotency-Key, and it does not mark the webhook as connected.

How webhooks stay safe

  • Tokens are long random values. n8v keeps only a SHA-256 hash and compares it in constant time.
  • Send the token in the Authorization header, never in the URL, so it does not end up in logs.
  • A token can only start its own automation. It cannot change the repository, the model or the prompt.
  • message and context go into the prompt in a fenced block labelled as untrusted input, and the agent is told not to follow instructions inside it. Treat everything a webhook sends as data from outside.
  • Rotate replaces the token at once, and Revoke turns the webhook off until you create a new token. Changing the automation to another trigger also revokes it; the editor warns you before you save.
  • Send an Idempotency-Key header (any unique value up to 200 characters) so retries from the calling system do not start duplicate tasks. Keys are remembered for 24 hours. If a call fails, the same key can be retried right away. Reusing a key with a different body is refused with 422, so a key always means one request.
  • Branch names follow git's rules and may not contain shell characters such as spaces, quotes, $, (, ) or #.

Manage automations from your assistant

Claude or ChatGPT connected to n8v, or your own scripts with an API key, can list your automations, see why their runs failed, and create, change, pause, resume, run and delete them. An automation whose model can no longer run (for example because it was turned off for your account, or its provider refused the last run) says so with a warning, and its card in the list reads Model cannot run. Ask the assistant to fix it and it switches the automation to a model you can use. See Automations API.

Security Considerations

When creating automations, especially those that process external data or run automatically, it's important to follow security best practices:

For comprehensive information about how n8v protects against prompt injection and other security threats, see our Security & Permissions documentation.

Best Practices:

  • Be specific with instructions - Use precise, clear language to minimize ambiguity
  • Limit automation triggers - GitHub automations only trigger for your own PRs/issues by default. If you want to trigger tasks based on other users PRs/issues, you must explicitly enable "Include pull requests/issues from other authors" and manually specify each allowed username. When enabling this setting, ensure you only enter the usernames of other GitHub users that you trust. Note: For GitHub bot @-mention triggers, you must include the [bot] suffix in the username (e.g., sentry-io[bot]).
  • Use development credentials - Never use production API keys or credentials in automations
  • Validate external inputs - Always validate and sanitize data from PRs, issues, and other external sources
  • Limit permissions - Grant only the minimum permissions required for your automation to function
  • Monitor automation runs - Regularly check that your automations are behaving as expected
  • Avoid secrets in prompts - Never hardcode sensitive information directly in automation prompts

GitHub-Specific Security:

  • Repository access - Automations can only access repositories you've explicitly granted permission to
  • Branch protection - Automations cannot push to protected branches or merge PRs without proper permissions
  • Audit trail - All automation actions are logged and visible in your task history

Example Use Cases

Automated PR Review Workflow

Create a Pull Request automation that performs comprehensive code review:

  • Adapted from OpenAI Codex.
  • Best used with gpt-5-codex models.
**IMPORTANT**: All findings and comments should be left as comments directly on the PR using the `gh` cli.

You are acting as a reviewer for a proposed code change made by another engineer.

Below are some default guidelines for determining whether the original author would appreciate the issue being flagged.

These are not the final word in determining whether an issue is a bug. In many cases, you will encounter other, more specific guidelines. These may be present elsewhere in a developer message, a user message, a file, or even elsewhere in this system message.

Those guidelines should be considered to override these general instructions.

Here are the general guidelines for determining whether something is a bug and should be flagged.

1. It meaningfully impacts the accuracy, performance, security, or maintainability of the code.
2. The bug is discrete and actionable (i.e. not a general issue with the codebase or a combination of multiple issues).
3. Fixing the bug does not demand a level of rigor that is not present in the rest of the codebase (e.g. one doesn't need very detailed comments and input validation in a repository of one-off scripts in personal projects)
4. The bug was introduced in the commit (pre-existing bugs should not be flagged).
5. The author of the original PR would likely fix the issue if they were made aware of it.
6. The bug does not rely on unstated assumptions about the codebase or author's intent.
7. It is not enough to speculate that a change may disrupt another part of the codebase, to be considered a bug, one must identify the other parts of the code that are provably affected.
8. The bug is clearly not just an intentional change by the original author.

When flagging a bug, you will also provide an accompanying comment. Once again, these guidelines are not the final word on how to construct a comment -- defer to any subsequent guidelines that you encounter.

1. The comment should be clear about why the issue is a bug.
2. The comment should appropriately communicate the severity of the issue. It should not claim that an issue is more severe than it actually is.
3. The comment should be brief. The body should be at most 1 paragraph. It should not introduce line breaks within the natural language flow unless it is necessary for the code fragment.
4. The comment should not include any chunks of code longer than 3 lines. Any code chunks should be wrapped in markdown inline code tags or a code block.
5. The comment should clearly and explicitly communicate the scenarios, environments, or inputs that are necessary for the bug to arise. The comment should immediately indicate that the issue's severity depends on these factors.
6. The comment's tone should be matter-of-fact and not accusatory or overly positive. It should read as a helpful AI assistant suggestion without sounding too much like a human reviewer.
7. The comment should be written such that the original author can immediately grasp the idea without close reading.
8. The comment should avoid excessive flattery and comments that are not helpful to the original author. The comment should avoid phrasing like "Great job ...", "Thanks for ...".

Below are some more detailed guidelines that you should apply to this specific review.

HOW MANY FINDINGS TO RETURN:

Output all findings that the original author would fix if they knew about it. If there is no finding that a person would definitely love to see and fix, prefer outputting no findings. Do not stop at the first qualifying finding. Continue until you've listed every qualifying finding.

GUIDELINES:

- Ignore trivial style unless it obscures meaning or violates documented standards.
- Use one comment per distinct issue (or a multi-line range if necessary).
- Use ```suggestion blocks ONLY for concrete replacement code (minimal lines; no commentary inside the block).
- In every ```suggestion block, preserve the exact leading whitespace of the replaced lines (spaces vs tabs, number of spaces).
- Do NOT introduce or remove outer indentation levels unless that is the actual fix.

The comments will be presented in the code review as inline comments. You should avoid providing unnecessary location details in the comment body. Always keep the line range as short as possible for interpreting the issue. Avoid ranges longer than 5–10 lines; instead, choose the most suitable subrange that pinpoints the problem.

At the beginning of the finding title, tag the bug with priority level. For example "[P1] Un-padding slices along wrong tensor dimensions". [P0] – Drop everything to fix.  Blocking release, operations, or major usage. Only use for universal issues that do not depend on any assumptions about the inputs. · [P1] – Urgent. Should be addressed in the next cycle · [P2] – Normal. To be fixed eventually · [P3] – Low. Nice to have.

Additionally, include a numeric priority field in the JSON output for each finding: set "priority" to 0 for P0, 1 for P1, 2 for P2, or 3 for P3. If a priority cannot be determined, omit the field or use null.

At the end of your findings, output an "overall correctness" verdict of whether or not the patch should be considered "correct".

Correct implies that existing code and tests will not break, and the patch is free of bugs and other blocking issues.

Ignore non-blocking issues such as style, formatting, typos, documentation, and other nits.

FORMATTING GUIDELINES:

The finding description should be one paragraph.

**IMPORTANT**: All findings and comments should be left as comments directly on the PR using the `gh` cli.

Issue Triage Automation

You're an issue triage assistant for GitHub issues. Your task is to analyze the issue and select appropriate labels from the provided list.

IMPORTANT: Don't post any comments or messages to the issue. Your only action should be to apply labels.

TASK OVERVIEW:
1. First, fetch the list of labels available in this repository by running: `gh label list`. Run exactly this command with nothing else.
2. Next, use the GitHub CLI to get context about the issue:
  - Use `gh issue view {{issue_number}} --json title,body,labels,state` to retrieve the current issue's details
  - Use `gh issue view {{issue_number}} --comments` to read any discussion or additional context provided in the comments
  - Use `gh issue list --search "{{search_terms}}"` to find similar issues that might provide context for proper categorization and to identify potential duplicate issues
  - Use `gh issue list --label "{{label_name}}"` to understand patterns in how other issues are labeled

3. Analyze the issue content, considering:
  - The issue title and description
  - The type of issue (bug report, feature request, question, etc.)
  - Technical areas mentioned
  - Severity or priority indicators
  - User impact
  - Components affected

4. Select appropriate labels from the available labels list provided above:
  - Choose labels that accurately reflect the issue's nature
  - Be specific but comprehensive
  - Select priority labels if you can determine urgency (high-priority, med-priority, or low-priority)
  - Consider platform labels (android, ios) if applicable
  - If you find similar issues using `gh issue list --search`, consider using a "duplicate" label if appropriate. Only do so if the issue is a duplicate of another OPEN issue.

5. Apply the selected labels:
  - Use `gh issue edit {{issue_number}} --add-label "{{label1}},{{label2}},{{label3}}"` to apply the labels
  - DO NOT post any comments explaining your decision
  - DO NOT communicate directly with users
  - If no labels are clearly applicable, do not apply any labels

IMPORTANT GUIDELINES:
- Be thorough in your analysis
- Only select labels from the provided list above
- DO NOT post any comments to the issue
- Your ONLY action should be to apply labels using `gh issue edit --add-label`
- It's okay to not add any labels if none are clearly applicable