如何在创建Bitbucket Server Git仓库时自动添加readme.md文件？

方案对比与可行性分析 #

1. Git 钩子（pre/post） #

Git 钩子属于仓库级配置，需要在仓库创建完成后才能部署。但 Bitbucket Server 通过 GUI 创建仓库时，新仓库处于初始空状态，钩子尚未存在，无法触发初始化操作。该方式仅适用于本地git init或事后手动配置钩子，不适用于自动触发场景。

2. Git init 模板文件 #

此方式在 Bitbucket GUI 创建仓库时不生效。Git init 模板仅针对本地git init命令，Bitbucket Server 服务端创建仓库的内部流程不会调用服务器全局 Git 模板目录（官方默认无此配置，修改全局模板也会导致所有仓库强制使用统一模板，灵活性差）。

3. Bitbucket ScriptRunner 监听器 #

这是当前场景下的最优方案。ScriptRunner 可以监听 Bitbucket 原生的RepositoryCreatedEvent事件，在仓库创建完成后自动执行脚本，完成 README.md 的添加与提交，完美适配 GUI 和 API 创建仓库的场景。

最优方案：ScriptRunner 监听器实现 #

配置步骤 #

1. 以管理员权限在 Bitbucket Server 中安装 ScriptRunner 插件
2. 新建「Repository Event Listener」，选择监听RepositoryCreatedEvent事件
3. 编写 Groovy 脚本实现自动添加 README 的逻辑

示例 Groovy 脚本 #

import com.atlassian.bitbucket.repository.Repository
import com.atlassian.bitbucket.content.ContentService
import com.atlassian.bitbucket.content.ContentCreateRequest
import com.atlassian.bitbucket.user.ApplicationUser
import com.atlassian.bitbucket.event.repository.RepositoryCreatedEvent

// 转换事件对象
def event = event as RepositoryCreatedEvent
Repository repo = event.getRepository()
// 使用创建仓库的用户作为提交者，也可指定固定管理员（如 userManager.getUserByName("admin")）
ApplicationUser submitter = event.getActor()

// 动态生成 README 内容
def readmeContent = """# ${repo.getName()}

这是仓库创建时自动生成的 README 文件。

## 项目说明
请在此补充项目描述、技术栈、使用文档等信息。
"""

// 获取 ContentService 实例
ContentService contentService = componentLocator.getComponent(ContentService)

// 构建创建请求
ContentCreateRequest createReq = contentService.newCreateRequestBuilder()
    .repository(repo)
    .branch(repo.getDefaultBranch().getName())
    .path("README.md")
    .content(readmeContent.getBytes("UTF-8"))
    .message("chore: 自动初始化 README.md")
    .author(submitter)
    .committer(submitter)
    .build()

// 执行创建提交
contentService.create(createReq)

脚本说明 #

• 监听仓库创建完成事件，无需手动触发
• 基于仓库名称动态生成 README 标题，可按需扩展内容模板
• 使用创建仓库的用户作为提交者，保证提交记录的合理性
• 自动提交到仓库默认分支，无需额外配置

备选方案：批量补全已创建仓库的 README #

如果需要给已存在的空仓库批量添加 README，可通过 Bitbucket REST API 编写脚本实现，以下是 Python 示例：

import requests
from requests.auth import HTTPBasicAuth

# 配置信息
BITBUCKET_SERVER = "http://你的Bitbucket服务器地址"
USERNAME = "管理员账号"
PASSWORD = "管理员密码"
PROJECT_KEY = "你的项目Key"

def add_readme(repo_slug):
    api_url = f"{BITBUCKET_SERVER}/rest/api/1.0/projects/{PROJECT_KEY}/repos/{repo_slug}/browse/README.md"
    readme_content = f"""# {repo_slug}

自动补全的 README 文件。
"""
    payload = {
        "content": readme_content,
        "message": "chore: 补全初始化 README.md",
        "branch": "master"  # 替换为你的仓库默认分支
    }
    resp = requests.put(api_url, json=payload, auth=HTTPBasicAuth(USERNAME, PASSWORD))
    if resp.status_code == 201:
        print(f"✅ 仓库 {repo_slug} 添加 README 成功")
    else:
        print(f"❌ 仓库 {repo_slug} 添加失败: {resp.text}")

# 获取项目下所有仓库并批量处理
repo_list_url = f"{BITBUCKET_SERVER}/rest/api/1.0/projects/{PROJECT_KEY}/repos"
repo_list = requests.get(repo_list_url, auth=HTTPBasicAuth(USERNAME, PASSWORD)).json()["values"]
for repo in repo_list:
    add_readme(repo["slug"])

总结 #

• 优先选择：ScriptRunner 监听器，实现仓库创建时自动触发，适配所有创建场景，无需人工干预
• 不推荐：Git 钩子/模板，无法适配 Bitbucket Server 服务端创建仓库的流程
• 批量补全：REST API 脚本，适合处理已存在的空仓库

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