Bitbucket 使用教程：仓库管理与管道集成

FreeGuideOnline 最新 2026-06-13

Bitbucket 使用教程：仓库管理与管道集成

Bitbucket 是 Atlassian 旗下的代码托管平台，支持 Git 版本控制，并内置持续集成 / 持续交付 (CI/CD) 工具 Bitbucket Pipelines。本教程面向初学者，将带你完成仓库创建、分支管理、协作流程以及自动化管道的配置，帮助你快速上手现代软件交付流程。

前置准备

  • 注册 Bitbucket Cloud 账号并登录。
  • 本地已安装 Git (git --version 检查版本)。
  • 了解基本的 Git 概念（commit、push、pull）。

仓库管理

创建新仓库

  1. 登录后，点击顶部导航栏的 + 按钮，选择 Repository。
  2. 填写仓库名称（如 my-first-repo）。
  3. 选择 Include a README? 建议勾选“Yes, with a tutorial”来获得一个学习指引，或选择“No”推送一个已有的项目。
  4. 将 Default branch name 保持为 main。
  5. 点击 Create repository。

创建后页面会显示仓库的远程地址，形如：

https://bitbucket.org/your-username/my-first-repo.git

克隆仓库到本地

在本地终端中执行：

git clone https://bitbucket.org/your-username/my-first-repo.git
cd my-first-repo

如果已有本地项目需要推送到空仓库：

git remote add origin https://bitbucket.org/your-username/my-first-repo.git
git push -u origin main

分支管理

Bitbucket 推荐基于分支的协作方式。在仓库页面左侧菜单 Branches 可以查看所有分支。

  • 创建新分支
    本地创建并推送：

    git checkout -b feature/add-new-page
git push -u origin feature/add-new-page

    分支名称建议使用描述性前缀，如 feature/、bugfix/。

  • 查看分支状态
    在 Bitbucket 仓库的 Branches 页面可以看到各个分支与 main 的同步状态，点击即可查看提交记录。

提交与推送

修改文件后：

git add .
git commit -m "docs: update homepage layout"
git push origin feature/add-new-page

在 Bitbucket 的 Commits 页面可以追溯所有变更历史。

创建 Pull Request（PR）进行协作

  1. 推送分支后，访问 Bitbucket 仓库页面，通常会自动弹出提示创建 Pull Request。也可以点击 Pull requests → Create a pull request。
  2. 选择源分支（feature/add-new-page）和目标分支（main）。
  3. 填写标题和描述，说明修改内容。
  4. 在右侧可添加审阅者（Reviewers）。
  5. 点击 Create pull request。

在 PR 页面可以查看代码差异（diff）、进行内联评论。审阅者同意后，点击 Merge 完成合并。合并后通常建议删除源分支。

合并策略

在合并 PR 时，Bitbucket 提供多种合并方式：

  • Merge commit：保留完整的分支历史。
  • Squash：将所有提交压缩为一个提交再合并，保持历史干净。
  • Fast-forward：若无分叉则直接前移指针。

你可以在仓库设置 → Merge strategies 中限制可用的策略。

Bitbucket Pipelines：自动化管道集成

什么是 Bitbucket Pipelines

Pipelines 是内置的 CI/CD 服务，基于 YAML 文件定义，在代码推送或 PR 时自动运行构建、测试、部署等任务。每个仓库每月有 50 分钟的免费构建时长（2024 年标准），足以应对个人或小型项目。

启用并配置 Pipelines

  1. 在仓库根目录创建 bitbucket-pipelines.yml 文件。
  2. Bitbucket 会自动检测该文件并激活管道的运行。
  3. 配置文件的基本结构：
image: atlassian/default-image:4

pipelines:
  default:
    - step:
        name: Build and Test
        script:
          - echo "Installing dependencies..."
          - npm install
          - npm test
  branches:
    main:
      - step:
          name: Deploy to Production
          script:
            - echo "Deploying..."
            - ./deploy.sh
  • image：定义使用的 Docker 镜像，提供运行环境。
  • pipelines：包含以下触发规则：
    • default：适用于所有分支中未被特定分支规则覆盖的 push。
    • branches：针对特定分支的步骤。
    • pull-requests：针对 PR 的事件。
  • step：一个执行单元，可以定义 name、script、artifacts 等。

管道集成示例：Node.js 项目自动测试与部署

假设项目是一个简单的 Node.js 应用，包含测试脚本 npm test 和部署脚本 deploy.sh（可能触发服务器更新）。

  1. 编写 bitbucket-pipelines.yml：
image: node:18

pipelines:
  default:
    - step:
        name: Install dependencies and test
        caches:
          - node
        script:
          - npm ci
          - npm test

  branches:
    main:
      - step:
          name: Build and Deploy
          caches:
            - node
          script:
            - npm ci
            - npm run build
            - chmod +x deploy.sh
            - ./deploy.sh
          artifacts:
            - build/**
  • caches：缓存 node_modules，加速后续构建。需在仓库设置中确认缓存 key。
  • artifacts：保留构建产物，可在后续步骤中使用或下载。
  1. 将文件提交并推送到仓库：
git add bitbucket-pipelines.yml
git commit -m "ci: add pipeline configuration"
git push origin main

推送后，进入 Bitbucket 仓库的 Pipelines 页面，你会看到流程自动开始运行。点击任意步骤可查看日志。

管理环境变量与部署

往往需要在管道中使用密钥（如 API key、部署 token），不应硬编码。在仓库页面 Settings → Pipelines → Repository variables 中添加变量，例如：

  • PRODUCTION_SERVER
  • SSH_PRIVATE_KEY

然后在 script 中通过环境变量引用：

script:
  - echo "Deploying to $PRODUCTION_SERVER"
  - ssh -i ~/.ssh/id_rsa user@$PRODUCTION_SERVER 'bash deploy.sh'

为安全地使用 SSH 密钥，可以配合 Pipelines 的 SSH keys 功能，将本地私钥添加后，管道自动配置 SSH 连接。

查看管道历史和调试

  • 每次 git push 都会触发新的管道运行，所有历史记录保存在 Pipelines 页面。
  • 若构建失败，点击失败的步骤，展开日志定位错误。
  • 可以在本地使用 docker 模拟管道环境进行调试：
docker run -v $PWD:/app --workdir /app node:18 /bin/sh -c "npm ci && npm test"

高级功能提示

  • 管道触发器与条件：可限定仅在特定路径变更时运行：

    pipelines:
  custom:
    manual:
      - step:
          script:
            - echo "Manual trigger"

    使用 custom 定义手动触发或定时触发管道。

  • 并行步骤：在同一阶段使用 - parallel: 加速任务。

  • Jira 集成：如果团队使用 Jira，可以在提交信息中添加 issue key（如 PROJ-123），Bitbucket 自动关联。

最佳实践总结

  1. 分支保护：在仓库设置中保护 main 分支，要求通过 PR 合并、通过 CI 检查。
  2. 提交信息规范：使用约定式提交（如 feat:、fix:），方便生成 Release Notes。
  3. 管道即代码：将 bitbucket-pipelines.yml 作为代码的一部分，随项目演进。
  4. 监控构建时长：合理利用缓存和并行步骤，减少不必要的资源消耗。
  5. 安全第一：敏感信息使用仓库变量，避免写入 YAML 文件。

通过掌握以上仓库管理和管道集成的技能，你可以利用 Bitbucket 高效完成从代码托管到自动化发布的完整软件开发周期。开始实践，将你的项目推上一条自动化的交付流水线吧。