Frontmatter Reference

This document provides a comprehensive reference for all available frontmatter configuration options in GitHub Agentic Workflows. The examples below are generated from the JSON Schema and include inline comments describing each field.

Schema Description

JSON Schema for validating agentic workflow frontmatter configuration

Complete Frontmatter Reference

---
# Workflow name that appears in the GitHub Actions interface. If not specified,
# defaults to the filename without extension.
# (optional)
name: "My Workflow"

# Optional workflow description that is rendered as a comment in the generated
# GitHub Actions YAML file (.lock.yml)
# (optional)
description: "Description of the workflow"

# Optional statement of the durable outcome the workflow exists to achieve. Unlike
# 'description', which explains what the workflow does, 'intent' explains why the
# workflow exists and should stay implementation-independent. Rendered as a
# comment in the generated GitHub Actions YAML file (.lock.yml).
# (optional)
intent: "example-value"

# Policy for pre-start Docker images in agent and detection jobs. 'always'
# (default) pulls images; 'never' validates exact local RepoDigests and does not
# contact a registry.
# (optional)
docker-image-pull-policy: "always"

# Optional emoji to represent the workflow visually in listings and UI surfaces.
# (optional)
emoji: "example-value"

# Optional source reference indicating where this workflow was added from. Format:
# owner/repo/path@ref (e.g., githubnext/agentics/workflows/ci-doctor.md@v1.0.0).
# Rendered as a comment in the generated lock file.
# (optional)
source: "example-value"

# Optional workflow location redirect for updates. Format: workflow spec or GitHub
# URL (e.g., owner/repo/path@ref or
# https://github.com/owner/repo/blob/main/path.md). When present, update follows
# this location and rewrites source.
# (optional)
redirect: "example-value"

# Optional tracker identifier to tag all created assets (issues, discussions,
# comments, pull requests). Must be at least 8 characters and contain only
# alphanumeric characters, hyphens, and underscores. This identifier will be
# inserted in the body/description of all created assets to enable searching and
# retrieving assets associated with this workflow.
# (optional)
tracker-id: "example-value"

# Auditable false-positive suppression annotations for compiler threat-detection
# rules.
# (optional)
threat-detection-suppress