Shopify Hydrogen关联GitHub报Branch isn't a valid name错误

1. 核心诱因（空仓库场景100%匹配）：Shopify的GitHub集成校验逻辑要求目标关联分支必须存在至少一个有效提交记录。空仓库没有任何commit时，远程根本没有生成实体分支，哪怕前端分支选择器能显示默认分支的占位名称（比如main/master），接口拿不到分支对应的commit哈希，就会直接抛出Branch isn't a valid name错误。
2. 次要诱因：目标分支名包含非法字符，包括Git本身不支持的~ ^ : ? * [ \等特殊符号、全角字符/中文、结尾带.或/、连续出现两个斜杠的命名，都会被校验规则拦截。
3. 小概率诱因：给Shopify授权的GitHub应用权限不足，仅能拉取仓库的基础列表信息，无法读取分支的元数据与内容信息，导致分支合法性校验失败。

按优先级依次操作即可：

• 为空仓库完成首次提交，创建实体默认分支：
  本地克隆目标空仓库，新增任意文件（比如README）后执行以下命令推送到远程：

  git add .
  git commit -m "init repository"
  git push origin main
  

  推送完成后回到Shopify后台重新走关联流程，选择已存在的main分支即可，空仓库导致的问题做完这步就能解决。
• 如果是分支名不合法：将目标分支重命名为仅含小写英文字母、数字、短横线/下划线的格式，例如main hydrogen-production，不要带特殊字符。
• 如果是权限问题：打开GitHub设置页，找到已安装的Shopify GitHub App，确认给目标关联仓库开放了Contents和Metadata的读取权限，重新授权后再尝试关联。

避坑提示：Hydrogen的仓库关联逻辑不支持关联无任何提交的空分支，哪怕分支名本身符合规则，只要没有有效commit就会触发校验报错。

内容的提问来源于stack exchange，提问作者bananasofa