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. It should be noted that the ubuntu-24.04 runner image is a beta release. 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
            - garden
            - harmonic
          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 Garden (Sep 2022 - Nov 2024)
            - ubuntu_distribution: ubuntu-20.04
              gazebo_distribution: garden

            # Gazebo Harmonic (Sep 2023 - Sep 2028)
            - ubuntu_distribution: ubuntu-22.04
              gazebo_distribution: harmonic
      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
          - garden
          - harmonic
        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 Garden (Sep 2022 - Nov 2024)
          - docker_image: ubuntu:focal
            gazebo_distribution: garden

          # Gazebo Harmonic (Sep 2023 - Sep 2028)
          - docker_image: ubuntu:jammy
            gazebo_distribution: harmonic
    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.

  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*]'

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.