cross-repo-workflows.md
1 # Cross-Repository Workflows 2 3 **Part of Phase 4: Repository Organization** 4 5 Guide for working with multiple Radicle repositories and shared tooling. 6 7 --- 8 9 ## Overview 10 11 Auxo's Radicle infrastructure supports multiple private repositories with shared CI/CD and workflow tools. 12 13 **Current Repositories**: 14 - `auxo-radicle-infrastructure` (rad:z2s159BoUPWefbmtu6s5DV5vvxymy) - Infrastructure and tooling 15 - `auxo-private-demo` (rad:z42aAW4f8gz6yMJ8DvLywsYgonckF) - Demo repository 16 - `unichrome` (rad:z3UNm83nRGt1o6powt9wUp5DpRou) - HEX Registry 17 18 --- 19 20 ## Shared Infrastructure 21 22 ### CI/CD System 23 24 All repositories can use the same CI infrastructure: 25 26 **Webhook Server** (`~/radicle-ci/ci-webhook-server.py`): 27 - Handles CI trigger events from any repository 28 - Single server instance serves all repos 29 - Runs on port 8888 30 31 **Notification Server** (`~/radicle-ci/notification-server.py`): 32 - Sends build notifications for all repositories 33 - Supports macOS, Slack, Discord, Email 34 - Runs on port 9000 35 36 **Docker Image** (`auxo-radicle-ci:latest`): 37 - Custom image with bash + shellcheck 38 - Used by all repositories for CI validation 39 - Built once, used everywhere 40 41 ### Workflow Scripts 42 43 Workflow scripts in `auxo-radicle-infrastructure/scripts/workflow/` work across all Radicle repos: 44 45 ```bash 46 # Works in any Radicle repository directory 47 ./path/to/auxo-radicle-infrastructure/scripts/workflow/sync-status.sh 48 ./path/to/auxo-radicle-infrastructure/scripts/workflow/list-patches.sh 49 ./path/to/auxo-radicle-infrastructure/scripts/workflow/ci-status.sh 50 ``` 51 52 --- 53 54 ## Working Across Repositories 55 56 ### Scenario 1: Create Patch in One Repo, Reference Another 57 58 ```bash 59 # In unichrome repository 60 git checkout -b feature/use-shared-script 61 62 # Reference script from infrastructure repo 63 ln -s ../../auxo-radicle-infrastructure/scripts/workflow/create-patch.sh scripts/ 64 65 # Commit and create patch 66 git add . 67 git commit -m "feat: Use shared workflow script" 68 rad patch create "feat: Use shared workflow script" 69 ``` 70 71 ### Scenario 2: Coordinated Changes Across Repos 72 73 ```bash 74 # Make changes in repo 1 75 cd auxo-radicle-infrastructure 76 git checkout -b feature/update-ci-image 77 # ... make changes ... 78 git commit -m "feat: Update CI Docker image" 79 rad patch create "feat: Update CI Docker image" 80 81 # Make corresponding changes in repo 2 82 cd ../unichrome 83 git checkout -b feature/use-new-ci-image 84 # Update .radicle/ci.yaml to use new image 85 git commit -m "feat: Adopt new CI image" 86 rad patch create "feat: Adopt new CI image" 87 88 # Link patches in comments 89 rad patch comment <patch-1-id> -m "Related: unichrome patch <patch-2-id>" 90 rad patch comment <patch-2-id> -m "Depends on: infrastructure patch <patch-1-id>" 91 ``` 92 93 ### Scenario 3: Shared Configuration 94 95 **Option A: Symbolic Links** 96 ```bash 97 # Link shared config from infrastructure repo 98 cd unichrome 99 ln -s ../auxo-radicle-infrastructure/.radicle/docker Dockerfile.ci 100 ``` 101 102 **Option B: Git Submodules** 103 ```bash 104 # Add infrastructure repo as submodule 105 cd unichrome 106 git submodule add rad://z2s159BoUPWefbmtu6s5DV5vvxymy .radicle/shared 107 ``` 108 109 **Option C: Copy on Setup** 110 ```bash 111 # Copy templates when initializing new repo 112 cp -r auxo-radicle-infrastructure/templates/radicle-repo/.radicle new-project/ 113 ``` 114 115 --- 116 117 ## Repository Templates 118 119 Use the template to create new Radicle repositories: 120 121 ```bash 122 cd auxo-radicle-infrastructure/templates/radicle-repo 123 ./init-radicle-repo.sh my-new-project "Description of my project" 124 ``` 125 126 This creates: 127 - Git repository with initial commit 128 - Radicle repository (private by default) 129 - CI/CD configuration 130 - Webhook setup 131 - README with best practices 132 - .gitignore 133 134 --- 135 136 ## CI/CD Setup for New Repository 137 138 ### 1. Copy CI Configuration 139 140 ```bash 141 # From within your new repository 142 cp ../auxo-radicle-infrastructure/templates/radicle-repo/.radicle/ci.yaml .radicle/ 143 cp -r ../auxo-radicle-infrastructure/templates/radicle-repo/.radicle/webhooks .radicle/ 144 ``` 145 146 ### 2. Customize for Your Project 147 148 Edit `.radicle/ci.yaml` based on your project type: 149 150 **For Shell Scripts** (default): 151 ```yaml 152 image: auxo-radicle-ci:latest 153 # Validation steps are built into the CI runner 154 ``` 155 156 **For Node.js/TypeScript**: 157 ```yaml 158 image: node:20-alpine 159 # Add custom validation steps 160 ``` 161 162 **For Python**: 163 ```yaml 164 image: python:3.11-slim 165 # Add custom validation steps 166 ``` 167 168 ### 3. Test CI 169 170 ```bash 171 # Create a test patch 172 git checkout -b test/ci-validation 173 echo "#!/bin/bash\necho 'test'" > scripts/test.sh 174 git add . 175 git commit -m "test: Validate CI setup" 176 rad patch create "test: Validate CI setup" 177 178 # CI will automatically run and post results 179 ``` 180 181 --- 182 183 ## Multi-Node Sync 184 185 ### Tailscale Mesh Network 186 187 All Radicle nodes are connected via Tailscale for private repository sync: 188 189 ```bash 190 # Check Tailscale status 191 tailscale status 192 193 # Ping other node 194 tailscale ping macbook2 195 ``` 196 197 ### Syncing Private Repos 198 199 ```bash 200 # On primary node (MacBook 1) 201 cd auxo-radicle-infrastructure 202 git push rad main 203 204 # On secondary node (MacBook 2) 205 # Repository will sync automatically via Tailscale mesh 206 207 # Manual sync if needed 208 rad sync 209 ``` 210 211 --- 212 213 ## Best Practices 214 215 ### 1. Centralize Shared Tools 216 217 Keep reusable scripts, configurations, and documentation in `auxo-radicle-infrastructure`. 218 219 ### 2. Version Control CI Changes 220 221 When updating CI infrastructure: 222 1. Update in `auxo-radicle-infrastructure` first 223 2. Create patch and get it approved 224 3. Roll out to other repos after testing 225 226 ### 3. Document Cross-Repo Dependencies 227 228 Use patch comments to link related changes: 229 ```bash 230 rad patch comment <patch-id> -m "Requires: repo-name patch <other-patch-id>" 231 ``` 232 233 ### 4. Consistent Naming 234 235 Use consistent branch and patch naming across repos: 236 - `feature/*` - New features 237 - `fix/*` - Bug fixes 238 - `docs/*` - Documentation 239 - `chore/*` - Maintenance 240 241 ### 5. Private by Default 242 243 Always use `--private` flag when creating new repositories: 244 ```bash 245 rad init --private 246 ``` 247 248 --- 249 250 ## Troubleshooting 251 252 ### CI Not Triggering 253 254 1. Check webhook server is running: 255 ```bash 256 lsof -i :8888 257 ``` 258 259 2. Verify webhook configuration: 260 ```bash 261 cat .radicle/webhooks/ci.yaml 262 ``` 263 264 3. Check CI logs: 265 ```bash 266 tail -f ~/radicle-ci/logs/ci-webhook-server.log 267 ``` 268 269 ### Repository Not Syncing 270 271 1. Check Tailscale connectivity: 272 ```bash 273 tailscale status 274 tailscale ping <node-name> 275 ``` 276 277 2. Verify repository is private: 278 ```bash 279 rad . | grep -i visibility 280 ``` 281 282 3. Check Radicle node is running: 283 ```bash 284 rad self 285 ``` 286 287 --- 288 289 ## Example: Adding CI to Existing Repository 290 291 ```bash 292 # Navigate to repository 293 cd unichrome 294 295 # Copy CI templates 296 mkdir -p .radicle/webhooks 297 cp ../auxo-radicle-infrastructure/templates/radicle-repo/.radicle/ci.yaml .radicle/ 298 cp ../auxo-radicle-infrastructure/templates/radicle-repo/.radicle/webhooks/ci.yaml .radicle/webhooks/ 299 300 # Commit CI setup 301 git add .radicle/ 302 git commit -m "ci: Add Radicle CI configuration" 303 git push rad main 304 305 # Test with a patch 306 git checkout -b test/ci 307 echo "test" > test.txt 308 git add test.txt 309 git commit -m "test: Validate CI" 310 rad patch create "test: Validate CI" 311 312 # CI should run and post results 313 rad patch show <patch-id> 314 ``` 315 316 --- 317 318 ## Links 319 320 - [Main Infrastructure Repo](rad:z2s159BoUPWefbmtu6s5DV5vvxymy) 321 - [Template Repository](../templates/radicle-repo/) 322 - [Workflow Scripts](../scripts/workflow/) 323 - [CI Documentation](./notifications.md) 324 325 --- 326 327 **Last Updated**: November 12, 2025 328 **Maintained By**: Project Auxo Inc.