How to Use Vibium in GitHub Actions

To run Vibium in GitHub Actions, add a workflow that sets up Python, installs Chrome's shared system libraries on the Ubuntu runner, then runs pip install vibium and vibium install before executing your script with headless=True. Vibium is a single Go binary that downloads its own Chrome for Testing, so there is no setup-chrome action, no ChromeDriver, and no driver-version matching — the classic source of flaky CI. The runner only needs Chrome's shared libraries (libnss3, libgbm1, libasound2, and friends), which you install once with apt-get. Running vibium install pre-fetches the browser so your script does not pay the download cost mid-job, and pairing it with actions/cache makes reruns even faster. Headless mode is just a launch flag, so the script you ran locally is byte-for-byte the one CI runs. Add a screenshot upload and you can see exactly what every run rendered.

What does the workflow file look like?

A single job handles setup, install, and run. Save this as .github/workflows/vibium.yml:

name: Vibium
 
on: [push, workflow_dispatch]
 
jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
 
      - name: Install Chrome system libraries
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            libnss3 libatk-bridge2.0-0 libgbm1 libasound2 \
            libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 \
            libxrandr2 libdrm2 libpango-1.0-0 libcairo2
 
      - name: Install Vibium and Chrome for Testing
        run: |
          pip install vibium
          vibium install
 
      - name: Run script
        run: python scrape.py
 
      - name: Upload screenshot
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: vibium-screenshot
          path: page.png

The if: always() on the upload step means you still get the screenshot even when the script fails — which is when you most want to see what happened.

What does the script need for CI?

The CI script is an ordinary headless Vibium script that saves a screenshot for the artifact step to pick up:

from vibium import browser_sync as browser
 
vibe = browser.launch(headless=True)
try:
    vibe.go("https://example.com")
    print("Title:", vibe.find("h1").text())
 
    png = vibe.screenshot(full_page=True)
    with open("page.png", "wb") as f:
        f.write(png)
finally:
    vibe.quit()

Launching with headless=True is the only CI-specific line. The finally: vibe.quit() block ensures Chrome is closed even if an assertion fails. For the underlying commands, see the screenshot command and the find-element command.

How do I cache Chrome to speed up runs?

Vibium stores Chrome for Testing in a cache directory, so caching that directory across runs avoids re-downloading the browser every time. Add an actions/cache step before the install step:

      - name: Cache Chrome for Testing
        uses: actions/cache@v4
        with:
          path: ~/.cache/vibium
          key: vibium-chrome-${{ runner.os }}

On a cache hit, vibium install finds the browser already present and finishes near-instantly. Pinning the Vibium version (covered in how to pin the Chrome version) keeps the cached browser stable, so a key based on the version makes the cache deterministic.

Why is Vibium a clean fit for GitHub Actions?

Two design choices remove the usual CI pain. First, the single Go binary bundles the WebDriver BiDi engine and pulls a known-good Chrome for Testing, so there is no driver to align with the browser — the breakage that plagues older Selenium pipelines simply does not exist. Second, headless is a launch flag rather than a separate code path, so local and CI behavior match exactly. That makes runs reproducible: if it passes on your machine, it passes on the runner for the same reason.

How do I run it on a schedule or matrix?

GitHub Actions can trigger Vibium on a cron schedule for monitoring, or fan it out across versions with a matrix. Add a schedule trigger for nightly checks:

on:
  schedule:
    - cron: "0 6 * * *"   # 06:00 UTC daily
  workflow_dispatch:

For containerized runs instead of the bare runner, the same setup works inside a Docker image — see how to run Vibium in Docker. To understand the headless deployment model in more depth, read how to run Vibium headless on a server.

Next steps

• How to run Vibium in Docker
• How to pin the Chrome version in Vibium
• How to run Vibium headless on a server