Set Up Continuous Integration and Deployment

Continuous Integration validates your Objectives on every pull request. Continuous Deployment installs validated MoveIt Pro releases on the hardware that runs them. This guide covers both halves of the pipeline.

note

The examples use GitHub Actions, but the patterns translate directly to GitLab, Jenkins, or any other CI host.

Continuous Integration

Reusable Workflows

We provide a reusable workflow for integration testing your robot configurations, running each Objective in a MoveIt Pro container in your CI pipeline. This ensures that your robot configurations are compatible with MoveIt Pro and that all Objectives are functioning as expected. To use this workflow in GitHub Actions:

jobs:
  integration-test-in-moveit-pro-container:
    uses: PickNikRobotics/moveit_pro_ci/.github/workflows/workspace_integration_test.yaml@v0.0.2
    with:
      image_tag: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.ref || github.ref_name }}
      colcon_test_args: "--executor sequential"
    secrets: inherit

For the full workflow source, visit the MoveIt Pro CI GitHub repository.

Custom Actions

We provide a custom action for linting your Objectives in a robot configuration. This action ensures that your Objectives are properly formatted and adhere to best practices. Add this job to your workflow:

jobs:
  validate_objectives:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v5
      - uses: PickNikRobotics/moveit_pro_lint@v0.0.1

For the full action source, visit the MoveIt Pro Lint GitHub repository.

Continuous Deployment

CD installs MoveIt Pro on your hardware automatically once a release is cut, so QA laptops, fleet robots, and demo machines never drift from the validated build.

Architecture

A CD pipeline for MoveIt Pro has four parts:

• Mesh VPN — gives the CI runner authenticated, encrypted access to each target machine without exposing SSH to the public internet.
• Root-owned installer wrapper (install-moveit-pro) — validates the version string, downloads the .deb to a root-owned cache, installs it, and deletes the file.
• Systemd template unit (moveit-pro@<user>.service) — runs moveit_pro run as the specified user. Does not restart on failure, so a crash surfaces as a notification instead of a silent retry loop.
• Narrow sudoers.d drop-in — grants the CI user passwordless sudo on only the installer and the systemd commands for its own unit. No wildcards, no shells.

The moveit_pro_hardware_scripts repository ships the installer, systemd unit, and sudoers template. The steps below use it directly.

Step 1 — Set up the mesh VPN

Tailscale is the recommended choice — it ships SSH with OAuth identity and tag-based ACLs, so the CI runner authenticates as a tagged machine rather than holding a long-lived SSH key.

On each target machine:

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
sudo tailscale set --ssh

Follow the authentication URL, then tag the machine (for example tag:cd-target) in the Tailscale admin console. Add an ACL rule that allows your CI runner tag to SSH as the CI user on tag:cd-target.

If your environment requires WireGuard instead, configure a point-to-point peer between the CI runner and each target machine and use standard SSH key authentication. The rest of the CD pattern is identical — only the transport and auth step change.

Step 2 — Install the hardware scripts

On the target machine:

git clone https://github.com/PickNikRobotics/moveit_pro_hardware_scripts.git
cd moveit_pro_hardware_scripts
sudo ./install.sh

install.sh:

• Copies install-moveit-pro to /usr/local/sbin/ (root-owned).
• Creates the root-owned cache directory /var/cache/moveit-pro/.
• Installs the moveit-pro@.service systemd template.
• Enables moveit-pro@<ci-user>.service for the current user.
• Drops a sudoers.d/<ci-user>-cd entry granting NOPASSWD on the installer and the user's own systemd restart/stop commands — and nothing else.

Step 3 — Provision the Endpoint Frontend Key

MoveIt Pro Runtime endpoints fail closed without MOVEIT_FRONTEND_KEY. Generate one key per deployment and install it for the systemd service:

FRONTEND_KEY="$(openssl rand -hex 32)"

# Work on a temporary copy so reruns preserve unrelated environment entries.
SYSTEMD_ENV_TMP="$(mktemp)"
trap 'rm -f "$SYSTEMD_ENV_TMP"' EXIT

if sudo test -f /etc/default/moveit-pro; then
  sudo cat /etc/default/moveit-pro > "$SYSTEMD_ENV_TMP"
fi

# Replace the current key entry while retaining every unrelated variable.
sed -i -e '/^MOVEIT_FRONTEND_KEY=/d' "$SYSTEMD_ENV_TMP"
if test -s "$SYSTEMD_ENV_TMP" && test -n "$(tail -c 1 "$SYSTEMD_ENV_TMP")"; then
  printf '\n' >> "$SYSTEMD_ENV_TMP"
fi
printf 'MOVEIT_FRONTEND_KEY=%s\n' "$FRONTEND_KEY" >> "$SYSTEMD_ENV_TMP"

# systemd reads this root-owned environment file before dropping privileges.
sudo install -m 0640 -o root -g root \
  "$SYSTEMD_ENV_TMP" /etc/default/moveit-pro
rm -f "$SYSTEMD_ENV_TMP"
trap - EXIT
unset FRONTEND_KEY

This systemd workflow starts Compose without the MoveIt Pro CLI, so rotate its key by repeating this step, restarting the service, and updating its clients. See Endpoint Security for certificate overrides and the self-signed development certificate model.

Step 4 — Verify passwordless sudo

Confirm the CI user can run the installer without a password prompt before wiring up the runner:

sudo -n /usr/local/sbin/install-moveit-pro 9.4.1

A password prompt means the sudoers drop-in did not land. Re-run install.sh and check visudo -c.

Step 5 — Wire up the CI runner

The following GitHub Actions job authenticates to Tailscale, validates the version, installs the release, and restarts the service:

jobs:
  deploy:
    runs-on: ubuntu-22.04
    steps:
      - name: Authenticate to Tailscale
        uses: tailscale/github-action@v3
        with:
          oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }}
          oauth-secret: ${{ secrets.TS_OAUTH_SECRET }}
          tags: tag:ci-runner

      - name: Install MoveIt Pro
        run: |
          tailscale ssh ${{ vars.CI_USER }}@${{ vars.TARGET_HOST }} \
            sudo -n /usr/local/sbin/install-moveit-pro ${{ inputs.version }}

      - name: Restart service
        run: |
          tailscale ssh ${{ vars.CI_USER }}@${{ vars.TARGET_HOST }} \
            sudo -n /bin/systemctl restart moveit-pro@${{ vars.CI_USER }}.service

The install and restart steps use sudo -n so the job fails immediately if passwordless sudo is misconfigured instead of hanging for a password prompt.

To kick off an Objective right after install, add a step that sends a /do_objective goal from a native ROS 2 client on the robot network. See Run an Existing Objective for an rclpy client and for the ros2 action send_goal command line. Detach the call so the SSH session returns while the Objective keeps running on the target machine after the CD job exits.

Example smoke-test scripts

The example_scripts/ directory in moveit_pro_hardware_scripts ships a small set of reference scripts that show how to drive an Objective from CD. install.sh copies them to /usr/bin/, where a CD job can invoke them over SSH — see the transport caveat below before you do:

• 3-waypoint-pick-and-place.py — runs the 3 Waypoints Pick and Place Objective.
• ml-segment-image.py — runs the ML Segment Image Loop Objective. Exercises the inference path on a GPU-enabled target.
• move-all-boxes.py — runs the Move Boxes Looping Objective. Long-running mobile-manipulation soak.

Each script is a two-line wrapper around cd_objective_lib.py's run_objective(<name>):

#!/usr/bin/env python3
import sys

sys.path.insert(0, "/usr/lib/moveit-pro-scripts")

from cd_objective_lib import run_objective

if __name__ == "__main__":
    run_objective("3 Waypoints Pick and Place")

cd_objective_lib.py handles the heavy lifting: it waits up to one hour for rosbridge on port 3201, which it hard-codes, then connects via roslibpy, waits for the /do_objective action server, sends the goal, and returns. On any timeout it stops moveit-pro@<user>.service and posts a Slack notification (set SLACK_WEBHOOK_URL in /etc/default/moveit-pro to enable the post).

Example scripts predate the current web bridge

Port 3201 serves the Foxglove WebSocket protocol over TLS and requires MOVEIT_FRONTEND_KEY; this release ships no rosbridge endpoint. The example scripts speak the rosbridge JSON protocol through roslibpy, so they do not connect to this release as written. Drive Objectives from a native ROS 2 client with rclpy instead. See Migrating rosbridge Clients.

The library also exposes run_objectives_forever([...]) for chaining multiple Objectives in a loop — useful for QA soak tests against Behavior Trees that do not self-loop.

Driving Objectives from your own scripts

The example scripts use roslibpy (Python) because the CD job already routes over SSH and a websocket was the simplest cross-network transport. As noted above, that path no longer reaches this release's web bridge — send the same goal from a native ROS 2 client with rclpy.

For the full reference of the /do_objective action, cancellation, and blackboard parameter overrides, see Run an Existing Objective. The Programmatic SDKs Overview covers client setup.