🏁 Triggers

Triggers are the sensors of your repository. They monitor for specific events, and once an event occurs, they initiate a workflow. Let's deep dive into how to write triggers.

Important: Before you begin writing a trigger, set up validation in your editor for ease of writing.

Triggers are located in your .autopr configuration directory, as the .autopr/triggers.yaml file. Alternatively, you can also define triggers in the .autopr/triggers/*.yaml folder.

🧐 Properties of different triggers

Each trigger has the run property, which specified the action or workflow that is activated when the trigger condition is met. run must either be an invocation of a workflow/action, or match the name of one.

Invocation Trigger

triggers:
  - type: "label"
    label_substring: "summarize"
    on_issue: false
    on_pull_request: true
    run:
      workflow: "summarize_pr"

Name Trigger

triggers:
  - type: "label"
    label_substring: "summarize"
    on_issue: false
    on_pull_request: true
    run: "summarize_pr"

Use the "Invocation Trigger" syntax if you'd like to specify a workflow's inputs or parameters.

A workflow's parameters property is optionally used to override global variables in the workflow. For example, the parameters property can be used to define the FILE_SUMMARY_PROMPT variable, which is used in the generate_readme_summaries workflow.

Additionally, each respective trigger has its own unique properties:

Label Trigger

Activates when a label is added to an issue or a pull request.

• label_substring: Trigger when a label contains this substring.
• on_issue: Whether the trigger should respond to issues.
• on_pull_request: Whether the trigger should respond to pull requests.

triggers:
  - type: "label"
    label_substring: "summarize"
    on_issue: false
    on_pull_request: true
    run: "summarize_pr"

Push Trigger

Activates when a push is made to the specified branch.

• branch_name: Pinpoints the branch that the trigger observes for changes.

triggers:
  - type: "push"
    branch_name: "main"
    run:
      workflow: "generate_readme_summaries"
      parameters:
        FILE_SUMMARY_PROMPT: "Write a summary of this file for first-timers. Use 3-6 bullet points with emojis."
        FOLDER_SUMMARY_PROMPT: "Give a quick summary of this folder in 3-5 sentences."
        IGNORE_FILES:
          - docs
          - .github
          - .autopr
          - tests

Cron Trigger

Activates on a schedule according to a cron expression. Feel free to use crontab.guru to help you write cron expressions.

• cron_schedule: The cron expression that specifies the schedule (e.g. 0 0 * * * for daily at midnight).

triggers:
  - type: "cron"
    cron_schedule: "0 0 * * *"
    run: "generate_readme_summaries"

When using a cron trigger, make sure to specify the same schedule in your .github/workflows/autopr.yml file:

name: autopr
on:
  schedule:
    - cron: "0 0 * * *"

🙊 Verbosity

The verbose property is used to show the output of the action/workflow that is run by the trigger. This is useful for debugging purposes, but defaults to false to avoid cluttering the pull request with progress updates.

For example, we can observe LLM calls that the generate_readme_summaries workflow performs by running it with the verbose property set to true:

triggers:
  - type: "push"
    branch_name: "main"
    verbose: true
    run:
      workflow: "generate_readme_summaries"
      parameters:
        IGNORE_FILES:
        - docs
        - .github
        - .autopr
        - tests

📄 Examples

Below is an example of a .autopr/triggers.yaml file, that summarizes pull requests when the summarize label is added, and generates README summaries when a push is made to the main branch.

triggers:
  - type: label
    label_substring: summarize
    on_issue: false
    on_pull_request: true
    run: summarize_pr
  - type: push
    branch_name: main
    run:
      workflow: generate_readme_summaries
      parameters:
        FILE_SUMMARY_PROMPT: "Write a summary of this file for first-timers. Use 3-6 bullet points with emojis."
        FOLDER_SUMMARY_PROMPT: "Give a quick summary of this folder in 3-5 sentences."
        IGNORE_FILES:
          - docs
          - .github
          - .autopr
          - tests

You can also run actions directly in triggers. For example, run black to format Python files when a "format" label is added to a pull request. Note that the verbose property is set to true to show the output of the black command:

trigger:
  - type: label
    label_substring: format
    on_issue: false
    on_pull_request: true
    verbose: true
    run:
      action: bash
      inputs:
        command: black .