> For the complete documentation index, see [llms.txt](https://docs.release.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.release.com/reference-documentation/application-settings/triggers.md).

# Triggers

{% hint style="warning" %}
Triggers are currently in limited access preview. Contact the Release support team to request access.
{% endhint %}

## Overview

Release Triggers provide automated responses to events within your development workflow. When specified events occur, such as GitHub pull request labels being added, triggers can automatically execute configurable actions, such as creating new environments or running workflows.

Triggers can be defined at both the app level and environment level within your Application Template, allowing you to create complex automation workflows that respond to your team's development patterns.

## Defining Triggers

### Basic Structure

Triggers are defined in your Application Template YAML under the `triggers` section:

```yaml
triggers:
  app:
    - events:
        - type: github.pull_request_labeled
          label: create-backend-environment
          repo_url: github.com/my-org/frontend
      actions:
        - type: release.create_environment
          app: backend
```

### App-Level vs Environment-Level Triggers

**App-Level Triggers** (`triggers.app`) run in the context of the current app and are typically used for creating new environments or performing app-wide actions.

**Environment-Level Triggers** (`triggers.environment`) run in the context of a specific environment and have access to environment-specific workflows and configurations.

## Events Reference

### `github.pull_request_labeled`

Triggers when a label is added to a GitHub pull request.

#### Properties

* `label` (string, required) - The exact label name that must be added to trigger the event (example: "Create Release Environment")
* `repo_url` (string, optional) - The GitHub repository URL. Defaults to the current app's repository
* `branch` (string, optional) - Filter to only trigger on specific branches
* `pull_request` (string, optional) - Filter to only trigger on specific pull requests (supports `"*"` wildcard)

#### Example

```yaml
events:
  - type: github.pull_request_labeled
    label: create-environment
    repo_url: github.com/myorg/myrepo
    branch: main
```

### `github.pull_request_created`

{% hint style="warning" %}
Coming soon - this will be implemented in a future release
{% endhint %}

Triggers when a new GitHub pull request is created.

#### Properties

* `repo_url` - The GitHub repository
* `branch` - The pull request's source branch

### `release.environment_created`

{% hint style="warning" %}
Coming soon - this will be implemented in a future release
{% endhint %}

Triggers when a new Release environment is created.

#### Properties

* `app` - The current app
* `environment` - The current environment

### `release.environment_config_changed`

{% hint style="warning" %}
Coming soon - this will be implemented in a future release
{% endhint %}

Triggers when an environment's configuration is updated.

#### Properties

* `app` - The environment's app
* `environment` - The environment's handle

### `git.push`

{% hint style="warning" %}
Coming soon - this will be implemented in a future release
{% endhint %}

Triggers when code is pushed to a Git repository.

#### Properties

* `repo_url` - The Git repository
* `branch` - The branch that was pushed to
* `commit` - The commit hash

### `aws.s3.object_created`

{% hint style="warning" %}
Coming soon - this will be implemented in a future release
{% endhint %}

Triggers when an object is created in an AWS S3 bucket.

#### Properties

* `aws_account` - The AWS account
* `bucket` - The S3 bucket name
* `object` - The object key

## Actions Reference

### `release.create_environment`

Creates a new Release environment.

#### Parameters

* `app` (string, optional) - The app to create an environment for. Defaults to the current app
* `parameters` (object, optional) - Parameters to pass to the new environment. Required if the app requires parameters
* `branch` (string, optional) - The Git branch to deploy. Defaults to the app's default branch
* `tag` (string, optional) - The Git tag to deploy (alternative to branch)
* `workflow` (string, optional) - The workflow to run after environment creation. Defaults to `"setup"`
* `app_imports` (array, optional) - App imports configuration. Defaults to the app's configured imports with a branch override. See below for more details.

{% hint style="info" %}
If `app_imports` are not specified, we default to the app's current app imports. If the app being created imports the app that defines the trigger and the triggering event includes a branch (e.g. `github.pull_request_labeled`), we will override the branch in the app import to match the event. This ensures that the code in the branch is what will be deployed in the created environment.
{% endhint %}

#### Example

```yaml
actions:
  - type: release.create_environment
    app: my-api
    branch: feature-branch
    workflow: custom_setup
    parameters:
      database_size: large
      debug_mode: true
    app_imports:
    - name: other-app
```

### `release.run_workflow`

{% hint style="warning" %}
Coming soon - this will be implemented in a future release
{% endhint %}

Runs a specific workflow in an environment.

#### Parameters

* `environment` (string, required) - The environment name or handle to run the workflow in. Defaults to the current environment if in an environment trigger.
* `workflow` (string, required) - The workflow name to execute

## Use Cases

### Automatic Environment Creation for Pull Requests

A common workflow is to automatically create preview environments when pull requests are labeled for review:

```yaml
triggers:
  app:
    - events:
        - type: github.pull_request_labeled
          label: create-environment
      actions:
        - type: release.create_environment
```

This configuration will create a new environment of the current app using the pull request's branch whenever someone adds the "create-environment" label to a GitHub pull request.

### Multi-Repository Deployments

For applications that span multiple repositories, you can create triggers that respond to events in any of the repositories:

```yaml
triggers:
  app:
    - events:
        - type: github.pull_request_labeled
          label: deploy-frontend
          repo_url: github.com/myorg/frontend-repo
      actions:
        - type: release.create_environment
          app: full-stack-app
    
    - events:
        - type: github.pull_request_labeled
          label: deploy-backend  
          repo_url: github.com/myorg/backend-repo
      actions:
        - type: release.create_environment
          app: full-stack-app
```

### Environment-Specific Workflows

{% hint style="warning" %}
Coming soon - this will be implemented in a future release
{% endhint %}

Environment-level triggers can run different workflows based on the specific environment context:

```yaml
triggers:
  environment:
    - events:
        - type: github.pull_request_labeled
          label: run-integration-tests
      actions:
        - type: release.run_workflow
          workflow: integration_tests
    
    - events:
        - type: github.pull_request_labeled
          label: performance-test
      actions:
        - type: release.run_workflow
          workflow: performance_suite
          parameters:
            test_duration: 60m
            load_level: high
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.release.com/reference-documentation/application-settings/triggers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.