Task¶
# yaml-language-server: $schema=https://saturn-bot.readthedocs.io/en/latest/schemas/task.schema.json
name: "Saturn Hello World"
prTitle: "Saturn Hello World"
prBody: |
Saturn Quickstart.
This pull request creates the file `hello-world.txt`.
# Filters tell Saturn which repositories to modify.
filters:
- filter: repository
params:
host: github.com
owner: wndhydrnt # Replace with your owner
name: saturn-example # Replace with your repository
# Actions tell Saturn how to modify each repository.
actions:
- action: fileCreate
params:
content: "Hello World"
path: "hello-world.txt"
actions¶
List of actions that modify a repository.
All available actions can be found here.
active¶
Set to false to temporarily deactivate the task and prevent it from executing.
Examples
assignees¶
A list of usernames to set as assignees of a pull request.
Note
If the task previously defined assignees and the list is set back to empty then Saturn doesn't remove the assignees from a pull request.
Examples
autoCloseAfter¶
Automatically close a pull request if it has been unmerged for the duration. Format is seconds. Set to 0, the default, to deactivate.
Examples
autoMerge¶
Merge a pull request automatically if all checks have passed and all approvals have been given.
Examples
autoMergeAfter¶
If set, automatically merge the pull request after it has been open for the specified amount of time. Only applied if autoMerge is true. The value is a Go duration, like 5m or 1h.
Examples
autoMergeWindow¶
Allow auto-merging of pull requests within the given window. Only has an effect if autoMerge=true.
This setting allows more fine-grained control over when Saturn auto-merges pull requests. It makes it possible to, for example, run Saturn regularly during the day and the night but limit auto-merging to business hours.
Examples
autoMerge: true
autoMergeWindow: between 9:00 and 16:00 from Monday to Thursday
Uses wandhydrant/go-human-timerange to parse the value. Please read the documentation of the library to learn how to write the statement.
autoMergeWindowTimeZone¶
The time zone to use when checking the autoMergeWindow. Defaults to the time zone of the system if unset.
Useful if the server(s) that execute Saturn use a different time zone than the users that write the tasks.
For a list of time zones, see List of tz database time zones.
Examples
autoMerge: true
autoMergeWindow: between 9:00 and 16:00 from Monday to Thursday
autoMergeWindowTimeZone: Europe/Brussels
branchName¶
If set, used as the name of the branch to commit changes to. Defaults to an auto-generated name if not set.
Supports templating.
Some git hosts restrict the maximum length of branch names. The branch name is automatically cut to 230 characters.
Examples
changeLimit¶
Number of pull requests to create or merge (combined) in one run. Useful to reduce strain on a system caused by, for example, many CI/CD jobs created at the same time.
commitMessage¶
If set, used as the message when changes get committed. Defaults to an auto-generated message if not set.
createOnly¶
Create pull requests only. Don't attempt to update a pull request on a subsequent run.
filters¶
Filters make Saturn pick the repositories to which it applies the task.
All available filters can be found here.
inputs¶
Inputs allows customizing a task at runtime.
Inputs provides more details on how to use them.
keepBranchAfterMerge¶
If true, keep the branch after a pull request has been merged.
labels¶
List of labels to attach to a pull request.
Forgejo
Forgejo does not create labels on-demand. If a label does not exist, then it will not be added to a pull request. The documentation on labels describes how to add labels.
maxOpenPRs¶
The number of pull requests that can be open at the same time. 0 disables the feature.
mergeOnce¶
If true, no new pull request is being created if a previous pull request has been merged for this task.
metricLabels¶
Key/value pairs to add as custom labels to the metric sb_server_task_run_success. Only available in server mode.
name¶
The name of the task. Used as an identifier.
plugins¶
List of plugins to start for the task.
plugins:
- path: ./example # Plugin binary to execute. Path is relative to the task file.
configuration:
# Arbitrary configuration to pass to the plugin.
message: "Hello Plugin"
Learn more about how to create plugins in the documentation.
prBody¶
If set, used as the body of the pull request.
Supports templating.
Examples
prTitle¶
If set, used as the title of the pull request.
Supports templating.
Examples
pushToDefaultBranch¶
If true, push changes directly to the default branch, like "main". If false, create a pull request to submit changes.
Defaults to false.
Examples
reviewers¶
A list of usernames to set as reviewers of the pull request.
Note
If the task previously defined reviewers and the list is set back to empty then Saturn doesn't remove the reviewers from a pull request.
Examples
trigger¶
Define when the task gets executed. Only relevant in server mode.
changes¶
Schedule a new run whenever the content of the task file and, optionally, additional files change.
trigger:
changes:
active: true
files: ["*.json"]
active¶
Activate scheduling on changes. Defaults to false.
files¶
List of additional files to consider. If one of the files changes, a new run will be scheduled. The path of each file can be a path relative to the task file or an absolute path. Supports globbing.
cron¶
Trigger the task based on a cron schedule.
crontab.guru supports with writing the cron schedule expression.
webhook¶
Execute the task when the server receives a webhook.
Trigger a task when a webhook is received describes how to set up a webhook.
See Webhook for reference.
delay¶
Delay the execution of the task, in seconds, after the webhook has been received by the server.