🚀 Example Workflows

Ready-to-use GitHub Actions workflows that leverage all CI tools in parallel

🎯 Overview

These example workflows demonstrate how to use the general CI tools in your consumer repositories. Each workflow is designed for different use cases and can be customized to fit your project’s needs.

Key Features

  • 🔄 Parallel Execution - Multiple jobs run simultaneously for maximum efficiency
  • 🛡️ Comprehensive Coverage - Lint, static analysis, documentation, and link checking
  • 📊 Smart Caching - Optimized dependency installation with built-in caching
  • 🎯 General Purpose - Designed for C/C++ projects with documentation

🏗️ Basic Workflow

Use Case: Simple projects that need basic CI/CD with lint and documentation checks.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

name: 🏗️ Basic CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  # Lint C/C++ code
  lint:
    uses: N3b3x/hf-general-ci-tools/.github/workflows/c-cpp-lint.yml@v1
    with:
      clang_version: "20"
      style: "file"
      extensions: "c,cpp,h,hpp"

  # Static analysis
  static:
    uses: N3b3x/hf-general-ci-tools/.github/workflows/c-cpp-static-analysis.yml@v1
    with:
      paths: "src include"
      std: "c++17"
      strict: false

  # Check documentation links
  docs-links:
    uses: N3b3x/hf-general-ci-tools/.github/workflows/docs-link-check.yml@v1
    with:
      paths: "docs/** *.md **/docs/**"

🚀 Advanced Parallel Workflow

Use Case: Production projects requiring comprehensive CI/CD with all checks running in parallel.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

name: 🚀 Advanced CI

on:
  push:
    branches: [main, develop, release/*]
  pull_request:
    branches: [main, develop]
  workflow_dispatch:
    inputs:
      run_strict_checks:
        description: 'Run strict static analysis'
        required: false
        default: false
        type: boolean

jobs:
  # C/C++ Linting
  lint:
    uses: N3b3x/hf-general-ci-tools/.github/workflows/c-cpp-lint.yml@v1
    with:
      clang_version: "20"
      style: "file"
      tidy_checks: "performance-*,modernize-*,readability-*"
      extensions: "c,cpp,cc,cxx,h,hpp"
      ignore: "build|.git|third_party"
      files_changed_only: true

  # Static Analysis
  static-analysis:
    uses: N3b3x/hf-general-ci-tools/.github/workflows/c-cpp-static-analysis.yml@v1
    with:
      paths: "src include examples"
      std: "c++17"
      strict: $

  # Documentation Generation
  docs:
    uses: N3b3x/hf-general-ci-tools/.github/workflows/docs.yml@v1
    with:
      doxygen_config: "Doxyfile"
      run_link_check: true
      link_check_paths: "docs/** *.md **/docs/**"
      jekyll_enabled: true
      jekyll_config: "_config.yml,_config_prod.yml"
      jekyll_environment: "production"

  # YAML Linting
  yaml-lint:
    uses: N3b3x/hf-general-ci-tools/.github/workflows/yamllint-reusable.yml@v1
    with:
      paths: "**/*.yml,**/*.yaml"
      strict_mode: false

  # Link Checking
  link-check:
    uses: N3b3x/hf-general-ci-tools/.github/workflows/docs-link-check.yml@v1
    with:
      paths: "docs/** *.md **/docs/**"
      fail_on_errors: true
      timeout: "30"

🔧 Development Workflow

Use Case: Development branches with relaxed checks and draft documentation.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

name: 🔧 Development CI

on:
  push:
    branches: [develop, feature/*]
  pull_request:
    branches: [develop]

jobs:
  # Quick lint check
  lint:
    uses: N3b3x/hf-general-ci-tools/.github/workflows/c-cpp-lint.yml@v1
    with:
      clang_version: "20"
      style: "file"
      files_changed_only: true

  # Documentation with drafts
  docs:
    uses: N3b3x/hf-general-ci-tools/.github/workflows/docs.yml@v1
    with:
      doxygen_config: "Doxyfile"
      run_link_check: false
      jekyll_enabled: true
      jekyll_config: "_config.yml,_config_dev.yml"
      jekyll_environment: "development"
      jekyll_drafts: true
      jekyll_future: true

📦 Release Workflow

Use Case: Release branches with strict checks and production documentation.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

name: 📦 Release CI

on:
  push:
    branches: [release/*]
  workflow_dispatch:
    inputs:
      release_version:
        description: 'Release version tag'
        required: true
        type: string

jobs:
  # Strict linting
  lint:
    uses: N3b3x/hf-general-ci-tools/.github/workflows/c-cpp-lint.yml@v1
    with:
      clang_version: "20"
      style: "file"
      tidy_checks: "performance-*,modernize-*,readability-*,bugprone-*"
      extensions: "c,cpp,cc,cxx,h,hpp"
      ignore: "build|.git"
      files_changed_only: false

  # Strict static analysis
  static-analysis:
    uses: N3b3x/hf-general-ci-tools/.github/workflows/c-cpp-static-analysis.yml@v1
    with:
      paths: "src include examples"
      std: "c++17"
      strict: true

  # Production documentation
  docs:
    uses: N3b3x/hf-general-ci-tools/.github/workflows/docs.yml@v1
    with:
      doxygen_config: "Doxyfile"
      run_link_check: true
      link_check_paths: "docs/** *.md **/docs/**"
      jekyll_enabled: true
      jekyll_config: "_config.yml,_config_prod.yml"
      jekyll_environment: "production"

  # Comprehensive link checking
  link-check:
    uses: N3b3x/hf-general-ci-tools/.github/workflows/docs-link-check.yml@v1
    with:
      paths: "docs/** *.md **/docs/**"
      fail_on_errors: true
      timeout: "60"

  # YAML validation
  yaml-lint:
    uses: N3b3x/hf-general-ci-tools/.github/workflows/yamllint-reusable.yml@v1
    with:
      paths: "**/*.yml,**/*.yaml"
      strict_mode: true

📚 Submodule Documentation Workflow

Use Case: Projects with documentation stored in submodules or external repositories.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

name: 📚 Submodule Documentation CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  # Documentation with submodule support
  docs:
    uses: N3b3x/hf-general-ci-tools/.github/workflows/docs.yml@v1
    with:
      checkout_recursive: true  # Enable submodule checkout
      doxygen_config: "Doxyfile"
      run_link_check: true
      link_check_paths: "docs/** *.md **/docs/**"
      jekyll_enabled: true
      jekyll_source: "docs"
      jekyll_config: "_config.yml"
      run_markdown_lint: true
      markdown_lint_paths: "docs/** *.md"
      run_spell_check: true
      spell_check_paths: "docs/** *.md"

  # Link checking for submodule content
  link-check:
    uses: N3b3x/hf-general-ci-tools/.github/workflows/docs-link-check.yml@v1
    with:
      paths: "docs/** *.md **/docs/**"
      fail_on_errors: true
      timeout: "30"

🎯 Workflow Selection Guide

Use Case Recommended Workflow Key Features
Simple Projects Basic Workflow Essential linting and link checking
Production Projects Advanced Parallel Comprehensive checks with parallel execution
Development Development Workflow Relaxed checks with draft support
Releases Release Workflow Strict checks with production documentation
Submodule Projects Submodule Documentation Recursive checkout with comprehensive docs

🔧 Customization Tips

Parallel vs Sequential

  • Use parallel jobs for faster execution
  • Use sequential jobs when dependencies exist

Conditional Execution 

1
2
3
4
5

# Only run on specific branches
if: github.ref == 'refs/heads/main'

# Only run when files change
if: contains(github.event.head_commit.modified, 'src/')

Matrix Strategies 

1
2
3
4
5
6
7
8

strategy:
  matrix:
    clang_version: [18, 19, 20]
    include:
      - clang_version: 20
        std: c++20
      - clang_version: 19
        std: c++17

Submodule Configuration 

1
2
3
4
5

# Enable submodule checkout for documentation projects
checkout_recursive: true

# Only when documentation is in submodules
# Disable for performance if not needed

Caching 

1
2
3
4
5
6
7
8
9
10
11

# Note: The reusable workflows handle their own optimized caching
# No additional caching needed for Doxygen/Graphviz dependencies

# For custom dependencies, you can still add caching:
- name: Cache custom dependencies
  uses: actions/cache@v3
  with:
    path: |
      ~/.cache/ccache
      build/
    key: $-$

← Previous: Jekyll Configuration Guide

📚 All Documentation 🏠 Main README

For more detailed configuration options, see the individual workflow documentation pages.