You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
|[Constraint Solving — Problem of the Day](https://github.com/github/gh-aw/blob/main/.github/workflows/constraint-solving-potd.md)| copilot |[](https://github.com/github/gh-aw/actions/workflows/constraint-solving-potd.lock.yml)| - | - |
Copy file name to clipboardExpand all lines: docs/src/content/docs/patterns/central-repo-ops.mdx
+123Lines changed: 123 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -269,6 +269,129 @@ This allows the worker to create pull requests and issues in the target reposito
269
269
270
270
After the setup is complete, you can run the orchestrator with `workflow_dispatch` (`target_repos`) or let the schedule trigger run automatically.
271
271
272
+
## Richer Triggers with a Trigger File
273
+
274
+
Embedding a `schedule:` trigger directly in the orchestrator is the simplest setup, but it limits the orchestrator to time-based execution only. A **trigger file** — a plain, hand-authored GitHub Actions workflow — solves this by separating the trigger definition from the agent logic:
275
+
276
+
- The compiled orchestrator exposes a `workflow_call` trigger.
277
+
- A stable, rarely-changing `.yml` file defines the actual GitHub events that kick off the run.
278
+
- The trigger file calls the compiled orchestrator via `workflow_call`, forwarding any inputs and secrets.
279
+
280
+
This means you can update when and why the orchestrator runs — reacting to a label, a repository push, a security alert, or a manual dispatch — without touching or recompiling the agentic workflow.
281
+
282
+
### Add `workflow_call` to the Orchestrator
283
+
284
+
Extend the orchestrator's `on:` section with `workflow_call` and declare any inputs you want callers to pass:
285
+
286
+
```aw wrap
287
+
---
288
+
on:
289
+
schedule: weekly on monday
290
+
workflow_call:
291
+
inputs:
292
+
reason:
293
+
description: "Why this run was triggered (label name, event type, etc.)"
294
+
type: string
295
+
default: "scheduled"
296
+
297
+
tools:
298
+
github:
299
+
github-token: ${{ secrets.GH_AW_READ_ORG_TOKEN }}
300
+
toolsets: [repos]
301
+
302
+
safe-outputs:
303
+
dispatch-workflow:
304
+
workflows: [dependabot-rollout]
305
+
max: 5
306
+
---
307
+
308
+
# Dependabot Rollout Orchestrator
309
+
310
+
...
311
+
```
312
+
313
+
Compile the workflow after adding `workflow_call`: `gh aw compile`.
314
+
315
+
### Create the Stable Trigger File
316
+
317
+
Add a plain GitHub Actions workflow alongside the compiled orchestrator. This file is written by hand, committed once, and rarely needs to change:
> The trigger file references the compiled **lock file** (`*.lock.yml`), not the markdown source. Recompiling the orchestrator regenerates the lock file in place; the trigger file does not need to change.
349
+
350
+
> [!TIP]
351
+
> Use `secrets: inherit` to forward all repository secrets to the called workflow automatically. If you prefer explicit control, list each secret under `secrets:` in the `uses` block.
352
+
353
+
### Calling the Orchestrator from Another Repository
354
+
355
+
The trigger file can also live in a **different repository** — for example, inside each target repo — and call back into the orchestrator in the central control repository. This lets individual repositories decide *when* to request a rollout without requiring direct access to the central repo.
> Cross-repository `workflow_call` requires the caller and the callee to be in the **same organization**. The called workflow's `on.workflow_call` section must be present (added in the orchestrator step above). The caller must have access to any secrets it forwards.
378
+
379
+
> [!WARNING]
380
+
> Cross-repository calls do not support `secrets: inherit`. You must explicitly list each secret forwarded from the calling repository.
381
+
382
+
### Trade-offs: Schedule Only vs Trigger File
383
+
384
+
| | Schedule only | Trigger file + `workflow_call` |
385
+
|---|---|---|
386
+
| **Setup** | Single file, no extra config | Two files (orchestrator + trigger file) |
387
+
| **Trigger flexibility** | Cron/schedule only | Any GitHub event (issues, push, PRs, labels…) |
388
+
| **Change trigger without recompile** | No — trigger is embedded in the agentic workflow | Yes — edit the plain `.yml` trigger file |
389
+
| **Pass event context to agent** | Not possible | Yes — via `workflow_call` inputs |
390
+
| **Stability** | Trigger changes on every recompile | Trigger file stays fixed across recompiles |
391
+
| **When to use** | Simple recurring jobs with no event dependency | Jobs that should react to repository activity or need flexible scheduling |
392
+
393
+
The schedule-only approach is perfectly fine for a standalone nightly or weekly orchestrator. Move to the trigger file pattern when you need to react to repository events, pass extra context to the agent, or decouple trigger changes from the compilation cycle.
394
+
272
395
## Best Practices
273
396
274
397
- Keep orchestrator permissions narrow; delegate repo-specific writes to workers.
0 commit comments