> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildpixel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Triggers

> Manual, push, scheduled. The three ways a build starts.

Every build setting has exactly one trigger. The trigger decides when the build fires.

## Manual

The simplest. A user clicks **Build now** in the dashboard, or you call the API:

```bash theme={null}
curl -X POST https://api.buildpixel.io/projects/$PROJECT_ID/build-settings/$SETTING_ID/trigger \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Use this when you want a human (or a script) to decide when a build runs.

## Push

The build setting fires every time a push to the tracked branch (or stream) lands.

### GitHub

GitHub pushes are delivered via the BuildPixel App's webhook automatically — no setup in your repo needed. Set:

```json theme={null}
{
  "trigger": "push",
  "branch": "main"
}
```

Push to `main` → matching build settings fire.

### Perforce triggers

Perforce has no native webhook. Wire a Helix `change-commit` trigger script that calls BuildPixel's trigger endpoint on every submit:

```bash theme={null}
#!/bin/bash
CHANGELIST=$1
TRIGGER_TOKEN="bp_..."
PROJECT_ID="..."
SETTING_ID="..."

curl -X POST https://api.buildpixel.io/projects/$PROJECT_ID/build-settings/$SETTING_ID/trigger \
  -H "Authorization: Bearer $TRIGGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"changelist\": \"$CHANGELIST\"}"
```

Register in `p4 triggers`:

```
Triggers:
    buildpixel-on-submit  change-commit  //streams/mygame-mainline/main/...  "%//perforce-trigger-buildpixel.sh% %changelist%"
```

## Scheduled

Pick a schedule for the build (e.g. nightly at 2am UTC). At fire time, BuildPixel pulls the latest commit / changelist and builds.

Set `trigger: "scheduled"` and configure the schedule in the dashboard's build setting view.

Useful for nightlies, weekly snapshots, or coordinating with other systems.

## Trigger metadata

Every build records its trigger:

* Manual via dashboard: `triggeredBy: "user:<userId>"`
* Manual via API: `triggeredBy: "api_token:<tokenId>"`
* Push: `triggeredBy: "push:<commit>"`
* Schedule: `triggeredBy: "cron"`

Visible in the build detail page, useful for "why did this build run?" debugging.