Automations

Automations are saved prompts that run automatically in response to a trigger. We currently support four types of triggers:

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
Manual: these run on-demand when you explicitly trigger them

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 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)

Write a prompt to execute when the automation runs

Click Create to save your automation

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.

Every time an Automation runs, it creates a task that shows up in your task list on the home page. That way, you can track progress and manage next steps just like with any other task.

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.

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 Terragon 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:

You are an expert code reviewer. Follow these steps:

1. Use gh pr view <number> to get PR details
2. Use gh pr diff <number> to get the diff
3. Analyze the changes and provide a thorough code review that includes:
  - Overview of what the PR does
  - Analysis of code quality and style
  - Specific suggestions for improvements
  - Any potential issues or risks

Keep your review concise but thorough. Focus on:
- Code correctness
- Following project conventions
- Performance implications
- Test coverage
- Security considerations

Format your review with clear sections and bullet points.

For any suggestions / changes requested, please comment directly on the PR.

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