authoring-github-workflows

Authoring GitHub Actions Workflows Safely

GitHub Actions workflow files are YAML, but valid YAML is not the same as a valid workflow. A workflow can parse cleanly with yaml.safe_load (or a casual review) yet still be rejected by GitHub Actions at load time — producing the opaque failure "This run likely failed because of a workflow file issue" with zero jobs started. This skill teaches the YAML-vs-Actions traps (the #-as-comment trap above all), how to quote expression scalars correctly, and how to validate with actionlint before merge.

Scope: syntactic vs. semantic. This skill is about the syntactic and structural correctness of workflow YAML — quoting, parsing, and actionlint-level validity that determines whether GitHub Actions will load and run a file at all. It is not about what a workflow should do or how an agentic workflow should behave. For semantic and functional guidance (designing workflow logic, agentic-workflow patterns, gh-aw authoring), use .github/agents/agentic-workflows.agent.md. The two are complementary: get the behavior right with the agent, get the YAML right with this skill.

When to Use

• Editing, adding, or reviewing any file under .github/workflows/.
• Writing a run-name, name, if, env, with, or run value that embeds a ${{ }} expression.
• A workflow run failed with "This run likely failed because of a workflow file issue" and no jobs ran.
• Eval/CI on main suddenly breaks for every run after a workflow edit merged, even though the change "looked fine."
• Deciding whether a YAML scalar needs quoting.

When Not to Use

• Authoring non-Actions YAML (app config, Kubernetes, Compose, Azure Pipelines, GitLab CI).
• Pure shell/script logic inside an already-valid run: block (that is a scripting task, not a workflow-syntax task).

The #1 Trap: # inside an unquoted expression becomes a YAML comment

In YAML, a space followed by # starts a comment. In an unquoted (plain) scalar, everything from that space-then-# to end-of-line is silently discarded:

# BAD — the run-name is silently truncated at " #"
run-name: ${{ inputs.pr_number != '' && format('Evaluate PR #{0} @ {1}', inputs.pr_number, inputs.head_sha) || '' }}

YAML parses this as run-name: ${{ inputs.pr_number != '' && format('Evaluate PR — an unterminated ${{ expression. yaml.safe_load succeeds (it just sees a truncated string with a trailing comment), so the bug passes naive validation, but GitHub Actions rejects the malformed expression and refuses to start any run.

# GOOD — wrap the whole value in double quotes so '#' stays inside the scalar
run-name: "${{ inputs.pr_number != '' && format('Evaluate PR #{0} @ {1}', inputs.pr_number, inputs.head_sha) || '' }}"

The inner expression already uses single quotes, so double-quoting the scalar is safe. This is exactly the bug that broke dotnet/skills evaluation on main (PR #746 → fixed by quoting).

Other characters that force quoting in a plain scalar

Rule of thumb: if a name, run-name, if, env, or with value contains a ${{ }} expression and any literal #, :, or leading special character, wrap the entire scalar in double quotes.

Workflow

Step 1: Identify the changed/authored workflow files

For each file, scan every line that contains ${{ together with a #, a colon-space, or a leading special character.

Step 2: Quote risky expression scalars

Wrap the full value in double quotes when the value embeds an expression and contains a # or other special character (see the table above). Prefer double quotes when the inner expression uses single quotes, and vice-versa. Do not escape the ${{ }} braces — quoting the scalar is enough.

Step 3: Validate with actionlint (authoritative)

actionlint understands the GitHub Actions schema and the expression grammar, so it catches exactly this class of bug that plain YAML linters miss. Download a pinned release and run it:

On Windows PowerShell, use the actionlint_<ver>_windows_amd64.zip asset and Expand-Archive.

The truncated-expression bug surfaces as:

A clean exit code 0 means the workflows are structurally valid.

Step 4: Confirm a YAML-only check is not enough

Do not rely on yaml.safe_load, yamllint, or "it parses" as proof. They accept the truncated-comment form. Only actionlint (or pushing and watching GitHub Actions parse it) validates the Actions layer.

Step 5: Keep the CI gate green

This repository runs actionlint automatically (see .github/workflows/actionlint.yml) on any PR that touches .github/workflows/. Ensure your change passes that check before requesting review. If you add a new workflow, the gate covers it automatically.

Validation

• Every ${{ }} value containing #, a colon-space, or a leading special character is wrapped in quotes.
• actionlint -shellcheck= -pyflakes= .github/workflows/*.yml exits 0.
• No workflow run reports "This run likely failed because of a workflow file issue".
• The actionlint CI check is green on the PR.

Common Pitfalls

References

• actionlint — static checker for GitHub Actions workflows.
• GitHub Actions: workflow syntax
• YAML 1.2 spec — comments
• Repository skill-authoring guide: .agents/skills/create-skill/SKILL.md](streamdown:incomplete-link)