CI/CD Documentation

This NixOS template includes comprehensive CI/CD workflows for automated code validation, formatting, and release management. All workflows are fully functional and pass validation for NixOS 26.05 compatibility.

GitHub Actions Workflows

1. Continuous Integration (ci.yml)

Runs on every push and pull request to validate code quality and functionality.

Jobs (All Passing):

Triggers:

2. Auto Format (format.yml)

Automatically formats code and commits changes.

Features:

Triggers:

3. Release Management (release.yml)

Automates release creation with comprehensive validation.

Features:

Triggers:

Pre-commit Hooks

Automated code quality checks that run before each commit.

Local Setup

# Install pre-commit hooks
just install-hooks

# Run hooks manually on all files
just run-hooks

# Update hook versions
just update-hooks

Included Hooks

Nix Code Quality:

Shell Scripts:

General:

Local Development Commands

Code Quality

# Run full validation suite
just validate

# Check code formatting without changes
just format-check

# Format all code
just fmt

# Lint Nix code
just lint

# Check for dead code
just dead-code-check

# Fix dead code automatically
just dead-code-fix

# Run security audit
just security-audit

# Full code quality suite
just quality

CI/CD Commands

# Run full CI validation locally
just ci-validate

# Prepare a release
just prepare-release v1.0.0

# Run security checks
just security-check

# Set up development environment
just dev-setup

Pre-commit Management

# Install pre-commit hooks
just install-hooks

# Run all pre-commit hooks
just run-hooks

# Test pre-commit hooks
just test-hooks

# Update pre-commit hook versions
just update-hooks

Validation Pipeline

1. Pre-commit Stage

2. CI Stage (GitHub Actions)

3. Release Stage

Configuration Files

.pre-commit-config.yaml

Pre-commit hook configuration with all quality checks.

.markdownlint.json

Markdown linting rules for documentation consistency.

.gitignore

Excludes build artifacts, secrets, and local configuration files.

Workflow Configuration Files

Recent Improvements

NixOS 26.05 Compatibility (Latest Update)

All deprecation warnings resolved:

Syntax Error Fixes:

Enhanced Validation:

Quality Standards

Code Formatting

Linting Rules

Security Checks

Integration with IDEs

VS Code

Install recommended extensions:

Vim/Neovim

Configure with appropriate language servers:

Troubleshooting

Pre-commit Hook Failures

# Skip hooks for emergency commits (use sparingly)
git commit --no-verify -m "emergency fix"

# Fix formatting issues
just fmt

# Check what failed
pre-commit run --all-files

CI Failures

# Run CI validation locally
just ci-validate

# Check specific validation
just validate
just lint
just security-check

Release Issues

# Validate before creating release
just prepare-release v1.0.0

# Check tag format
git tag --list | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$'

Best Practices

Development Workflow

  1. Start Development

    just dev-setup
  2. Make Changes
    • Edit configuration files
    • Add new features
    • Update documentation

  3. Validate Changes

    just validate
just test

  4. Commit Changes

    git add .
git commit -m "feature: add new functionality"
# Pre-commit hooks run automatically

  5. Push Changes

    git push origin feature-branch
# CI runs automatically on PR

Release Process

  1. Prepare Release

    just prepare-release v1.0.0

  2. Push Tag

    git push origin v1.0.0

  3. Automated Release

    • GitHub Actions creates release
    • Changelog generated automatically
    • Documentation assets included

Code Review Guidelines

Monitoring and Metrics

CI Metrics

Code Quality Metrics

Release Metrics

This comprehensive CI/CD system ensures high code quality, security, and reliability for the NixOS template while providing excellent developer experience.