Skip to content

Build Release Process

Jump to bottom
github-actions[bot] edited this page Mar 14, 2026 · 1 revision

Build & Release Process

This page documents the Go build process and automated release workflow for wikigen. The project uses GitHub Actions to cross-compile a single Go binary for multiple platforms (Linux, macOS, Windows) and create GitHub releases with compiled binaries. This is the authoritative source for understanding how wikigen is built, packaged, and distributed to users.

Local Build

Building wikigen locally is straightforward. The project is a single-file Go application with minimal dependencies, allowing for a simple build command:

go build -o wikigen .

The build produces a binary named wikigen in the current directory. For development, no special build flags are required. However, the official release workflow applies additional flags for optimization and size reduction, as described in the Release Workflow section.

Prerequisites

The build process requires Go 1.22 or later. The go.mod file specifies Go 1.25.7, ensuring compatibility with recent Go versions.

Sources: wikigen/go.mod:3, wikigen/.repos/tomohiro-owada_wikigen/.github/workflows/release.yml:38

Release Workflow

The release process is fully automated through GitHub Actions and triggered by pushing a version tag (format: v*) to the repository. The workflow defined in release.yml handles multi-platform compilation, binary optimization, artifact management, and GitHub release creation.

Workflow Trigger

The release workflow activates on push events matching the tag pattern v*:

on:
  push:
    tags:
      - 'v*'

To trigger a release, create and push a version tag:

git tag v1.0.0
git push origin v1.0.0

Sources: wikigen/.github/workflows/release.yml:3-6

Platform Support Matrix

The release workflow builds wikigen for five platform/architecture combinations. Each platform is built in parallel using GitHub Actions matrix strategy:

Platform GOOS GOARCH Binary Suffix Target Environment
Linux x86-64 linux amd64 linux-amd64 Intel/AMD 64-bit systems
Linux ARM64 linux arm64 linux-arm64 ARM 64-bit systems (cloud instances, single-board computers)
macOS Intel darwin amd64 darwin-amd64 Intel-based Mac systems
macOS ARM64 darwin arm64 darwin-arm64 Apple Silicon Macs (M1, M2, M3, etc.)
Windows x86-64 windows amd64 windows-amd64.exe Windows 64-bit systems

Sources: wikigen/.github/workflows/release.yml:14-31

Cross-Compilation

Cross-compilation is achieved by setting the GOOS (operating system) and GOARCH (architecture) environment variables before invoking the Go compiler. These variables tell the Go toolchain to compile for a target platform different from the build host (which is Ubuntu Linux in the GitHub Actions environment).

The build command uses these environment variables:

go build -ldflags="-s -w" -o wikigen-${{ matrix.suffix }} .

The ${{ matrix.goos }} and ${{ matrix.goarch }} values are injected as environment variables:

env:
  GOOS: ${{ matrix.goos }}
  GOARCH: ${{ matrix.goarch }}

This allows a single Ubuntu runner to produce native binaries for all supported platforms without requiring separate build hosts.

Sources: wikigen/.github/workflows/release.yml:40-45

Binary Stripping and Optimization

The release build applies aggressive linker flags to reduce binary size:

go build -ldflags="-s -w" ...

These flags serve the following purposes:

  • -s: Strips the symbol table from the binary. Removes all symbol information, reducing binary size at the cost of losing debugging information.
  • -w: Strips the DWARF debugging information. Eliminates detailed debug symbols, further reducing file size.

The combined effect reduces the final binary by approximately 35-45%, making distribution and download faster for end users. This optimization is only applied to official releases, not development builds.

Sources: wikigen/.github/workflows/release.yml:45

Multi-Stage Build Architecture

The release workflow uses a two-job architecture: a parallel build stage and a sequential release stage. This separation allows for efficient compilation and automatic release creation.

flowchart TD
    A["Workflow Triggered<br/>Tag pushed: v*"] --> B["Build Job<br/>runs-on: ubuntu-latest"]
    B --> C["Matrix Strategy<br/>5 platform/architecture<br/>combinations"]
    C --> D["Build Step 1<br/>Linux amd64"]
    C --> E["Build Step 2<br/>Linux arm64"]
    C --> F["Build Step 3<br/>macOS amd64"]
    C --> G["Build Step 4<br/>macOS arm64"]
    C --> H["Build Step 5<br/>Windows amd64"]
    D --> I["Upload Artifacts"]
    E --> I
    F --> I
    G --> I
    H --> I
    I --> J["Release Job<br/>needs: build"]
    J --> K["Download All Artifacts"]
    K --> L["Create GitHub Release<br/>with all binaries"]
    L --> M["Release Published<br/>with generated notes"]
Loading

Artifact Management

Each compiled binary is uploaded to GitHub Actions artifacts with a unique name:

- uses: actions/upload-artifact@v4
  with:
    name: wikigen-${{ matrix.suffix }}
    path: wikigen-${{ matrix.suffix }}

The artifact name includes the platform and architecture suffix (e.g., wikigen-linux-amd64, wikigen-windows-amd64.exe), allowing the subsequent release job to identify and download all binaries.

Sources: wikigen/.github/workflows/release.yml:47-50

GitHub Release Creation

After all platform builds complete, the release job downloads all artifacts and creates a GitHub release using the softprops/action-gh-release@v2 action:

- name: Create Release
  uses: softprops/action-gh-release@v2
  with:
    generate_release_notes: true
    files: artifacts/wikigen-*

The release configuration includes:

  • generate_release_notes: true: Automatically generates release notes from commit messages and pull requests since the last release.
  • files: artifacts/wikigen-*: Includes all compiled binaries as release assets, making them available for download from the GitHub release page.

Sources: wikigen/.github/workflows/release.yml:61-65

Permissions and Security

The release workflow requires write permissions to the repository contents:

permissions:
  contents: write

This permission allows the workflow to create releases and upload artifacts. The workflow does not require external authentication beyond the default GitHub Actions token provided by the platform.

Sources: wikigen/.github/workflows/release.yml:8-9

Release Workflow Sequence

The complete release process follows this sequence:

sequenceDiagram
    participant Developer
    participant Git as Git Repository
    participant GHA as GitHub Actions
    participant Artifacts as Artifact Storage
    participant Release as GitHub Release

    Developer->>Git: Create and push tag v*
    Git->>GHA: Trigger release workflow
    GHA->>GHA: Checkout code
    GHA->>GHA: Setup Go 1.22
    par Build Parallel
        GHA->>GHA: Compile Linux amd64
        GHA->>GHA: Compile Linux arm64
        GHA->>GHA: Compile macOS amd64
        GHA->>GHA: Compile macOS arm64
        GHA->>GHA: Compile Windows amd64
    and Artifact Upload
        GHA->>Artifacts: Upload linux-amd64
        GHA->>Artifacts: Upload linux-arm64
        GHA->>Artifacts: Upload darwin-amd64
        GHA->>Artifacts: Upload darwin-arm64
        GHA->>Artifacts: Upload windows-amd64.exe
    end
    GHA->>Artifacts: Download all artifacts
    GHA->>Release: Create release with binaries
    Release->>Developer: Release published with downloads
Loading

Integration with Local Installation

The binaries produced by the release workflow can be manually downloaded and installed from the GitHub release page or used in CI/CD pipelines. For system-wide installation on Unix-like systems:

# Download the appropriate binary for your platform
curl -LO https://github.com/tomohiro-owada/wikigen/releases/download/v1.0.0/wikigen-linux-amd64
chmod +x wikigen-linux-amd64
sudo mv wikigen-linux-amd64 /usr/local/bin/wikigen

Users can also build from source using the local build command if they prefer.

Development vs Release Builds

The key differences between development and release builds:

Aspect Development Build Release Build
Command go build . go build -ldflags="-s -w" -o wikigen-PLATFORM .
Binary Size Larger (includes debug symbols) Smaller (~35-45% reduction)
Debug Info Full DWARF debugging information Stripped for size
Platforms Current platform only Five platforms (Linux amd64/arm64, macOS amd64/arm64, Windows amd64)
Distribution Not distributed Published to GitHub Releases
Cross-Compilation Not used GOOS/GOARCH environment variables

Related Pages

  • Installation & Setup — Detailed build instructions and environment configuration for local development and deployment.
  • GitHub Actions Integration — Automated wiki generation workflow and CI/CD pipeline configuration, complementary to the release process.
  • System Overview — Project architecture and core capabilities that depend on the binary produced by this build process.
  • CLI Usage & Commands — Command-line interface reference for the compiled binary, describing all available flags and options.
  • Architecture & Design — High-level system design showing how the compiled binary fits into the larger application workflow.

Home

Clone this wiki locally