Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
160 changes: 93 additions & 67 deletions .github/workflows/build-ubuntu20.yml
Original file line number Diff line number Diff line change
@@ -1,85 +1,111 @@
name: Build Ubuntu 20.04 binaries

# Triggered manually for binary releases; see OPEN_SOURCE_AUDIT.md.

on:
workflow_dispatch:
inputs:
ref:
description: Git ref to build
description: Existing annotated vX.Y.Z tag from the selected Forge line
required: true
default: v1.0.0
type: string
version:
description: Release version without the v prefix
description: Exact node version in the tag and source manifest (not the Forge line)
required: true
default: 1.0.0

type: string
release_line:
description: Forge compatibility line
required: true
type: choice
options:
- 1.x
- 2.x
default: 1.x
workflow_call:
inputs:
ref:
description: Existing annotated vX.Y.Z tag from the selected Forge line
required: true
type: string
version:
description: Exact node version in the tag and source manifest (not the Forge line)
required: true
type: string
release_line:
description: Forge compatibility line
required: true
type: string
permissions:
contents: read

jobs:
build:
runs-on: ubuntu-latest
container:
image: ubuntu:20.04
env:
RELEASE_VERSION: ${{ inputs.version }}
RELEASE_TAG: ${{ inputs.ref }}
RELEASE_LINE: ${{ inputs.release_line }}
steps:
- name: Install system tools
run: |
apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y \
binutils \
ca-certificates \
curl \
file \
git
rm -rf /var/lib/apt/lists/*

- uses: actions/checkout@v6
with:
ref: ${{ inputs.ref }}

- name: Install uv and Python 3.12
run: |
curl -LsSf https://astral.sh/uv/0.12.5/install.sh |
env UV_INSTALL_DIR=/usr/local/bin sh
uv python install 3.12
uv --version
uv run --no-project --python 3.12 python --version

- name: Build with PyInstaller
run: ./scripts/build_pyinstaller.sh

- name: Verify and package binaries
run: |
test "${{ inputs.ref }}" = "v${RELEASE_VERSION}"
./dist/joint_trajectory_controller --help >/dev/null
./dist/gripper_action_controller --help >/dev/null
./dist/fake_joint_plant --help >/dev/null
file ./dist/joint_trajectory_controller ./dist/gripper_action_controller ./dist/fake_joint_plant
ldd --version | sed -n '1p'
archive="forge-controls-v${RELEASE_VERSION}-ubuntu20.04-x86_64.tar.gz"
tar \
--sort=name \
--mtime='UTC 1970-01-01' \
--owner=0 \
--group=0 \
--numeric-owner \
-C dist \
-czf "${archive}" \
joint_trajectory_controller \
gripper_action_controller \
fake_joint_plant
sha256sum "${archive}" > "${archive}.sha256"
tar -tzf "${archive}"
sha256sum --check "${archive}.sha256"

- uses: actions/upload-artifact@v6
with:
name: forge-controls-v${{ inputs.version }}-ubuntu20.04-x86_64
path: |
forge-controls-v${{ inputs.version }}-ubuntu20.04-x86_64.tar.gz
forge-controls-v${{ inputs.version }}-ubuntu20.04-x86_64.tar.gz.sha256
if-no-files-found: error
retention-days: 30
- name: Install system tools
run: |
apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y \
binutils \
ca-certificates \
curl \
file \
git
rm -rf /var/lib/apt/lists/*
- uses: actions/checkout@v6
with:
ref: refs/tags/${{ inputs.ref }}
fetch-depth: 0
persist-credentials: false
- name: Check out release tooling from the workflow commit
uses: actions/checkout@v6
with:
ref: ${{ github.workflow_sha }}
path: .release-tools
persist-credentials: false
- name: Install uv and Python 3.12
run: |
curl -LsSf https://astral.sh/uv/0.12.5/install.sh |
env UV_INSTALL_DIR=/usr/local/bin sh
uv python install 3.12
uv --version
uv run --no-project --python 3.12 python --version
- name: Validate Forge release line and source version
run: |
git config --global --add safe.directory "$(pwd -P)"
uv run --no-project --python 3.12 python .release-tools/scripts/check_release_line.py --line "$RELEASE_LINE" --tag "$RELEASE_TAG" --version "$RELEASE_VERSION" --default-branch main
- name: Build with PyInstaller
run: ./scripts/build_pyinstaller.sh
- name: Verify and package binaries
run: |
test "${RELEASE_TAG}" = "v${RELEASE_VERSION}"
./dist/joint_trajectory_controller --help >/dev/null
./dist/gripper_action_controller --help >/dev/null
./dist/fake_joint_plant --help >/dev/null
file ./dist/joint_trajectory_controller ./dist/gripper_action_controller ./dist/fake_joint_plant
ldd --version | sed -n '1p'
archive="forge-controls-v${RELEASE_VERSION}-ubuntu20.04-x86_64.tar.gz"
tar \
--sort=name \
--mtime='UTC 1970-01-01' \
--owner=0 \
--group=0 \
--numeric-owner \
-C dist \
-czf "${archive}" \
joint_trajectory_controller \
gripper_action_controller \
fake_joint_plant
sha256sum "${archive}" > "${archive}.sha256"
tar -tzf "${archive}"
sha256sum --check "${archive}.sha256"
- uses: actions/upload-artifact@v6
with:
name: forge-controls-v${{ inputs.version }}-ubuntu20.04-x86_64
path: |
forge-controls-v${{ inputs.version }}-ubuntu20.04-x86_64.tar.gz
forge-controls-v${{ inputs.version }}-ubuntu20.04-x86_64.tar.gz.sha256
if-no-files-found: error
retention-days: 30
24 changes: 24 additions & 0 deletions .github/workflows/release-checks.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
name: Release line checks
on:
pull_request:
paths:
- '.github/workflows/**'
- 'scripts/check_release_line.py'
- 'scripts/test_release_line.py'
push:
paths:
- '.github/workflows/**'
- 'scripts/check_release_line.py'
- 'scripts/test_release_line.py'
permissions:
contents: read
jobs:
release-line-checks:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v6
with:
python-version: '3.12'
- name: Test source selection, versions and Forge/Dora compatibility
run: python -m unittest discover -s scripts -p test_release_line.py -v
126 changes: 126 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
name: Build versioned release
on:
workflow_dispatch:
inputs:
release_line:
description: Forge compatibility line (independent of the node version)
type: choice
options:
- 1.x
- 2.x
default: 1.x
required: true
tag:
description: Existing annotated vX.Y.Z tag on the selected release line
type: string
required: true
build_binaries:
description: Include the existing Ubuntu binary build where available
type: boolean
default: false
permissions:
contents: read
concurrency:
group: release-${{ inputs.tag }}
cancel-in-progress: false
jobs:
packages:
runs-on: ubuntu-latest
outputs:
version: ${{ steps.release.outputs.version }}
steps:
- uses: actions/checkout@v6
with:
ref: refs/tags/${{ inputs.tag }}
fetch-depth: 0
persist-credentials: false
- name: Check out release tooling from the workflow commit
uses: actions/checkout@v6
with:
ref: ${{ github.workflow_sha }}
path: .release-tools
persist-credentials: false
- uses: actions/setup-python@v6
with:
python-version: '3.12'
- name: Validate release line and immutable source
id: release
env:
RELEASE_LINE: ${{ inputs.release_line }}
RELEASE_TAG: ${{ inputs.tag }}
run: python .release-tools/scripts/check_release_line.py --line "$RELEASE_LINE" --tag "$RELEASE_TAG" --default-branch main
- name: Build source archive and Python distributions when supported
env:
RELEASE_TAG: ${{ inputs.tag }}
RELEASE_LINE: ${{ inputs.release_line }}
PACKAGE_KIND: ${{ steps.release.outputs.package_kind }}
run: |
set -euo pipefail
mkdir -p release-assets
name="${GITHUB_REPOSITORY#*/}"
git archive --format=tar.gz --prefix="${name}-${RELEASE_TAG}/" \
--output="release-assets/${name}-forge-${RELEASE_LINE}-${RELEASE_TAG}-source.tar.gz" HEAD
if [ "$PACKAGE_KIND" = python ]; then
python -m pip install uv==0.13.7
uv build --no-sources --out-dir release-assets
python -m pip install twine==7.0.0
python -m twine check release-assets/*.whl release-assets/*[0-9].tar.gz
fi
python .release-tools/scripts/check_release_line.py \
--line "$RELEASE_LINE" --tag "$RELEASE_TAG" \
--default-branch main > release-assets/release-metadata.json
(cd release-assets && sha256sum ./* > source-SHA256SUMS.txt)
- uses: actions/upload-artifact@v6
with:
name: release-source-${{ inputs.release_line }}-${{ inputs.tag }}
path: release-assets/*
if-no-files-found: error
binaries:
needs: packages
if: ${{ inputs.build_binaries }}
permissions:
contents: read
uses: ./.github/workflows/build-ubuntu20.yml
with:
ref: ${{ inputs.tag }}
version: ${{ needs.packages.outputs.version }}
release_line: ${{ inputs.release_line }}
draft:
needs:
- packages
- binaries
if: ${{ always() && needs.packages.result == 'success' && (needs.binaries.result == 'success' || needs.binaries.result == 'skipped') }}
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/download-artifact@v6
with:
path: release-assets
merge-multiple: true
- name: Verify assets and attach to a draft without replacing published files
env:
GH_TOKEN: ${{ github.token }}
GH_REPO: ${{ github.repository }}
RELEASE_TAG: ${{ inputs.tag }}
RELEASE_LINE: ${{ inputs.release_line }}
run: |
set -euo pipefail
cd release-assets
sha256sum --check source-SHA256SUMS.txt
for checksum in ./*.sha256; do
[ -e "$checksum" ] || continue
sha256sum --check "$checksum"
done
if gh release view "$RELEASE_TAG" --json isDraft --jq .isDraft > /tmp/release-draft-state 2>/tmp/release-lookup-error; then
test "$(cat /tmp/release-draft-state)" = true
elif grep -qi 'release not found' /tmp/release-lookup-error; then
printf 'Forge %s release candidate from %s.\n\nUse peers and Dora from the same compatibility line. Build success does not establish hardware, model, sustained-run or rollback acceptance. Review the workflow results before publishing.\n' \
"$RELEASE_LINE" "$RELEASE_TAG" > /tmp/release-notes
gh release create "$RELEASE_TAG" --verify-tag --draft --latest=false \
--title "$RELEASE_TAG (Forge $RELEASE_LINE)" --notes-file /tmp/release-notes
else
cat /tmp/release-lookup-error >&2
exit 1
fi
gh release upload "$RELEASE_TAG" ./*
29 changes: 29 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Forge Controls

[English](README.md) | [简体中文](README_zh.md)

Reusable motion execution and control capabilities for Forge/Dora robotics dataflows.

The workspace provides lightweight motion controllers that consume Dora action payloads from
Expand Down Expand Up @@ -34,3 +36,30 @@ It also checks that missing or invalid required arguments produce argparse exit
this source repository and retain their respective licenses; see
[NOTICE](NOTICE) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
Review the complete bundled artifact before publishing standalone executables.

## Versioned releases

**Mandatory tag-first release rule:** merge the version/lock change, create an annotated version tag on that reviewed commit, build that exact tag, validate the artifacts, then publish. Moving branch names, untagged commit IDs and replacement of published tags are not release inputs.

| Release line | Source | Node/package version | Runtime |
| --- | --- | --- | --- |
| Forge 1.x | `stable/1.x` | `1.x`, tag `v1.X.Y` | Forge 1.x / Dora 0.4.x |
| Forge 2.x | `main` | `2.x`, tag `v2.X.Y` | Forge 2.x / Dora 1.x |

**Legacy normalization:** nodes previously at 0.x on `stable/1.x` release as **1.0.0**, retaining Forge 1.x / Dora 0.4.x dependencies and runtime behavior. Existing 1.x package versions are retained. Node/package majors now follow the Forge compatibility line; a 0.x tag is rejected.

Run **Build versioned release** from `main` for either line. First merge the version/lock changes into the selected source branch, then create an unused **annotated** tag on that reviewed commit. The tag must match package metadata. Never move existing tags or reuse a published version. Dispatch uses the workflow's reviewed tooling with the exact tagged source, so legacy tags need not contain the new release helper.

```bash
# Replace with an existing, reviewed and unpublished tag matching source metadata.
TAG=v1.0.0
gh workflow run release.yml --ref main -f release_line=1.x -f tag="$TAG"
TAG=v2.X.Y
gh workflow run release.yml --ref main -f release_line=2.x -f tag="$TAG"
```

The workflow verifies tag type, source commit, branch ancestry, source version and locked Forge/Dora compatibility. It builds source archives and wheel/sdist where supported, checks Python distribution metadata and SHA-256, and creates or attaches to a **draft GitHub Release**. Published releases/assets are not overwritten; review all build results and acceptance evidence before publishing. This workflow does not publish node packages to PyPI.

Set `build_binaries=true` to call the existing Ubuntu 20.04 binary workflow; its existing architecture, CLI and archive checks remain in force. You can also run `build-ubuntu20.yml` directly with `ref`, `version` and `release_line`; `ref` must be an annotated tag, not a moving branch. Binary artifacts are attached only after all selected jobs succeed.

The source archive preserves the tagged tree; external SDKs/submodules, model downloads and site configuration remain separate prerequisites. A dependency or SDK build failure is not successful release acceptance. Build success does not establish single-node or Gateway-chain `dora run`, hardware, real-model, sustained-run or rollback acceptance. Every acceptance chain must include `adapter-forge-gateway` from the same compatibility line. Forge 2.x is a **breaking change**: align Forge libraries, node versions and Dora across the entire deployment; keep 1.x on its maintenance branch.
Loading