Getting started¶

This tutorial will get you up and running with using Saturn to modify a repository that is hosted at GitHub or GitLab.

By the end, you'll understand how to write a task and use the run and try commands.

Prerequisites¶

Install Saturn¶

Before continuing, install Saturn on your local machine.

Create an access token¶

Saturn queries the API of the host that hosts the repository. It needs an access token to authenticate at the API.

Follow Create an access token for your host.

Store the access token in the file config.yaml. Replace <token> with the actual token.

GitHubGitLab

config.yaml

githubToken: <token>

config.yaml

gitlabToken: <token>

Create a repository¶

Create a repository for Saturn to modify. Skip this step if you already have a repository you can use for testing purposes.

Creating the task file¶

The task file contains all the information Saturn needs to discover which repositories to modify, how to modify them and how to create a pull request to submit the changes.

Without the task file, Saturn cannot do anything.

The following task file creates lets Saturn create the file hello-world.txt with the content Hello World in the root of a repository. Save it as hello-world.yaml.

hello-world.yaml

# 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 "Getting started" tutorial.

  This pull request creates the file `hello-world.txt`.

# Filters tell Saturn which repositories to modify.
filters:
  - filter: repository
    params:
      host: github.com # Replace with your host
      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"

Trying out the task¶

Let's check if the task modifies the repository. Saturn provides the try command to check locally what a task would do without pushing the changes to the repository. It allows to rapidly iterate when developing a task and inspect the changes and avoid, for example, repeatedly triggered CI/CD pipeline.

saturn try \
  --config config.yaml \
  --repository github.com/wndhydrnt/saturn-example \
  ./hello-world.yaml

Saturn lets you know that it has modified files:

✅ Filter repository(host=^github.com$,owner=^wndhydrnt$,name=^(saturn-example)$) of task Saturn Hello World matches
🏗️ Cloning repository
😍 Actions modified files - view checkout in ~/.saturn/data/git/github.com/wndhydrnt/saturn-example

Go to ~/.saturn/data/git/github.com/wndhydrnt/saturn-example and check that the file hello-world.txt exists:

cd ~/.saturn/data/git/github.com/wndhydrnt/saturn-example
cat hello-world.txt

Output:

Hello World

Executing the task¶

Now that you have checked what Saturn would change, it is time to execute saturn and create the pull request:

saturn run \
  --config config.yaml \
  --repository github.com/wndhydrnt/saturn-example \
  ./hello-world.yaml

Check that a new pull request with the title "Saturn Hello World" has been created.

What's next¶

Read the task reference to learn about all options, actions and filters of a task.