Skip to content

About

Utility scripts to ease management of GitHub projects for ROS / ROS 2

Resources

Stars

10 stars

Watchers

5 watching

Forks

Latest commit

 

History

47 Commits

Folders and files

Repository files navigation

ros-github-scripts

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.

Installation

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.

ros-ci-for-pr

With a list of PRs

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)

With a branch name

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

With a GitHub PR stack

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).

ros-github-contribution-report

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

Developing

Run tests by invoking tox in the repository directory.

For an editable install of the commands while developing, use:

uv tool install --editable .

About

Utility scripts to ease management of GitHub projects for ROS / ROS 2

Resources

Stars

10 stars

Watchers

5 watching

Forks

Releases

Packages

Used by

Contributors

Languages