mirror of
https://github.com/ivuorinen/actions.git
synced 2026-01-26 11:34:00 +00:00
feat: fixes, tweaks, new actions, linting (#186)
* feat: fixes, tweaks, new actions, linting * fix: improve docker publish loops and dotnet parsing (#193) * fix: harden action scripts and version checks (#191) * refactor: major repository restructuring and security enhancements Add comprehensive development infrastructure: - Add Makefile with automated documentation generation, formatting, and linting tasks - Add TODO.md tracking self-containment progress and repository improvements - Add .nvmrc for consistent Node.js version management - Create python-version-detect-v2 action for enhanced Python detection Enhance all GitHub Actions with standardized patterns: - Add consistent token handling across 27 actions using standardized input patterns - Implement bash error handling (set -euo pipefail) in all shell steps - Add comprehensive input validation for path traversal and command injection protection - Standardize checkout token authentication to prevent rate limiting - Remove relative action dependencies to ensure external usability Rewrite security workflow for PR-focused analysis: - Transform security-suite.yml to PR-only security analysis workflow - Remove scheduled runs, repository issue management, and Slack notifications - Implement smart comment generation showing only sections with content - Add GitHub Actions permission diff analysis and new action detection - Integrate OWASP, Semgrep, and TruffleHog for comprehensive PR security scanning Improve version detection and dependency management: - Simplify version detection actions to use inline logic instead of shared utilities - Fix Makefile version detection fallback to properly return 'main' when version not found - Update all external action references to use SHA-pinned versions - Remove deprecated run.sh in favor of Makefile automation Update documentation and project standards: - Enhance CLAUDE.md with self-containment requirements and linting standards - Update README.md with improved action descriptions and usage examples - Standardize code formatting with updated .editorconfig and .prettierrc.yml - Improve GitHub templates for issues and security reporting This refactoring ensures all 40 actions are fully self-contained and can be used independently when referenced as ivuorinen/actions/action-name@main, addressing the critical requirement for external usability while maintaining comprehensive security analysis and development automation. * feat: add automated action catalog generation system - Create generate_listing.cjs script for comprehensive action catalog - Add package.json with development tooling and npm scripts - Implement automated README.md catalog section with --update flag - Generate markdown reference-style links for all 40 actions - Add categorized tables with features, language support matrices - Replace static reference links with auto-generated dynamic links - Enable complete automation of action documentation maintenance * feat: enhance actions with improved documentation and functionality - Add comprehensive README files for 12 actions with usage examples - Implement new utility actions (go-version-detect, dotnet-version-detect) - Enhance node-setup with extensive configuration options - Improve error handling and validation across all actions - Update package.json scripts for better development workflow - Expand TODO.md with detailed roadmap and improvement plans - Standardize action structure with consistent inputs/outputs * feat: add comprehensive output handling across all actions - Add standardized outputs to 15 actions that previously had none - Implement consistent snake_case naming convention for all outputs - Add build status and test results outputs to build actions - Add files changed and status outputs to lint/fix actions - Add test execution metrics to php-tests action - Add stale/closed counts to stale action - Add release URLs and IDs to github-release action - Update documentation with output specifications - Mark comprehensive output handling task as complete in TODO.md * feat: implement shared cache strategy across all actions - Add caching to 10 actions that previously had none (Node.js, .NET, Python, Go) - Standardize 4 existing actions to use common-cache instead of direct actions/cache - Implement consistent cache-hit optimization to skip installations when cache available - Add language-specific cache configurations with appropriate key files - Create unified caching approach using ivuorinen/actions/common-cache@main - Fix YAML syntax error in php-composer action paths parameter - Update TODO.md to mark shared cache strategy as complete * feat: implement comprehensive retry logic for network operations - Create new common-retry action for standardized retry patterns with configurable strategies - Add retry logic to 9 actions missing network retry capabilities - Implement exponential backoff, custom timeouts, and flexible error handling - Add max-retries input parameter to all network-dependent actions (Node.js, .NET, Python, Go) - Standardize existing retry implementations to use common-retry utility - Update action catalog to include new common-retry action (41 total actions) - Update documentation with retry configuration examples and parameters - Mark retry logic implementation as complete in TODO.md roadmap * feat: enhance Node.js support with Corepack and Bun - Add Corepack support for automatic package manager version management - Add Bun package manager support across all Node.js actions - Improve Yarn Berry/PnP support with .yarnrc.yml detection - Add Node.js feature detection (ESM, TypeScript, frameworks) - Update package manager detection priority and lockfile support - Enhance caching with package-manager-specific keys - Update eslint, prettier, and biome actions for multi-package-manager support * fix: resolve critical runtime issues across multiple actions - Fix token validation by removing ineffective literal string comparisons - Add missing @microsoft/eslint-formatter-sarif dependency for SARIF output - Fix Bash variable syntax errors in username and changelog length checks - Update Dockerfile version regex to handle tags with suffixes (e.g., -alpine) - Simplify version selection logic with single grep command - Fix command execution in retry action with proper bash -c wrapper - Correct step output references using .outcome instead of .outputs.outcome - Add missing step IDs for version detection actions - Include go.mod in cache key files for accurate invalidation - Require minor version in all version regex patterns - Improve Bun installation security by verifying script before execution - Replace bc with sort -V for portable PHP version comparison - Remove non-existent pre-commit output references These fixes ensure proper runtime behavior, improved security, and better cross-platform compatibility across all affected actions. * fix: resolve critical runtime and security issues across actions - Fix biome-fix files_changed calculation using git diff instead of git status delta - Fix compress-images output description and add absolute path validation - Remove csharp-publish token default and fix token fallback in push commands - Add @microsoft/eslint-formatter-sarif to all package managers in eslint-check - Fix eslint-check command syntax by using variable assignment - Improve node-setup Bun installation security and remove invalid frozen-lockfile flag - Fix pre-commit token validation by removing ineffective literal comparison - Fix prettier-fix token comparison and expand regex for all GitHub token types - Add version-file-parser regex validation safety and fix csproj wildcard handling These fixes address security vulnerabilities, runtime errors, and functional issues to ensure reliable operation across all affected GitHub Actions. * feat: enhance Docker actions with advanced multi-architecture support Major enhancement to Docker build and publish actions with comprehensive multi-architecture capabilities and enterprise-grade features. Added features: - Advanced buildx configuration (version control, cache modes, build contexts) - Auto-detect platforms for dynamic architecture discovery - Performance optimizations with enhanced caching strategies - Security scanning with Trivy and image signing with Cosign - SBOM generation in multiple formats with validation - Verbose logging and dry-run modes for debugging - Platform-specific build args and fallback mechanisms Enhanced all Docker actions: - docker-build: Core buildx features and multi-arch support - docker-publish-gh: GitHub Packages with security features - docker-publish-hub: Docker Hub with scanning and signing - docker-publish: Orchestrator with unified configuration Updated documentation across all modified actions. * fix: resolve documentation generation placeholder issue Fixed Makefile and package.json to properly replace placeholder tokens in generated documentation, ensuring all README files show correct repository paths instead of ***PROJECT***@***VERSION***. * chore: simplify github token validation * chore(lint): optional yamlfmt, config and fixes * feat: use relative `uses` names * feat: comprehensive testing infrastructure and Python validation system - Migrate from tests/ to _tests/ directory structure with ShellSpec framework - Add comprehensive validation system with Python-based input validation - Implement dual testing approach (ShellSpec + pytest) for complete coverage - Add modern Python tooling (uv, ruff, pytest-cov) and dependencies - Create centralized validation rules with automatic generation system - Update project configuration and build system for new architecture - Enhance documentation to reflect current testing capabilities This establishes a robust foundation for action validation and testing with extensive coverage across all GitHub Actions in the repository. * chore: remove Dockerfile for now * chore: code review fixes * feat: comprehensive GitHub Actions restructuring and tooling improvements This commit represents a major restructuring of the GitHub Actions monorepo with improved tooling, testing infrastructure, and comprehensive PR #186 review implementation. ## Major Changes ### 🔧 Development Tooling & Configuration - **Shellcheck integration**: Exclude shellspec test files from linting - Updated .pre-commit-config.yaml to exclude _tests/*.sh from shellcheck/shfmt - Modified Makefile shellcheck pattern to skip shellspec files - Updated CLAUDE.md documentation with proper exclusion syntax - **Testing infrastructure**: Enhanced Python validation framework - Fixed nested if statements and boolean parameter issues in validation.py - Improved code quality with explicit keyword arguments - All pre-commit hooks now passing ### 🏗️ Project Structure & Documentation - **Added Serena AI integration** with comprehensive project memories: - Project overview, structure, and technical stack documentation - Code style conventions and completion requirements - Comprehensive PR #186 review analysis and implementation tracking - **Enhanced configuration**: Updated .gitignore, .yamlfmt.yml, pyproject.toml - **Improved testing**: Added integration workflows and enhanced test specs ### 🚀 GitHub Actions Improvements (30+ actions updated) - **Centralized validation**: Updated 41 validation rule files - **Enhanced actions**: Improvements across all action categories: - Setup actions (node-setup, version detectors) - Utility actions (version-file-parser, version-validator) - Linting actions (biome, eslint, terraform-lint-fix major refactor) - Build/publish actions (docker-build, npm-publish, csharp-*) - Repository management actions ### 📝 Documentation Updates - **README consistency**: Updated version references across action READMEs - **Enhanced documentation**: Improved action descriptions and usage examples - **CLAUDE.md**: Updated with current tooling and best practices ## Technical Improvements - **Security enhancements**: Input validation and sanitization improvements - **Performance optimizations**: Streamlined action logic and dependencies - **Cross-platform compatibility**: Better Windows/macOS/Linux support - **Error handling**: Improved error reporting and user feedback ## Files Changed - 100 files changed - 13 new Serena memory files documenting project state - 41 validation rules updated for consistency - 30+ GitHub Actions and READMEs improved - Core tooling configuration enhanced * feat: comprehensive GitHub Actions improvements and PR review fixes Major Infrastructure Improvements: - Add comprehensive testing framework with 17+ ShellSpec validation tests - Implement Docker-based testing tools with automated test runner - Add CodeRabbit configuration for automated code reviews - Restructure documentation and memory management system - Update validation rules for 25+ actions with enhanced input validation - Modernize CI/CD workflows and testing infrastructure Critical PR Review Fixes (All Issues Resolved): - Fix double caching in node-setup (eliminate redundant cache operations) - Optimize shell pipeline in version-file-parser (single awk vs complex pipeline) - Fix GitHub expression interpolation in prettier-check cache keys - Resolve terraform command order issue (validation after setup) - Add missing flake8-sarif dependency for Python SARIF output - Fix environment variable scope in pr-lint (export to GITHUB_ENV) Performance & Reliability: - Eliminate duplicate cache operations saving CI time - Improve shell script efficiency with optimized parsing - Fix command execution dependencies preventing runtime failures - Ensure proper dependency installation for all linting tools - Resolve workflow conditional logic issues Security & Quality: - All input validation rules updated with latest security patterns - Cross-platform compatibility improvements maintained - Comprehensive error handling and retry logic preserved - Modern development tooling and best practices adopted This commit addresses 100% of actionable feedback from PR review analysis, implements comprehensive testing infrastructure, and maintains high code quality standards across all 41 GitHub Actions. * feat: enhance expression handling and version parsing - Fix node-setup force-version expression logic for proper empty string handling - Improve version-file-parser with secure regex validation and enhanced Python detection - Add CodeRabbit configuration for CalVer versioning and README review guidance * feat(validate-inputs): implement modular validation system - Add modular validator architecture with specialized validators - Implement base validator classes for different input types - Add validators: boolean, docker, file, network, numeric, security, token, version - Add convention mapper for automatic input validation - Add comprehensive documentation for the validation system - Implement PCRE regex support and injection protection * feat(validate-inputs): add validation rules for all actions - Add YAML validation rules for 42 GitHub Actions - Auto-generated rules with convention mappings - Include metadata for validation coverage and quality indicators - Mark rules as auto-generated to prevent manual edits * test(validate-inputs): add comprehensive test suite for validators - Add unit tests for all validator modules - Add integration tests for the validation system - Add fixtures for version test data - Test coverage for boolean, docker, file, network, numeric, security, token, and version validators - Add tests for convention mapper and registry * feat(tools): add validation scripts and utilities - Add update-validators.py script for auto-generating rules - Add benchmark-validator.py for performance testing - Add debug-validator.py for troubleshooting - Add generate-tests.py for test generation - Add check-rules-not-manually-edited.sh for CI validation - Add fix-local-action-refs.py tool for fixing action references * feat(actions): add CustomValidator.py files for specialized validation - Add custom validators for actions requiring special validation logic - Implement validators for docker, go, node, npm, php, python, terraform actions - Add specialized validation for compress-images, common-cache, common-file-check - Implement version detection validators with language-specific logic - Add validation for build arguments, architectures, and version formats * test: update ShellSpec test framework for Python validation - Update all validation.spec.sh files to use Python validator - Add shared validation_core.py for common test utilities - Remove obsolete bash validation helpers - Update test output expectations for Python validator format - Add codeql-analysis test suite - Refactor framework utilities for Python integration - Remove deprecated test files * feat(actions): update action.yml files to use validate-inputs - Replace inline bash validation with validate-inputs action - Standardize validation across all 42 actions - Add new codeql-analysis action - Update action metadata and branding - Add validation step as first step in composite actions - Maintain backward compatibility with existing inputs/outputs * ci: update GitHub workflows for enhanced security and testing - Add new codeql-new.yml workflow - Update security scanning workflows - Enhance dependency review configuration - Update test-actions workflow for new validation system - Improve workflow permissions and security settings - Update action versions to latest SHA-pinned releases * build: update build configuration and dependencies - Update Makefile with new validation targets - Add Python dependencies in pyproject.toml - Update npm dependencies and scripts - Enhance Docker testing tools configuration - Add targets for validator updates and local ref fixes - Configure uv for Python package management * chore: update linting and documentation configuration - Update EditorConfig settings for consistent formatting - Enhance pre-commit hooks configuration - Update prettier and yamllint ignore patterns - Update gitleaks security scanning rules - Update CodeRabbit review configuration - Update CLAUDE.md with latest project standards and rules * docs: update Serena memory files and project metadata - Remove obsolete PR-186 memory files - Update project overview with current architecture - Update project structure documentation - Add quality standards and communication guidelines - Add modular validator architecture documentation - Add shellspec testing framework documentation - Update project.yml with latest configuration * feat: moved rules.yml to same folder as action, fixes * fix(validators): correct token patterns and fix validator bugs - Fix GitHub classic PAT pattern: ghp_ + 36 chars = 40 total - Fix GitHub fine-grained PAT pattern: github_pat_ + 71 chars = 82 total - Initialize result variable in convention_mapper to prevent UnboundLocalError - Fix empty URL validation in network validator to return error - Add GitHub expression check to docker architectures validator - Update docker-build CustomValidator parallel-builds max to 16 * test(validators): fix test fixtures and expectations - Fix token lengths in test data: github_pat 71 chars, ghp/gho 36 chars - Update integration tests with correct token lengths - Fix file validator test to expect absolute paths rejected for security - Rename TestGenerator import to avoid pytest collection warning - Update custom validator tests with correct input names - Change docker-build tests: platforms->architectures, tags->tag - Update docker-publish tests to match new registry enum validation * test(shellspec): fix token lengths in test helpers and specs - Fix default token lengths in spec_helper.sh to use correct 40-char format - Update csharp-publish default tokens in 4 locations - Update codeql-analysis default tokens in 2 locations - Fix codeql-analysis test tokens to correct lengths (40 and 82 chars) - Fix npm-publish fine-grained token test to use 82-char format * feat(actions): add permissions documentation and environment variable usage - Add permissions comments to all action.yml files documenting required GitHub permissions - Convert direct input usage to environment variables in shell steps for security - Add validation steps with proper error handling - Update input descriptions and add security notes where applicable - Ensure all actions follow consistent patterns for input validation * chore(workflows): update GitHub Actions workflow versions - Update workflow action versions to latest - Improve workflow consistency and maintainability * docs(security): add comprehensive security policy - Document security features and best practices - Add vulnerability reporting process - Include audit history and security testing information * docs(memory): add GitHub workflow reference documentation - Add GitHub Actions workflow commands reference - Add GitHub workflow expressions guide - Add secure workflow usage patterns and best practices * chore: token optimization, code style conventions * chore: cr fixes * fix: trivy reported Dockerfile problems * fix(security): more security fixes * chore: dockerfile and make targets for publishing * fix(ci): add creds to test-actions workflow * fix: security fix and checkout step to codeql-new * chore: test fixes * fix(security): codeql detected issues * chore: code review fixes, ReDos protection * style: apply MegaLinter fixes * fix(ci): missing packages read permission * fix(ci): add missing working directory setting * chore: linting, add validation-regex to use regex_pattern * chore: code review fixes * chore(deps): update actions * fix(security): codeql fixes * chore(cr): apply cr comments * chore: improve POSIX compatibility * chore(cr): apply cr comments * fix: codeql warning in Dockerfile, build failures * chore(cr): apply cr comments * fix: docker-testing-tools/Dockerfile * chore(cr): apply cr comments * fix(docker): update testing-tools image for GitHub Actions compatibility * chore(cr): apply cr comments * feat: add more tests, fix issues * chore: fix codeql issues, update actions * chore(cr): apply cr comments * fix: integration tests * chore: deduplication and fixes * style: apply MegaLinter fixes * chore(cr): apply cr comments * feat: dry-run mode for generate-tests * fix(ci): kcov installation * chore(cr): apply cr comments * chore(cr): apply cr comments * chore(cr): apply cr comments * chore(cr): apply cr comments, simplify action testing, use uv * fix: run-tests.sh action counting * chore(cr): apply cr comments * chore(cr): apply cr comments
This commit is contained in:
GitHub
526
validate-inputs/docs/ACTION_MAINTAINER.md
Normal file
526
validate-inputs/docs/ACTION_MAINTAINER.md
Normal file
@@ -0,0 +1,526 @@
|
||||
# Action Maintainer Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This guide helps action maintainers understand and use the validation system for their GitHub Actions.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [How Validation Works](#how-validation-works)
|
||||
2. [Using Automatic Validation](#using-automatic-validation)
|
||||
3. [Custom Validation](#custom-validation)
|
||||
4. [Testing Your Validation](#testing-your-validation)
|
||||
5. [Common Scenarios](#common-scenarios)
|
||||
6. [Troubleshooting](#troubleshooting)
|
||||
|
||||
## How Validation Works
|
||||
|
||||
### Automatic Integration
|
||||
|
||||
Your action automatically gets input validation when using `validate-inputs`:
|
||||
|
||||
```yaml
|
||||
# In your action.yml
|
||||
runs:
|
||||
using: composite
|
||||
steps:
|
||||
- name: Validate inputs
|
||||
uses: ./validate-inputs
|
||||
with:
|
||||
action-type: ${{ github.action }}
|
||||
```
|
||||
|
||||
### Validation Flow
|
||||
|
||||
1. **Input Collection**: All `INPUT_*` environment variables are collected
|
||||
2. **Validator Selection**: System chooses appropriate validator
|
||||
3. **Validation Execution**: Each input is validated
|
||||
4. **Error Reporting**: Any errors are reported via `::error::`
|
||||
5. **Status Output**: Results written to `GITHUB_OUTPUT`
|
||||
|
||||
## Using Automatic Validation
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
Name your inputs to get automatic validation:
|
||||
|
||||
| Input Pattern | Validation Type | Example |
|
||||
|----------------------|--------------------|----------------------------------|
|
||||
| `*-token` | Token validation | `github-token`, `npm-token` |
|
||||
| `*-version` | Version validation | `node-version`, `python-version` |
|
||||
| `dry-run`, `verbose` | Boolean | `dry-run: true` |
|
||||
| `max-*`, `*-limit` | Numeric range | `max-retries`, `rate-limit` |
|
||||
| `*-file`, `*-path` | File path | `config-file`, `output-path` |
|
||||
| `*-url`, `webhook-*` | URL validation | `api-url`, `webhook-endpoint` |
|
||||
|
||||
### Example Action
|
||||
|
||||
```yaml
|
||||
name: My Action
|
||||
description: Example action with automatic validation
|
||||
|
||||
inputs:
|
||||
github-token: # Automatically validates GitHub token format
|
||||
description: GitHub token for API access
|
||||
required: true
|
||||
default: ${{ github.token }}
|
||||
|
||||
node-version: # Automatically validates version format
|
||||
description: Node.js version to use
|
||||
required: false
|
||||
default: '18'
|
||||
|
||||
max-retries: # Automatically validates numeric range
|
||||
description: Maximum number of retries (1-10)
|
||||
required: false
|
||||
default: '3'
|
||||
|
||||
config-file: # Automatically validates file path
|
||||
description: Configuration file path
|
||||
required: false
|
||||
default: '.config.yml'
|
||||
|
||||
dry-run: # Automatically validates boolean
|
||||
description: Run in dry-run mode
|
||||
required: false
|
||||
default: 'false'
|
||||
|
||||
runs:
|
||||
using: composite
|
||||
steps:
|
||||
- uses: ./validate-inputs
|
||||
with:
|
||||
action-type: ${{ github.action }}
|
||||
|
||||
- run: echo "Inputs validated successfully"
|
||||
shell: bash
|
||||
```
|
||||
|
||||
### Validation Rules File
|
||||
|
||||
After creating your action, generate validation rules:
|
||||
|
||||
```bash
|
||||
# Generate rules for your action
|
||||
make update-validators
|
||||
|
||||
# Or for a specific action
|
||||
python3 validate-inputs/scripts/update-validators.py --action my-action
|
||||
```
|
||||
|
||||
This creates `my-action/rules.yml`:
|
||||
|
||||
```yaml
|
||||
schema_version: '1.0'
|
||||
action: my-action
|
||||
description: Example action with automatic validation
|
||||
required_inputs:
|
||||
- github-token
|
||||
optional_inputs:
|
||||
- node-version
|
||||
- max-retries
|
||||
- config-file
|
||||
- dry-run
|
||||
conventions:
|
||||
github-token: github_token
|
||||
node-version: semantic_version
|
||||
max-retries: numeric_range_1_10
|
||||
config-file: file_path
|
||||
dry-run: boolean
|
||||
```
|
||||
|
||||
## Custom Validation
|
||||
|
||||
### When to Use Custom Validation
|
||||
|
||||
Create a custom validator when:
|
||||
|
||||
- You have complex business logic
|
||||
- Cross-field validation is needed
|
||||
- Special format requirements exist
|
||||
- Default validation is insufficient
|
||||
|
||||
### Creating a Custom Validator
|
||||
|
||||
1. **Create `CustomValidator.py`** in your action directory:
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""Custom validator for my-action."""
|
||||
|
||||
from __future__ import annotations
|
||||
from pathlib import Path
|
||||
import sys
|
||||
|
||||
# Add validate-inputs to path
|
||||
validate_inputs_path = Path(__file__).parent.parent / "validate-inputs"
|
||||
sys.path.insert(0, str(validate_inputs_path))
|
||||
|
||||
from validators.base import BaseValidator
|
||||
from validators.version import VersionValidator
|
||||
|
||||
|
||||
class CustomValidator(BaseValidator):
|
||||
"""Custom validator for my-action."""
|
||||
|
||||
def __init__(self, action_type: str = "my-action") -> None:
|
||||
super().__init__(action_type)
|
||||
self.version_validator = VersionValidator(action_type)
|
||||
|
||||
def validate_inputs(self, inputs: dict[str, str]) -> bool:
|
||||
valid = True
|
||||
|
||||
# Check required inputs
|
||||
valid &= self.validate_required_inputs(inputs)
|
||||
|
||||
# Custom validation
|
||||
if inputs.get("environment"):
|
||||
valid &= self.validate_environment(inputs["environment"])
|
||||
|
||||
# Cross-field validation
|
||||
if inputs.get("environment") == "production":
|
||||
if not inputs.get("approval-required"):
|
||||
self.add_error(
|
||||
"Production deployments require approval-required=true"
|
||||
)
|
||||
valid = False
|
||||
|
||||
return valid
|
||||
|
||||
def get_required_inputs(self) -> list[str]:
|
||||
return ["environment", "target"]
|
||||
|
||||
def validate_environment(self, env: str) -> bool:
|
||||
valid_envs = ["development", "staging", "production"]
|
||||
if env not in valid_envs:
|
||||
self.add_error(
|
||||
f"Invalid environment: {env}. "
|
||||
f"Must be one of: {', '.join(valid_envs)}"
|
||||
)
|
||||
return False
|
||||
return True
|
||||
|
||||
def get_validation_rules(self) -> dict:
|
||||
"""Get validation rules."""
|
||||
rules_path = Path(__file__).parent / "rules.yml"
|
||||
return self.load_rules(rules_path)
|
||||
```
|
||||
|
||||
1. **Test your validator** (optional but recommended):
|
||||
|
||||
```python
|
||||
# my-action/test_custom_validator.py
|
||||
from CustomValidator import CustomValidator
|
||||
|
||||
def test_valid_inputs():
|
||||
validator = CustomValidator()
|
||||
inputs = {
|
||||
"environment": "production",
|
||||
"target": "app-server",
|
||||
"approval-required": "true"
|
||||
}
|
||||
assert validator.validate_inputs(inputs) is True
|
||||
assert len(validator.errors) == 0
|
||||
```
|
||||
|
||||
## Testing Your Validation
|
||||
|
||||
### Manual Testing
|
||||
|
||||
```bash
|
||||
# Test with environment variables
|
||||
export INPUT_ACTION_TYPE="my-action"
|
||||
export INPUT_GITHUB_TOKEN="${{ secrets.GITHUB_TOKEN }}"
|
||||
export INPUT_NODE_VERSION="18.0.0"
|
||||
export INPUT_DRY_RUN="true"
|
||||
|
||||
python3 validate-inputs/validator.py
|
||||
```
|
||||
|
||||
### Integration Testing
|
||||
|
||||
Create a test workflow:
|
||||
|
||||
```yaml
|
||||
# .github/workflows/test-my-action.yml
|
||||
name: Test My Action Validation
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
- 'my-action/**'
|
||||
- 'validate-inputs/**'
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
# Test valid inputs
|
||||
- name: Test with valid inputs
|
||||
uses: ./my-action
|
||||
with:
|
||||
github-token: ${{ secrets.GITHUB_TOKEN }}
|
||||
node-version: '18.0.0'
|
||||
dry-run: 'true'
|
||||
|
||||
# Test invalid inputs (should fail)
|
||||
- name: Test with invalid inputs
|
||||
id: invalid
|
||||
continue-on-error: true
|
||||
uses: ./my-action
|
||||
with:
|
||||
github-token: 'invalid-token'
|
||||
node-version: 'not-a-version'
|
||||
dry-run: 'maybe'
|
||||
|
||||
- name: Check failure
|
||||
if: steps.invalid.outcome != 'failure'
|
||||
run: exit 1
|
||||
```
|
||||
|
||||
### Generating Tests
|
||||
|
||||
Use the test generator:
|
||||
|
||||
```bash
|
||||
# Generate tests for your action
|
||||
make generate-tests
|
||||
|
||||
# Preview what would be generated
|
||||
make generate-tests-dry
|
||||
|
||||
# Run the generated tests
|
||||
make test
|
||||
```
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
### Scenario 1: Required Inputs
|
||||
|
||||
```yaml
|
||||
inputs:
|
||||
api-key:
|
||||
description: API key for service
|
||||
required: true # No default value
|
||||
```
|
||||
|
||||
Validation automatically enforces this requirement.
|
||||
|
||||
### Scenario 2: Dependent Inputs
|
||||
|
||||
Use custom validator for dependent fields:
|
||||
|
||||
```python
|
||||
def validate_inputs(self, inputs: dict[str, str]) -> bool:
|
||||
# If using custom registry, token is required
|
||||
if inputs.get("registry") and not inputs.get("registry-token"):
|
||||
self.add_error("registry-token required when using custom registry")
|
||||
return False
|
||||
return True
|
||||
```
|
||||
|
||||
### Scenario 3: Complex Formats
|
||||
|
||||
```python
|
||||
def validate_cron_schedule(self, schedule: str) -> bool:
|
||||
"""Validate cron schedule format."""
|
||||
import re
|
||||
|
||||
# Simple cron pattern (not exhaustive)
|
||||
pattern = r'^(\*|[0-9,\-\*/]+)\s+(\*|[0-9,\-\*/]+)\s+(\*|[0-9,\-\*/]+)\s+(\*|[0-9,\-\*/]+)\s+(\*|[0-9,\-\*/]+)$'
|
||||
|
||||
if not re.match(pattern, schedule):
|
||||
self.add_error(f"Invalid cron schedule: {schedule}")
|
||||
return False
|
||||
return True
|
||||
```
|
||||
|
||||
### Scenario 4: External Service Validation
|
||||
|
||||
```python
|
||||
def validate_docker_image_exists(self, image: str) -> bool:
|
||||
"""Check if Docker image exists (example)."""
|
||||
# Note: Be careful with external calls in validation
|
||||
# Consider caching or making this optional
|
||||
|
||||
# Allow GitHub Actions expressions
|
||||
if self.is_github_expression(image):
|
||||
return True
|
||||
|
||||
# Simplified check - real implementation would need error handling
|
||||
import subprocess
|
||||
result = subprocess.run(
|
||||
["docker", "manifest", "inspect", image],
|
||||
capture_output=True,
|
||||
text=True
|
||||
)
|
||||
|
||||
if result.returncode != 0:
|
||||
self.add_error(f"Docker image not found: {image}")
|
||||
return False
|
||||
return True
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: Validation Not Running
|
||||
|
||||
**Check**:
|
||||
|
||||
1. Is `validate-inputs` action called in your workflow?
|
||||
2. Is `action-type` parameter set correctly?
|
||||
3. Are environment variables prefixed with `INPUT_`?
|
||||
|
||||
**Debug**:
|
||||
|
||||
```yaml
|
||||
- name: Debug inputs
|
||||
run: |
|
||||
env | grep INPUT_ | sort
|
||||
shell: bash
|
||||
|
||||
- uses: ./validate-inputs
|
||||
with:
|
||||
action-type: ${{ github.action }}
|
||||
```
|
||||
|
||||
### Issue: Custom Validator Not Found
|
||||
|
||||
**Check**:
|
||||
|
||||
1. Is `CustomValidator.py` in action directory?
|
||||
2. Is class named exactly `CustomValidator`?
|
||||
3. Is file readable and valid Python?
|
||||
|
||||
**Debug**:
|
||||
|
||||
```bash
|
||||
# Test import directly
|
||||
python3 -c "from my_action.CustomValidator import CustomValidator; print('Success')"
|
||||
```
|
||||
|
||||
### Issue: Validation Too Strict
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Allow GitHub expressions**:
|
||||
|
||||
```python
|
||||
if self.is_github_expression(value):
|
||||
return True
|
||||
```
|
||||
|
||||
1. **Make fields optional**:
|
||||
|
||||
```python
|
||||
if not value or not value.strip():
|
||||
return True # Empty is OK for optional fields
|
||||
```
|
||||
|
||||
1. **Add to allowed values**:
|
||||
|
||||
```python
|
||||
valid_values = ["option1", "option2", "custom"] # Add more options
|
||||
```
|
||||
|
||||
### Issue: Validation Not Strict Enough
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Create custom validator** with stricter rules
|
||||
2. **Add pattern matching**:
|
||||
|
||||
```python
|
||||
import re
|
||||
if not re.match(r'^[a-z0-9\-]+$', value):
|
||||
self.add_error("Only lowercase letters, numbers, and hyphens allowed")
|
||||
```
|
||||
|
||||
1. **Add length limits**:
|
||||
|
||||
```python
|
||||
if len(value) > 100:
|
||||
self.add_error("Value too long (max 100 characters)")
|
||||
```
|
||||
|
||||
### Getting Validation Status
|
||||
|
||||
Access validation results in subsequent steps:
|
||||
|
||||
```yaml
|
||||
- uses: ./validate-inputs
|
||||
id: validation
|
||||
with:
|
||||
action-type: my-action
|
||||
|
||||
- name: Check validation status
|
||||
run: |
|
||||
echo "Status: ${{ steps.validation.outputs.status }}"
|
||||
echo "Valid: ${{ steps.validation.outputs.valid }}"
|
||||
echo "Action: ${{ steps.validation.outputs.action }}"
|
||||
echo "Inputs validated: ${{ steps.validation.outputs.inputs_validated }}"
|
||||
shell: bash
|
||||
```
|
||||
|
||||
### Debugging Validation Errors
|
||||
|
||||
Enable debug output:
|
||||
|
||||
```yaml
|
||||
- uses: ./validate-inputs
|
||||
with:
|
||||
action-type: my-action
|
||||
env:
|
||||
ACTIONS_RUNNER_DEBUG: true
|
||||
ACTIONS_STEP_DEBUG: true
|
||||
```
|
||||
|
||||
View specific errors:
|
||||
|
||||
```bash
|
||||
# In your action
|
||||
- name: Validate
|
||||
id: validate
|
||||
uses: ./validate-inputs
|
||||
continue-on-error: true
|
||||
with:
|
||||
action-type: my-action
|
||||
|
||||
- name: Show errors
|
||||
if: steps.validate.outcome == 'failure'
|
||||
run: |
|
||||
echo "Validation failed!"
|
||||
# Errors are already shown via ::error::
|
||||
shell: bash
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use conventions** when possible for automatic validation
|
||||
2. **Document validation rules** in your action's README
|
||||
3. **Test with invalid inputs** to ensure validation works
|
||||
4. **Allow GitHub expressions** (`${{ }}`) in all validators
|
||||
5. **Provide clear error messages** that explain how to fix the issue
|
||||
6. **Make validation fast** - avoid expensive operations
|
||||
7. **Cache validation results** if checking external resources
|
||||
8. **Version your validation** - use `validate-inputs@v1` etc.
|
||||
9. **Monitor validation failures** in your action's usage
|
||||
|
||||
## Resources
|
||||
|
||||
- [API Documentation](./API.md) - Complete validator API reference
|
||||
- [Developer Guide](./DEVELOPER_GUIDE.md) - Adding new validators
|
||||
- [Test Generator](../scripts/generate-tests.py) - Automatic test creation
|
||||
- [Rule Generator](../scripts/update-validators.py) - Rule file generation
|
||||
|
||||
## Support
|
||||
|
||||
For validation issues:
|
||||
|
||||
1. Check error messages for specific problems
|
||||
2. Review validation rules in action folder's `rules.yml`
|
||||
3. Test with simplified inputs
|
||||
4. Create custom validator if needed
|
||||
5. Report bugs via GitHub Issues
|
||||
447
validate-inputs/docs/API.md
Normal file
447
validate-inputs/docs/API.md
Normal file
@@ -0,0 +1,447 @@
|
||||
# Validator API Documentation
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Base Validator](#base-validator)
|
||||
2. [Core Validators](#core-validators)
|
||||
3. [Registry System](#registry-system)
|
||||
4. [Custom Validators](#custom-validators)
|
||||
5. [Conventions](#conventions)
|
||||
|
||||
## Base Validator
|
||||
|
||||
### `BaseValidator`
|
||||
|
||||
The abstract base class for all validators. Provides common functionality for validation, error handling, and rule loading.
|
||||
|
||||
```python
|
||||
from validators.base import BaseValidator
|
||||
|
||||
class MyValidator(BaseValidator):
|
||||
def validate_inputs(self, inputs: dict[str, str]) -> bool:
|
||||
# Implementation
|
||||
pass
|
||||
```
|
||||
|
||||
#### Methods
|
||||
|
||||
| Method | Description | Returns |
|
||||
|-------------------------------------------------|---------------------------------------|-------------|
|
||||
| `validate_inputs(inputs)` | Main validation entry point | `bool` |
|
||||
| `validate_required_inputs(inputs)` | Validates required inputs are present | `bool` |
|
||||
| `validate_path_security(path)` | Checks for path traversal attacks | `bool` |
|
||||
| `validate_security_patterns(value, field_name)` | Checks for injection attacks | `bool` |
|
||||
| `add_error(message)` | Adds an error message | `None` |
|
||||
| `clear_errors()` | Clears all error messages | `None` |
|
||||
| `get_required_inputs()` | Returns list of required input names | `list[str]` |
|
||||
| `get_validation_rules()` | Returns validation rules dictionary | `dict` |
|
||||
| `load_rules(action_type)` | Loads rules from YAML file | `dict` |
|
||||
|
||||
#### Properties
|
||||
|
||||
| Property | Type | Description |
|
||||
|---------------|-------------|---------------------------------|
|
||||
| `errors` | `list[str]` | Accumulated error messages |
|
||||
| `action_type` | `str` | The action type being validated |
|
||||
|
||||
## Core Validators
|
||||
|
||||
### `BooleanValidator`
|
||||
|
||||
Validates boolean inputs with flexible string representations.
|
||||
|
||||
```python
|
||||
from validators.boolean import BooleanValidator
|
||||
|
||||
validator = BooleanValidator()
|
||||
validator.validate_boolean("true", "dry-run") # Returns True
|
||||
validator.validate_boolean("yes", "dry-run") # Returns False (not allowed)
|
||||
```
|
||||
|
||||
**Accepted Values**: `true`, `false`, `True`, `False`, `TRUE`, `FALSE`
|
||||
|
||||
### `VersionValidator`
|
||||
|
||||
Validates version strings in multiple formats.
|
||||
|
||||
```python
|
||||
from validators.version import VersionValidator
|
||||
|
||||
validator = VersionValidator()
|
||||
validator.validate_semantic_version("1.2.3") # SemVer
|
||||
validator.validate_calver("2024.3.15") # CalVer
|
||||
validator.validate_flexible_version("v1.2.3") # Either format
|
||||
```
|
||||
|
||||
**Supported Formats**:
|
||||
|
||||
- **SemVer**: `1.2.3`, `1.0.0-alpha`, `2.1.0+build123`
|
||||
- **CalVer**: `2024.3.1`, `2024.03.15`, `24.3.1`
|
||||
- **Prefixed**: `v1.2.3`, `v2024.3.1`
|
||||
|
||||
### `TokenValidator`
|
||||
|
||||
Validates authentication tokens for various services.
|
||||
|
||||
```python
|
||||
from validators.token import TokenValidator
|
||||
|
||||
validator = TokenValidator()
|
||||
validator.validate_github_token("ghp_...") # Classic PAT
|
||||
validator.validate_github_token("github_pat_...") # Fine-grained PAT
|
||||
validator.validate_github_token("${{ secrets.GITHUB_TOKEN }}") # Expression
|
||||
```
|
||||
|
||||
**Token Types**:
|
||||
|
||||
- **GitHub**: `ghp_`, `gho_`, `ghu_`, `ghs_`, `ghr_`, `github_pat_`
|
||||
- **NPM**: UUID format, `${{ secrets.NPM_TOKEN }}`
|
||||
- **Docker**: Any non-empty value
|
||||
|
||||
### `NumericValidator`
|
||||
|
||||
Validates numeric values and ranges.
|
||||
|
||||
```python
|
||||
from validators.numeric import NumericValidator
|
||||
|
||||
validator = NumericValidator()
|
||||
validator.validate_numeric_range("5", 0, 10) # Within range
|
||||
validator.validate_numeric_range("15", 0, 10) # Out of range (fails)
|
||||
```
|
||||
|
||||
**Common Ranges**:
|
||||
|
||||
- `0-100`: Percentages
|
||||
- `1-10`: Retry counts
|
||||
- `1-128`: Thread/worker counts
|
||||
|
||||
### `FileValidator`
|
||||
|
||||
Validates file paths with security checks.
|
||||
|
||||
```python
|
||||
from validators.file import FileValidator
|
||||
|
||||
validator = FileValidator()
|
||||
validator.validate_file_path("./config.yml") # Valid
|
||||
validator.validate_file_path("../../../etc/passwd") # Path traversal (fails)
|
||||
validator.validate_file_path("/absolute/path") # Absolute path (fails)
|
||||
```
|
||||
|
||||
**Security Checks**:
|
||||
|
||||
- No path traversal (`../`)
|
||||
- No absolute paths
|
||||
- No special characters that could cause injection
|
||||
|
||||
### `NetworkValidator`
|
||||
|
||||
Validates network-related inputs.
|
||||
|
||||
```python
|
||||
from validators.network import NetworkValidator
|
||||
|
||||
validator = NetworkValidator()
|
||||
validator.validate_url("https://example.com")
|
||||
validator.validate_email("user@example.com")
|
||||
validator.validate_hostname("api.example.com")
|
||||
validator.validate_ip_address("192.168.1.1")
|
||||
```
|
||||
|
||||
**Validation Types**:
|
||||
|
||||
- **URLs**: HTTP/HTTPS with valid structure
|
||||
- **Emails**: RFC-compliant email addresses
|
||||
- **Hostnames**: Valid DNS names
|
||||
- **IPs**: IPv4 and IPv6 addresses
|
||||
- **Ports**: 1-65535 range
|
||||
|
||||
### `DockerValidator`
|
||||
|
||||
Validates Docker-specific inputs.
|
||||
|
||||
```python
|
||||
from validators.docker import DockerValidator
|
||||
|
||||
validator = DockerValidator()
|
||||
validator.validate_image_name("nginx")
|
||||
validator.validate_tag("latest")
|
||||
validator.validate_architectures("linux/amd64,linux/arm64")
|
||||
validator.validate_registry("ghcr.io")
|
||||
```
|
||||
|
||||
**Docker Validations**:
|
||||
|
||||
- **Images**: Lowercase, alphanumeric with `-`, `_`, `/`
|
||||
- **Tags**: Alphanumeric with `-`, `_`, `.`
|
||||
- **Platforms**: Valid OS/architecture combinations
|
||||
- **Registries**: Known registries or valid hostnames
|
||||
|
||||
### `SecurityValidator`
|
||||
|
||||
Performs security-focused validations.
|
||||
|
||||
```python
|
||||
from validators.security import SecurityValidator
|
||||
|
||||
validator = SecurityValidator()
|
||||
validator.validate_no_injection("safe input")
|
||||
validator.validate_safe_command("echo hello")
|
||||
validator.validate_safe_environment_variable("PATH=/usr/bin")
|
||||
validator.validate_no_secrets("normal text")
|
||||
```
|
||||
|
||||
**Security Patterns Detected**:
|
||||
|
||||
- Command injection: `;`, `&&`, `||`, `` ` ``, `$()`
|
||||
- SQL injection: `' OR '1'='1`, `DROP TABLE`, `--`
|
||||
- Path traversal: `../`, `..\\`
|
||||
- Script injection: `<script>`, `javascript:`
|
||||
- Secrets: API keys, tokens, passwords
|
||||
|
||||
### `CodeQLValidator`
|
||||
|
||||
Validates CodeQL-specific inputs.
|
||||
|
||||
```python
|
||||
from validators.codeql import CodeQLValidator
|
||||
|
||||
validator = CodeQLValidator()
|
||||
validator.validate_languages(["javascript", "python"])
|
||||
validator.validate_codeql_queries(["security", "quality"])
|
||||
validator.validate_codeql_config("./codeql-config.yml")
|
||||
```
|
||||
|
||||
**Supported Languages**: JavaScript, TypeScript, Python, Java, C#, C/C++, Go, Ruby, Kotlin, Swift
|
||||
|
||||
## Registry System
|
||||
|
||||
### `ValidatorRegistry`
|
||||
|
||||
Manages validator discovery and caching.
|
||||
|
||||
```python
|
||||
from validators.registry import ValidatorRegistry
|
||||
|
||||
registry = ValidatorRegistry()
|
||||
validator = registry.get_validator("docker-build") # Gets appropriate validator
|
||||
```
|
||||
|
||||
#### Methods
|
||||
|
||||
| Method | Description | Returns |
|
||||
|---------------------------------------------|---------------------------|-----------------|
|
||||
| `get_validator(action_type)` | Gets validator for action | `BaseValidator` |
|
||||
| `register_validator(name, validator_class)` | Registers a validator | `None` |
|
||||
| `clear_cache()` | Clears validator cache | `None` |
|
||||
|
||||
### `ConventionBasedValidator`
|
||||
|
||||
Automatically selects validators based on input naming conventions.
|
||||
|
||||
```python
|
||||
from validators.conventions import ConventionBasedValidator
|
||||
|
||||
validator = ConventionBasedValidator("my-action")
|
||||
validator.validate_inputs({
|
||||
"github-token": "ghp_...", # Uses TokenValidator
|
||||
"version": "1.2.3", # Uses VersionValidator
|
||||
"dry-run": "true", # Uses BooleanValidator
|
||||
"max-retries": "5" # Uses NumericValidator
|
||||
})
|
||||
```
|
||||
|
||||
## Custom Validators
|
||||
|
||||
Custom validators extend the base functionality for specific actions.
|
||||
|
||||
### Creating a Custom Validator
|
||||
|
||||
1. Create `CustomValidator.py` in your action directory:
|
||||
|
||||
```python
|
||||
from pathlib import Path
|
||||
import sys
|
||||
|
||||
# Add validate-inputs to path
|
||||
validate_inputs_path = Path(__file__).parent.parent / "validate-inputs"
|
||||
sys.path.insert(0, str(validate_inputs_path))
|
||||
|
||||
from validators.base import BaseValidator
|
||||
from validators.docker import DockerValidator
|
||||
|
||||
class CustomValidator(BaseValidator):
|
||||
def __init__(self, action_type: str = "my-action") -> None:
|
||||
super().__init__(action_type)
|
||||
self.docker_validator = DockerValidator(action_type)
|
||||
|
||||
def validate_inputs(self, inputs: dict[str, str]) -> bool:
|
||||
valid = True
|
||||
|
||||
# Validate required inputs
|
||||
valid &= self.validate_required_inputs(inputs)
|
||||
|
||||
# Custom validation logic
|
||||
if inputs.get("special-field"):
|
||||
valid &= self.validate_special_field(inputs["special-field"])
|
||||
|
||||
return valid
|
||||
|
||||
def get_required_inputs(self) -> list[str]:
|
||||
return ["special-field", "another-required"]
|
||||
|
||||
def validate_special_field(self, value: str) -> bool:
|
||||
# Custom validation logic
|
||||
if not value.startswith("special-"):
|
||||
self.add_error(f"Special field must start with 'special-': {value}")
|
||||
return False
|
||||
return True
|
||||
```
|
||||
|
||||
### Error Propagation
|
||||
|
||||
When using sub-validators, propagate their errors:
|
||||
|
||||
```python
|
||||
result = self.docker_validator.validate_image_name(image_name, "image")
|
||||
if not result:
|
||||
for error in self.docker_validator.errors:
|
||||
if error not in self.errors:
|
||||
self.add_error(error)
|
||||
self.docker_validator.clear_errors()
|
||||
```
|
||||
|
||||
## Conventions
|
||||
|
||||
### Input Naming Conventions
|
||||
|
||||
The system automatically detects validation types based on input names:
|
||||
|
||||
| Pattern | Validator | Example |
|
||||
|-------------------------------|------------------|----------------------------------|
|
||||
| `*-token` | TokenValidator | `github-token`, `npm-token` |
|
||||
| `*-version` | VersionValidator | `node-version`, `dotnet-version` |
|
||||
| `dry-run`, `debug`, `verbose` | BooleanValidator | `dry-run`, `skip-tests` |
|
||||
| `*-retries`, `*-limit` | NumericValidator | `max-retries`, `rate-limit` |
|
||||
| `*-file`, `*-path` | FileValidator | `config-file`, `output-path` |
|
||||
| `*-url`, `webhook-*` | NetworkValidator | `api-url`, `webhook-endpoint` |
|
||||
| `*-email` | NetworkValidator | `maintainer-email` |
|
||||
| `dockerfile` | FileValidator | `dockerfile` |
|
||||
| `image-*`, `tag`, `platform` | DockerValidator | `image-name`, `tag` |
|
||||
|
||||
### GitHub Expression Support
|
||||
|
||||
All validators support GitHub Actions expressions:
|
||||
|
||||
```python
|
||||
validator.validate_inputs({
|
||||
"token": "${{ secrets.GITHUB_TOKEN }}",
|
||||
"version": "${{ github.event.release.tag_name }}",
|
||||
"dry-run": "${{ github.event_name == 'pull_request' }}"
|
||||
})
|
||||
```
|
||||
|
||||
Expressions containing `${{` are automatically considered valid.
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Error Messages
|
||||
|
||||
Error messages should be:
|
||||
|
||||
- Clear and actionable
|
||||
- Include the invalid value
|
||||
- Suggest the correct format
|
||||
|
||||
```python
|
||||
self.add_error(f"Invalid version format: {value}. Expected SemVer (1.2.3) or CalVer (2024.3.1)")
|
||||
```
|
||||
|
||||
### Error Collection
|
||||
|
||||
Validators collect all errors before returning:
|
||||
|
||||
```python
|
||||
def validate_inputs(self, inputs: dict[str, str]) -> bool:
|
||||
valid = True
|
||||
|
||||
# Check multiple conditions
|
||||
if not self.validate_field1(inputs.get("field1")):
|
||||
valid = False
|
||||
|
||||
if not self.validate_field2(inputs.get("field2")):
|
||||
valid = False
|
||||
|
||||
# Return False only after checking everything
|
||||
return valid
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Caching
|
||||
|
||||
The registry caches validator instances:
|
||||
|
||||
```python
|
||||
registry = ValidatorRegistry()
|
||||
validator1 = registry.get_validator("docker-build") # Creates new
|
||||
validator2 = registry.get_validator("docker-build") # Returns cached
|
||||
assert validator1 is validator2 # Same instance
|
||||
```
|
||||
|
||||
### Lazy Loading
|
||||
|
||||
Validators are loaded only when needed:
|
||||
|
||||
```python
|
||||
# Only loads DockerValidator if docker-related inputs exist
|
||||
validator = ConventionBasedValidator("my-action")
|
||||
validator.validate_inputs(inputs) # Loads validators on demand
|
||||
```
|
||||
|
||||
## Testing Validators
|
||||
|
||||
### Unit Testing
|
||||
|
||||
```python
|
||||
import pytest
|
||||
from validators.version import VersionValidator
|
||||
|
||||
def test_version_validation():
|
||||
validator = VersionValidator()
|
||||
|
||||
# Test valid versions
|
||||
assert validator.validate_semantic_version("1.2.3", "version")
|
||||
assert validator.validate_calver("2024.3.1", "version")
|
||||
|
||||
# Test invalid versions
|
||||
assert not validator.validate_semantic_version("invalid", "version")
|
||||
assert len(validator.errors) > 0
|
||||
```
|
||||
|
||||
### Integration Testing
|
||||
|
||||
```python
|
||||
def test_custom_validator():
|
||||
validator = CustomValidator("my-action")
|
||||
|
||||
inputs = {
|
||||
"special-field": "special-value",
|
||||
"another-required": "test"
|
||||
}
|
||||
|
||||
assert validator.validate_inputs(inputs)
|
||||
assert len(validator.errors) == 0
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always validate required inputs first**
|
||||
2. **Use sub-validators for standard validations**
|
||||
3. **Propagate errors from sub-validators**
|
||||
4. **Support GitHub expressions**
|
||||
5. **Provide clear, actionable error messages**
|
||||
6. **Test both valid and invalid inputs**
|
||||
7. **Document custom validation rules**
|
||||
8. **Follow naming conventions for automatic detection**
|
||||
617
validate-inputs/docs/DEVELOPER_GUIDE.md
Normal file
617
validate-inputs/docs/DEVELOPER_GUIDE.md
Normal file
@@ -0,0 +1,617 @@
|
||||
# Developer Guide - Adding New Validators
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Quick Start](#quick-start)
|
||||
2. [Creating a Core Validator](#creating-a-core-validator)
|
||||
3. [Creating a Custom Validator](#creating-a-custom-validator)
|
||||
4. [Adding Convention Patterns](#adding-convention-patterns)
|
||||
5. [Writing Tests](#writing-tests)
|
||||
6. [Debugging](#debugging)
|
||||
7. [Common Patterns](#common-patterns)
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Adding validation for a new input type
|
||||
|
||||
1. **Check if existing validator covers it**:
|
||||
|
||||
```bash
|
||||
# Search for similar validation patterns
|
||||
grep -r "validate_.*" validate-inputs/validators/
|
||||
```
|
||||
|
||||
2. **Use convention-based detection** (easiest):
|
||||
- Name your input following conventions (e.g., `my-token`, `api-version`)
|
||||
- System automatically uses appropriate validator
|
||||
|
||||
3. **Create custom validator** (for complex logic):
|
||||
|
||||
```bash
|
||||
# Create CustomValidator.py in your action directory
|
||||
touch my-action/CustomValidator.py
|
||||
```
|
||||
|
||||
## Creating a Core Validator
|
||||
|
||||
### Step 1: Create the Validator File
|
||||
|
||||
Create `validate-inputs/validators/mytype.py`:
|
||||
|
||||
```python
|
||||
"""Validator for MyType inputs."""
|
||||
|
||||
from __future__ import annotations
|
||||
import re
|
||||
from typing import Any
|
||||
|
||||
from .base import BaseValidator
|
||||
|
||||
|
||||
class MyTypeValidator(BaseValidator):
|
||||
"""Validates MyType-specific inputs."""
|
||||
|
||||
def __init__(self, action_type: str = "") -> None:
|
||||
"""Initialize the MyType validator."""
|
||||
super().__init__(action_type)
|
||||
|
||||
def validate_inputs(self, inputs: dict[str, str]) -> bool:
|
||||
"""Validate MyType inputs based on conventions.
|
||||
|
||||
Args:
|
||||
inputs: Dictionary of input names to values
|
||||
|
||||
Returns:
|
||||
True if all validations pass, False otherwise
|
||||
"""
|
||||
valid = True
|
||||
|
||||
for input_name, value in inputs.items():
|
||||
# Check if this input should be validated by this validator
|
||||
if self._should_validate(input_name):
|
||||
if not self.validate_mytype(value, input_name):
|
||||
valid = False
|
||||
|
||||
return valid
|
||||
|
||||
def _should_validate(self, input_name: str) -> bool:
|
||||
"""Check if input should be validated by this validator."""
|
||||
# Define patterns that trigger this validator
|
||||
patterns = [
|
||||
"mytype",
|
||||
"-mytype",
|
||||
"mytype-",
|
||||
]
|
||||
|
||||
name_lower = input_name.lower()
|
||||
return any(pattern in name_lower for pattern in patterns)
|
||||
|
||||
def validate_mytype(self, value: str, field_name: str) -> bool:
|
||||
"""Validate a MyType value.
|
||||
|
||||
Args:
|
||||
value: The value to validate
|
||||
field_name: Name of the field being validated
|
||||
|
||||
Returns:
|
||||
True if valid, False otherwise
|
||||
"""
|
||||
# Allow empty for optional fields
|
||||
if not value or not value.strip():
|
||||
return True
|
||||
|
||||
# Allow GitHub Actions expressions
|
||||
if self.is_github_expression(value):
|
||||
return True
|
||||
|
||||
# Your validation logic here
|
||||
pattern = r"^mytype-[a-z0-9]+$"
|
||||
if not re.match(pattern, value):
|
||||
self.add_error(
|
||||
f"Invalid MyType format for '{field_name}': {value}. "
|
||||
f"Expected format: mytype-xxxxx"
|
||||
)
|
||||
return False
|
||||
|
||||
return True
|
||||
```
|
||||
|
||||
### Step 2: Register the Validator
|
||||
|
||||
Add to `validate-inputs/validators/__init__.py`:
|
||||
|
||||
```python
|
||||
from .mytype import MyTypeValidator
|
||||
|
||||
__all__ = [
|
||||
# ... existing validators ...
|
||||
"MyTypeValidator",
|
||||
]
|
||||
```
|
||||
|
||||
### Step 3: Add Convention Patterns
|
||||
|
||||
Update `validate-inputs/validators/conventions.py`:
|
||||
|
||||
```python
|
||||
# In ConventionBasedValidator.PATTERNS dict:
|
||||
PATTERNS = {
|
||||
# Exact matches (highest priority)
|
||||
"exact": {
|
||||
# ... existing patterns ...
|
||||
"mytype-config": "mytype",
|
||||
},
|
||||
|
||||
# Prefix patterns
|
||||
"prefix": {
|
||||
# ... existing patterns ...
|
||||
"mytype-": "mytype",
|
||||
},
|
||||
|
||||
# Suffix patterns
|
||||
"suffix": {
|
||||
# ... existing patterns ...
|
||||
"-mytype": "mytype",
|
||||
},
|
||||
}
|
||||
|
||||
# In get_validator_class method:
|
||||
validator_map = {
|
||||
# ... existing mappings ...
|
||||
"mytype": MyTypeValidator,
|
||||
}
|
||||
```
|
||||
|
||||
## Creating a Custom Validator
|
||||
|
||||
### For Complex Action-Specific Logic
|
||||
|
||||
Create `my-action/CustomValidator.py`:
|
||||
|
||||
```python
|
||||
"""Custom validator for my-action.
|
||||
|
||||
This validator handles complex validation logic specific to my-action.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
from pathlib import Path
|
||||
import sys
|
||||
|
||||
# Add validate-inputs directory to path
|
||||
validate_inputs_path = Path(__file__).parent.parent / "validate-inputs"
|
||||
sys.path.insert(0, str(validate_inputs_path))
|
||||
|
||||
from validators.base import BaseValidator
|
||||
from validators.version import VersionValidator
|
||||
from validators.token import TokenValidator
|
||||
|
||||
|
||||
class CustomValidator(BaseValidator):
|
||||
"""Custom validator for my-action."""
|
||||
|
||||
def __init__(self, action_type: str = "my-action") -> None:
|
||||
"""Initialize the custom validator."""
|
||||
super().__init__(action_type)
|
||||
# Initialize sub-validators
|
||||
self.version_validator = VersionValidator(action_type)
|
||||
self.token_validator = TokenValidator(action_type)
|
||||
|
||||
def validate_inputs(self, inputs: dict[str, str]) -> bool:
|
||||
"""Validate my-action specific inputs.
|
||||
|
||||
Args:
|
||||
inputs: Dictionary of input names to values
|
||||
|
||||
Returns:
|
||||
True if all validations pass, False otherwise
|
||||
"""
|
||||
valid = True
|
||||
|
||||
# Validate required inputs
|
||||
valid &= self.validate_required_inputs(inputs)
|
||||
|
||||
# Use sub-validators
|
||||
if inputs.get("api-token"):
|
||||
if not self.token_validator.validate_github_token(
|
||||
inputs["api-token"], "api-token"
|
||||
):
|
||||
# Propagate errors
|
||||
for error in self.token_validator.errors:
|
||||
if error not in self.errors:
|
||||
self.add_error(error)
|
||||
self.token_validator.clear_errors()
|
||||
valid = False
|
||||
|
||||
# Custom validation logic
|
||||
if inputs.get("mode"):
|
||||
valid &= self.validate_mode(inputs["mode"])
|
||||
|
||||
# Cross-field validation
|
||||
if inputs.get("source") and inputs.get("target"):
|
||||
valid &= self.validate_source_target(
|
||||
inputs["source"],
|
||||
inputs["target"]
|
||||
)
|
||||
|
||||
return valid
|
||||
|
||||
def get_required_inputs(self) -> list[str]:
|
||||
"""Get list of required inputs.
|
||||
|
||||
Returns:
|
||||
List of required input names
|
||||
"""
|
||||
return ["api-token", "mode"]
|
||||
|
||||
def validate_mode(self, mode: str) -> bool:
|
||||
"""Validate operation mode.
|
||||
|
||||
Args:
|
||||
mode: The mode value
|
||||
|
||||
Returns:
|
||||
True if valid, False otherwise
|
||||
"""
|
||||
valid_modes = ["development", "staging", "production"]
|
||||
|
||||
if mode not in valid_modes:
|
||||
self.add_error(
|
||||
f"Invalid mode: {mode}. "
|
||||
f"Must be one of: {', '.join(valid_modes)}"
|
||||
)
|
||||
return False
|
||||
|
||||
return True
|
||||
|
||||
def validate_source_target(self, source: str, target: str) -> bool:
|
||||
"""Validate source and target relationship.
|
||||
|
||||
Args:
|
||||
source: Source value
|
||||
target: Target value
|
||||
|
||||
Returns:
|
||||
True if valid, False otherwise
|
||||
"""
|
||||
if source == target:
|
||||
self.add_error("Source and target cannot be the same")
|
||||
return False
|
||||
|
||||
return True
|
||||
```
|
||||
|
||||
## Adding Convention Patterns
|
||||
|
||||
### Pattern Priority
|
||||
|
||||
Patterns are checked in this order:
|
||||
|
||||
1. **Exact match** (highest priority)
|
||||
2. **Prefix match** (`token-*`)
|
||||
3. **Suffix match** (`*-token`)
|
||||
4. **Contains match** (lowest priority)
|
||||
|
||||
### Adding a New Pattern
|
||||
|
||||
```python
|
||||
# In validate-inputs/validators/conventions.py
|
||||
|
||||
# For automatic token validation of "api-key" inputs:
|
||||
PATTERNS = {
|
||||
"exact": {
|
||||
"api-key": "token", # Maps api-key to TokenValidator
|
||||
},
|
||||
}
|
||||
|
||||
# For all inputs ending with "-secret":
|
||||
PATTERNS = {
|
||||
"suffix": {
|
||||
"-secret": "security", # Maps to SecurityValidator
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Writing Tests
|
||||
|
||||
### Core Validator Tests
|
||||
|
||||
Create `validate-inputs/tests/test_mytype.py`:
|
||||
|
||||
```python
|
||||
"""Tests for MyTypeValidator."""
|
||||
|
||||
import pytest
|
||||
from validators.mytype import MyTypeValidator
|
||||
|
||||
|
||||
class TestMyTypeValidator:
|
||||
"""Test MyTypeValidator functionality."""
|
||||
|
||||
def setup_method(self):
|
||||
"""Set up test fixtures."""
|
||||
self.validator = MyTypeValidator("test-action")
|
||||
|
||||
def test_initialization(self):
|
||||
"""Test validator initialization."""
|
||||
assert self.validator.action_type == "test-action"
|
||||
assert self.validator.errors == []
|
||||
|
||||
def test_valid_mytype(self):
|
||||
"""Test valid MyType values."""
|
||||
valid_cases = [
|
||||
"mytype-abc123",
|
||||
"mytype-test",
|
||||
"${{ secrets.MYTYPE }}", # GitHub expression
|
||||
"", # Empty allowed
|
||||
]
|
||||
|
||||
for value in valid_cases:
|
||||
self.validator.clear_errors()
|
||||
result = self.validator.validate_mytype(value, "test")
|
||||
assert result is True, f"Failed for: {value}"
|
||||
assert len(self.validator.errors) == 0
|
||||
|
||||
def test_invalid_mytype(self):
|
||||
"""Test invalid MyType values."""
|
||||
invalid_cases = [
|
||||
("invalid", "Invalid MyType format"),
|
||||
("mytype-", "Invalid MyType format"),
|
||||
("MYTYPE-123", "Invalid MyType format"), # Uppercase
|
||||
]
|
||||
|
||||
for value, expected_error in invalid_cases:
|
||||
self.validator.clear_errors()
|
||||
result = self.validator.validate_mytype(value, "test")
|
||||
assert result is False, f"Should fail for: {value}"
|
||||
assert any(
|
||||
expected_error in error
|
||||
for error in self.validator.errors
|
||||
)
|
||||
|
||||
def test_validate_inputs(self):
|
||||
"""Test full input validation."""
|
||||
inputs = {
|
||||
"mytype-field": "mytype-valid",
|
||||
"other-field": "ignored",
|
||||
}
|
||||
|
||||
result = self.validator.validate_inputs(inputs)
|
||||
assert result is True
|
||||
assert len(self.validator.errors) == 0
|
||||
```
|
||||
|
||||
### Custom Validator Tests
|
||||
|
||||
Create `my-action/test_custom_validator.py`:
|
||||
|
||||
```python
|
||||
"""Tests for my-action CustomValidator."""
|
||||
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
# Add parent to path for imports
|
||||
sys.path.insert(0, str(Path(__file__).parent.parent))
|
||||
|
||||
from my_action.CustomValidator import CustomValidator
|
||||
|
||||
|
||||
def test_custom_validator():
|
||||
"""Test custom validation logic."""
|
||||
validator = CustomValidator()
|
||||
|
||||
# Test valid inputs
|
||||
inputs = {
|
||||
"api-token": "${{ secrets.GITHUB_TOKEN }}",
|
||||
"mode": "production",
|
||||
"source": "dev",
|
||||
"target": "prod",
|
||||
}
|
||||
|
||||
assert validator.validate_inputs(inputs) is True
|
||||
assert len(validator.errors) == 0
|
||||
|
||||
# Test invalid mode
|
||||
validator.clear_errors()
|
||||
inputs["mode"] = "invalid"
|
||||
|
||||
assert validator.validate_inputs(inputs) is False
|
||||
assert "Invalid mode" in str(validator.errors)
|
||||
```
|
||||
|
||||
### Using Test Generator
|
||||
|
||||
Generate test scaffolding automatically:
|
||||
|
||||
```bash
|
||||
# Generate missing tests
|
||||
make generate-tests
|
||||
|
||||
# Preview what would be generated
|
||||
make generate-tests-dry
|
||||
|
||||
# Test specific action
|
||||
python3 validate-inputs/scripts/generate-tests.py --action my-action
|
||||
```
|
||||
|
||||
## Debugging
|
||||
|
||||
### Enable Debug Output
|
||||
|
||||
```python
|
||||
import logging
|
||||
|
||||
# In your validator
|
||||
logging.basicConfig(level=logging.DEBUG)
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
class MyValidator(BaseValidator):
|
||||
def validate_mytype(self, value: str, field_name: str) -> bool:
|
||||
logger.debug(f"Validating {field_name}: {value}")
|
||||
# ... validation logic ...
|
||||
```
|
||||
|
||||
### Test Validator Directly
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""Debug validator directly."""
|
||||
|
||||
from validators.mytype import MyTypeValidator
|
||||
|
||||
validator = MyTypeValidator("debug")
|
||||
result = validator.validate_mytype("test-value", "field")
|
||||
|
||||
print(f"Valid: {result}")
|
||||
print(f"Errors: {validator.errors}")
|
||||
```
|
||||
|
||||
### Check Convention Matching
|
||||
|
||||
```python
|
||||
from validators.conventions import ConventionBasedValidator
|
||||
|
||||
validator = ConventionBasedValidator("test")
|
||||
mapper = validator.convention_mapper
|
||||
|
||||
# Check what validator would be used
|
||||
validator_type = mapper.get_validator_type("my-field-name")
|
||||
print(f"Would use: {validator_type}")
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Pattern 1: Composing Validators
|
||||
|
||||
```python
|
||||
class CustomValidator(BaseValidator):
|
||||
def __init__(self, action_type: str) -> None:
|
||||
super().__init__(action_type)
|
||||
# Compose multiple validators
|
||||
self.token_val = TokenValidator(action_type)
|
||||
self.version_val = VersionValidator(action_type)
|
||||
self.docker_val = DockerValidator(action_type)
|
||||
```
|
||||
|
||||
### Pattern 2: Error Propagation
|
||||
|
||||
```python
|
||||
def validate_inputs(self, inputs: dict[str, str]) -> bool:
|
||||
# Use sub-validator
|
||||
result = self.docker_val.validate_image_name(
|
||||
inputs["image"], "image"
|
||||
)
|
||||
|
||||
if not result:
|
||||
# Propagate errors
|
||||
for error in self.docker_val.errors:
|
||||
if error not in self.errors:
|
||||
self.add_error(error)
|
||||
self.docker_val.clear_errors()
|
||||
return False
|
||||
```
|
||||
|
||||
### Pattern 3: GitHub Expression Support
|
||||
|
||||
```python
|
||||
def validate_field(self, value: str, field_name: str) -> bool:
|
||||
# Allow GitHub Actions expressions
|
||||
if self.is_github_expression(value):
|
||||
return True
|
||||
|
||||
# Your validation logic
|
||||
# ...
|
||||
```
|
||||
|
||||
### Pattern 4: Optional vs Required
|
||||
|
||||
```python
|
||||
def validate_field(self, value: str, field_name: str) -> bool:
|
||||
# Allow empty for optional fields
|
||||
if not value or not value.strip():
|
||||
return True
|
||||
|
||||
# Validate non-empty values
|
||||
# ...
|
||||
```
|
||||
|
||||
### Pattern 5: Security Checks
|
||||
|
||||
```python
|
||||
def validate_input(self, value: str, field_name: str) -> bool:
|
||||
# Always check for injection attempts
|
||||
if not self.validate_security_patterns(value, field_name):
|
||||
return False
|
||||
|
||||
# Your validation logic
|
||||
# ...
|
||||
```
|
||||
|
||||
## Performance Tips
|
||||
|
||||
1. **Cache Regex Patterns**:
|
||||
|
||||
```python
|
||||
class MyValidator(BaseValidator):
|
||||
# Compile once at class level
|
||||
PATTERN = re.compile(r"^mytype-[a-z0-9]+$")
|
||||
|
||||
def validate_mytype(self, value: str, field_name: str) -> bool:
|
||||
if not self.PATTERN.match(value):
|
||||
# ...
|
||||
```
|
||||
|
||||
2. **Lazy Load Sub-Validators**:
|
||||
|
||||
```python
|
||||
@property
|
||||
def docker_validator(self):
|
||||
if not hasattr(self, "_docker_validator"):
|
||||
self._docker_validator = DockerValidator(self.action_type)
|
||||
return self._docker_validator
|
||||
```
|
||||
|
||||
3. **Early Returns**:
|
||||
|
||||
```python
|
||||
def validate_inputs(self, inputs: dict[str, str]) -> bool:
|
||||
# Check required inputs first
|
||||
if not self.validate_required_inputs(inputs):
|
||||
return False # Exit early
|
||||
|
||||
# Continue with other validations
|
||||
# ...
|
||||
```
|
||||
|
||||
## Checklist for New Validators
|
||||
|
||||
- [ ] Create validator class extending `BaseValidator`
|
||||
- [ ] Implement `validate_inputs` method
|
||||
- [ ] Add to `__init__.py` exports
|
||||
- [ ] Add convention patterns if applicable
|
||||
- [ ] Write comprehensive tests
|
||||
- [ ] Test with GitHub expressions (`${{ }}`)
|
||||
- [ ] Test with empty/whitespace values
|
||||
- [ ] Document validation rules
|
||||
- [ ] Handle error propagation from sub-validators
|
||||
- [ ] Run linting: `make lint-python`
|
||||
- [ ] Run tests: `make test-python`
|
||||
- [ ] Generate tests: `make generate-tests`
|
||||
|
||||
## Getting Help
|
||||
|
||||
1. **Check existing validators** for similar patterns
|
||||
2. **Run tests** to verify your implementation
|
||||
3. **Use debugging** to trace validation flow
|
||||
4. **Review API documentation** for method signatures
|
||||
5. **Check test files** for usage examples
|
||||
|
||||
## Next Steps
|
||||
|
||||
After creating your validator:
|
||||
|
||||
1. **Update action rules**: Run `make update-validators`
|
||||
2. **Test with real action**: Use the validator with your GitHub Action
|
||||
3. **Document special rules**: Add to action's README
|
||||
4. **Monitor for issues**: Check GitHub Actions logs for validation errors
|
||||
351
validate-inputs/docs/README_ARCHITECTURE.md
Normal file
351
validate-inputs/docs/README_ARCHITECTURE.md
Normal file
@@ -0,0 +1,351 @@
|
||||
# Validate Inputs - Modular Validation System
|
||||
|
||||
A comprehensive, modular validation system for GitHub Actions inputs with automatic convention-based detection, custom validator support, and extensive testing capabilities.
|
||||
|
||||
## Features
|
||||
|
||||
- 🔍 **Automatic Validation** - Convention-based input detection
|
||||
- 🧩 **Modular Architecture** - 11+ specialized validators
|
||||
- 🛡️ **Security First** - Injection and traversal protection
|
||||
- 🎯 **Custom Validators** - Action-specific validation logic
|
||||
- 🧪 **Test Generation** - Automatic test scaffolding
|
||||
- 📊 **Performance Tools** - Benchmarking and profiling
|
||||
- 🐛 **Debug Utilities** - Troubleshooting helpers
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Using in Your Action
|
||||
|
||||
```yaml
|
||||
# In your action.yml
|
||||
runs:
|
||||
using: composite
|
||||
steps:
|
||||
- name: Validate inputs
|
||||
uses: ./validate-inputs
|
||||
with:
|
||||
action-type: ${{ github.action }}
|
||||
```
|
||||
|
||||
### Automatic Validation
|
||||
|
||||
Name your inputs following conventions for automatic validation:
|
||||
|
||||
```yaml
|
||||
inputs:
|
||||
github-token: # Automatically validates token format
|
||||
description: GitHub token
|
||||
default: ${{ github.token }}
|
||||
|
||||
node-version: # Automatically validates version format
|
||||
description: Node.js version
|
||||
default: '18'
|
||||
|
||||
dry-run: # Automatically validates boolean
|
||||
description: Run without making changes
|
||||
default: 'false'
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
```text
|
||||
validate-inputs/
|
||||
├── validators/ # Core validator modules
|
||||
│ ├── base.py # Abstract base class
|
||||
│ ├── registry.py # Dynamic validator discovery
|
||||
│ ├── conventions.py # Pattern-based matching
|
||||
│ ├── boolean.py # Boolean validation
|
||||
│ ├── version.py # Version validation (SemVer/CalVer)
|
||||
│ ├── token.py # Token validation
|
||||
│ ├── numeric.py # Numeric range validation
|
||||
│ ├── file.py # File path validation
|
||||
│ ├── network.py # URL/email validation
|
||||
│ ├── docker.py # Docker-specific validation
|
||||
│ ├── security.py # Security pattern detection
|
||||
│ └── codeql.py # CodeQL validation
|
||||
├── scripts/
|
||||
│ ├── update-validators.py # Generate validation rules
|
||||
│ ├── generate-tests.py # Generate test files
|
||||
│ ├── debug-validator.py # Debug validation issues
|
||||
│ └── benchmark-validator.py # Performance testing
|
||||
├── docs/
|
||||
│ ├── API.md # Complete API reference
|
||||
│ ├── DEVELOPER_GUIDE.md # Adding new validators
|
||||
│ └── ACTION_MAINTAINER.md # Using validation
|
||||
├── rules/ # Auto-generated validation rules
|
||||
├── tests/ # Comprehensive test suite
|
||||
└── validator.py # Main entry point
|
||||
```
|
||||
|
||||
## Core Validators
|
||||
|
||||
### Version Validator
|
||||
|
||||
- **SemVer**: `1.2.3`, `2.0.0-beta.1`
|
||||
- **CalVer**: `2024.3.15`, `24.03`
|
||||
- **Flexible**: Accepts both formats
|
||||
|
||||
### Token Validator
|
||||
|
||||
- **GitHub**: `ghp_*`, `github_pat_*`, `${{ secrets.GITHUB_TOKEN }}`
|
||||
- **NPM**: UUID format
|
||||
- **Docker**: Any non-empty value
|
||||
|
||||
### Boolean Validator
|
||||
|
||||
- **Accepted**: `true`, `false` (case-insensitive)
|
||||
- **Rejected**: `yes`, `no`, `1`, `0`
|
||||
|
||||
### Numeric Validator
|
||||
|
||||
- **Ranges**: `0-100`, `1-10`, `1-128`
|
||||
- **Types**: Integers only by default
|
||||
|
||||
### File Validator
|
||||
|
||||
- **Security**: No path traversal (`../`)
|
||||
- **Paths**: Relative paths only
|
||||
- **Extensions**: Validates common file types
|
||||
|
||||
### Network Validator
|
||||
|
||||
- **URLs**: HTTP/HTTPS validation
|
||||
- **Emails**: RFC-compliant
|
||||
- **Hostnames**: Valid DNS names
|
||||
- **IPs**: IPv4 and IPv6
|
||||
|
||||
### Docker Validator
|
||||
|
||||
- **Images**: Lowercase, valid characters
|
||||
- **Tags**: Alphanumeric with `-`, `_`, `.`
|
||||
- **Platforms**: `linux/amd64`, `linux/arm64`, etc.
|
||||
- **Registries**: Known registries validation
|
||||
|
||||
### Security Validator
|
||||
|
||||
- **Injection**: Command, SQL, script detection
|
||||
- **Traversal**: Path traversal prevention
|
||||
- **Secrets**: API key and password detection
|
||||
|
||||
## Convention Patterns
|
||||
|
||||
The system automatically detects validation types based on input names:
|
||||
|
||||
| Pattern | Validator | Examples |
|
||||
|----------------------|------------------|-------------------------------|
|
||||
| `*-token` | TokenValidator | `github-token`, `api-token` |
|
||||
| `*-version` | VersionValidator | `node-version`, `go-version` |
|
||||
| `dry-run`, `debug` | BooleanValidator | `dry-run`, `verbose` |
|
||||
| `max-*`, `*-limit` | NumericValidator | `max-retries`, `rate-limit` |
|
||||
| `*-file`, `*-path` | FileValidator | `config-file`, `output-path` |
|
||||
| `*-url`, `webhook-*` | NetworkValidator | `api-url`, `webhook-endpoint` |
|
||||
| `dockerfile` | FileValidator | `dockerfile` |
|
||||
| `image-*`, `tag` | DockerValidator | `image-name`, `tag` |
|
||||
|
||||
## Custom Validators
|
||||
|
||||
Create action-specific validation logic:
|
||||
|
||||
```python
|
||||
# my-action/CustomValidator.py
|
||||
from pathlib import Path
|
||||
import sys
|
||||
|
||||
validate_inputs_path = Path(__file__).parent.parent / "validate-inputs"
|
||||
sys.path.insert(0, str(validate_inputs_path))
|
||||
|
||||
from validators.base import BaseValidator
|
||||
|
||||
class CustomValidator(BaseValidator):
|
||||
def validate_inputs(self, inputs: dict[str, str]) -> bool:
|
||||
# Custom validation logic
|
||||
return True
|
||||
|
||||
def get_required_inputs(self) -> list[str]:
|
||||
return ["required-field"]
|
||||
```
|
||||
|
||||
## Development Tools
|
||||
|
||||
### Generate Validation Rules
|
||||
|
||||
```bash
|
||||
# Update all action rules
|
||||
make update-validators
|
||||
|
||||
# Update specific action
|
||||
python3 validate-inputs/scripts/update-validators.py --action my-action
|
||||
```
|
||||
|
||||
### Generate Tests
|
||||
|
||||
```bash
|
||||
# Generate missing tests
|
||||
make generate-tests
|
||||
|
||||
# Preview changes
|
||||
make generate-tests-dry
|
||||
```
|
||||
|
||||
### Debug Validation
|
||||
|
||||
```bash
|
||||
# Test specific inputs
|
||||
./validate-inputs/scripts/debug-validator.py \
|
||||
--action docker-build \
|
||||
--input "image-name=myapp" \
|
||||
--input "tag=v1.0.0"
|
||||
|
||||
# Test input matching
|
||||
./validate-inputs/scripts/debug-validator.py \
|
||||
--test-matching github-token node-version dry-run
|
||||
|
||||
# List available validators
|
||||
./validate-inputs/scripts/debug-validator.py --list-validators
|
||||
```
|
||||
|
||||
### Performance Testing
|
||||
|
||||
```bash
|
||||
# Benchmark specific action
|
||||
./validate-inputs/scripts/benchmark-validator.py \
|
||||
--action docker-build \
|
||||
--inputs 20 \
|
||||
--iterations 1000
|
||||
|
||||
# Compare validators
|
||||
./validate-inputs/scripts/benchmark-validator.py --compare
|
||||
|
||||
# Profile for bottlenecks
|
||||
./validate-inputs/scripts/benchmark-validator.py \
|
||||
--profile docker-build
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
make test
|
||||
|
||||
# Run Python tests only
|
||||
make test-python
|
||||
|
||||
# Run specific test
|
||||
uv run pytest validate-inputs/tests/test_version_validator.py
|
||||
|
||||
# Run with coverage
|
||||
make test-python-coverage
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
- **[API Reference](API.md)** - Complete validator API documentation
|
||||
- **[Developer Guide](DEVELOPER_GUIDE.md)** - Adding new validators
|
||||
- **[Action Maintainer Guide](ACTION_MAINTAINER.md)** - Using validation in actions
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use Conventions** - Name inputs to trigger automatic validation
|
||||
2. **Allow Expressions** - Always support `${{ }}` GitHub expressions
|
||||
3. **Clear Errors** - Provide actionable error messages
|
||||
4. **Test Thoroughly** - Test valid, invalid, and edge cases
|
||||
5. **Document Rules** - Document validation in action README
|
||||
6. **Performance** - Keep validation fast (< 10ms typical)
|
||||
|
||||
## Examples
|
||||
|
||||
### Complete Action with Validation
|
||||
|
||||
```yaml
|
||||
name: Deploy Application
|
||||
description: Deploy application with validation
|
||||
|
||||
inputs:
|
||||
environment:
|
||||
description: Deployment environment
|
||||
required: true
|
||||
|
||||
github-token:
|
||||
description: GitHub token for API access
|
||||
default: ${{ github.token }}
|
||||
|
||||
node-version:
|
||||
description: Node.js version
|
||||
default: '18'
|
||||
|
||||
dry-run:
|
||||
description: Preview changes without deploying
|
||||
default: 'false'
|
||||
|
||||
runs:
|
||||
using: composite
|
||||
steps:
|
||||
# Validate all inputs
|
||||
- uses: ./validate-inputs
|
||||
with:
|
||||
action-type: deploy-application
|
||||
|
||||
# Setup Node.js
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ inputs.node-version }}
|
||||
|
||||
# Deploy application
|
||||
- run: |
|
||||
if [[ "${{ inputs.dry-run }}" == "true" ]]; then
|
||||
echo "DRY RUN: Would deploy to ${{ inputs.environment }}"
|
||||
else
|
||||
./deploy.sh --env "${{ inputs.environment }}"
|
||||
fi
|
||||
shell: bash
|
||||
```
|
||||
|
||||
### Custom Validator Example
|
||||
|
||||
```python
|
||||
# deploy-application/CustomValidator.py
|
||||
class CustomValidator(BaseValidator):
|
||||
def validate_inputs(self, inputs: dict[str, str]) -> bool:
|
||||
valid = True
|
||||
|
||||
# Validate environment
|
||||
if inputs.get("environment"):
|
||||
valid_envs = ["dev", "staging", "prod"]
|
||||
if inputs["environment"] not in valid_envs:
|
||||
self.add_error(
|
||||
f"Invalid environment: {inputs['environment']}. "
|
||||
f"Must be one of: {', '.join(valid_envs)}"
|
||||
)
|
||||
valid = False
|
||||
|
||||
# Production requires explicit token
|
||||
if inputs.get("environment") == "prod":
|
||||
if not inputs.get("github-token"):
|
||||
self.add_error("Production deployments require github-token")
|
||||
valid = False
|
||||
|
||||
return valid
|
||||
|
||||
def get_required_inputs(self) -> list[str]:
|
||||
return ["environment"]
|
||||
```
|
||||
|
||||
## Quality Metrics
|
||||
|
||||
- **Test Coverage**: 100% (303 tests)
|
||||
- **Validators**: 11 core + unlimited custom
|
||||
- **Performance**: < 10ms typical validation time
|
||||
- **Zero Dependencies**: Uses only Python stdlib + PyYAML
|
||||
- **Production Ready**: Zero defects policy
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Create new validator in `validators/` directory
|
||||
2. Add convention patterns to `conventions.py`
|
||||
3. Write comprehensive tests
|
||||
4. Update documentation
|
||||
5. Run `make all` to verify
|
||||
|
||||
## License
|
||||
|
||||
Part of ivuorinen/actions - see repository license.
|
||||
Reference in New Issue
Block a user