Principle:MarketSquare Robotframework browser Release Publication

Overview

The robotframework-browser project uses a fully automated multi-platform release pipeline triggered by GitHub release events. When a release is published on GitHub, a GitHub Actions workflow builds, tests, and publishes the library to multiple distribution channels: PyPI, Docker Hub, GitHub Container Registry (GHCR), and GitHub Pages. The pipeline includes smoke testing of built artifacts before any publishing step.

Core Concept

The release publication pipeline follows a build-test-publish pattern with multiple stages:

Build -- Compile and package the library on all supported platforms
Test -- Install the built packages on clean systems and run acceptance tests
Publish -- Upload verified packages to distribution channels

This approach ensures that only tested artifacts reach end users, and that the library works on all supported platforms before publication.

Trigger

The pipeline is triggered by a single event:

on:
  release:
    types: [ published ]

When a project maintainer creates and publishes a GitHub release (typically after running the release preparation tasks), the entire pipeline runs automatically.

Platform Matrix

The build and test stages run on a matrix of operating systems to ensure cross-platform compatibility:

Platform	Runner	Architecture	Notes
Ubuntu (latest)	`ubuntu-latest`	x86_64	Primary build platform; produces the universal Python wheel
Ubuntu ARM	`ubuntu-24.04-arm`	aarch64	ARM Linux platform
Windows	`windows-latest`	x86_64	Windows platform
macOS Intel	`macos-15-intel`	x86_64	Intel Mac platform
macOS ARM	`macos-latest`	arm64	Apple Silicon platform

Pipeline Stages

Stage 1: GitHub Pages Deployment

Deploys keyword documentation to GitHub Pages:

Builds the project and generates documentation with inv build and inv docs
Generates the documentation index page with inv gh-pages-index
Deploys the docs/ folder to the gh-pages branch

Stage 2: Build Wheels

Builds distribution packages on all platforms:

Browser wheel (Python): Built only on Ubuntu (platform-independent py3-none-any.whl)
BrowserBatteries wheel (platform-specific): Built on each platform with a compiled Node.js gRPC server binary
Demo app: Zipped for each platform for use in testing

Stage 3: Test Wheels

Validates built packages on clean installations:

Downloads the Browser wheel and platform-specific BrowserBatteries wheel
Installs both packages with pip
Runs rfbrowser install --with-deps to install Playwright browsers
Runs acceptance tests in smoke mode (fast subset)
Tests run on all platforms in the matrix

Stage 4: Publish Browser to PyPI

Publishes the universal Python wheel:

Uses PyPI's trusted publisher mechanism (id-token: write permission)
Verifies the package with twine check before uploading
Publishes via pypa/gh-action-pypi-publish

Stage 5: Publish BrowserBatteries to PyPI

Publishes platform-specific BrowserBatteries wheels:

Downloads all platform-specific wheels (from the build matrix)
Merges multiple artifacts into a single directory
Publishes all wheels via pypa/gh-action-pypi-publish

Stage 6: Docker Image Build and Push

Builds and pushes multi-architecture Docker images:

Builds for linux/arm64/v8 and linux/amd64 using Docker Buildx with QEMU
Pushes to Docker Hub (marketsquare/robotframework-browser) with semantic version tags (e.g., 19, 19.13, 19.13.0, latest)
Pushes to GHCR (ghcr.io/marketsquare/robotframework-browser/rfbrowser-stable) with the same tag set

Stage 7: Test Docker Image

Validates the published Docker image:

Pulls the newly published image
Builds a test Docker image on top of it
Runs acceptance tests inside the container with xvfb-run

Job Dependencies

The jobs have explicit dependency chains to ensure correct ordering:

gh-pages                          (independent)
build_browser_wheels              (independent)
  └── test_browser_wheels         (needs: build_browser_wheels)
        ├── publish-browser-to-pypi       (needs: build + test)
        └── publish-browserbatteries-to-pypi  (needs: build + test)
              └── docker-image            (needs: publish-browser-to-pypi)
                    └── test-docker-image (needs: docker-image)

Smoke Testing

Built artifacts are smoke-tested before publishing:

On Ubuntu and Ubuntu ARM: acceptance tests run via xvfb-run invoke atest-robot --smoke
On Windows and macOS: acceptance tests run via inv atest-robot (no xvfb needed)
The --smoke flag excludes slow tests for faster feedback

Domains

Continuous_Delivery -- The pipeline automates the full release process from build to publication
Release_Management -- Multiple distribution channels are managed in a coordinated workflow

Implemented By

Implementation:MarketSquare_Robotframework_browser_Github_Release_Workflow

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment