pantheon-ai/github-actions-validator

Comprehensive toolkit for validating, linting, and testing GitHub Actions workflow files, custom local actions, and public actions. Use this skill when working with GitHub Actions YAML files (.github/workflows/*.yml), validating workflow syntax, testing workflow execution with act, or debugging workflow issues.

Overall
score

93%

Review — 93%

Does it follow best practices?

Validation — 11 / 11 Passed

Validation for skill structure

Common GitHub Actions Errors and Solutions

Name: pantheon-ai/github-actions-validator
Author: pantheon-ai

This reference lists common errors encountered when working with GitHub Actions and how to fix them.

Syntax Errors

1. Invalid YAML Syntax

Error:

Error: Unable to process file command 'workflow' successfully.

Common Causes:

Incorrect indentation (YAML is whitespace-sensitive)
Missing colons
Unquoted strings containing special characters
Tabs instead of spaces

Fix:

# Bad
name:My Workflow
jobs:
build:
  runs-on: ubuntu-latest

# Good
name: My Workflow
jobs:
  build:
    runs-on: ubuntu-latest

2. Missing Required Fields

Error:

Required property is missing: name

Fix:

# Every workflow needs a name
name: CI Pipeline

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0

3. Invalid Workflow Triggers

Error:

The workflow is not valid. Unexpected value 'on'

Fix:

# Bad - wrong event name
on:
  pull-request:  # Should be pull_request

# Good
on:
  pull_request:
  push:

Expression Errors

1. Incorrect Expression Syntax

Error:

Unrecognized named-value: 'github'. Located at position 1 within expression: github.ref

Fix:

# Bad - missing ${{ }}
if: github.ref == 'refs/heads/main'

# Good
if: ${{ github.ref == 'refs/heads/main' }}

# Even better (GitHub Actions auto-evaluates if conditions)
if: github.ref == 'refs/heads/main'

2. Type Mismatches

Error:

Expected boolean value, got string

Fix:

# Bad
if: ${{ 'true' }}  # String, not boolean

# Good
if: ${{ true }}
if: ${{ success() }}
if: ${{ github.event_name == 'push' }}

3. Script Injection Vulnerabilities

Warning:

Potential script injection via untrusted input

Fix:

# Bad - vulnerable to injection
run: echo ${{ github.event.issue.title }}

# Good - use environment variables
env:
  TITLE: ${{ github.event.issue.title }}
run: echo "$TITLE"

Action Errors

1. Action Not Found

Error:

Can't find 'action.yml', 'action.yaml' or 'Dockerfile' under '/home/runner/work/_actions/actions/chekout/v4'

Common Causes:

Typo in action name
Invalid action reference
Action doesn't exist or was removed

Fix:

# Bad
- uses: actions/chekout@v4  # Typo

# Good
- uses: actions/checkout@v4

2. Missing Required Inputs

Error:

Input required and not supplied: path

Fix:

# Bad
- uses: some-action@v1

# Good
- uses: some-action@v1
  with:
    path: ./my-path

3. Unknown Action Inputs

Error:

Unexpected input 'invalid_input'

Fix:

# Check the action's documentation for valid inputs
- uses: actions/checkout@v4
  with:
    # Only use documented inputs
    ref: main
    # Remove undocumented inputs

4. Deprecated Action Versions

Warning:

Node.js 12/16 actions are deprecated

Fix:

# Deprecated - Node.js 12 (EOL April 2022)
- uses: actions/checkout@v2

# Deprecated - Node.js 16 (EOL September 2023)
- uses: actions/checkout@v3

# Older - Node.js 20 (EOL April 2026)
- uses: actions/checkout@v4
- uses: actions/checkout@v5

# Current - Node.js 20+/24 (v6)
- uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0
- uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903  # v6.0.0

# Note: Node.js 20 EOL is April 2026, Node.js 22 and 24 are current

Job Configuration Errors

1. Invalid Runner Label

Error:

Unable to locate executable file: ubuntu-lastest

Fix:

# Bad
runs-on: ubuntu-lastest  # Typo

# Good
runs-on: ubuntu-latest

Valid runner labels:

ubuntu-latest, ubuntu-22.04, ubuntu-20.04
windows-latest, windows-2025, windows-2022, windows-2019
macos-latest (now macOS 15), macos-15, macos-14, macos-26 (preview)
macos-13 (RETIRED November 14, 2025 - no longer available)
macos-15-intel, macos-15-large (Intel x86_64, long-term deprecated)
macos-15-xlarge, macos-14-xlarge (M2 Pro with GPU)
gpu-t4-4-core (GPU runners for ML/AI)
ARM64 runners (free for public repos)

2. Undefined Job Dependency

Error:

Job 'deploy' depends on job 'biuld' which does not exist

Fix:

# Bad
jobs:
  build:
    runs-on: ubuntu-latest
  deploy:
    needs: biuld  # Typo

# Good
jobs:
  build:
    runs-on: ubuntu-latest
  deploy:
    needs: build

3. Circular Job Dependencies

Error:

Circular dependency detected

Fix:

# Bad
jobs:
  job1:
    needs: job2
  job2:
    needs: job1  # Circular!

# Good
jobs:
  job1:
    runs-on: ubuntu-latest
  job2:
    needs: job1

Schedule Errors

1. Invalid CRON Syntax

Error:

Invalid CRON expression: '0 0 * * 8'

Fix:

# Bad
schedule:
  - cron: '0 0 * * 8'  # Day 8 doesn't exist

# Good
schedule:
  - cron: '0 0 * * 0'  # Sunday

# CRON format: minute hour day month weekday
# Minute: 0-59
# Hour: 0-23
# Day: 1-31
# Month: 1-12
# Weekday: 0-6 (0 = Sunday)

2. Multiple Schedule Entries

# Correct way to define multiple schedules
on:
  schedule:
    - cron: '0 0 * * 1'  # Monday at midnight
    - cron: '0 12 * * 5'  # Friday at noon

Path Filter Errors

1. Invalid Glob Pattern

Error:

Invalid glob pattern: '**.js'

Fix:

# Bad
on:
  push:
    paths:
      - '**.js'  # Missing directory separator

# Good
on:
  push:
    paths:
      - '**/*.js'
      - 'src/**'

Environment and Secrets

1. Secret Not Found

Error:

Secret MY_SECRET not found

Fix:

Ensure the secret is defined in repository settings
Check secret name spelling (case-sensitive)
Verify secret scope (repository vs organization vs environment)

# Use secrets correctly
env:
  API_KEY: ${{ secrets.MY_SECRET }}  # Must match name in settings

2. Environment Variables in run

Common Issue:

# Bad - environment variable not accessible
steps:
  - run: echo $MY_VAR  # May not work on Windows

# Good - use env
steps:
  - name: Print variable
    env:
      MY_VAR: ${{ secrets.MY_SECRET }}
    run: echo "$MY_VAR"  # Unix
    # or
    run: echo $env:MY_VAR  # Windows PowerShell

Matrix Strategy Errors

1. Invalid Matrix Configuration

Error:

Matrix configuration is invalid

Fix:

# Bad
strategy:
  matrix:
    os: ubuntu-latest  # Should be an array

# Good
strategy:
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
    node: [20, 22, 24]  # Node 16 EOL Sep 2023, Node 20 EOL Apr 2026

2. Matrix Variable Reference

# Correct way to reference matrix variables
strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
jobs:
  test:
    runs-on: ${{ matrix.os }}

Conditional Execution Errors

1. Always/Cancelled/Failure Conditions

# Understanding conditions
steps:
  - name: Run on success (default)
    run: echo "Runs only if previous steps succeeded"

  - name: Run always
    if: always()
    run: echo "Runs whether previous steps succeeded or failed"

  - name: Run on failure
    if: failure()
    run: echo "Runs only if a previous step failed"

  - name: Run on success
    if: success()
    run: echo "Runs only if all previous steps succeeded"

Debugging Tips

1. Enable Debug Logging

Set secrets in repository settings:

ACTIONS_STEP_DEBUG = true (detailed step logs)
ACTIONS_RUNNER_DEBUG = true (runner diagnostic logs)

2. Use tmate for Interactive Debugging

steps:
  - name: Setup tmate session
    if: failure()
    uses: mxschmitt/action-tmate@v3

3. Print Context Information

steps:
  - name: Dump GitHub context
    run: echo '${{ toJSON(github) }}'

  - name: Dump job context
    run: echo '${{ toJSON(job) }}'

  - name: Dump runner context
    run: echo '${{ toJSON(runner) }}'

Best Practices

Always use specific action versions: actions/checkout@v6 not actions/checkout@main
Quote strings with special characters: name: "My: Workflow"
Use shellcheck: Enable shell script linting
Validate locally: Use act and actionlint before pushing
Use env for secrets: Never put secrets directly in run commands
Keep workflows DRY: Use reusable workflows and composite actions
Set timeouts: Prevent runaway jobs with timeout-minutes
Use concurrency: Cancel redundant runs with concurrency groups

# Example of good practices
name: Production Deployment

on:
  push:
    branches: [main]

concurrency:
  group: production
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0

      - name: Deploy
        env:
          API_KEY: ${{ secrets.API_KEY }}
        run: |
          ./deploy.sh

Install with Tessl CLI

npx tessl i pantheon-ai/github-actions-validator@0.1.0

assets

references

scripts

pantheon-ai/github-actions-validator

common_errors.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}references/

Common GitHub Actions Errors and Solutions

Syntax Errors

1. Invalid YAML Syntax

2. Missing Required Fields

3. Invalid Workflow Triggers

Expression Errors

1. Incorrect Expression Syntax

2. Type Mismatches

3. Script Injection Vulnerabilities

Action Errors

1. Action Not Found

2. Missing Required Inputs

3. Unknown Action Inputs

4. Deprecated Action Versions

Job Configuration Errors

1. Invalid Runner Label

2. Undefined Job Dependency

3. Circular Job Dependencies

Schedule Errors

1. Invalid CRON Syntax

2. Multiple Schedule Entries

Path Filter Errors

1. Invalid Glob Pattern

Environment and Secrets

1. Secret Not Found

2. Environment Variables in run

Matrix Strategy Errors

1. Invalid Matrix Configuration

2. Matrix Variable Reference

Conditional Execution Errors

1. Always/Cancelled/Failure Conditions

Debugging Tips

1. Enable Debug Logging

2. Use tmate for Interactive Debugging

3. Print Context Information

Best Practices

common_errors.mdreferences/