# Workflow Dispatch and Runner Registration

## Workflow Dispatch

Trigger a workflow run manually via the API. The workflow must have `workflow_dispatch` defined as a trigger event.

### Trigger Workflow

```
POST /repos/{owner}/{repo}/actions/workflows/{workflowfilename}/dispatches
```

The `workflowfilename` is the filename of the workflow (e.g., `build.yml`, `deploy.yaml`).

#### Request Body

```json
{
  "ref": "{branch}",
  "inputs": {
    "key": "value"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `ref` | string | Branch or tag to run the workflow on (required) |
| `inputs` | object | Key-value pairs matching the workflow's `workflow_dispatch.inputs` definition |

#### Example

```bash
# Trigger a workflow on the main branch with no inputs
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"ref": "{branch}"}' \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/actions/workflows/{workflow_file}/dispatches"

# Trigger a workflow with inputs
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "{branch}",
    "inputs": {
      "environment": "{environment}",
      "dry_run": "false"
    }
  }' \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/actions/workflows/{workflow_file}/dispatches"

# Trigger a workflow on a specific branch
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"ref": "feature/my-branch"}' \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/actions/workflows/{workflow_file}/dispatches"
```

#### Workflow Definition Example

For the dispatch to work, the workflow file must include `workflow_dispatch`:

```yaml
on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production
      dry_run:
        description: 'Run without applying changes'
        required: false
        default: 'true'
        type: boolean
```

## Runner Registration Tokens

Get a registration token to register a new Forgejo Actions runner. These tokens are short-lived and single-use.

### Repository Runner Token

```
GET /repos/{owner}/{repo}/actions/runners/registration-token
```

```bash
curl -s -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/actions/runners/registration-token"
```

### Organization Runner Token

```
GET /orgs/{org}/actions/runners/registration-token
```

```bash
curl -s -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/orgs/{org}/actions/runners/registration-token"
```

### User Runner Token

```
GET /user/actions/runners/registration-token
```

```bash
curl -s -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/user/actions/runners/registration-token"
```

### Admin Runner Token

```
GET /admin/runners/registration-token
```

```bash
# Admin only
curl -s -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/admin/runners/registration-token"
```

### Registration Token Response

```json
{
  "token": "runner_registration_token_value"
}
```

### Registering a Runner

After obtaining the token, use it with the `forgejo-runner` CLI:

```bash
forgejo-runner register \
  --instance "${FORGEJO_URL}" \
  --token "runner_registration_token_value" \
  --name "my-runner" \
  --labels "ubuntu-latest,docker"
```

## Important Notes

- Workflow dispatch returns `204 No Content` on success — there is no response body
- The workflow file must exist on the specified `ref` branch/tag
- Runner registration tokens expire quickly and are single-use
- Repository-level runners only execute jobs for that repository; org-level runners serve all repos in the org
