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
> _Optional: a section-by-section walkthrough of the opening three frontmatter sections in a `gh-aw` workflow file. Work through this before building Step 11, then continue to [Part B: Tools, Outputs, and the Agent Body](side-quest-11-08-frontmatter-tools-outputs.md) or return to the main path._
5
+
> _Optional: configure each of the opening three frontmatter sections of an agentic workflow file — metadata, triggers, and permissions. Work through this before building Step 11, then continue to [Part B: Tools, Outputs, and the Agent Body](side-quest-11-08-frontmatter-tools-outputs.md) or return to the main path._
6
6
7
7
## 📋 Before You Start
8
8
9
-
You have read [Step 11](07-your-first-workflow.md) and have a draft frontmatter file open.
9
+
Open the draft workflow file you started in [Step 11](07-your-first-workflow.md).
10
10
11
11
---
12
12
13
-
An agentic workflow file opens with a YAML **[frontmatter](https://github.github.com/gh-aw/reference/frontmatter/)** block between `---`fences. This block configures when the workflow runs and what it is allowed to do. This page covers the first three sections: metadata, triggers, and permissions.
13
+
An agentic workflow file opens with a YAML **[frontmatter](https://github.github.com/gh-aw/reference/frontmatter/)** block between `---`separators. This block configures when the workflow runs and what it is allowed to do.
14
14
15
15
---
16
16
@@ -24,17 +24,22 @@ emoji: 📊
24
24
description: Post a daily repository status summary as a GitHub issue comment.
25
25
```
26
26
27
-
**What this section does:** Opens the YAML frontmatter and declares human-readable metadata.
27
+
**What this section does:** Declares the workflow's metadata.
28
28
29
29
| Field | Purpose |
30
30
|-------|---------|
31
-
| `---` | Signals the start of YAML frontmatter. Everything until the next `---` is structured configuration. |
32
-
| `emoji` | A decorative label shown in the `gh aw` dashboard. Pick any emoji that fits. |
33
-
| `description` | A one-sentence summary shown in the GitHub Actions UI and in `gh aw list`. |
31
+
| `emoji` | Decorative label in the `gh aw` dashboard. Pick any emoji that fits. |
32
+
| `description` | Summary shown in the Actions UI and in `gh aw list`. |
34
33
35
-
**✏️ Try it:** Update `emoji` and `description` in your draft file to match your workflow.
34
+
**✏️ Try it:** Update both fields in your draft, then run `gh aw compile` and confirm no errors appear.
36
35
37
-
**✅ Check:** Run `gh aw compile` — the output should list your workflow with no errors.
36
+
```yaml
37
+
# Your turn
38
+
---
39
+
emoji: ???
40
+
description: ???
41
+
---
42
+
```
38
43
39
44
---
40
45
@@ -48,20 +53,37 @@ on:
48
53
workflow_dispatch: {}
49
54
```
50
55
51
-
**What this section does:** Tells GitHub Actions _when_ to run this workflow.
56
+
**What this section does:** Declares when the workflow runs.
52
57
53
58
| Field | Purpose |
54
59
|-------|---------|
55
-
| `on:` | Declares all triggers. Every GitHub Actions workflow must have this key. |
56
-
| `schedule: daily` | Runs once per day at a compiler-assigned time (scattered to avoid load spikes). Also available: `hourly`, `weekly`. |
57
-
| `workflow_dispatch: {}` | Adds a **Run workflow** button in the GitHub Actions UI. The `{}` means no custom inputs are required. |
60
+
| `on:` | Declares all triggers. |
61
+
| `schedule: daily` | Daily run at a compiler-assigned time. See the [triggers reference](https://github.github.com/gh-aw/reference/triggers/) for other intervals. |
62
+
| `workflow_dispatch: {}` | Adds a manual trigger button in the Actions UI. |
58
63
59
64
> [!TIP]
60
-
> Keep `workflow_dispatch` even after going to production — it lets you re-run the report on demand without changing the schedule.
65
+
> Keep `workflow_dispatch: {}` even after going to production — it lets you re-run the report on demand.
66
+
67
+
**✏️ Try it:** Add both trigger keys to your draft and run `gh aw compile`. Then extend the block to also fire on pushes to the main branch:
68
+
69
+
```yaml
70
+
on:
71
+
schedule: daily
72
+
push:
73
+
branches: [main]
74
+
workflow_dispatch: {}
75
+
```
61
76
62
-
**✏️ Try it:** Add both trigger keys to your draft file and save.
77
+
```yaml
78
+
# Your turn: configure schedule, push to main, and manual triggers
79
+
on:
80
+
???: ??? # daily run
81
+
push:
82
+
branches: [???] # target branch
83
+
???: {} # manual trigger
84
+
```
63
85
64
-
**✅ Check:** Run `gh aw compile` — the compile should succeed, and you should see both `schedule` and `workflow_dispatch` listed under triggers.
86
+
**✅ Check:** Run `gh aw compile` — the compiled output should list all three triggers.
65
87
66
88
---
67
89
@@ -78,26 +100,112 @@ permissions:
78
100
actions: read
79
101
```
80
102
81
-
**What this section does:** Declares exactly which GitHub API scopes this workflow is allowed to use. Minimal permissions are a security best practice.
103
+
**What this section does:** Declares the GitHub API scopes this workflow may use — fewer scopes is safer.
82
104
83
-
The five entries above cover reading repository content, issues, pull requests, and workflow runs, plus the `copilot-requests: write` scope that the Copilot engine requires to authenticate with `${{ github.token }}`. Full definitions for each field are in [Part B: Tools, Outputs, and the Agent Body](side-quest-11-08-frontmatter-tools-outputs.md).
105
+
| Field | Purpose |
106
+
|-------|---------|
107
+
| `permissions:` | Lists every scope the workflow may use; omitted scopes are denied. |
108
+
| `contents: read` | Read access to repository files and commits. |
109
+
| `copilot-requests: write` | Required by the Copilot engine. |
0 commit comments