Weiran Framework

Appearance

自动化部署 @github ​

Generated By 🤖, Modified By Duoli

1. 配置 POPPY_RELEASE_TOKEN ​

Step 1 — 创建 App ​

打开 Apps 创建位置

这里注意, 私有的 app 安装授权范围不同, 个人私有仅仅授权个人账号下, 团队私有仅仅授权团队下

团队入口 :

  1. 个人仓库：https://github.com/settings/apps/new
  2. 团队仓库 : https://github.com/organizations/{team-name}/settings/apps

填写资料:

  • GitHub App name: poppy-release-bot（必须全局唯一）

  • Homepage URL: 填写个人主页或者团队主页即可

  • Webhook: ❌ 取消勾选 "Active"（我们不需要 webhook，push 事件自动触发）

  • Permissions → Repository permissions:

    • Contents: Read and write（推送代码、创建 Release）
    • Metadata: Read-only（默认就有）

  • Where can this GitHub App be installed?: 选 "Only on this account" 或 "Any account"

  1. 点 Create GitHub App

Step 2 — 生成 App 私钥 ​

  1. App 创建后跳转到配置项

    1. 个人 https://github.com/settings/apps/poppy-release-bot
    2. 团队 : https://github.com/organizations/{team-name}/settings/apps/{app-name}

  2. 滚到 Private keys 段

  3. 点 Generate a private key → 自动下载 poppy-release-bot.<日期>.private-key.pem

  4. 用文本编辑器打开 .pem，复制整段内容（含 BEGIN/END 标记）

Step 3 — 配置仓库 Secrets ​

在主仓库密钥 / actions 段落(这里我们以团队仓库做示例)

回到 https://github.com/poppy-framework/poppy/settings/secrets/actions，加 3 个 secret：

NameValue
POPPY_RELEASE_CLIENT_IDApp 详情页顶部的 "CLIENT ID"（如 Client ID: Iv23***xxhX）
POPPY_RELEASE_APP_KEY.pem 文件的整段内容（多行，从 -----BEGIN RSA PRIVATE KEY----- 到 -----END RSA PRIVATE KEY-----）

Step 4 — 安装 App 到组织 ​

  1. 浏览器打开 https://github.com/settings/apps/poppy-release-bot/installations
  2. 点 Install → 选 poppy-framework 组织
  3. 选择 All repositories（推荐）或 Select repositories 选 21 个目标仓库
  4. 点 Install
  5. 安装后 URL 变成 https://github.com/settings/installations/<INSTALLATION_ID>

Step 5 — 修改 workflow 用 App 签 token ​

在 .github/workflows/release.yml 里把 token 步骤设置成：

这里注意一定要加上 owner, 否则无法生成 token

YAML
jobs:
  release:
    name: Release ${{ github.ref_name }}
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - name: Generate GitHub App Token
        id: app-token
        uses: actions/create-github-app-token@v3
        with:
          client-id: ${{ secrets.POPPY_RELEASE_CLIENT_ID }}
          private-key: ${{ secrets.POPPY_RELEASE_APP_KEY }}
          owner: poppy-framework

2. 发版验证流程 ​

按这个顺序跑，从轻到重：

2.1 本地 dry-run（不需要 token） ​

Bash
composer release:dry-run
# 或：
./.github/scripts/release.sh 4.2.1-rc1 "" "" --dry-run

期望：列出 21 个模块，每个模块说明 "Would release: xxx → poppy-framework/xxx"。

2.2 发布 ​

Bash
# 匹配单一模块
git tag v4.2.1-rc1 -m "only: framework"
git push origin v4.2.1-rc1

# 匹配全部模块
git tag v4.2.1 -m ""
git push origin v4.2.1

# 删除远端 tag 重推
git push origin :refs/tags/v4.2.1
git push origin v4.2.1

# skip / only 控制
git tag v4.2.2 -m "skip: ad, im-rpc, ext-phpstan"
git push origin v4.2.2

3. 特殊运维项目 ​

精细控制语法速查 ​

Bash
# 跳过指定模块（保留其上次版本号，不 push / 不 Release）
git tag v4.2.1 -m "skip: ad, im-rpc, ext-phpstan"

# 只发指定模块（其余不发布）
git tag v4.2.1 -m "only: framework, core"

# skip + only 同时使用（取交集：only 中去掉 skip 的）
git tag v4.2.1 -m "skip: faker
only: framework, core, faker"
# 实际发布：framework, core（faker 被 skip）

# 默认（全 21 个模块都发布）
git tag v4.2.1 -m ""

添加新模块的步骤 ​

  1. 在 poppy/<name>/ 准备子目录（含 composer.json，描述写清楚）

  2. 在 .github/release-manifest.yml 里加一条：

    YAML
    - name: <name>
  description: <your description>
  dependencies: []

  3. 在 poppy-framework 组织下创建 poppy-framework/<name> 仓库

  4. 推 tag 即可触发发布

packagist.org webhook 配置 ​

如果有开团队或者个人的授权可以不用配置这个项目

每个目标仓库独立配：

  1. 登录 https://packagist.org → Submit → 输入 https://github.com/poppy-framework/<module>
  2. 进入包详情页 → Settings → Webhooks → Add webhook
  3. 填 https://github.com/poppy-framework/<module> + 选择事件 "push" / "release"
  4. Save

文件位置速查 ​

文件作用
.github/release-manifest.yml21 个模块的发布清单（添加/删除模块改这里）
.github/workflows/release.ymltag 触发 workflow
.github/scripts/release.sh主调度（解析 tag message + dry-run）
.github/scripts/release-module.sh单模块发布（split → push → Release）
.github/scripts/changelog.sh从 git log 抽取模块 changelog
.github/scripts/inject-version.sh注入 composer.json version 字段
composer.json含 release:dry-run 脚本入口
README.md给开发者看的发布流程概述

4. QA ​

  1. Workflow 日志显示 "Resource not accessible by integration"

原因：token 没权限访问目标仓库

解决：

  • 重新安装 App 并勾选该仓库
  1. Workflow 日志显示 "Bad credentials"

原因：token 拼写错误或过期

解决：去 Settings → Secrets 重新粘贴新 token

  1. "git subtree split failed"

原因：poppy/<module>/ 目录不存在

解决：检查 .github/release-manifest.yml 里 name 和实际目录名一致

  1. "release already exists"

正常行为（幂等性）。已存在的 Release 不会被覆盖。

  1. 部分模块失败但其他成功

正常行为（顺序执行，每个模块独立 try-catch）。失败的会列在 "Release Summary → Failed" 里，逐个排查。