{"id":13719430,"url":"https://github.com/ros-tooling/setup-ros","last_synced_at":"2026-03-13T02:37:35.920Z","repository":{"id":38334430,"uuid":"215879926","full_name":"ros-tooling/setup-ros","owner":"ros-tooling","description":"Github Action to set up ROS 2 on hosts","archived":false,"fork":false,"pushed_at":"2025-05-02T19:27:23.000Z","size":24647,"stargazers_count":95,"open_issues_count":20,"forks_count":45,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-05-02T20:27:10.640Z","etag":null,"topics":["ci","colcon","ros2"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ros-tooling.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-10-17T20:28:14.000Z","updated_at":"2025-05-02T19:24:43.000Z","dependencies_parsed_at":"2023-01-04T12:39:13.094Z","dependency_job_id":"45f72a54-8192-401a-ac38-ddf34b8d8aa1","html_url":"https://github.com/ros-tooling/setup-ros","commit_stats":{"total_commits":623,"total_committers":31,"mean_commits":"20.096774193548388","dds":0.5104333868378812,"last_synced_commit":"1abdebd3c052ad2a676f5dfe1a65eba5fbf8cee9"},"previous_names":[],"tags_count":69,"template":false,"template_full_name":"actions/typescript-action","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ros-tooling%2Fsetup-ros","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ros-tooling%2Fsetup-ros/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ros-tooling%2Fsetup-ros/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ros-tooling%2Fsetup-ros/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ros-tooling","download_url":"https://codeload.github.com/ros-tooling/setup-ros/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252563151,"owners_count":21768411,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ci","colcon","ros2"],"created_at":"2024-08-03T01:00:48.590Z","updated_at":"2026-03-13T02:37:35.871Z","avatar_url":"https://github.com/ros-tooling.png","language":"TypeScript","funding_links":[],"categories":["Development Environment"],"sub_categories":["Unit and Integration Test"],"readme":"# `setup-ros`\n\n[![GitHub Action Status](https://github.com/ros-tooling/setup-ros/workflows/Test%20setup-ros/badge.svg)](https://github.com/ros-tooling/setup-ros)\n[![codecov](https://codecov.io/gh/ros-tooling/setup-ros/branch/main/graph/badge.svg)](https://codecov.io/gh/ros-tooling/setup-ros)\n[![Dependabot Status](https://api.dependabot.com/badges/status?host=github\u0026repo=ros-tooling/setup-ros)](https://dependabot.com)\n[![License](https://img.shields.io/github/license/ros-tooling/setup-ros)](https://github.com/ros-tooling/setup-ros/blob/main/LICENSE)\n\nThis action sets up a [ROS] and [ROS 2] environment for use in actions.\n\n1. [Overview](#Overview)\n1. [Supported platforms](#Supported-platforms)\n1. [Tasks performed by the action](#Tasks-performed-by-the-action)\n1. [Usage](#Usage)\n   1. [Setting up the worker, and installing the system dependencies](#Setting-up-the-worker-and-installing-the-system-dependencies)\n   1. [Setting up the worker, and installing system dependencies on all OSes](#Setting-up-the-worker-and-installing-system-dependencies-on-all-OSes)\n   1. [Setting up the worker, installing system dependencies and ROS (Linux)](#Setting-up-the-worker-installing-system-dependencies-and-ROS-Linux)\n   1. [Use pre-release ROS 2 binaries for testing](#Use-pre-release-ROS-2-binaries-for-testing)\n   1. [Including RTI Connext](#Including-RTI-Connext)\n   1. [Iterating on all ROS distributions, for all platforms](#Iterating-on-all-ROS-distributions-for-all-platforms)\n1. [Alternative to `setup-ros`](#Alternative-to-setup-ros)\n1. [Developing](#Developing)\n1. [License](#License)\n\n## Overview\n\n`setup-ros` sets up an environment so that:\n\n- [ROS 2 latest development branch][ros2_latest_development_setup] builds from source,\n- non-EOL (End Of Life) distribution of ROS 2 builds from source,\n- any ROS, and ROS 2 package depending on non-EOL distribution builds from source\n\nThe action will not install ROS, or ROS 2, by default.\nTo install a ROS binary distribution, pass a value to `required-ros-distributions` (see example below).\n\n:warning: `apt-get update` is flaky on bare metal GitHub actions Linux workers relying on the GitHub APT mirrors.\nIt is recommended to run `setup-ros` in a Docker container.\nSee [`jobs.\u003cjob_id\u003e.container` documentation](https://help.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idcontainer).\nAn alternative approach is to edit APT sources on the bare metal worker (see [#80](https://github.com/ros-tooling/setup-ros/issues/80) for details).\n\n## Supported platforms\n\nThis GitHub action aims for strict [REP-3] and [REP-2000] compliance.\n`setup-ros` supports all non-EOL ROS distributions, on all Tier-1 platforms.\nIn particular, this action supports Ubuntu, macOS, and Microsoft Windows.\n\nFor macOS, and Microsoft Windows, the OS version specified in the REPs may not be available as a [GitHub Hosted runners][github_hosted_runners].\nIn this case, this GitHub action CI runs the closest available worker environment.\n\nUsers requiring exact REP compliance should run the action on a [self-hosted runner][self_hosted_runner].\n\nThis problem does not apply to Linux workers, where Docker can ensure that the action runs the Linux distribution specified by the REPs.\n\n## Tasks performed by the action\n\n`setup-ros` installs the following command-line tools:\n\n- `colcon`\n- `rosdep`\n- `vcs`\n\nIt also performs the following actions:\n\n- On Ubuntu:\n  - Setting the locale to `en_US.UTF-8` and, the timezone to UTC\n  - GCC and clang default APT packages\n  - Registering the Open Robotics APT repository\n  - Installing ROS and ROS 2 system dependencies using APT\n- On macOS:\n  - Installing ROS and ROS 2 system dependencies using [Homebrew] and [pip]\n- On Microsoft Windows:\n  - Installing ROS and ROS 2 system dependencies using [Chocolatey]\n\nThe dependencies installed by this package include ROS 2 DDS vendor packages, such as Eclipse Cyclone DDS, eProsima Fast DDS, and RTI Connext DDS.\nSee [`src/package_manager/*.ts`](./src/package_manager/) for the complete list.\n\n## Usage\n\nSee [action.yml](action.yml).\n\n`setup-ros` is under active development, and compatibility between releases is not yet guaranteed.\nPlease do not use `ros-tooling/setup-ros@main`.\nInstead, pin your workflows to a particular release, e.g.: `ros-tooling/setup-ros@v0.7`.\n\n### Setting up the worker, and installing the system dependencies\n\nThe default behavior is to only install development tools.\nNo ROS binary distribution is installed in this case.\nThis setup should be used when ROS is built entirely from source.\n\n```yaml\nsteps:\n  - uses: ros-tooling/setup-ros@v0.7\n  - run: vcs --help\n```\n\n### Setting up the worker, and installing system dependencies on all OSes\n\nIt is possible to iterate on macOS and Windows from the same job (`build`).\nUbuntu requires its own separate workflow as additional configuration is required for Docker.\n\n```yaml\njobs:\n  build:\n    runs-on: ${{ matrix.os }}\n    strategy:\n      fail-fast: false\n      matrix:\n        os: [macOS-latest, windows-latest]\n    steps:\n      - name: Setup ROS\n        uses: ros-tooling/setup-ros@v0.7\n      - run: vcs --help\n\n  build_docker:\n    runs-on: ubuntu-latest\n    container:\n      image: ubuntu:noble\n    steps:\n      - name: Setup ROS\n        uses: ros-tooling/setup-ros@v0.7\n      - run: vcs --help\n```\n\n### Setting up the worker, installing system dependencies and ROS (Linux)\n\nOne or more ROS distributions can be installed simultaneously by passing multiple values to `required-ros-distributions`.\n\n```yaml\nbuild_docker:\n  runs-on: ubuntu-latest\n  container:\n    image: ubuntu:noble\n  steps:\n    - uses: ros-tooling/setup-ros@v0.7\n      with:\n        required-ros-distributions: jazzy rolling\n    - run: \"source /opt/ros/jazzy/setup.bash \u0026\u0026 ros2 run --help\"\n    - run: \"source /opt/ros/rolling/setup.bash \u0026\u0026 ros2 run --help\"\n```\n\n**Note: on Ubuntu, `required-ros-distributions` installs the desktop variant for that distribution. This option is not required, and should probably be avoided in most workflows. It is retained for historical reasons and those who specifically do not care about whether their application specifies its dependencies properly.**\n\n### Use pre-release ROS 2 binaries for testing\n\nYou can specify if you'd like to use the [pre-release ROS 2 repository][pre_release_testing] in your sources list file by setting the `use-ros2-testing` parameter to `true`.\n\n```yaml\nbuild_docker:\n  runs-on: ubuntu-latest\n  container:\n    image: ubuntu:noble\n  steps:\n    - uses: ros-tooling/setup-ros@v0.7\n      with:\n        use-ros2-testing: true\n        required-ros-distributions: jazzy\n```\n\n### Including RTI Connext\n\nBy default this action will not install RTI Connext as it requires acceptance of a non-commerical license.\nThe license agreement should be reviewed by users on their own before accepting it.\nTo include RTI Connext, simply set the `install-connext` parameter to `true`.\n\n```yaml\nbuild_docker:\n  runs-on: ubuntu-latest\n  container:\n    image: ubuntu:noble\n  steps:\n    - uses: ros-tooling/setup-ros@v0.7\n      with:\n        install-connext: true\n        use-ros2-testing: true\n        required-ros-distributions: jazzy\n```\n\n### Iterating on all ROS distributions, for all platforms\n\nThis workflow illustrates how to spawn one job per ROS release, for every supported platform.\n\nThe workflow `test` is iterating on all ROS 2 distributions, on macOS, and Windows.\n\nThe workflow `test_docker` is iterating on all ROS and ROS 2 distributions, for all supported Ubuntu distributions, using Docker.\nThe test matrix associates each distribution with one Docker image.\nThis is required to ensure that the appropriate Ubuntu container is used.\nFor example, Noetic requires `focal`, Humble requires `jammy`, Jazzy requires `noble`, etc.\n\n```yaml\njobs:\n  test: # Docker is not supported on macOS and Windows.\n    runs-on: ${{ matrix.os }}\n    strategy:\n      matrix:\n        os: [macOS-latest, windows-latest]\n        ros_distribution: # Only include ROS 2 distributions, as ROS 1 does not support macOS and Windows.\n          - humble\n          - iron\n    steps:\n      - uses: ros-tooling/setup-ros@v0.7\n        with:\n          required-ros-distributions: ${{ matrix.ros_distribution }}\n      - name: build and test\n        uses: ros-tooling/action-ros-ci@v0.3\n        with:\n          package-name: YOUR_PACKAGE_HERE MORE_PACKAGES_HERE\n          target-ros2-distro: ${{ matrix.ros_distribution }}\n\n  test_docker: # On Linux, iterates on all ROS 1 and ROS 2 distributions.\n    runs-on: ubuntu-latest\n    strategy:\n      matrix:\n        ros_distribution:\n          - noetic\n          - humble\n          - iron\n          - jazzy\n          - rolling\n\n        # Define the Docker image(s) associated with each ROS distribution.\n        # The include syntax allows additional variables to be defined, like\n        # docker_image in this case. See documentation:\n        # https://help.github.com/en/actions/reference/workflow-syntax-for-github-actions#example-including-configurations-in-a-matrix-build\n        #\n        # Platforms are defined in REP 3 and REP 2000:\n        # https://ros.org/reps/rep-0003.html\n        # https://ros.org/reps/rep-2000.html\n        include:\n          # Noetic Ninjemys (May 2020 - May 2025)\n          - docker_image: ubuntu:focal\n            ros_distribution: noetic\n            ros_version: 1\n\n          # Humble Hawksbill (May 2022 - May 2027)\n          - docker_image: ubuntu:jammy\n            ros_distribution: humble\n            ros_version: 2\n\n          # Iron Irwini (May 2023 - November 2024)\n          - docker_image: ubuntu:jammy\n            ros_distribution: iron\n            ros_version: 2\n\n          # Jazzy Jalisco (May 2024 - May 2029)\n          - docker_image: ubuntu:noble\n            ros_distribution: jazzy\n            ros_version: 2\n\n          # Rolling Ridley (No End-Of-Life)\n          - docker_image: ubuntu:noble\n            ros_distribution: rolling\n            ros_version: 2\n    container:\n      image: ${{ matrix.docker_image }}\n    steps:\n      - name: setup ROS environment\n        uses: ros-tooling/setup-ros@v0.7\n        with:\n          required-ros-distributions: ${{ matrix.ros_distribution }}\n      - name: build and test ROS 1\n        if: ${{ matrix.ros_version == 1 }}\n        uses: ros-tooling/action-ros-ci@v0.3\n        with:\n          package-name: YOUR_PACKAGE_HERE MORE_PACKAGES_HERE\n          target-ros1-distro: ${{ matrix.ros_distribution }}\n      - name: build and test ROS 2\n        if: ${{ matrix.ros_version == 2 }}\n        uses: ros-tooling/action-ros-ci@v0.3\n        with:\n          package-name: YOUR_PACKAGE_HERE MORE_PACKAGES_HERE\n          target-ros2-distro: ${{ matrix.ros_distribution }}\n```\n\n## Alternative to `setup-ros`\n\nOn Linux workers, an alternative to `setup-ros` is to run actions on a Docker container where ROS is pre-installed.\nSee [Open Robotics DockerHub page][dockerhub_osrf], for instance.\n\n## Developing\n\nFor developing and releasing `setup-ros`, see [`DEVELOPING.md`](DEVELOPING.md).\n\n## License\n\nThe scripts and documentation in this project are released under the [Apache 2](LICENSE) license.\n\n[ros]: https://www.ros.org/\n[ROS 2]: https://docs.ros.org/en/rolling/index.html\n[ros2_latest_development_setup]: https://docs.ros.org/en/rolling/Installation/Alternatives/Latest-Development-Setup.html\n[rep-2000]: https://www.ros.org/reps/rep-2000.html\n[rep-3]: https://www.ros.org/reps/rep-0003.html\n[chocolatey]: https://chocolatey.org/\n[homebrew]: https://brew.sh/\n[pip]: https://pip.pypa.io/en/stable/\n[dockerhub_osrf]: https://hub.docker.com/r/osrf/ros/\n[github_hosted_runners]: https://help.github.com/en/actions/automating-your-workflow-with-github-actions/software-installed-on-github-hosted-runners\n[pre_release_testing]: https://docs.ros.org/en/rolling/Installation/Prerelease-Testing.html\n[self_hosted_runner]: https://help.github.com/en/actions/automating-your-workflow-with-github-actions/about-self-hosted-runners\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fros-tooling%2Fsetup-ros","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fros-tooling%2Fsetup-ros","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fros-tooling%2Fsetup-ros/lists"}