GitHub Actions Setup for InfraNotes Gateway

This document explains how to set up GitHub Actions for automated building, testing, and deployment of the InfraNotes API Gateway.

🚀 Workflow Overview

The GitHub Actions workflow (build-and-deploy.yml) provides:

Automated Versioning: Semantic versioning based on commit messages
Comprehensive Testing: Unit tests, linting, security scans
Docker Image Building: Multi-stage builds with optimization
Automated Releases: GitHub releases with changelogs
Docker Hub Publishing: Automated image publishing

🔧 Required Secrets

Configure these secrets in your GitHub repository settings:

Docker Hub Credentials

DOCKER_USERNAME: your-dockerhub-username
DOCKERHUB_TOKEN: your-dockerhub-access-token

To create a Docker Hub access token:

Go to Docker Hub Account Settings
Click "New Access Token"
Name it "GitHub Actions"
Copy the token and add it as DOCKERHUB_TOKEN secret

📋 Workflow Triggers

The workflow runs on:

Push to main/develop: Full build and deploy pipeline
Pull Requests: Testing and validation only
Manual Trigger: Via GitHub Actions UI (workflow_dispatch)

Paths Ignored

These file changes won't trigger the workflow:

**.md files (documentation)
docs/** directory
Project documentation files (progress.md, PRD.md, etc.)

🏷️ Semantic Versioning

Version bumps are determined by commit message patterns:

Commit Pattern	Version Bump	Example
`BREAKING CHANGE:` or `breaking:`	Major (1.0.0 → 2.0.0)	`breaking: remove deprecated API`
`feat:` or `feature:` or `add:` or `implement:`	Minor (1.0.0 → 1.1.0)	`feat: add rate limiting`
`fix:` or `Fix` or `deployment` or `docker` or `bug`	Patch (1.0.0 → 1.0.1)	`fix: memory leak in proxy`

Initial Version

First build starts at v1.0.0
Subsequent versions follow semantic versioning rules

🧪 Testing Pipeline

The workflow includes comprehensive testing:

1. Code Quality Checks

go vet - Static analysis
gofmt - Code formatting validation
staticcheck - Advanced static analysis

2. Security Scanning

gosec - Security vulnerability scanning
SARIF results uploaded to GitHub Security tab

3. Unit Tests

Test execution with race detection
Coverage report generation
Codecov integration (optional)

4. Integration Tests

Redis and NATS services available during tests
Real dependency integration testing

🐳 Docker Image Building

Build Features

Multi-stage builds for minimal image size
Version injection via build arguments
Build caching for faster builds
Security hardening with non-root user
Comprehensive labels for metadata

Image Tags

Images are tagged with:

latest (main branch only)
v{version} (semantic version)
{branch-name} (feature branches)
pr-{number} (pull requests)

Build Arguments

The following are injected during build:

VERSION: Git tag version
COMMIT_SHA: Git commit SHA
BUILD_DATE: Build timestamp

📦 Release Process

Automatic Releases

When code is pushed to main and version changes:

Changelog Generation: Creates/updates CHANGELOG.md
Git Tagging: Creates annotated git tag
GitHub Release: Creates release with notes
Docker Publishing: Pushes to Docker Hub

Release Notes

Auto-generated release notes include:

Change summary from commits
Docker pull command
Quick start instructions
Documentation links

🔄 Workflow Jobs

1. Version Job

Determines if version should be bumped
Generates changelog content
Outputs version information for other jobs

2. Test Job

Runs all quality checks and tests
Uses service containers for dependencies
Generates coverage reports

3. Security Job

Runs security vulnerability scans
Uploads results to GitHub Security

4. Build Job

Builds and pushes Docker images
Only runs if version changed or manually triggered
Uses Docker Buildx for advanced features

5. Release Job

Creates GitHub releases
Updates changelog
Only runs on main branch with version changes

6. Notify Job

Provides deployment success notification
Displays important links and information

🛠️ Local Testing

Test the workflow components locally:

# Run tests like CI
make test

# Build Docker image
make docker-build

# Check formatting
make fmt

# Run security scan
make security-scan

# Test version injection
go run -ldflags="-X main.version=v1.2.3" cmd/gateway/main.go --version

🔍 Troubleshooting

Common Issues

Test Failures: Ensure all tests pass locally before pushing
Docker Login: Verify Docker Hub credentials are correct
Permission Errors: Ensure GITHUB_TOKEN has proper permissions
Version Not Bumping: Check commit message format

Debug Information

The workflow provides debug output for:

Commit message analysis
Version bump decisions
Tag creation process

Manual Workflow Trigger

Use GitHub UI to trigger workflow manually:

Go to Actions tab
Select "Build and Publish InfraNotes Gateway"
Click "Run workflow"
Choose branch and click "Run workflow"

📊 Monitoring

Monitor workflow execution:

GitHub Actions: View build logs and status
Docker Hub: Check image builds and pulls
GitHub Releases: Track version releases
Security Tab: Review security scan results

🎯 Best Practices

Commit Messages: Use conventional commit format
Branch Protection: Require status checks on main branch
Secret Rotation: Regularly rotate Docker Hub tokens
Dependency Updates: Keep GitHub Actions up to date
Testing: Ensure comprehensive test coverage

Welcome