使用 GitHub Actions 导入器从 Bitbucket Pipelines 迁移

法律声明

关于使用 GitHub Actions 导入器从 Bitbucket Pipelines 迁移

以下说明将指导您配置环境，以便使用 GitHub Actions 导入器将 Bitbucket Pipelines 迁移到 GitHub Actions。

先决条件

一个可以运行基于 Linux 的容器并安装必要工具的环境。
- Docker 已安装并正在运行。
- GitHub CLI 已安装。
注意：GitHub Actions 导入器容器和 CLI 不需要安装在与您的 CI 平台相同的服务器上。

限制

使用 GitHub Actions 导入器从 Bitbucket Pipelines 迁移到 GitHub Actions 时，存在一些限制。

不支持私有 AWS ECR 中的镜像。
不支持 Bitbucket Pipelines 选项 size。如果 GitHub Actions 中需要额外的运行器资源，请考虑使用更大的运行器。有关更多信息，请参阅“关于更大的运行器”。
forecast 命令不支持详细说明作业排队时间的指标。

Bitbucket after-scripts 支持使用 GitHub Actions always() 结合检查上一步的 steps.<step_id>.conclusion。有关更多信息，请参阅“上下文”。

以下是如何使用 always() 与 steps.<step_id>.conclusion 的示例。

  - name: After Script 1
    run: |-
      echo "I'm after the script ran!"
      echo "We should be grouped!"
    id: after-script-1
    if: "${{ always() }}"
  - name: After Script 2
    run: |-
      echo "this is really the end"
      echo "goodbye, for now!"
    id: after-script-2
    if: "${{ steps.after-script-1.conclusion == 'success' && always() }}"

手动任务

某些 Bitbucket Pipelines 结构必须手动迁移。这些包括

安全存储库、工作区和部署变量
SSH 密钥

安装 GitHub Actions 导入器 CLI 扩展

Bash

gh extension install github/gh-actions-importer

gh extension install github/gh-actions-importer

验证扩展是否已安装

$ gh actions-importer -h
Options:
  -?, -h, --help  Show help and usage information

Commands:
  update     Update to the latest version of GitHub Actions Importer.
  version    Display the version of GitHub Actions Importer.
  configure  Start an interactive prompt to configure credentials used to authenticate with your CI server(s).
  audit      Plan your CI/CD migration by analyzing your current CI/CD footprint.
  forecast   Forecast GitHub Actions usage from historical pipeline utilization.
  dry-run    Convert a pipeline to a GitHub Actions workflow and output its yaml file.
  migrate    Convert a pipeline to a GitHub Actions workflow and open a pull request with the changes.

配置凭据

configure CLI 命令用于在使用 Bitbucket Pipelines 和 GitHub 时设置 GitHub Actions 导入器所需的凭据和选项。

创建一个 GitHub 个人访问令牌（经典）。有关更多信息，请参阅“管理您的个人访问令牌”。

您的令牌必须具有 workflow 范围。

创建令牌后，将其复制并保存在安全的位置以备后用。
为 Bitbucket Pipelines 创建一个工作区访问令牌。有关更多信息，请参阅 Bitbucket 文档中的工作区访问令牌权限。您的令牌必须对管道、项目和存储库具有 `read` 范围。
在您的终端中，运行 GitHub Actions Importer 的 `configure` CLI 命令
```
gh actions-importer configure
```
`configure` 命令将提示您输入以下信息
- 对于“您要配置哪些 CI 提供商？”，使用箭头键选择 `Bitbucket`，按 空格键 选择它，然后按 回车键。
- 对于“GitHub 的个人访问令牌”，输入您之前创建的个人访问令牌（经典）的值，然后按 回车键。
- 对于“GitHub 实例的基准 URL”，按 回车键 接受默认值（`https://github.com`）。
- 对于“Bitbucket 的个人访问令牌”，输入您之前创建的工作区访问令牌，然后按 回车键。
- 对于“Bitbucket 实例的基准 URL”，输入您的 Bitbucket 实例的 URL，然后按 回车键。
下面显示了 `configure` 命令的示例
```
$ gh actions-importer configure
✔ Which CI providers are you configuring?: Bitbucket
Enter the following values (leave empty to omit):
✔ Personal access token for GitHub: ***************
✔ Base url of the GitHub instance: https://github.com
✔ Personal access token for Bitbucket: ********************
✔ Base url of the Bitbucket instance: https://bitbucket.example.com
Environment variables successfully updated.
```
在您的终端中，运行 GitHub Actions Importer 的 `update` CLI 命令，以连接到 GitHub Packages 容器注册表并确保容器映像更新到最新版本
```
gh actions-importer update
```
该命令的输出应类似于以下内容
```
Updating ghcr.io/actions-importer/cli:latest...
ghcr.io/actions-importer/cli:latest up-to-date
```

执行 Bitbucket 实例的审计

您可以使用审计命令来获取 Bitbucket 实例中管道的概览。

审计命令执行以下步骤。

获取工作区的所有管道。
将管道转换为等效的 GitHub Actions 工作流。
生成一份报告，总结使用 GitHub Actions Importer 可以实现的迁移的完整性和复杂性。

运行审计命令

要执行审计，请在您的终端中运行以下命令，将 `:workspace` 替换为要审计的 Bitbucket 工作区的名称。

gh actions-importer audit bitbucket --workspace :workspace--output-dir tmp/audit

可选地，可以向审计命令提供 `--project-key` 选项，以将结果限制为仅与项目关联的管道。

在以下示例命令中，`：project_key` 应替换为要审计的项目的键。项目键可以在 Bitbucket 的工作区项目页面中找到。

gh actions-importer audit bitbucket --workspace :workspace --project-key :project_key --output-dir tmp/audit

检查审计结果

指定输出目录中的文件包含审计结果。请参阅 `audit_summary.md` 文件以了解审计结果的摘要。

审计摘要包含以下部分。

管道

“管道”部分包含有关 GitHub Actions Importer 完成的转换率的统计信息。

以下是“管道”部分中可能出现的关键术语

成功的管道已将 100% 的管道结构和单个项目自动转换为其 GitHub Actions 等效项。
部分成功的管道已将所有管道结构转换，但某些单个项目未自动转换为其 GitHub Actions 等效项。
不支持的管道是 GitHub Actions Importer 不支持的定义类型。
失败的管道在转换时遇到了致命错误。这可能由于以下三种原因之一导致
- 管道配置错误，在 Bamboo 中无效。
- GitHub Actions Importer 在转换时遇到了内部错误。
- 网络响应不成功导致管道无法访问，这通常是由于凭据无效导致的。

构建步骤

“构建步骤”部分概述了所有管道中使用的各个构建步骤，以及 GitHub Actions Importer 自动转换了多少个步骤。

以下是“构建步骤”部分中可能出现的关键术语

已知构建步骤是已自动转换为等效操作的步骤。
未知构建步骤是未自动转换为等效操作的步骤。
不支持的构建步骤是以下两种情况之一：
- GitHub Actions 本质上不支持。
- 以与 GitHub Actions 不兼容的方式配置。
操作是已在转换后的工作流中使用的操作列表。这对于以下情况很重要：
- 如果您使用 GitHub Enterprise Server，则收集要同步到您的实例的操作列表。
- 定义组织级允许的操作列表。此操作列表是安全或合规团队可能需要审查的全面操作列表。

手动任务

“手动任务”部分概述了 GitHub Actions Importer 无法自动完成的任务，您必须手动完成这些任务。

以下是“手动任务”部分中可能出现的关键术语

秘密是指在转换后的管道中使用的存储库或组织级秘密。这些秘密必须在 GitHub Actions 中手动创建，才能使这些管道正常运行。有关更多信息，请参阅“在 GitHub Actions 中使用秘密”。
自托管运行器是指在转换后的管道中引用的运行器标签，它不是 GitHub 托管的运行器。您需要手动定义这些运行器，才能使这些管道正常运行。

文件

审计报告的最后一部分提供了在审计期间写入磁盘的所有文件的清单。

每个管道文件都包含审计中包含的各种文件，包括

在 GitHub 中定义的原始管道。
用于转换管道的任何网络响应。
转换后的工作流文件。
可用于排查管道转换失败的堆栈跟踪。

此外，workflow_usage.csv 文件包含每个成功转换的管道使用的所有操作、秘密和运行器的逗号分隔列表。这对于确定哪些工作流使用哪些操作、秘密或运行器非常有用，并且可以用于执行安全审查。

预测使用情况

您可以使用 forecast 命令通过计算 Bitbucket 实例中已完成的管道运行的指标来预测潜在的 GitHub Actions 使用情况。

运行预测命令

要执行潜在 GitHub Actions 使用情况的预测，请在您的终端中运行以下命令，将 :workspace 替换为要预测的 Bitbucket 工作区的名称。默认情况下，GitHub Actions Importer 会在预测报告中包含前七天。

gh actions-importer forecast bitbucket --workspace :workspace --output-dir tmp/forecast_reports

预测项目

要将预测限制为某个项目，您可以使用 --project-key 选项。将 :project_key 的值替换为要预测的项目的项目密钥。

gh actions-importer forecast bitbucket --workspace :workspace --project-key :project_key --output-dir tmp/forecast_reports

检查预测报告

指定输出目录中的 forecast_report.md 文件包含预测结果。

以下是预测报告中可能出现的一些关键术语

作业数量是指已完成作业的总数。
流水线数量是指使用的唯一流水线的数量。
执行时间描述了运行器在作业上花费的时间。此指标可用于帮助规划 GitHub 托管运行器的成本。
- 此指标与您在 GitHub Actions 中预计的支出相关。这将根据用于这些分钟的硬件而有所不同。您可以使用 GitHub Actions 定价计算器来估算成本。
并发作业指标描述了在任何给定时间运行的作业数量。

执行干运行迁移

您可以使用干运行命令将 Bitbucket 流水线转换为等效的 GitHub Actions 工作流。干运行会在指定目录中创建输出文件，但不会打开拉取请求以迁移流水线。

运行干运行命令

要执行将 Bitbucket 流水线迁移到 GitHub Actions 的干运行，请在您的终端中运行以下命令，将 :workspace 替换为工作区名称，将 :repo 替换为 Bitbucket 中存储库的名称。

gh actions-importer dry-run bitbucket --workspace :workspace --repository :repo --output-dir tmp/dry-run

检查转换后的工作流

您可以在指定的输出目录中查看干运行的日志和转换后的工作流文件。

如果 GitHub Actions Importer 无法自动转换任何内容，例如未知构建步骤或部分成功的流水线，您可能需要创建自定义转换器来进一步自定义转换过程。有关更多信息，请参阅“使用自定义转换器扩展 GitHub Actions Importer”。

执行生产迁移

您可以使用 migrate 命令转换 Bitbucket 流水线并使用等效的 GitHub Actions 工作流打开拉取请求。

运行 migrate 命令

要将 Bitbucket 流水线迁移到 GitHub Actions，请在您的终端中运行以下命令，替换以下值。

将 target-url 值替换为您的 GitHub 存储库的 URL。
将 :repo 替换为 Bitbucket 中存储库的名称。
将 :workspace 替换为工作区的名称。

gh actions-importer migrate bitbucket --workspace :workspace --repository :repo --target-url https://github.com/:owner/:repo --output-dir tmp/dry-run

该命令的输出包括将转换后的工作流添加到您的存储库的拉取请求的 URL。成功输出的示例类似于以下内容

gh actions-importer migrate bitbucket --workspace actions-importer --repository custom-trigger --target-url https://github.com/valet-dev-testing/demo-private --output-dir tmp/bitbucket
[2023-07-18 09:56:06] Logs: 'tmp/bitbucket/log/valet-20230718-165606.log'
[2023-07-18 09:56:24] Pull request: 'https://github.com/valet-dev-testing/demo-private/pull/55'

检查拉取请求

成功运行 migrate 命令的输出包含一个指向新拉取请求的链接，该请求将转换后的工作流添加到您的存储库。

拉取请求的一些重要元素包括

在拉取请求描述中，有一个名为 **手动步骤** 的部分，其中列出了您在完成将管道迁移到 GitHub Actions 之前必须手动完成的步骤。例如，此部分可能会告诉您创建工作流中使用的任何秘密。
转换后的工作流文件。在拉取请求中选择 **已更改的文件** 选项卡以查看将添加到您的 GitHub 存储库的工作流文件。

完成检查拉取请求后，您可以合并它以将工作流添加到您的 GitHub 存储库。

参考

本节包含使用 GitHub Actions Importer 从 Bitbucket Pipelines 迁移时有关环境变量、可选参数和支持语法的参考信息。

使用环境变量

GitHub Actions Importer 使用环境变量进行身份验证配置。这些变量在使用 configure 命令遵循配置过程时设置。有关更多信息，请参阅“配置凭据”部分。

GitHub Actions Importer 使用以下环境变量连接到您的 Bitbucket 实例。

GITHUB_ACCESS_TOKEN：用于使用转换后的工作流创建拉取请求的个人访问令牌（经典）（需要 repo 和 workflow 范围）。
GITHUB_INSTANCE_URL：目标 GitHub 实例的 URL。（例如 https://github.com）
BITBUCKET_ACCESS_TOKEN：具有管道、项目和存储库读取范围的工作区访问令牌。

这些环境变量可以在 .env.local 文件中指定，该文件将在运行时由 GitHub Actions Importer 加载。分发存档包含一个 .env.local.template 文件，可用于创建这些文件。

可选参数

您可以使用 GitHub Actions Importer 子命令的可选参数来自定义迁移。

`--source-file-path`

您可以将 --source-file-path 参数与 dry-run 或 migrate 子命令一起使用。

默认情况下，GitHub Actions Importer 从 Bitbucket 实例获取管道内容。--source-file-path 参数告诉 GitHub Actions Importer 使用指定的源文件路径。

例如

gh actions-importer dry-run bitbucket --workspace :workspace --repository :repo --output-dir tmp/dry-run --source-file-path path/to/my/pipeline/file.yml

`--config-file-path`

您可以将 --config-file-path 参数与 audit、dry-run 和 migrate 子命令一起使用。

默认情况下，GitHub Actions Importer 从 Bitbucket 实例获取管道内容。--config-file-path 参数告诉 GitHub Actions Importer 使用指定的源文件。

审计示例

在此示例中，GitHub Actions Importer 使用指定的 YAML 配置文件执行审计。

gh actions-importer audit bitbucket --workspace :workspace --output-dir tmp/audit --config-file-path "path/to/my/bitbucket/config.yml"

要使用配置文件审计 Bitbucket 实例，配置文件必须采用以下格式，并且每个 repository_slug 必须是唯一的

source_files:
  - repository_slug: repo_name
    path: path/to/one/source/file.yml
  - repository_slug: another_repo_name
    path: path/to/another/source/file.yml

支持的 Bitbucket Pipelines 语法

下表显示了 GitHub Actions Importer 目前能够转换的属性类型。

Bitbucket	GitHub Actions	状态
`after-script`	`jobs.<job_id>.steps[*]`	支持
`工件`	`actions/upload-artifact` & `download-artifact`	支持
`缓存`	`actions/cache`	支持
`克隆`	`actions/checkout`	支持
`条件`	`job.<job_id>.steps[*].run`	支持
`部署`	`jobs.<job_id>.environment`	支持
`镜像`	`jobs.<job_id>.container`	支持
`最大时间`	`jobs.<job_id>.steps[*].timeout-minutes`	支持
`options.docker`	无	支持
`options.max-time`	`jobs.<job_id>.steps[*].timeout-minutes`	支持
`并行`	`jobs.<job_id>`	支持
`pipelines.branches`	`on.push`	支持
`pipelines.custom`	`on.workflow_dispatch`	支持
`pipelines.default`	`on.push`	支持
`pipelines.pull-requests`	`on.pull_requests`	支持
`pipelines.tags`	`on.tags`	支持
`运行于`	`jobs.<job_id>.runs-on`	支持
`脚本`	`job.<job_id>.steps[*].run`	支持
`服务`	`jobs.<job_id>.service`	支持
`阶段`	`jobs.<job_id>`	支持
`步骤`	`jobs.<job_id>.steps[*]`	支持
`触发器`	`on.workflow_dispatch`	支持
`fail-fast`	无	不支持
`oidc`	无	不支持
`options.size`	无	不支持
`大小`	无	不支持

环境变量映射

GitHub Actions Importer 使用下表中的映射将默认的 Bitbucket 环境变量转换为 GitHub Actions 中最接近的等效项。

Bitbucket	GitHub Actions
`CI`	`true`
`BITBUCKET_BUILD_NUMBER`	`${{ github.run_number }}`
`BITBUCKET_CLONE_DIR`	`${{ github.workspace }}`
`BITBUCKET_COMMIT`	`${{ github.sha }}`
`BITBUCKET_WORKSPACE`	`${{ github.repository_owner }}`
`BITBUCKET_REPO_SLUG`	`${{ github.repository }}`
`BITBUCKET_REPO_UUID`	`${{ github.repository_id }}`
`BITBUCKET_REPO_FULL_NAME`	`${{ github.repository_owner }}`/`${{ github.repository }}`
`BITBUCKET_BRANCH`	`${{ github.ref }}`
`BITBUCKET_TAG`	`${{ github.ref }}`
`BITBUCKET_PR_ID`	`${{ github.event.pull_request.number }}`
`BITBUCKET_PR_DESTINATION_BRANCH`	`${{ github.event.pull_request.base.ref }}`
`BITBUCKET_GIT_HTTP_ORIGIN`	`${{ github.event.repository.clone_url }}`
`BITBUCKET_GIT_SSH_ORIGIN`	`${{ github.event.repository.ssh_url }}`
`BITBUCKET_EXIT_CODE`	`${{ job.status }}`
`BITBUCKET_STEP_UUID`	`${{ job.github_job }}`
`BITBUCKET_PIPELINE_UUID`	`${{ github.workflow }}`
`BITBUCKET_PROJECT_KEY`	`${{ github.repository_owner }}`
`BITBUCKET_PROJECT_UUID`	`${{ github.repository_owner }}`
`BITBUCKET_STEP_TRIGGERER_UUID`	`${{ github.actor_id }}`
`BITBUCKET_SSH_KEY_FILE`	`${{ github.workspace }}/.ssh/id_rsa`
`BITBUCKET_STEP_OIDC_TOKEN`	无映射
`BITBUCKET_DEPLOYMENT_ENVIRONMENT`	无映射
`BITBUCKET_DEPLOYMENT_ENVIRONMENT_UUID`	无映射
`BITBUCKET_BOOKMARK`	无映射
`BITBUCKET_PARALLEL_STEP`	无映射
`BITBUCKET_PARALLEL_STEP_COUNT`	无映射

系统变量

任务中使用的系统变量将转换为等效的 bash shell 变量，并假定可用。例如，${system.<variable.name>} 将转换为 $variable_name。我们建议您验证这一点，以确保工作流正常运行。

法律声明

部分内容已从 https://github.com/github/gh-actions-importer/ 移植，并根据 MIT 许可证发布

MIT License

Copyright (c) 2022 GitHub

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

使用 GitHub Actions 导入器从 Bitbucket Pipelines 迁移

本文档