Utility scripts to ease management of GitHub projects for ROS / ROS 2
Driving these tools with an AI coding agent (Claude, Codex, Cursor, etc.)?
See AGENTS.md for agent-facing usage guidance.
These are Python command-line tools. The recommended way to install them is with
uv, which puts the commands on your PATH inside an
isolated, uv-managed virtual environment.
After installation you can run the commands directly, without a uv run prefix
or manually activating a venv.
# Note that this is by _path_, it's not the name of a package on PyPI - so substitute as appropriate for your working directory
uv tool install ./ros-github-scripts
To upgrade an existing install after pulling new changes, add --force:
uv tool install --force ./ros-github-scripts
If the commands are not found afterwards, run uv tool update-shell and restart
your shell so uv's tool directory is on your PATH.
pipx provides the same isolated-venv behavior if you
prefer it:
pipx install ./ros-github-scripts
Standard pip install ./ros-github-scripts also still works, but you are then
responsible for providing the virtual environment yourself.
Creates a github gist containing a modified ros2.repos, with the source branches from one or more PRs. Optionally, runs ci.ros2.org jobs and comments the status badges on the PRs in question - if the user has build access to ci.ros2.org.
See ros-ci-for-pr --help for full usage.
Example average case:
export GITHUB_ACCESS_TOKEN=$GITHUB_TOKEN
ros-ci-for-pr \
--pulls ros2/rosbag2#654 \
--packages rosbag2_cpp rosbag2_tests \
--build \
--colcon-build-args="--continue-on-error" \
--comment
Note that the access token must have at least the "public_repo" permission (to be able to post comments), the "gist" permission (to be able to create gists), and the "read:org" permission (to be able to create the Jenkins job).
Important
Please use classic access token instead of fine-grained access token. (see Fine-grained personal access tokens limitations)
As an alternative to the above, a branch name can be provided using the --branch option.
CI tries to check out that branch in all ROS 2 core repositories; if such a branch exists, it then merges it into the distro's target branch and tests that.
This is useful when making changes to multiple repos at once, but it requires pushing branches to the actual repository and not a fork.
When using the --branch and --comment options, provide a list of PRs on which to comment using either --pulls or --interactive.
Example:
export GITHUB_ACCESS_TOKEN=$GITHUB_TOKEN
ros-ci-for-pr \
--branch username/multi-repo-feature \
--pulls ros2/repo1#123 ros2/repo2#456 ros2/repo3#789 \
--packages pkg1 pkg2 pkg3 \
--build \
--comment
As another alternative, a PR that is part of a GitHub PR stack can be provided using the --stack option, in the same format as --pulls.
Any PR of the stack can be provided: the whole stack is looked up, and the source branch of the top PR is used in the modified ros2.repos, so CI tests the changes from all PRs of the stack together.
When using the --comment option, the comment is posted on every open PR of the stack.
Example:
export GITHUB_ACCESS_TOKEN=$GITHUB_TOKEN
ros-ci-for-pr \
--stack ros2/repo#123 \
--packages pkg1 pkg2 \
--build \
--comment
Testing a PR stack along with other PRs is not supported for now: the --stack option cannot be combined with --pulls, --interactive, or --branch.
Also note that GitHub requires all branches of a stack to be in the same repository: stacks across forks are not supported.
Before starting a build, you are asked for confirmation if the stack targets a different branch than the selected --target release, or if the top PR is missing changes from other PRs of the stack (i.e., the stack needs to be rebased).
Generates a report of merged PRs on GitHub from a set of authors, optionally filtered by time and destination, and rendered to a variety of formats.
See ros-github-contribution-report --help for full usage.
Example average case:
ros-github-contribution-report \
--since 2021-01-01 \
--token $GITHUB_ACCESS_TOKEN \
--authors emersonknapp \
--orgs ros2 ros-tooling \
--format table \
--render > my_contributions_this_year.html
Run tests by invoking tox in the repository directory.
For an editable install of the commands while developing, use:
uv tool install --editable .