github action to build .deb packages from ROS sources

This repository provides actions and resusable workflows helping to build Debian packages from ROS package sources.

For convenience, the built packages from ros-one.repos are deployed to https://ros.packages.techfak.net.
If you want any other packages to be included in the repository, please open an issue or pull request.

Interactive build workflow

For building a ROS distro it is recommended to use the high-level interactive.yaml workflow. This manually triggered workflow builds all packages from the given source(s) and provides the resulting .debs as an artifact. Optionally, the .debs can be deployed to a github repo. However, using github for this purpose is not recommended (slow and size limitations). Better use a dedicated repository server like aptly or reprepro. The reprepro-import.sh script helps with the latter.

What to build?

ROS_SOURCES specifies a (space-separated) list of inputs. Usually these should be .repos or .rosinstall files suitable for vcs import. However, an URL pointing to a release .tar.gz or a github repository is also supported. In the latter case, use the following scheme: github:organization/repo#version. Other URLs are interpreted as inputs for vcs import.

A subset of packages can be selected via colcon package selection options specified in COLCON_PKG_SELECTION. For example:

• To rebuild a specific package and all its downstream dependencies:
  --packages-above-and-dependencies <pkg ...>
• To rebuild a single package (only use if ABI/API hasn't changed):
  --packages-select <pkg ...>

Where to start building from?

Building a complete ROS distro from scratch takes a lot of time, often more than the 6 hours allowed by default GHA runners. For this reason, it is possible to continue a build either from a previous build (downloading an existing debs artifact) or from an existing repository. For the former, set the input DOWNLOAD_DEBS=true, for the latter add the deploy repository to EXTRA_DEB_SOURCES. Note that this variable supports shell variable expansion, i.e. you can use $DEB_DISTRO and/or $ROS_DISTRO to generically specify the deploy repository across different builds. In both cases, set the variable/input SKIP_EXISTING=true to actually skip building already existing packages.

In the interactive.yaml workflow, a combination of these options is offered:

• Tick option Continue from previous build to draw on https://ros.packages.techfak.net (or untick to trigger a clean build from sratch).
• Tick option Skip already built packages? to skip existing packages (or untick to enforce a rebuild).
• Simply rerun the workflow to automatically continue building a previous build that was cancelled due to a timeout.

Reusable workflows build.yaml + deploy.yaml

These workflows are intended for reuse by an external repository to build a custom list of ROS packages. The build workflow stores created .debs as an artifact that can be manually downloaded or automatically uploaded to a repository server (via the deploy workflow) subsequently.

A simple usage example looks like this:

jobs:
  build:
    uses: ubi-agni/ros-builder-action/.github/workflows/build.yaml@main
    with:
      ROS_SOURCES: '*.repos'

  deploy:
    needs: build
    if: always()
    uses: ubi-agni/ros-builder-action/.github/workflows/deploy.yaml@main
    with:
      DEPLOY_URL: ${{ vars.DEPLOY_URL || 'self' }}
      TOKEN: ${{ secrets.GITHUB_TOKEN }}                  # used for own repo
      SSH_PRIVATE_KEY: ${{ secrets.DEPLOY_PRIVATE_KEY }}  # used for other repo

More complex usage examples can be found in interactive.yaml or splitted.yaml.

Environment variables

The build process is controlled by several environment variables. Usually, those environment variables are inititialized from inputs, repository variables, or the given default value - in that order.

variable	type	default	semantics
ROS_DISTRO	string	one	ROS distribution codename to compile for
DEB_DISTRO	string	jammy	The Debian/Ubuntu distribution codename to compile for.
ROS_SOURCES	string	*.repos	ROS sources to compile
COLCON_PKG_SELECTION	string		colcon package selectio argument(s)
	Workflow control
SKIP_EXISTING	boolean	false	Skip (re)building packages already existing in the repository
DOWNLOAD_DEBS	boolean	false	Continue building from previous debs artifact?
BUILD_TIMEOUT	number	340	Cancel build after this time, before github will do (minutes)
CONTINUE_ON_ERROR	boolean	false	Continue building even if some packages already failed
	Package source options
EXTRA_DEB_SOURCES	string		Extra debian sources to use in host and sbuild chroot
INSTALL_GPG_KEYS	string		code to run for installing GPG keys (for use with EXTRA_DEB_SOURCES)
EXTRA_ROSDEP_SOURCES	string		path to a rosdep-compatible yaml file specifying custom dependency mappings
	Package source options
EXTRA_SBUILD_CONFIG	string		lines to add to ~/.sbuildrc
EXTRA_SBUILD_OPTS	string		options to pass to sbuild on commandline
DEB_BUILD_OPTIONS	string	nocheck	options used debian/rules
	Deployment variables
DEBS_PATH	string	~/debs	path to store generated .debs in
DEPLOY_URL	string		repository URL for deployment
DEPLOY_FILES	string	deb	list of file types to deploy: deb, ddeb, dsc, changes
DEPLOY_FILE_SIZE_LIMIT	string		size limit for files (100M on github)
TOKEN	secret	secrets.GITHUB_TOKEN	github token for pushing to own repo
SSH_PRIVATE_KEY	secret		ssh private key for pushing to an external repo
	Debugging options
VERBOSE	string		verboseness for all (value true) or selected steps (bloom sbuild apt ccache)
TRACE	boolean	false	Enable function tracing
DEBUG_BASH	boolean	false	Enable bash debugging (set -x) and tracing

Where to deploy?

The built packages can be deployed to a flat Debian repository, for example on a github branch. The easiest way to do so is to specify DEPLOY_URL=self, causing deployment to the active github repository into the branch $DEB_DISTRO-$ROS-DISTRO. However, you can also specify another github repo.