Skip to content

Customization Guide

This guide covers advanced customization options for Rhiza-Go-based projects.

🛠️ Makefile Hooks & Extensions

Rhiza uses a modular Makefile system with extension points (hooks) that let you customize workflows without modifying core files.

Important: All customizations should be made in your root Makefile, not in .rhiza/. The .rhiza/ directory is template-managed and will be overwritten during sync operations.

Available Hooks

You can hook into standard workflows using double-colon syntax (::) in your root Makefile:

  • pre-install / post-install - Runs around make install
  • pre-sync / post-sync - Runs around repository synchronization
  • pre-validate / post-validate - Runs around validation checks
  • pre-release / post-release - Runs around release process
  • pre-bump / post-bump - Runs around version bumping

Example: Installing System Dependencies

Add to your root Makefile (before the include .rhiza/rhiza.mk line):

pre-install::
    @if ! command -v dot >/dev/null 2>&1; then \
        echo "Installing graphviz..."; \
        sudo apt-get update && sudo apt-get install -y graphviz; \
    fi

This hook runs automatically before make install, ensuring graphviz is available.

Example: Post-Release Tasks

Add to your root Makefile:

post-release::
    @echo "Running post-release tasks..."
    @./scripts/notify-team.sh
    @./scripts/update-changelog.sh

This runs automatically after make release completes.

Example: Custom Build Steps

Add to your root Makefile:

post-install::
    @echo "Installing additional Go tools..."
    @go install github.com/securego/gosec/v2/cmd/gosec@latest

##@ Custom Tasks
generate: ## Run code generation
    @go generate ./...

🔒 CodeQL Configuration

The CodeQL workflow (.github/workflows/rhiza_codeql.yml) performs security analysis on your code. However, CodeQL requires GitHub Advanced Security, which is:

  • ✅ Available for free on public repositories
  • ⚠️ Requires GitHub Enterprise license for private repositories

Automatic Behavior

By default, the CodeQL workflow: - Runs automatically on public repositories - Skips automatically on private repositories (unless you have Advanced Security)

Controlling CodeQL

You can override the default behavior using a repository variable:

  1. Go to your repository → Settings → Secrets and variables → Actions → Variables tab
  2. Create a new repository variable named CODEQL_ENABLED
  3. Set the value:
  4. true - Force CodeQL to run (use if you have Advanced Security on a private repo)
  5. false - Disable CodeQL entirely (e.g., if it's causing issues)

For Private Repositories with Advanced Security

If you have a GitHub Enterprise license with Advanced Security enabled:

# Enable CodeQL for your private repository
gh variable set CODEQL_ENABLED --body "true"

For Users Without Advanced Security

No action needed! The workflow will automatically skip for private repositories. If you want to completely disable it:

# Disable CodeQL workflow
gh variable set CODEQL_ENABLED --body "false"

Or delete the workflow file:

# Remove CodeQL workflow
git rm .github/workflows/rhiza_codeql.yml
git commit -m "Remove CodeQL workflow"

⚙️ Configuration Variables

You can configure certain aspects of the Makefile by overriding variables. These can be set in your main Makefile (before the include line), a local.mk file (for local developer overrides), or passed as environment variables / command-line arguments.

Global Configuration

Add these to your root Makefile (before include .rhiza/rhiza.mk) or local.mk:

# Override test coverage threshold (default: 90)
COVERAGE_FAIL_UNDER = 80

# Include the Rhiza API (template-managed)
include .rhiza/rhiza.mk

On-Demand Configuration

You can also pass variables directly to make for one-off commands:

# Run tests requiring only 80% coverage
make test COVERAGE_FAIL_UNDER=80

🎨 Documentation Customization

API Reference (GO_REPO_PRIVATE)

The API Reference page (docs/API.md) is generated by make docs and always appears in the MkDocs navigation. How it is generated depends on whether your repository is public or private.

Public repositories (default, GO_REPO_PRIVATE = false):

make docs generates a link page pointing to pkg.go.dev, which indexes public modules automatically and provides the canonical Go documentation experience.

Private repositories (GO_REPO_PRIVATE = true):

make docs runs gomarkdoc to generate fully inline API documentation embedded directly into docs/API.md. This is rendered as a static page in the MkDocs build, so it works on GitHub Pages and any static host without requiring pkg.go.dev access.

Set the variable in your root Makefile or local.mk:

# Makefile (committed — applies to all contributors)
GO_REPO_PRIVATE = true

include .rhiza/rhiza.mk

# local.mk (not committed — for local developer overrides only)
GO_REPO_PRIVATE = true

Or pass it ad hoc:

make docs GO_REPO_PRIVATE=true

In both modes, make docs-serve starts a local pkgsite server at http://localhost:6060 for interactive browsing.

Official Docs (OFFICIAL_DOCS_URL)

You can surface a link to your project's official hosted documentation site in the make book navigation bar.

Set OFFICIAL_DOCS_URL in your root Makefile or local.mk:

OFFICIAL_DOCS_URL = https://your-project.example.com

When set, the book's navigation will include an Official Docs link pointing to that URL alongside the API Reference, Test Report, and Coverage links.

To also add it to the MkDocs site navigation, edit docs/mkdocs.yml and uncomment the placeholder:

nav:
  - Home: index.md
  - API Reference: API.md
  - Official Docs: https://your-project.example.com
  ...

The documentation includes a logo. You can override the default logo by setting the LOGO_FILE variable in your Makefile or local.mk:

LOGO_FILE := assets/my-custom-logo.png

📖 Complete Documentation

For detailed information about extending and customizing the Makefile system, see .rhiza/make.d/README.md.