This document describes the automated build and release pipeline for g4f, including the GitHub Actions workflows that build multi-platform executables, Docker images, Python packages, and create releases. The pipeline handles version management, artifact creation, and distribution across multiple package managers and platforms.
For deployment configuration and environment setup, see Environment Configuration. For package distribution details including PyPI and WinGet, see Package Distribution.
The build pipeline is implemented as GitHub Actions workflows that execute on tagged releases or manual triggers. The system builds five primary artifact types: PyPI packages, Windows/Linux/macOS executables, Docker images, WinGet manifests, and GitHub releases.
Sources: .github/workflows/build-packages.yml1-490
Diagram: Complete Build and Release Workflow
Sources: .github/workflows/build-packages.yml3-37 .github/workflows/build-packages.yml40-471
The prepare job determines the build version using a hierarchical fallback strategy:
| Source | Condition | Version Value | Release Flag |
|---|---|---|---|
| Git Tag | refs/tags/* push | Tag name (e.g., 0.3.5) | true |
| Manual Input | workflow_dispatch with version | User-provided version | false |
| Development | Default | 0.0.0-dev | false |
Sources: .github/workflows/build-packages.yml22-36
The version is injected into builds through multiple mechanisms:
G4F_VERSION set for all build jobsg4f_cli.pybuild-argsExample of CLI entry point generation:
Sources: .github/workflows/build-packages.yml90-106 .github/workflows/build-packages.yml156-171
Diagram: PyPI Package Build Steps
The PyPI build job uses the Python build module to create both a wheel (.whl) and source distribution (.tar.gz). The twine tool validates the package structure before uploading as an artifact.
Sources: .github/workflows/build-packages.yml40-65
The executable build jobs run in parallel across multiple platforms and architectures:
| Platform | Job Name | Runner | Architectures | Output Format |
|---|---|---|---|---|
| Windows | build-windows-exe | windows-latest | x64 | .exe (zipped) |
| Linux | build-linux-exe | ubuntu-latest, ubuntu-24.04-arm | x64, arm64 | Binary executable |
| macOS | build-macos-exe | macos-latest | x64, arm64 | Binary executable |
Sources: .github/workflows/build-packages.yml68-237
Diagram: Nuitka Executable Build Flow
Sources: .github/workflows/build-packages.yml78-129 .github/workflows/build-packages.yml144-184
Each platform creates a custom g4f_cli.py entry point that:
g4f.debug.version_check = False)g4f.debug.version = "...")This ensures executables have frozen versions and don't make network requests for version checks.
Sources: .github/workflows/build-packages.yml90-106 .github/workflows/build-packages.yml156-171 .github/workflows/build-packages.yml209-224
Docker builds execute only for tagged releases (is_release == 'true') and produce three image variants:
Diagram: Docker Multi-Platform Build Architecture
Sources: .github/workflows/build-packages.yml240-298
Each image variant receives the version as a build argument:
Docker image build details:
| Variant | Dockerfile | Platforms | Purpose |
|---|---|---|---|
| armv7 | docker/Dockerfile-armv7 | linux/arm/v7 | ARM v7 devices (Raspberry Pi, etc.) |
| slim | docker/Dockerfile-slim | linux/amd64, linux/arm64 | Minimal dependencies, smaller size |
| full | docker/Dockerfile | linux/amd64 | Includes Selenium, Chrome, browser automation |
Sources: .github/workflows/build-packages.yml262-298
Diagram: WinGet Manifest Creation
Sources: .github/workflows/build-packages.yml334-409
The WinGet manifest consists of three YAML files following the WinGet manifest schema v1.4.0:
g4f.yaml): Package identifier and versiong4f.installer.yaml): Download URL, SHA256 hash, installer type (zip with nested portable exe)g4f.locale.en-US.yaml): Package metadata, description, tagsThe installer URL points to GitHub releases:
Sources: .github/workflows/build-packages.yml352-404
The create-release job depends on all build jobs and executes only for tagged releases:
Diagram: Release Creation and Asset Attachment
Sources: .github/workflows/build-packages.yml412-471
The release body includes download instructions for each distribution method:
Sources: .github/workflows/build-packages.yml434-458
A simplified PyPI publishing workflow exists as a separate file for direct publishing:
Diagram: Standalone PyPI Publishing Workflow
This workflow uses PyPI's trusted publishing mechanism (OIDC token authentication) instead of API keys. It only runs for the main repository and requires the pypi environment to be configured.
Sources: .github/workflows/publish-to-pypi.yml1-51
Diagram: Unit Test Workflow
The unittest workflow tests on minimum Python version (3.8) with minimal dependencies, then on latest Python (3.14) with full dependencies. It saves the PR number as an artifact for use by downstream workflows.
Sources: .github/workflows/unittest.yml1-46
Diagram: AI Code Review Workflow Execution
The AI code review workflow triggers after unit tests complete. It uses the g4f library itself to generate code reviews:
create_review_promptanalyze_code and create_analyze_promptSources: .github/workflows/copilot.yml1-58 etc/tool/copilot.py1-256
The copilot tool (etc/tool/copilot.py) implements:
| Function | Purpose |
|---|---|
get_pr_details | Retrieves PR from pr_number file |
get_diff | Fetches PR diff via HTTP |
get_ai_response | Calls g4f.ChatCompletion.create with configured model/provider |
analyze_code | Parses diff, sends chunks to AI for line-by-line review |
create_analyze_prompt | Generates prompt with PR context and code changes |
create_review_prompt | Generates prompt for overall PR review |
read_json / read_text | Parses AI responses from markdown code blocks |
The tool uses environment variables:
GITHUB_TOKEN: GitHub authenticationGITHUB_REPOSITORY: Repository identifierG4F_PROVIDER: Optional provider overrideG4F_MODEL: Model selection (defaults to g4f.models.gpt_4)Sources: etc/tool/copilot.py18-256
The workflow executes scripts/build-nuitka.sh with environment variables:
| Variable | Purpose |
|---|---|
G4F_VERSION | Version string embedded in executable |
PLATFORM | Target platform (windows, linux, darwin) |
ARCHITECTURE | Target architecture (x86_64, arm64, aarch64) |
The script is invoked as:
Output executables follow the naming pattern: g4f-{platform}-{version}-{architecture}[.exe]
Sources: .github/workflows/build-packages.yml113-115 .github/workflows/build-packages.yml172-179
Each workflow declares minimum required permissions:
| Workflow | Permissions | Purpose |
|---|---|---|
build-packages.yml | contents: write (release job) | Create releases and attach assets |
publish-to-pypi.yml | id-token: write | Trusted publishing to PyPI |
copilot.yml | contents: read, pull-requests: write | Post review comments |
unittest.yml | Default | Read repository, upload artifacts |
Sources: .github/workflows/build-packages.yml416-417 .github/workflows/publish-to-pypi.yml42-43 .github/workflows/copilot.yml12-14
The workflows use GitHub secrets:
| Secret | Usage | Workflow |
|---|---|---|
DOCKER_USERNAME | Docker Hub authentication | build-packages.yml (Docker build) |
DOCKER_PASSWORD | Docker Hub password | build-packages.yml (Docker build) |
GITHUB_TOKEN | Automatic token for GitHub API | All workflows |
Sources: .github/workflows/build-packages.yml260-261 .github/workflows/copilot.yml55-56
The unit tests (etc/unittest/main.py etc/unittest/backend.py) verify:
g4f.version.utils.current_version and latest_versionTests use conditional skipping for optional dependencies:
Sources: etc/unittest/main.py1-17 etc/unittest/backend.py1-57
| Python Version | Dependencies | Test Execution |
|---|---|---|
| 3.8 | requirements-min.txt | Minimum supported version |
| 3.14 | requirements.txt | Latest Python with full dependencies |
Sources: .github/workflows/unittest.yml18-36
All build artifacts follow consistent naming patterns:
| Artifact Type | Pattern | Example |
|---|---|---|
| PyPI package | g4f-{version}.tar.gz, g4f-{version}-py3-none-any.whl | g4f-0.3.5.tar.gz |
| Windows exe | g4f-windows-{version}-{arch}.zip | g4f-windows-0.3.5-x64.zip |
| Linux binary | g4f-linux-{version}-{arch} | g4f-linux-0.3.5-x64 |
| macOS binary | g4f-macos-{version}-{arch} | g4f-macos-0.3.5-arm64 |
| Docker image | hlohaus789/g4f:{version}[-variant] | hlohaus789/g4f:0.3.5-slim |
Sources: .github/workflows/build-packages.yml116-129 .github/workflows/build-packages.yml269-296 .github/workflows/build-packages.yml461-467
Refresh this wiki