Consolidated GitHub Actions Project 🚀

A comprehensive, production-ready GitHub Actions project demonstrating modern CI/CD best practices, automated semantic versioning, Docker containerization, and AWS Lambda deployment workflows.

📋 Table of Contents

• Overview
• Features
• Project Structure
• Getting Started
• Workflows
• Custom Actions
• Example Applications
• Semantic Versioning
• Best Practices
• Contributing
• License

🎯 Overview

This project consolidates best practices from multiple GitHub Actions learning projects into a single, comprehensive reference implementation. It showcases:

• CI/CD Pipelines: Automated testing, building, and deployment
• Semantic Versioning: Automated version management based on conventional commits
• Docker Integration: Multi-stage builds, multi-platform support, and security scanning
• AWS Lambda Deployment: Serverless function packaging and deployment
• Custom Actions: Reusable action development with Node.js
• Code Quality: Linting, security scanning, and automated PR checks

✨ Features

🔄 CI/CD Workflows

• Continuous Integration: Matrix builds across multiple Node.js versions and OS platforms
• Code Quality Checks: ESLint, Prettier, and CodeQL analysis
• Security Scanning: Dependency audits, secret detection, and vulnerability scanning
• Automated Testing: Unit tests, integration tests, and coverage reporting
• Pull Request Validation: Automated PR labeling, size checking, and quality gates

🐳 Docker Support

• Multi-stage Builds: Optimized images with minimal attack surface
• Multi-platform Support: Builds for amd64 and arm64 architectures
• Container Security: Trivy scanning for vulnerabilities
• Registry Publishing: Automated pushes to Docker Hub and GitHub Container Registry
• Health Checks: Built-in container health monitoring

📦 Semantic Release

• Automated Versioning: Version bumps based on commit messages
• Changelog Generation: Auto-generated release notes
• Git Tagging: Automatic tag creation and management
• GitHub Releases: Release creation with assets
• Commit Convention: Enforced conventional commit format

☁️ AWS Lambda Deployment

• Automated Packaging: Lambda function ZIP creation with dependencies
• Environment Management: Deploy to dev, staging, or production
• Post-deployment Testing: Automated Lambda invocation tests
• CloudWatch Integration: Logging and monitoring support

🎨 Custom GitHub Action

• Reusable Component: Example action demonstrating best practices
• Input Validation: Proper parameter handling and validation
• Output Generation: Structured outputs for subsequent steps
• Error Handling: Comprehensive error management
• Documentation: Inline comments and usage examples

📁 Project Structure

github-actions/
├── .github/
│   ├── actions/
│   │   └── hello-action/          # Custom GitHub Action
│   │       ├── action.yml         # Action metadata
│   │       ├── index.js           # Action implementation
│   │       └── package.json       # Action dependencies
│   └── workflows/
│       ├── ci.yml                 # Continuous Integration
│       ├── docker.yml             # Docker build and push
│       ├── release.yml            # Semantic release
│       ├── deploy-lambda.yml      # AWS Lambda deployment
│       └── pr-checks.yml          # Pull request validation
├── examples/
│   ├── node-app/                  # Node.js Express application
│   │   ├── server.js              # Express server
│   │   ├── test.js                # Test suite
│   │   ├── worker.js              # Worker thread
│   │   ├── Dockerfile             # Multi-stage Docker build
│   │   └── package.json           # App dependencies
│   └── lambda-function/           # AWS Lambda function
│       ├── lambda_function.py     # Lambda handler
│       └── requirements.txt       # Python dependencies
├── package.json                   # Root package.json
├── release.config.js              # Semantic release config
├── .commitlintrc.json             # Commit message linting
├── .gitignore                     # Git ignore rules
└── README.md                      # This file

🚀 Getting Started

Prerequisites

• Node.js: v18+ and npm v9+
• Docker: For building and running containers
• AWS CLI: For Lambda deployment (optional)
• Git: For version control

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/github-actions.git
   cd github-actions

2. Install dependencies:

   npm run install:all

3. Set up Git hooks (optional):

   npm run prepare

Local Development

Run the Node.js Application

cd examples/node-app
npm install
npm start

Visit http://localhost:8000 to see the application.

Test the Lambda Function

cd examples/lambda-function
python3 lambda_function.py

Test the Custom Action

cd .github/actions/hello-action
npm install
node index.js

🔧 Workflows

1. CI Pipeline (ci.yml)

Triggers: Push to main/develop, Pull requests

Jobs:

• Code quality checks (linting, formatting)
• Security scanning (npm audit, CodeQL)
• Matrix builds (Node 18, 20, 21 × Ubuntu, Windows, macOS)
• Custom action testing
• Build summary generation

Usage:

# Automatically runs on push and PR
# Manual trigger from Actions tab

2. Docker Build & Push (docker.yml)

Triggers: Push to main, Version tags

Jobs:

• Build Docker image with BuildKit caching
• Run container tests
• Vulnerability scanning with Trivy
• Multi-platform build (amd64, arm64)
• Push to Docker Hub and GHCR

Usage:

# Triggered automatically on push to main
# Or manually trigger from Actions tab

3. Semantic Release (release.yml)

Triggers: Push to main branch

Jobs:

• Validate commit messages
• Analyze commits for version bump
• Generate changelog
• Create GitHub release
• Update package.json versions
• Trigger downstream workflows

Commit Convention:

feat: add new feature        # Minor version bump
fix: resolve bug             # Patch version bump
feat!: breaking change       # Major version bump
docs: update documentation   # No release
chore: maintenance task      # No release

Usage:

# Make commits following conventional format
git commit -m "feat: add user authentication"
git push origin main
# Release is automatically created

4. Lambda Deployment (deploy-lambda.yml)

Triggers: Push to main, Manual dispatch

Jobs:

• Validate Python code (linting)
• Create deployment package
• Deploy to AWS Lambda
• Run post-deployment tests
• Check CloudWatch logs

Usage:

# Manual deployment with environment selection
# Go to Actions → Deploy to AWS Lambda → Run workflow
# Select environment: development, staging, or production

Prerequisites:

• Set AWS_ACCESS_KEY_ID secret
• Set AWS_SECRET_ACCESS_KEY secret
• Lambda function must exist in AWS

5. PR Validation (pr-checks.yml)

Triggers: Pull request events

Jobs:

• Auto-label PRs by size and type
• Check PR title format
• Code quality checks
• Secret scanning
• Test execution
• Generate PR summary

Usage:

# Automatically runs on PR creation/update
# No manual intervention needed

🎭 Custom Actions

Hello Action

A demonstration action showing best practices for custom action development.

Inputs:

• who-to-greet: Name of person to greet (default: "World")
• greeting-style: Style of greeting (formal/casual/enthusiastic)
• include-timestamp: Whether to include timestamp

Outputs:

• message: Complete greeting message
• timestamp: ISO 8601 timestamp
• greeted-person: Name of greeted person

Usage:

- name: Use custom action
  uses: ./.github/actions/hello-action
  with:
    who-to-greet: 'GitHub Actions Expert'
    greeting-style: 'enthusiastic'
    include-timestamp: 'true'

📱 Example Applications

Node.js Express Server

A production-ready Express.js application featuring:

• Health check endpoints (/health, /ready)
• Metrics endpoint (/metrics)
• Worker thread support (/heavy)
• Graceful shutdown handling
• Request logging
• Error handling

Endpoints:

• GET / - Application info
• GET /health - Health check
• GET /ready - Readiness check
• GET /metrics - Application metrics
• GET /heavy - CPU-intensive task demo

AWS Lambda Function

A well-structured Lambda function demonstrating:

• Input validation
• Error handling
• Structured logging
• CloudWatch integration
• Type hints
• Local testing support

Handler: lambda_handler Runtime: Python 3.11+

📊 Semantic Versioning

This project uses semantic-release for automated version management.

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Types

Type	Description	Version Bump
feat	New feature	Minor (0.x.0)
fix	Bug fix	Patch (0.0.x)
feat!	Breaking change	Major (x.0.0)
perf	Performance improvement	Patch
refactor	Code refactoring	Patch
docs	Documentation	None
test	Tests	None
chore	Maintenance	None
ci	CI/CD changes	None

Examples

# Feature (minor bump)
git commit -m "feat: add user authentication"

# Bug fix (patch bump)
git commit -m "fix: resolve login error"

# Breaking change (major bump)
git commit -m "feat!: migrate to new API

BREAKING CHANGE: The API has been completely redesigned"

# Documentation (no release)
git commit -m "docs: update installation guide"

🏆 Best Practices

Workflow Design

✅ DO:

• Use matrix builds for multiple versions/platforms
• Cache dependencies for faster builds
• Use specific action versions (@v4, not @main)
• Set minimal required permissions
• Fail fast on critical errors
• Use environment-specific configurations

❌ DON'T:

• Hardcode secrets in workflows
• Use @latest or @main for actions in production
• Grant excessive permissions
• Skip security checks
• Ignore linter warnings

Docker Best Practices

✅ DO:

• Use multi-stage builds
• Run as non-root user
• Use specific base image tags
• Implement health checks
• Scan for vulnerabilities
• Minimize layer count

❌ DON'T:

• Use latest tag in production
• Run as root user
• Include secrets in images
• Copy unnecessary files
• Ignore security warnings

Security

✅ DO:

• Use GitHub secrets for sensitive data
• Enable Dependabot
• Run security scans (CodeQL, Trivy)
• Use OIDC for AWS authentication (when possible)
• Rotate credentials regularly
• Review and audit third-party actions

❌ DON'T:

• Commit secrets to repository
• Use personal access tokens unnecessarily
• Skip vulnerability scans
• Ignore security alerts
• Use untrusted third-party actions

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feat/amazing-feature
3. Make your changes
4. Commit using conventional format: git commit -m "feat: add amazing feature"
5. Push to your fork: git push origin feat/amazing-feature
6. Open a Pull Request

Commit Message Guidelines

Please follow the Conventional Commits specification. Use npm run commit to use the interactive commit tool.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

This project consolidates learning from multiple GitHub Actions experiments and incorporates best practices from:

• GitHub Actions documentation
• Docker best practices
• AWS Lambda development guidelines
• Semantic release community
• Open source CI/CD patterns

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: See workflow files for inline documentation

🔗 Resources

• GitHub Actions Documentation
• Semantic Release Documentation
• Docker Best Practices
• AWS Lambda Documentation
• Conventional Commits

---

Built with ❤️ for the DevOps community

If you find this project helpful, please consider giving it a ⭐ on GitHub!