Task¶

Example

# 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`.

# Repository filters allow targeting specific repositories.
repositories:
  - host: codeberg.org # Replace with your host
    owner: saturn-sync # Replace with your owner
    name: saturn-example # Replace with your repository

# Add one or more script commands to modify a repository.
script:
  - echo "Hello World" > hello-world.txt

active¶

Set to false to temporarily deactivate the task and prevent it from executing.

Examples

# Activate the task (default)
active: true

# Deactivate the task
active: false

afterScript¶

One or more script commands that are executed after the "script" commands.

If any command exits with an exit code != 0, Saturn does not consider the execution as failed.

Saturn sets all environment variables listed in script plus the following environment variables:

Name	Description	Example
`ACTION`	Action that Saturn took.	See below
`PULL_REQUEST_URL`	URL of the pull request managed by Saturn.	`https://codeberg.org/saturn-sync/saturn/pulls/168`

Value of `ACTION`¶

Use ACTION, for example, to send a message when Saturn creates a pull request.

ACTION can have one of the following values:

Value	Description
`closed`	Saturn closed the pull request.
`created`	Saturn created the pull request.
`merged`	Saturn merged the pull request.
`pushed`	Saturn pushed changes to the default branch.
`<empty>`	Saturn did not take any action.

Examples

Send an e-mail when Saturn creates a pull request

script:
  - echo "example" > example.txt

afterScript:
  - |
    if [[ "$ACTION" == "created" ]]; then
      echo "Please take a look at $PULL_REQUEST_URL." | mail -s "New pull request for $REPOSITORY" team@example
    fi

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.

Note

Bitbucket does not support assignees.

Examples

Set assignees

assignees:
  - ellie
  - joel

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

Close pull request after it being open for 14 days

autoCloseAfter: 1209600

Deactivate auto-close, the default

autoCloseAfter: 0

autoMerge¶

Merge a pull request automatically if all checks have passed and all approvals have been given.

Examples

# Enable auto-merge behavior
autoMerge: true

# Disable auto-merge behavior
autoMerge: false

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

# Automatically merges pull requests once they’ve been open for 30 min.
autoMergeAfter: 30m

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

Allow auto-merging between 9:00 and 16:00 from Monday to Thursday

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

autoMergeWindow with a time zone

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

Set a custom branch

branchName: "feature/hello-world"

Use a template variable

branchName: "feature/{{.TaskName}}"

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.

Allow up to 5 pull requests combined to be created or merged in one run of Saturn

changeLimit: 5

Disable the feature

changeLimit: 0

commitMessage¶

The message to use when committing changes. Defaults to changes by Saturn if not set.

Supports templating.

Examples

Set a custom commit message

commitMessage: "create hello-world.txt"

Use a template variable

commitMessage: "changes by Saturn task {{.TaskName}}"

createOnly¶

Create pull requests only. Don't attempt to update a pull request on a subsequent run.

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.

Allow 5 pull requests to be open at the same time

maxOpenPRs: 5

Disable the feature

maxOpenPRs: 0

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.

Define a custom label

metricLabels:
  task_owner: some-team

name¶

The name of the task. Used as an identifier.

prBody¶

If set, used as the body of the pull request.

Supports templating.

Examples

Custom pull request body

prBody: |
  Describe what the change does.

  Supports multi-lines.

Use a template variable

prBody: |
  This pull request modifies repository {{.Repository.FullName}}.

prBodyPlain¶

If true, Saturn does not append additional text, such as the "... created by Saturn ..." message, to the end of the description of a pull request.

This option removes any hint that Saturn was used by the user to create the pull request from the description of a pull request.

Note

Activating this option turns off the "check this box to rebase" functionality.

Examples

Render additional text by Saturn (default)

prBody: "Update some files."
prBodyPlain: false

Render the body as is

prBody: "Update some files."
prBodyPlain: true

prTitle¶

If set, used as the title of the pull request.

Supports templating.

Examples

Custom pull request title

prTitle: "feat: Custom title"

Use a template variable

prTitle: "Apply task {{.TaskName}}"

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

Create a pull request if task changes content

pushToDefaultBranch: false

Push changes to the default branch

pushToDefaultBranch: true

repositories¶

One or more filters to match repositories.

Saturn, by default, applies a task to all repositories it has access to. Repository filters allow targeting specific repositories, such as those owned by a specific organization or group.

Repository filters support with gradually rolling out a change to a few repositories before rolling it out across all repositories. Repository filters can also reduce the runtime of each task and load on a Git host because Saturn has to clone fewer repositories.

The value of host, owner and name is a regular expression. Each value is automatically enclosed with ^ and $.

Examples

Target one repository

repositories:
  - host: "github.com"
    owner: "octocat"
    name: "Hello-World"

Target all repositories of organization octocat

repositories:
  - host: "github.com"
    owner: "octocat"
    name: ".*"

Target all repositories of organization octocat that start with api-

repositories:
  - host: "github.com"
    owner: "octocat"
    name: "api-.*"

Target all repositories of organization octocat except Hello-World

repositories:
  - host: "github.com"
    owner: "octocat"
    name: ".*"
  - host: "github.com"
    owner: "octocat"
    name: "Hello-World"
    reverse: true

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

Set reviewers

reviewers:
  - ellie
  - joel

script¶

One or more script commands to modify the content in a repository.

If any command exits with an exit code != 0, Saturn considers the execution as failed.

Saturn sets the following environment variables:

Name	Description	Example
`INPUT_<name>`	Values of one of the inputs of the task.	`INPUT_greeting`
`REPOSITORY`	Full name of the repository.	`codeberg.org/saturn-sync/saturn`
`REPOSITORY_HOST`	Host of the repository.	`codeberg.org`
`REPOSITORY_OWNER`	Owner of the repository.	`saturn-sync`
`REPOSITORY_NAME`	Name of the repository.	`saturn`
`TASK`	Name of the current task.	`Hello World`
`TASK_SLUG`	Sluggified version of the name of the current task.	`hello-world`
`TASK_DIR`	Path to the directory that contains the current task file.	`/tasks`

Examples

Create a new file in the root of the repository

script:
  - echo "example" > example.txt

Replace a string in a file

script:
  - sed -i'' 's/World/world/g' hello-world.txt

Executing a script file

script:
  # Note: script.sh needs to be executable
  - $TASK_DIR/script.sh

scriptShell¶

Path to the shell to execute the script. Searches $PATH if the value isn't an absolute path.

Examples

Use the Bash shell and look it up in $PATH

script:
  - echo "example" > example.txt
scriptShell: "bash"

Use the Bash shell from the given location

script:
  - echo "example" > example.txt
scriptShell: "/bin/bash"

scriptTimeout¶

Maximum time a script is allowed to run, in Go duration notation. Defaults to 1m.

Note

The timeout is per script execution. Saturn executes the script in a new process for each repository. If Saturn tries to modify 5 repositories, then it executes the script 5 times and each execution has its own timeout.

Examples

Increase the timeout to two minutes

script:
  - echo "example" > example.txt
scriptTimeout: "2m"

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.

The server automatically schedules a new run the first time it discovers the task.

Schedule a new run whenever the task file changes

trigger:
  changes:
    active: true

Schedule a new run whenever the task file or any JSON file next to the task file 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.

Define a cron trigger

trigger:
  cron: "0 8,13 * * *"

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.

Delay the task by 5 minutes

trigger:
  webhook:
    delay: 300
    # ... other webhook settings

Task¶

active¶

afterScript¶

Value of ACTION¶

assignees¶

autoCloseAfter¶

autoMerge¶

autoMergeAfter¶

autoMergeWindow¶

autoMergeWindowTimeZone¶

branchName¶

changeLimit¶

commitMessage¶

createOnly¶

inputs¶

keepBranchAfterMerge¶

labels¶

maxOpenPRs¶

mergeOnce¶

metricLabels¶

name¶

prBody¶

prBodyPlain¶

prTitle¶

pushToDefaultBranch¶

repositories¶

reviewers¶

script¶

scriptShell¶

scriptTimeout¶

trigger¶

changes¶

active¶

files¶

cron¶

webhook¶

delay¶

Value of `ACTION`¶