rules

README

Rules

Rules marked as Online require network access (e.g., GitHub API) and are disabled by default. Use --online to enable them.

Rule	Description	Online
invalid-workflow	Validates that a GitHub Actions workflow file has the required structure.
invalid-action	Validates that a GitHub Actions action metadata file has the required structure.
unpinned-action	Checks that third-party action references are pinned to a full-length commit SHA.
checkout-persist-credentials	Checks that actions/checkout is configured with persist-credentials: false.
dangerous-checkout	Checks that actions/checkout in pull_request_target workflows does not check out pull request head code.
default-permissions	Checks that workflow-level permissions is set to {}.
job-all-permissions	Checks that job-level permissions does not use read-all or write-all.
job-timeout-minutes	Checks that every job explicitly sets timeout-minutes.
invalid-expression	Validates ${{ }} expression syntax in workflow and action files.
missing-sha-ref-comment	Checks that actions pinned to a full-length commit SHA have an inline comment containing a valid git ref.
script-injection	Checks that run: steps and actions/github-script's script: input do not contain ${{ }} expressions.
unused-ignore	Reports unused, unknown, or invalid ghasec-ignore directives.
impostor-commit	Checks that a commit SHA pinned in an action reference is reachable from a branch or tag in the referenced repository.	Yes
mismatched-sha-tag	Checks that a commit SHA pinned in an action reference matches the tag in its inline comment.	Yes

Documentation

Index

• func CheckUnknownKeys(mapping workflow.Mapping, knownKeys map[string]bool) []*diagnostic.Error
• func ExpressionSpanToken(node ast.Node, value string, spanStart, spanEnd int) *token.Token
• func ExpressionSpanTokens(node ast.Node) []*token.Token
• func IsAliasNode(n ast.Node) bool
• func IsBoolean(n ast.Node) bool
• func IsExpressionNode(n ast.Node) bool
• func IsMapping(n ast.Node) bool
• func IsNull(n ast.Node) bool
• func IsNumber(n ast.Node) bool
• func IsSequence(n ast.Node) bool
• func IsString(n ast.Node) bool
• func JoinOr(items []string) string
• func JoinPlural(items []string) string
• func NodeTypeName(n ast.Node) string
• func StringValue(n ast.Node) string
• func UnwrapNode(n ast.Node) ast.Node
• type ActionRule
• type ErrorKind
• type Explainer
• type Rule
• type ValidationError
  • func Dedup(errs []ValidationError) []ValidationError
  • func SortRequiredFirst(errs []ValidationError) []ValidationError
• type WorkflowRule

Functions

func CheckUnknownKeys

func CheckUnknownKeys(mapping workflow.Mapping, knownKeys map[string]bool) []*diagnostic.Error

CheckUnknownKeys reports an error for each mapping entry whose key is not present in knownKeys.

func ExpressionSpanToken

func ExpressionSpanToken(node ast.Node, value string, spanStart, spanEnd int) *token.Token

ExpressionSpanToken creates a synthetic token that points to a ${{ }} span within a string value, for precise error positioning. It adjusts the line, column, and value to cover only the expression span (e.g., "${{ github.actor }}") rather than the entire string.

For block scalars (| and >), the function correctly computes the line and column by accounting for newlines within the value and the content indentation.

spanStart is the byte offset of "${{" within the string value. spanEnd is the byte offset past "}}" within the string value.

func ExpressionSpanTokens

func ExpressionSpanTokens(node ast.Node) []*token.Token

ExpressionSpanTokens returns a synthetic token for each ${{ }} span in a string node's value. If the value contains no expressions, returns nil.

func IsAliasNode

func IsAliasNode(n ast.Node) bool

IsAliasNode returns true if the node (after unwrapping anchors) is an alias. Generated validation code uses this to skip type-mismatch diagnostics for alias nodes, because the corresponding anchor definition is validated in place. This prevents false positives like `"steps" elements must be mappings, but got alias`.

func IsBoolean

func IsBoolean(n ast.Node) bool

func IsExpressionNode

func IsExpressionNode(n ast.Node) bool

func IsMapping

func IsMapping(n ast.Node) bool

func IsNull

func IsNull(n ast.Node) bool

func IsNumber

func IsNumber(n ast.Node) bool

func IsSequence

func IsSequence(n ast.Node) bool

func IsString

func IsString(n ast.Node) bool

func JoinOr

func JoinOr(items []string) string

JoinOr formats alternatives with proper English: "a", "a or b", "a, b, or c".

func JoinPlural

func JoinPlural(items []string) string

JoinPlural formats allowed types in plural form: "strings", "mappings", etc.

func NodeTypeName

func NodeTypeName(n ast.Node) string

func StringValue

func StringValue(n ast.Node) string

func UnwrapNode

func UnwrapNode(n ast.Node) ast.Node

UnwrapNode unwraps AnchorNode wrappers to get the actual value node. AliasNode is NOT unwrapped because its Value field contains the alias name, not the resolved target.

Types

type ActionRule

type ActionRule interface {
	Rule
	CheckAction(mapping workflow.ActionMapping) []*diagnostic.Error
}

ActionRule validates action metadata files (action.yml|yaml). CheckAction must be safe for concurrent use from multiple goroutines.

type ErrorKind

type ErrorKind int

const (
	KindUnknownKey ErrorKind = iota
	KindRequiredKey
	KindTypeMismatch
	KindInvalidEnum
	KindMinItems   // sequence/mapping has too few items
	KindDependency // property dependency: key present but required co-key missing
)

type Explainer

type Explainer interface {
	Why() string
	Fix() string
}

Explainer provides optional guidance for markdown output. Rules that implement this interface will have Why/Fix fields included in the markdown output format.

type Rule

type Rule interface {
	ID() string
	Required() bool
	Online() bool
}

Rule defines common metadata for all validation rules.

type ValidationError

type ValidationError struct {
	Kind    ErrorKind
	Path    string   // dotted path (e.g. "jobs.build.permissions")
	Parent  string   // parent key name for context-rich messages (e.g. "permissions", "branding")
	Context string   // domain term for the error (e.g. "scope", "color", "event")
	Key     string   // target key name or value
	Got     string   // actual value/type
	Allowed []string // allowed values (for enum, etc.)
	Token   *token.Token
}

func Dedup

func Dedup(errs []ValidationError) []ValidationError

Dedup removes duplicate ValidationErrors (same token offset + kind + key + got).

func SortRequiredFirst

func SortRequiredFirst(errs []ValidationError) []ValidationError

SortRequiredFirst reorders errors so that KindRequiredKey errors at the same position come before other errors.

type WorkflowRule

type WorkflowRule interface {
	Rule
	CheckWorkflow(mapping workflow.WorkflowMapping) []*diagnostic.Error
}

WorkflowRule validates workflow files (.github/workflows/*.yml|yaml). CheckWorkflow must be safe for concurrent use from multiple goroutines.