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 --no-browser as the specified user. Restarts on failure.
• 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

Backend endpoints fail closed without MOVEIT_FRONTEND_KEY. Generate one key per deployment and install it for both the systemd service and the unprivileged smoke-test process:

FRONTEND_KEY="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"

# Work on temporary copies so reruns preserve unrelated environment entries.
install -d -m 0700 "$HOME/.config/moveit_pro"
SYSTEMD_ENV_TMP="$(mktemp)"
SMOKE_ENV_TMP="$(mktemp "$HOME/.config/moveit_pro/cd.env.XXXXXX")"
trap 'rm -f "$SYSTEMD_ENV_TMP" "$SMOKE_ENV_TMP"' EXIT

if sudo test -f /etc/default/moveit-pro; then
  sudo cat /etc/default/moveit-pro > "$SYSTEMD_ENV_TMP"
fi
if test -f "$HOME/.config/moveit_pro/cd.env"; then
  cat "$HOME/.config/moveit_pro/cd.env" > "$SMOKE_ENV_TMP"
fi

# Replace the current/legacy key entries while retaining every unrelated variable.
sed -i -e '/^MOVEIT_FRONTEND_KEY=/d' -e '/^MOVEIT_API_KEY=/d' \
  "$SYSTEMD_ENV_TMP" "$SMOKE_ENV_TMP"
for ENV_TMP in "$SYSTEMD_ENV_TMP" "$SMOKE_ENV_TMP"; do
  if test -s "$ENV_TMP" && test -n "$(tail -c 1 "$ENV_TMP")"; then
    printf '\n' >> "$ENV_TMP"
  fi
done
printf 'MOVEIT_FRONTEND_KEY=%s\n' "$FRONTEND_KEY" | \
  tee -a "$SYSTEMD_ENV_TMP" "$SMOKE_ENV_TMP" > /dev/null

# 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

# Detached smoke tests run as the CI user, outside systemd.
install -m 0600 "$SMOKE_ENV_TMP" "$HOME/.config/moveit_pro/cd.env"
rm -f "$SYSTEMD_ENV_TMP" "$SMOKE_ENV_TMP"
trap - EXIT
unset FRONTEND_KEY

Keep the same key in both files. See Endpoint Security for certificate overrides, key rotation, and the self-signed development certificate model.

After the backend has started once, install the certificate for the unprivileged Node.js smoke-test process. For the generated loopback certificate:

install -m 0644 "$HOME/.local/share/moveit_pro/tls/cert.pem" \
  "$HOME/.config/moveit_pro/backend-ca.pem"
printf 'NODE_EXTRA_CA_CERTS=%s\n' \
  "$HOME/.config/moveit_pro/backend-ca.pem" >> \
  "$HOME/.config/moveit_pro/cd.env"

For an operator certificate, copy its issuing CA certificate instead. Node reads NODE_EXTRA_CA_CERTS when the smoke-test process starts, so the detached client validates TLS without a verification bypass.

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, append a detached SSH call:

      - name: Smoke-test the deploy
        run: |
          tailscale ssh ${{ vars.CI_USER }}@${{ vars.TARGET_HOST }} \
            "set -a; . ~/.config/moveit_pro/cd.env; set +a; \
             setsid -f /usr/bin/3-waypoint-pick-and-place.mjs </dev/null >/tmp/cd-objective.log 2>&1"

The SSH session returns immediately; 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/ so the CD job can invoke them directly over SSH:

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

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

#!/usr/bin/env node
import { runObjective } from "/usr/lib/moveit-pro-scripts/cd_objective_lib.mjs";

await runObjective("3 Waypoints Pick and Place");

cd_objective_lib.mjs handles the heavy lifting: it waits up to one hour for the web bridge (foxglove_bridge, port 3201) to open, connects via foxglove-ros-adapter, waits for the /do_objective action server, sends the goal, and returns. The library must read MOVEIT_FRONTEND_KEY, URL-encode it, and connect to wss://localhost:3201/?token=${encodeURIComponent(process.env.MOVEIT_FRONTEND_KEY)}. For a generated self-signed certificate, the SSH-local smoke-test client must explicitly trust that certificate or use its narrowly scoped development insecure-TLS option; do not disable verification for deployments with an operator-supplied trusted certificate. 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).

No sidecar needed

The scripts speak the Foxglove protocol to the always-on web bridge on 3201, so the target needs no --enable-rosbridge flag and no rosbridge_server. foxglove-ros-adapter is the Foxglove-native drop-in for roslibjs; see Legacy Websocket Compatibility for the full client mapping.

The library also exposes runObjectivesForever([...]) 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 foxglove-ros-adapter (Node) because the CD job already routes over SSH and a websocket is the simplest cross-network transport — connecting to the always-on web bridge on 3201. The same goal can be sent from a native ROS 2 client with rclpy, or from any other websocket client — the action interface is identical across transports.

For the full reference of the /do_objective action, cancellation, blackboard parameter overrides, and side-by-side rclpy / roslibpy examples, see Run an Existing Objective. The Programmatic SDKs Overview covers when to pick each transport.