feat: automate artifact backport to main

Signed-off-by: Tomás Migone <tomas@edgeandnode.com>

Author: tmigone

.github/workflows/backport-artifacts.yml

@@ -0,0 +1,82 @@
+name: Backport Deployment Artifacts
+
+on:
+  push:
+    branches:
+      - deployed/testnet
+      - deployed/mainnet
+
+jobs:
+  backport:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check for commits to backport
+        id: check
+        run: |
+          BRANCH="${GITHUB_REF#refs/heads/}"
+
+          # Count commits in deployment branch that aren't in main
+          COMMITS_AHEAD=$(git rev-list --count main..$BRANCH)
+
+          echo "branch=$BRANCH" >> $GITHUB_OUTPUT
+          echo "commits_ahead=$COMMITS_AHEAD" >> $GITHUB_OUTPUT
+
+          if [ "$COMMITS_AHEAD" -gt 0 ]; then
+            echo "has_commits=true" >> $GITHUB_OUTPUT
+            echo "Found $COMMITS_AHEAD commit(s) to backport from $BRANCH to main"
+          else
+            echo "has_commits=false" >> $GITHUB_OUTPUT
+            echo "No commits to backport"
+          fi
+
+      - name: Check for existing PR
+        if: steps.check.outputs.has_commits == 'true'
+        id: existing
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          BRANCH="${{ steps.check.outputs.branch }}"
+
+          # Check if a backport PR already exists
+          EXISTING_PR=$(gh pr list --base main --head "$BRANCH" --state open --json number --jq '.[0].number // empty')
+
+          if [ -n "$EXISTING_PR" ]; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+            echo "PR #$EXISTING_PR already exists"
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create backport PR
+        if: steps.check.outputs.has_commits == 'true' && steps.existing.outputs.exists == 'false'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          BRANCH="${{ steps.check.outputs.branch }}"
+          NETWORK="${BRANCH#deployed/}"
+
+          gh pr create \
+            --base main \
+            --head "$BRANCH" \
+            --title "Backport: ${NETWORK} deployment artifacts" \
+            --body "$(cat <<'EOF'
+          Automated backport of deployment artifacts from \`${{ steps.check.outputs.branch }}\`.
+
+          This PR brings deployment artifacts (e.g., updated addresses.json) back to main.
+
+          ---
+          *Created automatically by the backport-artifacts workflow.*
+          EOF
+          )"
+
+          echo "## Backport PR Created" >> $GITHUB_STEP_SUMMARY
+          echo "- **From:** $BRANCH" >> $GITHUB_STEP_SUMMARY
+          echo "- **To:** main" >> $GITHUB_STEP_SUMMARY
+          echo "- **Commits:** ${{ steps.check.outputs.commits_ahead }}" >> $GITHUB_STEP_SUMMARY

DEPLOYMENT.md

@@ -138,3 +138,9 @@ PRs to `main` that modify Solidity contract files require an `audited` label bef
 - **Label:** `audited`
 
 This enforces principle #2: code in `main` must be audited.
+
+### Artifact Backporting
+
+When deployment artifacts are committed to a deployment branch, a PR is automatically created to backport them to `main` (`.github/workflows/backport-artifacts.yml`).
+
+This ensures `main` stays in sync with deployed artifacts (e.g., updated `addresses.json`) without manual backporting.