From cdf865ca911a32c9fb203b65971ff2ef039e4e75 Mon Sep 17 00:00:00 2001 From: Erick Bourgeois Date: Fri, 19 Dec 2025 21:45:17 -0500 Subject: [PATCH] Add badges to README.md Signed-off-by: Erick Bourgeois --- README.md | 34 +++- RELEASE_PROCESS.md | 398 --------------------------------------- TIER1_ACTIONS.md | 197 ------------------- TIER2_ACTIONS_SUMMARY.md | 261 ------------------------- 4 files changed, 33 insertions(+), 857 deletions(-) delete mode 100644 RELEASE_PROCESS.md delete mode 100644 TIER1_ACTIONS.md delete mode 100644 TIER2_ACTIONS_SUMMARY.md diff --git a/README.md b/README.md index 5b89fbd..5223215 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,40 @@ **Reusable composite GitHub Actions for CI/CD pipelines** -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +## Project Status + +[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![GitHub Release](https://img.shields.io/github/v/release/firestoned/github-actions)](https://github.com/firestoned/github-actions/releases) +[![GitHub commits since latest release](https://img.shields.io/github/commits-since/firestoned/github-actions/latest)](https://github.com/firestoned/github-actions/commits/main) +[![Last Commit](https://img.shields.io/github/last-commit/firestoned/github-actions)](https://github.com/firestoned/github-actions/commits/main) + +## CI/CD Status + +[![PR Tests](https://github.com/firestoned/github-actions/workflows/Test%20GitHub%20Actions/badge.svg)](https://github.com/firestoned/github-actions/actions/workflows/pr.yml) +[![Release Workflow](https://github.com/firestoned/github-actions/workflows/Release%20GitHub%20Actions/badge.svg)](https://github.com/firestoned/github-actions/actions/workflows/release.yml) + +## Technology & Compatibility + [![GitHub Actions](https://img.shields.io/badge/GitHub%20Actions-2088FF?logo=github-actions&logoColor=white)](https://github.com/features/actions) +[![Rust](https://img.shields.io/badge/Rust-000000?logo=rust&logoColor=white)](https://www.rust-lang.org/) +[![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black)](https://www.linux.org/) +[![macOS](https://img.shields.io/badge/macOS-000000?logo=apple&logoColor=white)](https://www.apple.com/macos/) + +## Security & Compliance + +[![SPDX](https://img.shields.io/badge/SPDX-License--Identifier-blue)](https://spdx.dev/) +[![CycloneDX](https://img.shields.io/badge/CycloneDX-SBOM-orange)](https://cyclonedx.org/) +[![Trivy](https://img.shields.io/badge/Trivy-Security%20Scanning-blue)](https://trivy.dev/) +[![Cosign](https://img.shields.io/badge/Cosign-Artifact%20Signing-purple)](https://docs.sigstore.dev/cosign/overview/) + +## Community & Support + +[![Issues](https://img.shields.io/github/issues/firestoned/github-actions)](https://github.com/firestoned/github-actions/issues) +[![Pull Requests](https://img.shields.io/github/issues-pr/firestoned/github-actions)](https://github.com/firestoned/github-actions/pulls) +[![Contributors](https://img.shields.io/github/contributors/firestoned/github-actions)](https://github.com/firestoned/github-actions/graphs/contributors) +[![Stars](https://img.shields.io/github/stars/firestoned/github-actions?style=social)](https://github.com/firestoned/github-actions/stargazers) + +--- A collection of production-ready, reusable GitHub Actions composite workflows for Rust, Docker, security scanning, and compliance. Built for enterprise environments with a focus on security, supply chain integrity, and regulatory compliance. diff --git a/RELEASE_PROCESS.md b/RELEASE_PROCESS.md deleted file mode 100644 index f18ac80..0000000 --- a/RELEASE_PROCESS.md +++ /dev/null @@ -1,398 +0,0 @@ -# Release Process - -This document explains how to release new versions of the firestoned/github-actions repository. - -## Overview - -The release process is **event-driven** and automated. When you publish a GitHub Release, the workflow automatically: - -1. Validates the version format -2. Validates all action files (syntax, required fields, documentation, licenses) -3. Runs the test suite -4. Creates major and minor version tags (for stable releases) -5. Verifies all tags exist -6. Provides usage instructions - -## Release Workflow - -### Trigger: `release.published` Event - -The [.github/workflows/release.yml](.github/workflows/release.yml) workflow runs automatically when you **publish a release** on GitHub. - -### Workflow Jobs - -``` -extract-version → validate → test → create-tags → post-release - ↓ - (all jobs depend on extract-version) -``` - -1. **extract-version**: Parses the release tag and extracts version information -2. **validate**: Validates all action files, documentation, and licenses -3. **test**: Runs functional tests on key actions -4. **create-tags**: Creates major (`v1`) and minor (`v1.0`) tags for stable releases -5. **post-release**: Verifies tags exist and displays usage instructions - -## How to Release - -### Step 1: Update CHANGELOG.md - -Before creating a release, ensure your [CHANGELOG.md](CHANGELOG.md) has an entry for the version: - -```markdown -## [1.0.0] - 2025-12-18 - -### Added -- New feature descriptions -- Bug fixes -- Breaking changes (if any) -``` - -### Step 2: Create and Publish a GitHub Release - -#### Option A: Using GitHub Web UI - -1. Go to **Releases** → **Draft a new release** -2. Click **Choose a tag** -3. Type the version (e.g., `v1.0.0`) and click **Create new tag** -4. Fill in: - - **Release title**: `v1.0.0` (or descriptive title) - - **Description**: Copy from CHANGELOG.md or write release notes - - **Set as a pre-release**: Check this for beta/RC versions -5. Click **Publish release** - -#### Option B: Using GitHub CLI - -```bash -# Stable release -gh release create v1.0.0 \ - --title "v1.0.0 - Initial Stable Release" \ - --notes "$(sed -n '/## \[1.0.0\]/,/## \[/p' CHANGELOG.md | sed '$d')" - -# Pre-release -gh release create v1.1.0-beta.1 \ - --title "v1.1.0-beta.1" \ - --notes "Beta release for testing" \ - --prerelease -``` - -### Step 3: Workflow Runs Automatically - -Once you publish the release, the workflow will: - -- ✅ Validate the release tag format (must be semver: `vX.Y.Z` or `vX.Y.Z-prerelease`) -- ✅ Run all validation checks -- ✅ Run the test suite -- ✅ Create moving tags (only for stable releases): - - `v1.0` → points to latest `v1.0.x` - - `v1` → points to latest `v1.x.x` -- ✅ Verify everything is ready - -### Step 4: Monitor Workflow - -1. Go to **Actions** → **Release GitHub Actions** -2. Watch the workflow run -3. Check the summary for usage instructions - -## Version Tags Explained - -### Exact Version Tag (Created by Release) - -When you create a release with tag `v1.0.0`, GitHub creates this tag automatically. - -**Example**: `v1.0.0` -- Never moves -- Always points to the same commit -- Use for reproducible builds - -### Moving Tags (Created by Workflow) - -For **stable releases only** (not pre-releases), the workflow creates/updates: - -**Minor Tag**: `v1.0` -- Points to the latest `v1.0.x` release -- Updates when you release `v1.0.1`, `v1.0.2`, etc. -- Users get patch updates automatically - -**Major Tag**: `v1` -- Points to the latest `v1.x.x` release -- Updates when you release `v1.1.0`, `v1.2.0`, etc. -- Users get minor and patch updates automatically - -### Tag Behavior for Pre-releases - -Pre-releases (e.g., `v1.1.0-beta.1`) **DO NOT** update moving tags. - -**Why?** Users who pin to `@v1` should only get stable releases, not beta versions. - -## Release Types - -### Stable Release (v1.0.0, v1.1.0, v2.0.0) - -```bash -gh release create v1.0.0 --title "v1.0.0" --notes "Release notes here" -``` - -**Result**: -- Creates tag `v1.0.0` ✅ -- Updates tag `v1.0` → `v1.0.0` ✅ -- Updates tag `v1` → `v1.0.0` ✅ - -**Users can reference**: -```yaml -uses: firestoned/github-actions/rust/cache-cargo@v1 # Recommended -uses: firestoned/github-actions/rust/cache-cargo@v1.0 # Conservative -uses: firestoned/github-actions/rust/cache-cargo@v1.0.0 # Exact -``` - -### Patch Release (v1.0.1) - -```bash -gh release create v1.0.1 --title "v1.0.1" --notes "Bug fixes" -``` - -**Result**: -- Creates tag `v1.0.1` ✅ -- Updates tag `v1.0` → `v1.0.1` ✅ (moves forward) -- Updates tag `v1` → `v1.0.1` ✅ (moves forward) - -### Minor Release (v1.1.0) - -```bash -gh release create v1.1.0 --title "v1.1.0" --notes "New features" -``` - -**Result**: -- Creates tag `v1.1.0` ✅ -- Creates tag `v1.1` → `v1.1.0` ✅ (new minor tag) -- Updates tag `v1` → `v1.1.0` ✅ (moves forward) - -### Pre-release (v1.1.0-beta.1) - -```bash -gh release create v1.1.0-beta.1 \ - --title "v1.1.0-beta.1" \ - --notes "Beta release" \ - --prerelease -``` - -**Result**: -- Creates tag `v1.1.0-beta.1` ✅ -- **DOES NOT** update `v1.1` or `v1` ⚠️ - -**Users must use exact version**: -```yaml -uses: firestoned/github-actions/rust/cache-cargo@v1.1.0-beta.1 -``` - -## Semantic Versioning - -This repository follows [Semantic Versioning 2.0.0](https://semver.org/): - -### Major Version (v1.0.0 → v2.0.0) - -**Breaking changes** to action inputs/outputs. - -**Example**: -- Removing an input parameter -- Changing output format -- Renaming an action - -**Users**: Must update their workflows manually. - -### Minor Version (v1.0.0 → v1.1.0) - -**New features**, backward compatible. - -**Example**: -- Adding a new optional input -- Adding a new output -- Adding a new action - -**Users**: Get updates automatically if using `@v1`. - -### Patch Version (v1.0.0 → v1.0.1) - -**Bug fixes**, backward compatible. - -**Example**: -- Fixing a bug -- Updating documentation -- Security patches - -**Users**: Get updates automatically if using `@v1` or `@v1.0`. - -## Validation Checks - -The workflow runs these validations before creating tags: - -### 1. Version Format - -```bash -# Valid -v1.0.0 -v1.0.0-beta.1 -v2.0.0-rc.1 - -# Invalid -1.0.0 # Missing 'v' prefix -v1.0 # Missing patch version -v1.0.0.1 # Too many segments -``` - -### 2. Action Files - -- All `action.yml` files must be valid YAML -- Required fields: `name`, `description`, `runs.using` -- Must have SPDX license headers - -### 3. Documentation - -- Every action must have a `README.md` -- Must include usage examples - -### 4. License - -- Repository must have `LICENSE` file -- All action files must have SPDX headers - -### 5. Functional Tests - -- Tests run for key actions (cache-cargo, extract-version, license-check, setup-docker) -- Docker Buildx verification - -## Troubleshooting - -### Workflow Failed During Validation - -**Problem**: Action files have syntax errors or missing fields. - -**Solution**: -1. Check the workflow logs for specific errors -2. Fix the issues in your code -3. Delete the release (if it was published) -4. Create a new release with a new tag - -### Tags Not Created - -**Problem**: Moving tags (`v1`, `v1.0`) weren't created. - -**Possible causes**: -1. **Pre-release**: Moving tags are intentionally skipped for pre-releases -2. **Workflow failed**: Check the workflow logs -3. **Permissions**: Workflow needs `contents: write` permission (already configured) - -**Solution**: Check workflow logs in the Actions tab. - -### Wrong Version Tag Format - -**Problem**: Workflow failed because tag doesn't match semver format. - -**Solution**: -1. Delete the release -2. Create a new release with correct format: `vX.Y.Z` - -### Need to Re-run Workflow - -**Problem**: Workflow failed but you've fixed the issue. - -**Solution**: -You can re-run the workflow from the Actions tab, but **only if** the release tag hasn't changed. If you need to change the tag: -1. Delete the release -2. Delete the tag: `git push origin :refs/tags/vX.Y.Z` -3. Create a new release with the corrected tag - -## Best Practices - -### 1. Always Update CHANGELOG.md First - -Before creating a release, document the changes in CHANGELOG.md. - -### 2. Test Before Releasing - -Ensure all tests pass locally: -```bash -# Run validation manually -find . -name "action.yml" -o -name "action.yaml" | while read action; do - python3 -c "import yaml; yaml.safe_load(open('$action'))" -done -``` - -### 3. Use Pre-releases for Testing - -For beta/RC versions, mark the release as a pre-release: -```bash -gh release create v1.1.0-beta.1 --prerelease -``` - -### 4. Don't Skip Versions - -Release versions in order: `v1.0.0` → `v1.0.1` → `v1.1.0` → `v2.0.0` - -Don't skip from `v1.0.0` to `v1.2.0`. - -### 5. Communicate Breaking Changes - -For major version bumps, clearly document: -- What changed -- Migration guide -- Timeline for deprecation (if applicable) - -## Example Release Workflow - -### Releasing v1.0.1 (Patch) - -```bash -# 1. Update CHANGELOG.md -cat >> CHANGELOG.md <'` -- Branding: Icon and color for GitHub Marketplace - -### 2. Comprehensive Documentation -Each README.md includes: -- Feature overview -- Usage examples (basic and advanced) -- Complete input/output parameter tables -- "How It Works" section -- Best practices -- Troubleshooting guide -- Advanced usage examples -- Performance tips -- Related actions links -- Compatibility notes -- Complete workflow examples - -### 3. Minor Code Improvements -- **rust/setup-rust-build**: Added `cross-version` input for version pinning -- **rust/security-scan**: Fixed cache-cargo path reference -- All others: Copied as-is with documentation enhancements - -## Documentation Quality - -All READMEs follow consistent structure: -1. Title and description -2. Features list -3. Usage examples (basic → advanced) -4. Input/output tables -5. How It Works section -6. Best practices -7. Troubleshooting -8. Advanced usage -9. Performance tips -10. Related actions -11. License and compatibility -12. Complete workflow examples - -## Total Files Created - -- **8 action.yaml files** (all with branding and author) -- **8 comprehensive README.md files** (averaging 300-400 lines each) -- **All files** include MIT license headers - -## Next Steps - -1. **Review**: Check all documentation for accuracy -2. **Test**: Validate action.yaml syntax -3. **Publish**: Push to GitHub repository -4. **Version**: Tag with v1 for initial release -5. **Marketplace**: Publish to GitHub Marketplace (optional) - -## Validation Commands - -```bash -# Verify all action files exist -find /tmp/github-actions -name "action.yaml" | wc -l -# Should output: 8 - -# Verify all READMEs exist -find /tmp/github-actions -path "*/rust/*" -o -path "*/security/*" -o -path "*/docker/*" | grep README.md | wc -l -# Should output: 8 - -# Check copyright headers -find /tmp/github-actions -name "action.yaml" -exec grep -l "Copyright (c) 2025 Erick Bourgeois" {} \; | wc -l -# Should output: 8 - -# Check branding -find /tmp/github-actions -name "action.yaml" -exec grep -l "branding:" {} \; | wc -l -# Should output: 8 -``` - -## License - -All actions are licensed under MIT License. -Copyright (c) 2025 Erick Bourgeois, firestoned diff --git a/TIER2_ACTIONS_SUMMARY.md b/TIER2_ACTIONS_SUMMARY.md deleted file mode 100644 index 32dabae..0000000 --- a/TIER2_ACTIONS_SUMMARY.md +++ /dev/null @@ -1,261 +0,0 @@ -# Tier 2 Actions - Refactoring and Documentation Summary - -## Overview - -This document summarizes the refactoring and documentation work completed for the two Tier 2 actions: **extract-version** and **license-check**. - -## 1. Extract Version Action - -**Location:** `/tmp/github-actions/versioning/extract-version/` - -### Key Changes - -The action was **already refactored** to accept the `repository` input instead of hardcoding "firestoned/bindy". The action now supports: - -- **Repository parameter**: Accepts `repository` input (e.g., `${{ github.repository }}`) -- **Three workflow types**: `main`, `pr`, `release` -- **Image suffix support**: Built-in support for image variants (e.g., `-distroless`) - -### Documentation Created - -**File:** `README.md` (662 lines) - -**Sections:** -- Features overview -- Basic and advanced usage examples for all three workflow types -- Complete input/output parameter tables -- How it works (detailed explanation of each workflow type) -- Complete workflow examples (main, PR, release, multi-variant) -- Migration guide from hardcoded to parameterized version -- Best practices -- Troubleshooting -- Advanced usage -- Version format reference table -- Related actions -- Compatibility information - -**Highlights:** -- Shows clear examples for each workflow type -- Documents the image-suffix feature for distroless variants -- Provides migration examples from hardcoded approach -- Includes troubleshooting for common issues - ---- - -## 2. License Check Action - -**Location:** `/tmp/github-actions/security/license-check/` - -### Key Changes - -The action was **refactored** from the original hardcoded version to accept inputs: - -**Before (Hardcoded):** -- Copyright holder: "Erick Bourgeois, firestoned" (hardcoded) -- License: "MIT" (hardcoded) -- No configurability -- Not reusable by other projects - -**After (Parameterized):** -- `copyright-holder` input (required) -- `license-id` input (required) -- `check-rust`, `check-shell`, `check-makefiles`, `check-yaml` toggles -- `exclude-paths` for custom exclusions -- Fully reusable across projects - -### Refactored Action.yml - -**File:** `action.yml` (new version) - -**New inputs:** -- `copyright-holder` - Configurable copyright holder name -- `license-id` - Configurable SPDX license identifier -- `check-rust` - Toggle for Rust file checking (default: true) -- `check-shell` - Toggle for Shell script checking (default: true) -- `check-makefiles` - Toggle for Makefile checking (default: true) -- `check-yaml` - Toggle for YAML checking (default: true) -- `exclude-paths` - Comma-separated exclusion paths (default: target/,.git/,docs/target/) - -**Features:** -- Dynamic exclude pattern building -- Configurable file type checking -- Dynamic copyright and license in error messages -- Supports all SPDX license identifiers - -### Documentation Created - -**File:** `README.md` (724 lines) - -**Sections:** -- Features overview -- Basic usage with different license types (MIT, Apache-2.0, GPL-3.0) -- Selective file type checking examples -- Custom exclusion paths -- Complete input parameter table -- How it works (scan process, file types, SPDX identifiers) -- Supported file types with expected header formats -- Complete workflow examples -- Migration guide from hardcoded to parameterized version -- Best practices (repository variables, pre-commit hooks, etc.) -- Troubleshooting -- Advanced usage (matrix builds, auto-fix, custom validation) -- Understanding SPDX section -- Related actions -- Compatibility information -- Resources - -**Highlights:** -- Documents all supported SPDX license types -- Shows expected header format for each file type -- Provides migration examples from hardcoded to parameterized -- Includes comprehensive SPDX education section -- Shows how to use with repository variables -- Includes auto-fix workflow example - ---- - -## Improvements Made - -### 1. Parameterization - -Both actions now accept inputs instead of hardcoding values: - -**Extract Version:** -- `repository` input instead of hardcoded "firestoned/bindy" -- Works with any repository via `${{ github.repository }}` - -**License Check:** -- `copyright-holder` input instead of hardcoded "Erick Bourgeois, firestoned" -- `license-id` input instead of hardcoded "MIT" -- Supports all SPDX license identifiers - -### 2. Comprehensive Documentation - -Both READMEs follow the same comprehensive style as other Tier 1 actions: - -- **300-700 lines** of detailed documentation -- **Features** section highlighting key capabilities -- **Basic and advanced usage** examples -- **Input/output parameter tables** with descriptions -- **How it works** section explaining internals -- **Complete workflow examples** for different scenarios -- **Migration guides** showing before/after -- **Best practices** section -- **Troubleshooting** section with common issues -- **Advanced usage** for power users -- **Related actions** for discoverability -- **Compatibility** information -- **License and contributing** information - -### 3. Reusability - -Both actions are now truly reusable: - -- **Extract Version**: Works with any repository, not just bindy -- **License Check**: Works with any copyright holder and any SPDX license - ---- - -## File Structure - -``` -/tmp/github-actions/ -├── versioning/ -│ └── extract-version/ -│ ├── action.yml (already refactored) -│ └── README.md (NEW - 662 lines) -└── security/ - └── license-check/ - ├── action.yml (REFACTORED - 6.8KB) - └── README.md (NEW - 724 lines) -``` - ---- - -## Migration Examples - -### Extract Version - -**Before:** -```yaml -- name: Set version - run: echo "image=ghcr.io/firestoned/bindy:main-$(date +%Y.%m.%d)" >> $GITHUB_OUTPUT -``` - -**After:** -```yaml -- name: Extract version - id: version - uses: firestoned/github-actions/versioning/extract-version@v1 - with: - repository: ${{ github.repository }} - workflow-type: main -``` - -### License Check - -**Before:** -```yaml -- uses: firestoned/bindy/.github/actions/license-check@main -# Hardcoded: "Erick Bourgeois, firestoned" and "MIT" -``` - -**After:** -```yaml -- uses: firestoned/github-actions/security/license-check@v1 - with: - copyright-holder: 'Erick Bourgeois, firestoned' - license-id: MIT -# Or with repository variables: -- uses: firestoned/github-actions/security/license-check@v1 - with: - copyright-holder: ${{ vars.COPYRIGHT_HOLDER }} - license-id: ${{ vars.LICENSE_ID }} -``` - ---- - -## Testing Recommendations - -### Extract Version - -Test all three workflow types: -1. **Main branch**: Verify date-based versioning -2. **Pull request**: Verify PR number in tag -3. **Release**: Verify version extraction from tag -4. **Distroless variant**: Verify image-suffix appends to repository name - -### License Check - -Test different scenarios: -1. **All headers present**: Should pass -2. **Missing headers**: Should fail with clear error -3. **Different license types**: MIT, Apache-2.0, GPL-3.0 -4. **Exclusion paths**: Verify excluded files are skipped -5. **Selective file types**: Verify toggling check-rust, check-shell, etc. - ---- - -## Next Steps - -1. **Copy actions to bindy repository** (or wherever they'll be used) -2. **Update existing workflows** to use the parameterized versions -3. **Test in real workflows** to verify behavior -4. **Add repository variables** for COPYRIGHT_HOLDER and LICENSE_ID -5. **Document in main README** that these are Tier 2 actions -6. **Create GitHub releases** with proper version tags - ---- - -## Summary - -Both Tier 2 actions have been successfully refactored and documented: - -✅ **Extract Version**: Already parameterized, now fully documented -✅ **License Check**: Refactored from hardcoded to parameterized, fully documented -✅ **Comprehensive READMEs**: 662 and 724 lines respectively -✅ **Migration guides**: Clear before/after examples -✅ **Best practices**: Documented recommended usage patterns -✅ **Troubleshooting**: Common issues and solutions documented - -Both actions are now production-ready and can be used by any project, not just the original bindy repository.