setup-gazebo

This action sets up a Gazebo environment.

1. Overview
2. Supported platforms
3. Tasks performed by the action
4. Usage
   1. Ubuntu
      1. Setting up worker and installing a compatible Gazebo and Ubuntu combination
      2. Iterating on all Gazebo and Ubuntu combinations
      3. Using prerelease and/or nightly Gazebo binaries
      4. Installing ROS 2 and Gazebo side-by-side along with ros_gz
   2. macOS
      1. Setting up worker to install Gazebo on macOS
   3. Windows
      1. Setting up worker to install Gazebo on Windows
5. License

Overview

The setup-gazebo GitHub Action sets up an environment to install a Gazebo release in the platform of choice. The action takes in the following parameters as input:

• required-gazebo-distributions: A required parameter that specifies the Gazebo distribution to be installed.
• use-gazebo-prerelease: An optional parameter to install pre-release binaries from OSRF repository.
• use-gazebo-nightly: An optional parameter to install nightly binaries from OSRF repository.
• install-ros-gz: An optional parameter to install the ROS 2 Gazebo bridge (ros_gz). This will require a previous ROS installation which can be done using the setup-ros GitHub action. Installation of the ros_gz bridge supports the ROS official and ROS non-official (from packages.osrfoundation.org) variants following the Installing Gazebo with ROS documentation.

Supported platforms

setup-gazebo action works for all non-EOL Gazebo releases on the following platforms:

• Ubuntu
• macOS
• Windows

Tasks performed by the action

The setup-gazebo action performs the following tasks:

• On Ubuntu:
  • Installs sudo in case it is missing
  • Sets the locale to en_US.UTF-8 and timezone to UTC
  • Install necessary APT packages
  • Registers the Open Robotics APT repository
• On macOS:
  • Tapping into the osrf/homebrew-simulation using Homebrew
• On Windows:
  • Installing Gazebo using Conda from conda-forge

Usage

See action.yml

Ubuntu

The setup-gazebo GitHub action can be run using GitHub-hosted Ubuntu runners or inside Ubuntu docker containers.

Note

The available GitHub-hosted runners can be found here. An alternative approach is using a docker container as shown in the following sections.

Setting up worker and installing a compatible Gazebo and Ubuntu combination

This workflow shows how to spawn a job to install Gazebo on an Ubuntu distribution. The action needs an input in the required-gazebo-distributions field.

• Default: Using GitHub-hosted runners systems

  The following code snippet shows the installation of Gazebo Harmonic on Ubuntu Noble.

  jobs:
    test_gazebo:
      runs-on: ubuntu-24.04
      steps:
        - uses: actions/checkout@v4
        - uses: actions/[email protected]
          with:
            node-version: '20.x'
        - name: 'Setup Gazebo'
          uses: gazebo-tooling/[email protected]
          with:
            required-gazebo-distributions: harmonic
        - name: 'Test Gazebo installation'
          run: 'gz sim --versions'

• Using Ubuntu docker containers

  The following code snippet shows the installation of Gazebo Harmonic on Ubuntu Noble.

  jobs:
    test_gazebo:
      runs-on: ubuntu-latest
      container:
        image: ubuntu:noble
      steps:
        - uses: actions/checkout@v4
        - uses: actions/[email protected]
          with:
            node-version: '20.x'
        - name: 'Setup Gazebo'
          uses: gazebo-tooling/[email protected]
          with:
            required-gazebo-distributions: harmonic
        - name: 'Test Gazebo installation'
          run: 'gz sim --versions'

Iterating on all Gazebo and Ubuntu combinations

This workflow shows how to spawn one job per Gazebo release and iterates over all specified Gazebo and Ubuntu combinations. It is done by defining a matrix to iterate over jobs.

• Default: Using GitHub-hosted runners systems

  jobs:
    test_gazebo:
      runs-on: ${{ matrix.ubuntu_distribution }}
      strategy:
        fail-fast: false
        matrix:
          gazebo_distribution:
            - citadel
            - fortress
            - harmonic
            - ionic
          include:
            # Gazebo Citadel (Dec 2019 - Dec 2024)
            - ubuntu_distribution: ubuntu-20.04
              gazebo_distribution: citadel

            # Gazebo Fortress (Sep 2021 - Sep 2026)
            - ubuntu_distribution: ubuntu-20.04
              gazebo_distribution: fortress

            # Gazebo Harmonic (Sep 2023 - Sep 2028)
            - ubuntu_distribution: ubuntu-22.04
              gazebo_distribution: harmonic

            # Gazebo Ionic (Sep 2024 - Sep 2026)
            - ubuntu_distribution: ubuntu-24.04
              gazebo_distribution: ionic
      steps:
        - uses: actions/checkout@v4
        - uses: actions/[email protected]
          with:
            node-version: '20.x'
        - name: 'Check Gazebo installation on Ubuntu runner'
          uses: gazebo-tooling/[email protected]
          with:
            required-gazebo-distributions: ${{ matrix.gazebo_distribution }}
        - name: 'Test Gazebo installation'
          run: |
            if command -v ign > /dev/null; then
              ign gazebo --versions
            elif command -v gz > /dev/null; then
              gz sim --versions
            else
              echo "Neither ign nor gz command found"
              exit 1
            fi

• Using Ubuntu docker containers

  jobs:
    test_gazebo:
      runs-on: ubuntu-latest
      container:
        image: ${{ matrix.docker_image }}
      strategy:
        fail-fast: false
        matrix:
          gazebo_distribution:
            - citadel
            - fortress
            - harmonic
            - ionic
          include:
            # Gazebo Citadel (Dec 2019 - Dec 2024)
            - docker_image: ubuntu:focal
              gazebo_distribution: citadel

            # Gazebo Fortress (Sep 2021 - Sep 2026)
            - docker_image: ubuntu:focal
              gazebo_distribution: fortress

            # Gazebo Harmonic (Sep 2023 - Sep 2028)
            - docker_image: ubuntu:jammy
              gazebo_distribution: harmonic

            # Gazebo Ionic (Sep 2024 - Sep 2026)
            - docker_image: ubuntu:noble
              gazebo_distribution: ionic
      steps:
        - uses: actions/checkout@v4
        - uses: actions/[email protected]
          with:
            node-version: '20.x'
        - name: 'Check Gazebo installation on Ubuntu runner'
          uses: gazebo-tooling/[email protected]
          with:
            required-gazebo-distributions: ${{ matrix.gazebo_distribution }}
        - name: 'Test Gazebo installation'
          run: |
            if command -v ign > /dev/null; then
              ign gazebo --versions
            elif command -v gz > /dev/null; then
              gz sim --versions
            else
              echo "Neither ign nor gz command found"
              exit 1
            fi

Using pre-release and/or nightly Gazebo binaries

This workflow shows how to use binaries from pre-release or nightly Gazebo repositories instead of the stable repository by setting the use-gazebo-prerelease or use-gazebo-nightly to true.

  jobs:
    test_gazebo:
      runs-on: ubuntu-latest
      container:
        image: ubuntu:noble
      steps:
        - uses: actions/checkout@v4
        - uses: actions/[email protected]
          with:
            node-version: '20.x'
        - name: 'Check Gazebo installation on Ubuntu runner'
          uses: gazebo-tooling/[email protected]
          with:
            required-gazebo-distributions: 'ionic'
            use-gazebo-prerelease: 'true'
            use-gazebo-nightly: 'true'
        - name: 'Test Gazebo installation'
          run: 'gz sim --versions'

Installing ROS 2 and Gazebo side-by-side along with ros_gz

This workflow shows how to install ROS 2 using the GitHub action ros-tooling/setup-ros along with Gazebo installed using setup-gazebo. The ros-gz package can be installed by setting the input parameter install-ros-gz to the required ROS 2 distributions.

Starting with ROS 2 Jazzy, Gazebo is also available to be installed from ROS packages via vendor packages. When using install-ros-gz this action will check for availability of these Gazebo vendor packages and install them if available for the specified ROS 2 distribution. Only the default (recommended) Gazebo release is currently available for the ROS 2 releases using the vendor packages (i.e if ROS 2 Jazzy is used, only Gazebo Harmonic is the valid option). More information on vendor packages can be found in the official documentation.

• Installing a ROS-Gazebo combination

This example shows the installation of ROS 2 Iron and Gazebo Harmonic which is a supported ROS-Gazebo combination.

  jobs:
    test_gazebo:
      env:
        ROS_DISTROS: 'iron'
      runs-on: ubuntu-latest
      container:
        image: ubuntu:jammy
      steps:
        - uses: actions/checkout@v4
        - uses: actions/[email protected]
          with:
            node-version: '20.x'
        - name: 'Install ROS 2 Iron'
          uses: ros-tooling/[email protected]
          with:
            required-ros-distributions: ${{ env.ROS_DISTROS }}
        - name: 'Install Gazebo Harmonic with ros_gz'
          uses: gazebo-tooling/[email protected]
          with:
            required-gazebo-distributions: 'harmonic'
            install-ros-gz: ${{ env.ROS_DISTROS }}
        - name: Test Iron ros_gz installation
          run: |
            source /opt/ros/iron/setup.bash
            ros2 pkg list | grep ros_gz
            gz sim --version | grep 'version 8.[0-9*].[0-9*]'

• Installing Gazebo through vendor packages

This example shows the installation of ROS 2 Jazzy and Gazebo Harmonic which is a recommended ROS-Gazebo combination. In this case, Gazebo libraries are will be installed as ROS packages.

  jobs:
    test_gazebo:
      env:
        ROS_DISTROS: 'jazzy'
      runs-on: ubuntu-latest
      container:
        image: ubuntu:noble
      steps:
        - uses: actions/checkout@v4
        - uses: actions/[email protected]
          with:
            node-version: '20.x'
        - name: 'Install ROS 2 Jazzy'
          uses: ros-tooling/[email protected]
          with:
            required-ros-distributions: ${{ env.ROS_DISTROS }}
        - name: 'Install Gazebo with ros_gz'
          uses: gazebo-tooling/[email protected]
          with:
            required-gazebo-distributions: 'harmonic'
            install-ros-gz: ${{ env.ROS_DISTROS }}
        - name: Test Jazzy ros_gz installation
          run: |
            source /opt/ros/jazzy/setup.bash
            ! [ $(apt list --installed gz-harmonic) ]
            ros2 pkg list | grep ros_gz
            gz sim --version | grep 'version 8.[0-9*].[0-9*]'

macOS

Setting up worker to install Gazebo on macOS

This workflow shows how to install Gazebo on a macOS worker using the Homebrew package manager which is installed by the action. To run, this action needs an input for required-gazebo-distributions parameter.

  jobs:
    test_gazebo:
      runs-on: macos-13
      steps:
        - uses: actions/checkout@v4
        - uses: actions/[email protected]
          with:
            node-version: '20.x'
        - name: 'Check Gazebo installation on MacOS runner'
          uses: gazebo-tooling/[email protected]
          with:
            required-gazebo-distributions: 'harmonic'
        - name: 'Test Gazebo installation'
          run: 'gz sim --versions'

Windows

This workflow shows how to install Gazebo on a Windows worker. The action requires a Conda package management system such as miniconda as all Gazebo packages are available on conda-forge. The action is run by specifying the distribution of choice in required-gazebo-distributions field.

Setting up worker to install Gazebo on Windows

  jobs:
    test_gazebo:
      runs-on: windows-latest
      steps:
        - uses: actions/checkout@v4
        - uses: actions/[email protected]
          with:
            node-version: '20.x'
        - uses: conda-incubator/setup-miniconda@v3
        - name: 'Check Gazebo installation on Windows runner'
          uses: gazebo-tooling/[email protected]
          with:
            required-gazebo-distributions: 'harmonic'
        - name: 'Test Gazebo installation'
          shell: pwsh
          run: |
            conda activate
            gz sim --versions

License

The scripts and documentation in this project are released under the Apache 2 license.