Continuous Integration - GitHub - Publish

---

Overview

Opinionated GitHub Actions and workflows for streamlined release, deployment, and publishing.

Requirements

Use GitHub.com with GitHub Actions runner 2.336.0 or newer. Internal actions use $/ references to resolve paths from this repository at the same revision as the defining action or workflow, without a separate checkout of this repository.

Actions

ArgoCD

Actions dedicated to ArgoCD workflows.

- Get manifest files

Checks

Actions for validating the result of a deploy.

- URL - Lighthouse

- URL - Ping

Clean deploy

Actions for cleaning deployments on various platforms.

- Repository dispatch

Deploy

Actions for deploying to various platforms.

- Argocd manifest files

- Get environment

- GitHub Pages

- Helm repository dispatch

- Jampack

- Jekyll

- Report

Deployment

Actions for managing deployments.

- Create

- Delete

- Get finished

- Read

- Update

Release

Actions for managing releases.

- Create or refresh release

- Delete

- Plan

- Update

- Recommended release workflow

- Summarize changelog

Workflow

Actions for managing workflows.

- Get workflow failure

Reusable Workflows

Cleaning deploy

- Clean deploy

- Clean deploy argocd app of apps

Performs deploy

- Deploy argocd app of apps

- Deploy chart

- Deploy start

- Deploy checks

- Deploy finish

- Finish deploy argocd app of apps

Releases

Reusable workflows for managing release process.

- Prepare release

- Release actions

Contributing

Contributions are welcome! Please see the contributing guidelines for more details.

Action Structure Pattern

All actions follow this consistent structure:

actions/{category}/{action-name}/
├── action.yml          # Action definition with inputs/outputs
├── README.md          # Usage documentation
└── *.js              # Optional Node.js scripts (e.g., prepare-site.js)

Development Standards

Action Definition Standards

1. Consistent branding: All actions use author: hoverkraft, icon: <specific-icon>, color: blue
2. Composite actions: Use using: "composite" with GitHub Script for complex logic
3. Pinned dependencies: Pin external action versions with SHA (e.g., @ed597411d8f924073f98dfc5c65a23a2325f34cd); use $/ references for actions in this repository
4. Input validation: Validate inputs early in GitHub Script steps

JavaScript Patterns

• Class-based architecture: Use classes like AssetManager for complex functionality
• Path utilities: Extensive use of Node.js path module for cross-platform compatibility
• Regular expression patterns: Define constants for reusable patterns (MARKDOWN_IMAGE_REGEX, HTML_IMAGE_REGEX)
• Caching: Implement Map-based caching for expensive operations

Development Workflow

Linting & Testing

make lint        # Run Super Linter (dockerized)
make lint-fix    # Auto-fix issues where possible
make npm-update  # Choose dependency upgrades interactively for each action package

# Use GitHub Actions locally with `act`
gh act -W .github/workflows/workflow-file-to-test.yml

make npm-update uses npm-check-updates to select dependency upgrades for each package under actions/, excluding node_modules. After selection, it runs npm install in that package to refresh its lockfile. Run it from an interactive terminal with npm 10+ and Node.js 24.15+ (24.x) or 26+.

Commitlint uses the Conventional Commits preset, including the ! marker for breaking changes. Duplicate-code checks keep the 5% threshold and scan action and workflow documentation. Repeated sections use inline <!-- jscpd:ignore-start --> and <!-- jscpd:ignore-end --> comments in the affected files. Place these comments outside the documentation generator's section markers so regeneration preserves them.

The Jampack action installs its locked dependencies with security overrides for esbuild, file-type, sharp, and undici. Keep these overrides until Jampack adopts patched versions upstream; removing them reintroduces security findings. Its integration test exercises CSS, JavaScript, and local and remote images. Trivy's scoped exception records the unpatched braces advisory: this action uses fixed glob patterns and passes the input path as a directory. The exception expires on November 12, 2026, and must be reassessed if Jampack or its CLI arguments change. npm audit still reports this advisory and its dependent packages until an upstream fix is available.

File Conventions

• Dockerfile: Uses Super Linter slim image for consistent code quality
• Tests: Located in tests/ with expected vs actual file comparisons
• Workflows: Private workflows prefixed with __ (e.g., __main-ci.yml)

Action Development Conventions

Always follow these patterns when creating/modifying actions:

1. Pinned Dependencies: Use exact SHA commits for external action dependencies:

   uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0

   Reference actions in this repository from its root with $/:

   uses: $/actions/release/get-configuration

2. Consistent Branding: Every action.yml must include:

   author: hoverkraft
   branding:
     icon: <specific-icon>
     color: blue

3. Input Validation: Always validate inputs early in GitHub Script steps:

   const urlInput = ${{ toJson(inputs.url ) }};
   if (!urlInput) {
     return core.setFailed("URL input is required.");
   }

JavaScript Development Patterns

For Node.js scripts (like prepare-site.js):

• Use class-based architecture for complex functionality
• Define regular expression patterns as constants (MARKDOWN_IMAGE_REGEX, HTML_IMAGE_REGEX)
• Implement Map-based caching for expensive operations
• Always use Node.js path module for cross-platform compatibility

File Structure Understanding

actions/{category}/{action-name}/     # Modular action organization
├── action.yml                        # Action definition with inputs/outputs
├── README.md                         # Usage documentation
└── *.js                             # Optional Node.js scripts

.github/workflows/                    # Reusable workflows
├── deploy-*.yml                      # Deployment orchestration
├── clean-deploy-*.yml               # Cleanup workflows
└── __*.yml                          # Private/internal workflows

tests/                               # Expected vs actual comparisons
└── argocd-app-of-apps/             # Template testing structure

Author

🏢 Hoverkraft contact@hoverkraft.cloud

• Site: https://hoverkraft.cloud
• GitHub: @hoverkraft-tech

License

This project is licensed under the MIT License.

SPDX-License-Identifier: MIT

Copyright © 2025 hoverkraft-tech

For more details, see the license.