This action builds and tests a ROS or ROS 2 workspace from source.
- Requirements
- Overview
- Action Output
- Usage
- Build and run tests for your ROS 2 package
- Build with a custom
reposorrosinstallfile - Build a ROS 1 workspace
- Skip tests
- Use a
colcondefaults.yamlfile - Do not use
--symlink-installwhen building - Enable Address Sanitizer to automatically report memory issues
- Generate and process code coverage data
- Store
colconlogs as build artifacts - Use with private repos
- Skip
rosdep install - Interdependent pull requests or merge requests
- Developing
- License
This action requires the following ROS development tools to be installed (and initialized if applicable) on the CI worker instance:
colcon-common-extensions
colcon-lcov-result # Optional
colcon-coveragepy-result
colcon-mixin
rosdep
vcstool
On Linux, the setup can be done through ros-tooling/setup-ros, or by running the action in a Docker image containing the appropriate binaries.
Note: for Windows, action-ros-ci currently needs to be run on windows-2019 or needs another action to install Visual Studio 2019.
The action first assembles a workspace, then runs colcon build, and colcon test in it.
The workspace is built by running:
vcs importon the repo file(s) specified through thevcs-repo-file-urlargument, if any (defaults to none)- checkout the code under test in the workspace using
vcs rosdep installfor the workspace, to get its dependencies- run
colcon build(optionally limited to packages specified inpackage-name) - run
colcon test(optionally limited to packages specified inpackage-name; optionally skipped)
This action requires targeting a ROS or ROS 2 distribution explicitly.
This is provided via the target-ros1-distro or target-ros2-distro inputs, respectively.
Either or both may be specified, if neither is provided an error will be raised.
This input is used to source setup.sh for any installed ROS binaries (e.g. installed using ros-tooling/setup-ros), as well as used as an argument to rosdep install.
This action defines an output variable: ros-workspace-directory-name.
It contains the path to the root of the ROS workspace assembled by the action.
The variable value should be used to retrieve logs, binaries, etc. after the action completes.
See action.yml to get the list of inputs supported by this action.
action-ros-ci-template offers a template for using action-ros-ci.
Here are the two simplest use-cases.
In this case, action-ros-ci will rely on setup-ros for installing ROS 2 binaries.
steps:
- uses: ros-tooling/[email protected]
with:
required-ros-distributions: jazzy
- uses: ros-tooling/[email protected]
with:
package-name: my_package
target-ros2-distro: jazzyIn this case, action-ros-ci will build all necessary ROS 2 dependencies of my_package from source.
steps:
- uses: ros-tooling/[email protected]
- uses: ros-tooling/[email protected]
with:
package-name: my_package
target-ros2-distro: jazzy
vcs-repo-file-url: https://raw.githubusercontent.com/ros2/ros2/jazzy/ros2.reposIf you want to continue supporting older ROS releases while developing on an the main branch use acton-ros-ci with ref on a scheduled job.
Without setting ref the default branch and most recent commit will be used.
name: Jazzy Source Build
on:
schedule:
# At 00:00 on Sunday.
- cron '0 0 * * 0'
jobs:
jazzy_source:
runs_on: ubuntu-latest
container:
image: ubuntu:noble
steps:
- uses: ros-tooling/[email protected]
with:
required-ros-distributions: jazzy
- uses: ros-tooling/[email protected]
with:
package-name: my_package
ref: jazzy
target-ros2-distro: jazzy
vcs-repo-file-url: https://raw.githubusercontent.com/ros2/ros2/jazzy/ros2.reposYou can specify your own repos file using the vcs-repo-file-url input.
You can also automatically generate your package's dependencies using the following workflow:
steps:
- uses: actions/checkout@v4
- uses: ros-tooling/[email protected]
# Run the generator and output the results to a file.
- run: |
rosinstall_generator <package-name> --rosdistro <target-distro> \
--deps-only --deps --upstream-development > /tmp/deps.repos
# Pass the file to the action
- uses: ros-tooling/[email protected]
with:
package-name: my_package
target-ros2-distro: jazzy
vcs-repo-file-url: /tmp/deps.reposNote that the actions/checkout step is required when using a custom repos file from your repository.
Building a ROS 1 workspace works the same way.
Simply use target-ros1-distro instead of target-ros2-distro.
steps:
- uses: ros-tooling/[email protected]
with:
required-ros-distributions: noetic
- uses: ros-tooling/[email protected]
with:
package-name: my_package
target-ros1-distro: noeticTo skip tests and code coverage data processing, set the skip-tests option to true.
steps:
- uses: ros-tooling/[email protected]
with:
required-ros-distributions: jazzy
- uses: ros-tooling/[email protected]
with:
package-name: my_package
target-ros2-distro: jazzy
skip-tests: trueTo use a colcon defaults.yaml file, provide a valid JSON string through the colcon-defaults input.
This allows using a colcon option/argument that is not exposed by this action's inputs.
steps:
- uses: ros-tooling/[email protected]
with:
required-ros-distributions: jazzy
- uses: ros-tooling/[email protected]
with:
package-name: my_package
target-ros2-distro: jazzy
colcon-defaults: |
{
"build": {
"cmake-args": [
"-DMY_CUSTOM_OPTION=ON"
]
}
}By default, --symlink-install is used with colcon build.
To avoid this, set the no-symlink-install input to true.
steps:
- uses: ros-tooling/[email protected]
with:
required-ros-distributions: jazzy
- uses: ros-tooling/[email protected]
with:
package-name: my_package
target-ros2-distro: jazzy
no-symlink-install: trueASan is an open-source tool developed to automatically report memory corruption bugs.
steps:
- uses: ros-tooling/[email protected]
with:
required-ros-distributions: jazzy
- uses: ros-tooling/[email protected]
with:
colcon-defaults: |
{
"build": {
"mixin": ["asan-gcc"]
}
}
colcon-mixin-repository: https://raw.githubusercontent.com/colcon/colcon-mixin-repository/b8436aa16c0bdbc01081b12caa253cbf16e0fb82/index.yaml
package-name: my_package
target-ros2-distro: jazzyTo look for detected memory errors, check the build logs for entries containing ERROR: AddressSanitizer. Example:
==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8
ASan is analyzing memory issues at runtime. ASan diagnostic messages will be emitted by the package tests when they run.
Generate code coverage information for C/C++ files using the appropriate mixins for gcc.
action-ros-ci uses colcon-lcov-result to aggregate generated coverage information.
Flags can be passed manually using, for instance, extra-cmake-args, but it is
preferable to use a colcon mixin (through colcon-defaults) to pass the appropriate flags automatically.
steps:
- uses: ros-tooling/[email protected]
with:
required-ros-distributions: jazzy
- uses: ros-tooling/[email protected]
with:
package-name: my_package
target-ros2-distro: jazzy
colcon-defaults: |
{
"build": {
"mixin": ["coverage-gcc"]
}
}
# If possible, pin the repository in the workflow to a specific commit to avoid
# changes in colcon-mixin-repository from breaking your tests.
colcon-mixin-repository: https://raw.githubusercontent.com/colcon/colcon-mixin-repository/b8436aa16c0bdbc01081b12caa253cbf16e0fb82/index.yamlGenerate code coverage information for Python files using the appropriate mixins.
action-ros-ci uses colcon-coveragepy-result to aggregate generated coverage information.
steps:
- uses: ros-tooling/[email protected]
with:
required-ros-distributions: jazzy
- uses: ros-tooling/[email protected]
with:
package-name: my_package
target-ros2-distro: jazzy
colcon-defaults: |
{
"build": {
"mixin": ["coverage-pytest"]
},
"test": {
"mixin": ["coverage-pytest"]
}
}
# If possible, pin the repository in the workflow to a specific commit to avoid
# changes in colcon-mixin-repository from breaking your tests.
colcon-mixin-repository: https://raw.githubusercontent.com/colcon/colcon-mixin-repository/b8436aa16c0bdbc01081b12caa253cbf16e0fb82/index.yamlThe generated code coverage information can be uploaded to codecov.io.
For a private repo, you will need to setup a secret CODECOV_TOKEN in your repository settings.
See codecov/codecov-action documentation for more information about how to setup the action.
steps:
- uses: actions/checkout@v4
- uses: ros-tooling/[email protected]
with:
required-ros-distributions: jazzy
- uses: ros-tooling/[email protected]
with:
package-name: my_package
target-ros2-distro: jazzy
colcon-defaults: |
{
"build": {
"mixin": ["coverage-gcc", "coverage-pytest"]
},
"test": {
"mixin": ["coverage-pytest"]
}
}
# If possible, pin the repository in the workflow to a specific commit to avoid
# changes in colcon-mixin-repository from breaking your tests.
colcon-mixin-repository: https://raw.githubusercontent.com/colcon/colcon-mixin-repository/b8436aa16c0bdbc01081b12caa253cbf16e0fb82/index.yaml
- uses: codecov/[email protected]
with:
token: ${{ secrets.CODECOV_TOKEN }} # only needed for private repos
files: ros_ws/lcov/total_coverage.info,ros_ws/coveragepy/.coverage
flags: unittests
name: codecov-umbrellaYou will also need to add a codecov.yml configuration file (at the root of your repo):
fixes:
# For each package in your repo
- "ros_ws/src/*/my_repo/my_package/::"The configuration file is required to let codecov map the workspace directory structure to the Git repository structure, and setup the links between codecov and GitHub properly.
Note here that actions/checkout is required because codecov/codecov-action needs the codecov.yml file.
GitHub workflows can persist data generated in workers during the build using artifacts. action-ros-ci generated colcon logs can be saved as follows:
steps:
# ...
- uses: ros-tooling/[email protected]
id: action_ros_ci_step
with:
package-name: ament_copyright
target-ros2-distro: jazzy
- uses: actions/upload-artifact@v1
with:
name: colcon-logs
path: ${{ steps.action_ros_ci_step.outputs.ros-workspace-directory-name }}/log
if: always() # upload the logs even when the build failsaction-ros-ci needs a token to be able to clone private repositories.
If the only private repository your workflow needs is the one against which it runs, using the default GITHUB_TOKEN will work.
However, if your workflow also clones other private repositories (e.g., repositories included in repos files provided through vcs-repo-file-url), you will need to generate a personal access token (PAT) with the "repo" scope and add it to your repo's secrets.
For example, if this secret is called REPO_TOKEN:
steps:
# ...
- uses: ros-tooling/[email protected]
with:
package-name: my_package
# If there are no private dependencies, no need to create a PAT or add a secret
import-token: ${{ secrets.GITHUB_TOKEN }}
# If there are private dependencies (e.g., in a file provided through vcs-repo-file-url), a PAT is required
import-token: ${{ secrets.REPO_TOKEN }}
# ...Include an option to bypass rosdep install for workflow that uses specific docker image and better control of dependencies. To check for missing dependencies within the workflow's image, user can run with rosdep-check: true flag.
runs-on: ubuntu-latest
container:
image: ghcr.io/ros-tooling/setup-ros-docker/setup-ros-docker-ubuntu-noble-ros-jazzy-ros-base
steps:
# ...
- uses: ros-tooling/[email protected]
with:
target-ros2-distro: jazzy
package-name: ament_copyright
vcs-repo-file-url: "https://raw.githubusercontent.com/ros2/ros2/release-jazzy-20240523/ros2.repos"
skip-rosdep-install: true
rosdep-check: trueThis action allows declaring PR dependencies by providing:
- repos file(s) to override the one(s) defined through the
vcs-repo-file-urlaction input - supplemental repos file(s) to be used along with the rest
For example, this may be useful when your PR depends on PRs/MRs/branches from other repos for it to work or be properly tested.
Include links in your PR's description using the following format:
action-ros-ci-repos-override: https://gist.github.com/some-user/some.repos
action-ros-ci-repos-override: https://gist.github.com/some-user/some-other.repos
action-ros-ci-repos-supplemental: https://gist.github.com/some-user/some-supplemental.repos
action-ros-ci-repos-supplemental: file://path/to/some/other/supplemental.repos
For developing and releasing action-ros-ci, see DEVELOPING.md.
The scripts and documentation in this project are released under the Apache 2 license.
![dependabot-preview[bot] avatar](https://avatars.githubusercontent.com/in/2141?v=4 "dependabot-preview[bot]")
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
![greenkeeper[bot] avatar](https://avatars.githubusercontent.com/in/505?v=4 "greenkeeper[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent