法律声明
以下说明将指导您配置环境以使用 GitHub Actions 导入器将 Bamboo 管道迁移到 GitHub Actions。
- 一个 Bamboo 帐户或组织，其中包含您想要转换为 GitHub Actions 工作流的项目和管道。
- Bamboo 版本 7.1.1 或更高版本。
- 访问权限以创建您帐户或组织的 Bamboo 个人访问令牌。
- 可以运行基于 Linux 的容器并安装必要工具的环境。
注意
GitHub Actions 导入器容器和 CLI 不需要安装在与您的 CI 平台相同的服务器上。
使用 GitHub Actions 导入器从 Bamboo 迁移到 GitHub Actions 时存在一些限制。
- GitHub Actions 导入器依赖于 Bamboo 服务器生成的 YAML 规范来执行迁移。当 Bamboo 不支持将某些内容导出到 YAML 时，未迁移缺少的信息。
- 不支持触发条件。当 GitHub Actions 导入器遇到带有条件的触发器时，该条件将显示为注释，并且触发器将在没有条件的情况下进行转换。
- 带有用于存储构件的自定义设置的 Bamboo 计划不会被转换。相反，构件将使用
upload-artifact 和 download-artifact 操作进行存储和检索。
- 必须在 GitHub UI 中手动禁用已禁用的计划。有关更多信息，请参阅“禁用和启用工作流”。
- 已禁用的作业将使用
if: false 条件进行转换，这将阻止其运行。您必须将其删除才能重新启用作业。
- 已禁用的任务不会被转换，因为在使用 Bamboo API 时，它们不包含在导出的计划中。
- Bamboo 提供了在构建完成后清理构建工作区的选项。这些不会被转换，因为假设 GitHub 托管的运行器或短暂的自托管运行器将自动处理此问题。
- 挂起构建检测选项不会被转换，因为 GitHub Actions 中没有等效项。最接近的选项是作业上的
timeout-minutes，可用于设置作业运行的最大分钟数。有关更多信息，请参阅“GitHub Actions 的工作流语法”。
- 模式匹配标签不会被转换，因为 GitHub Actions 中没有等效项。
- 所有构件都将转换为
actions/upload-artifact，无论它们是否为 shared，以便可以从工作流中的任何作业下载它们。
- 权限不会被转换，因为 GitHub Actions 中没有合适的等效项。
- 如果 Bamboo 版本介于 7.1.1 和 8.1.1 之间，则不会迁移项目和计划变量。
某些 Bamboo 结构必须手动迁移。这些包括
-
安装 GitHub Actions Importer CLI 扩展
Bashgh 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 命令用于在使用 Bamboo 和 GitHub 时设置 GitHub Actions Importer 的必需凭据和选项。
-
创建一个 GitHub 个人访问令牌（经典版）。有关更多信息，请参阅“管理您的个人访问令牌”。
您的令牌必须具有 workflow 范围。
创建令牌后，复制并将其保存在安全位置以备后用。
-
创建一个 Bamboo 个人访问令牌。有关更多信息，请参阅 Bamboo 文档中的 个人访问令牌。
您的令牌必须具有以下权限，具体取决于将转换哪些资源。
创建令牌后，复制并将其保存在安全位置以备后用。
-
在您的终端中，运行 GitHub Actions Importer configure CLI 命令
gh actions-importer configure
configure 命令将提示您输入以下信息
- 对于“您要配置哪些 CI 提供程序？”，使用箭头键选择
Bamboo，按 Space 选择它，然后按 Enter。
- 对于“GitHub 的个人访问令牌”，输入您之前创建的个人访问令牌（经典版）的值，然后按 Enter。
- 对于“GitHub 实例的基本 URL”，按 Enter 接受默认值（
https://github.com）。
- 对于“Bamboo 的个人访问令牌”，输入您之前创建的 Bamboo 个人访问令牌的值，然后按 Enter。
- 对于“Bamboo 实例的基本 URL”，输入 Bamboo Server 或 Bamboo Data Center 实例的 URL，然后按 Enter。
下面显示了 configure 命令的示例
$ gh actions-importer configure
✔ Which CI providers are you configuring?: Bamboo
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 Bamboo: ********************
✔ Base url of the Bamboo instance: https://bamboo.example.com
Environment variables successfully updated.
-
在您的终端中，运行 GitHub Actions Importer update CLI 命令以连接到 GitHub Packages Container 注册表并确保容器映像已更新到最新版本
gh actions-importer update
该命令的输出应类似于以下内容
Updating ghcr.io/actions-importer/cli:latest...
ghcr.io/actions-importer/cli:latest up-to-date
您可以使用 audit 命令获取 Bamboo 组织中所有项目的概览。
audit 命令执行以下步骤
- 获取 Bamboo 组织中定义的所有项目。
- 将每个管道转换为其等效的 GitHub Actions 工作流。
- 生成一份报告，总结使用 GitHub Actions Importer 可以实现多完整的迁移以及迁移的复杂程度。
要执行 Bamboo 实例的审核，请在您的终端中运行以下命令
gh actions-importer audit bamboo --output-dir tmp/audit
指定输出目录中的文件包含审核结果。请参阅 audit_summary.md 文件以获取审核结果的摘要。
审核摘要包含以下部分。
“管道”部分包含有关 GitHub Actions Importer 完成的转换率的高级统计信息。
下面列出了一些可能出现在“管道”部分中的关键术语
- 成功管道已将 100% 的管道结构和各个项目自动转换为其 GitHub Actions 等效项。
- 部分成功管道已转换所有管道结构，但是，某些单独的项目未自动转换为其 GitHub Actions 等效项。
- 不支持的管道是 GitHub Actions Importer 不支持的定义类型。
- 失败的管道在转换时遇到致命错误。这可能是由于以下三种原因之一造成的
- 管道最初配置错误且无效。
- 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 命令通过计算 Bamboo 实例中已完成管道运行的指标来预测潜在的 GitHub Actions 使用情况。
要预测潜在的 GitHub Actions 使用情况，请在您的终端中运行以下命令。默认情况下，GitHub Actions Importer 在预测报告中包含前七天。
gh actions-importer forecast bamboo --output-dir tmp/forecast_reports
要将预测限制为与项目关联的计划和部署环境，您可以使用 --project 选项，其中值设置为构建项目密钥。
例如
gh actions-importer forecast bamboo --project PAN --output-dir tmp/forecast_reports
指定输出目录中的 forecast_report.md 文件包含预测结果。
下面列出了一些可能出现在预测报告中的一些关键术语
- 作业数是已完成作业的总数。
- 管道数是使用的唯一管道的数量。
- 执行时间描述运行器在作业上花费的时间。此指标可用于帮助规划 GitHub 托管运行器的成本。
- 排队时间指标描述作业等待运行器可用以执行它所花费的时间。
- 并发作业指标描述了在任何给定时间运行的作业数量。此指标可用于
您可以使用dry-run命令将 Bamboo 管道转换为等效的 GitHub Actions 工作流。试运行会在指定的目录中创建输出文件，但不会打开拉取请求以迁移管道。
要执行将 Bamboo 构建计划迁移到 GitHub Actions 的试运行，请在您的终端中运行以下命令，将:my_plan_slug替换为计划的项目和计划密钥，格式为<projectKey>-<planKey>（例如：PAN-SCRIP）。
gh actions-importer dry-run bamboo build --plan-slug :my_plan_slug --output-dir tmp/dry-run
要执行将 Bamboo 部署项目迁移到 GitHub Actions 的试运行，请在您的终端中运行以下命令，将:my_deployment_project_id替换为您要转换的部署项目的 ID。
gh actions-importer dry-run bamboo deployment --deployment-project-id :my_deployment_project_id --output-dir tmp/dry-run
您可以在指定的输出目录中查看试运行的日志和转换后的工作流文件。
如果 GitHub Actions 导入程序无法自动转换任何内容，例如未知的构建步骤或部分成功的管道，您可能需要创建自定义转换器以进一步自定义转换过程。有关更多信息，请参阅“使用自定义转换器扩展 GitHub Actions 导入程序”。
您可以使用migrate命令转换 Bamboo 管道并使用等效的 GitHub Actions 工作流打开拉取请求。
要将 Bamboo 构建计划迁移到 GitHub Actions，请在您的终端中运行以下命令，将target-url值替换为 GitHub 存储库的 URL，并将:my_plan_slug替换为计划的项目和计划密钥，格式为<projectKey>-<planKey>。
gh actions-importer migrate bamboo build --plan-slug :my_plan_slug --target-url :target_url --output-dir tmp/migrate
命令的输出包括将转换后的工作流添加到您的存储库的拉取请求的 URL。成功输出的示例类似于以下内容
$ gh actions-importer migrate bamboo build --plan-slug :PROJECTKEY-PLANKEY --target-url https://github.com/octo-org/octo-repo --output-dir tmp/migrate
[2022-08-20 22:08:20] Logs: 'tmp/migrate/log/actions-importer-20220916-014033.log'
[2022-08-20 22:08:20] Pull request: 'https://github.com/octo-org/octo-repo/pull/1'
要将 Bamboo 部署项目迁移到 GitHub Actions，请在您的终端中运行以下命令，将target-url值替换为 GitHub 存储库的 URL，并将:my_deployment_project_id替换为您要转换的部署项目的 ID。
gh actions-importer migrate bamboo deployment --deployment-project-id :my_deployment_project_id --target-url :target_url --output-dir tmp/migrate
命令的输出包括将转换后的工作流添加到您的存储库的拉取请求的 URL。成功输出的示例类似于以下内容
$ gh actions-importer migrate bamboo deployment --deployment-project-id 123 --target-url https://github.com/octo-org/octo-repo --output-dir tmp/migrate
[2023-04-20 22:08:20] Logs: 'tmp/migrate/log/actions-importer-20230420-014033.log'
[2023-04-20 22:08:20] Pull request: 'https://github.com/octo-org/octo-repo/pull/1'
成功运行migrate命令的输出包含一个链接，指向将转换后的工作流添加到您的存储库的新拉取请求。
拉取请求的一些重要元素包括
- 在拉取请求描述中，一个名为手动步骤的部分，其中列出了在完成将管道迁移到 GitHub Actions 之前必须手动完成的步骤。例如，此部分可能会告诉您创建工作流中使用的任何机密。
- 转换后的工作流文件。选择拉取请求中的已更改的文件选项卡以查看将添加到您的 GitHub 存储库的工作流文件。
完成检查拉取请求后，您可以将其合并以将工作流添加到您的 GitHub 存储库。
本节包含使用 GitHub Actions 导入程序从 Bamboo 迁移时的环境变量、可选参数和支持的语法的参考信息。
GitHub Actions 导入程序使用环境变量进行身份验证配置。在使用configure命令遵循配置过程时设置这些变量。有关更多信息，请参阅“配置凭据”部分。
GitHub Actions 导入程序使用以下环境变量连接到您的 Bamboo 实例
GITHUB_ACCESS_TOKEN：用于使用转换后的工作流创建拉取请求的个人访问令牌（经典）（需要repo和workflow范围）。GITHUB_INSTANCE_URL：目标 GitHub 实例的 URL（例如，https://github.com）。BAMBOO_ACCESS_TOKEN：用于对您的 Bamboo 实例进行身份验证的 Bamboo 个人访问令牌。BAMBOO_INSTANCE_URL：Bamboo 实例的 URL（例如，https://bamboo.example.com）。
这些环境变量可以在.env.local文件中指定，该文件在运行 GitHub Actions 导入程序时由其加载。
您可以使用 GitHub Actions 导入程序子命令的一些可选参数来自定义您的迁移。
您可以将--source-file-path参数与dry-run或migrate子命令一起使用。
默认情况下，GitHub Actions 导入程序从 Bamboo 实例获取管道内容。--source-file-path参数告诉 GitHub Actions 导入程序改为使用指定的源文件路径。
例如
gh actions-importer dry-run bamboo build --plan-slug IN-COM -o tmp/bamboo --source-file-path ./path/to/my/bamboo/file.yml
您可以将--config-file-path参数与audit、dry-run和migrate子命令一起使用。
默认情况下，GitHub Actions 导入程序从 Bamboo 实例获取管道内容。--config-file-path参数告诉 GitHub Actions 导入程序改为使用指定的源文件。
在此示例中，GitHub Actions 导入程序使用指定的 YAML 配置文件执行审计。
gh actions-importer audit bamboo -o tmp/bamboo --config-file-path "./path/to/my/bamboo/config.yml"
要使用配置文件审计 Bamboo 实例，配置文件必须采用以下格式，并且每个repository_slug必须唯一
source_files:
- repository_slug: IN/COM
path: path/to/one/source/file.yml
- repository_slug: IN/JOB
path: path/to/another/source/file.yml
在此示例中，GitHub Actions 导入程序使用指定的 YAML 配置文件作为源文件执行试运行。
存储库标识符是使用--plan-slug选项构建的。源文件路径与指定的源文件匹配并从中提取。
gh actions-importer dry-run bamboo build --plan-slug IN-COM -o tmp/bamboo --config-file-path "./path/to/my/bamboo/config.yml"
下表显示了 GitHub Actions 导入程序当前能够转换的属性类型。
| Bamboo | GitHub Actions | 状态 |
|---|
环境 | 作业 | 支持 |
environments.<environment_id> | jobs.<job_id> | 支持 |
<job_id>.artifacts | jobs.<job_id>.steps.actions/upload-artifact | 支持 |
<job_id>.artifact-subscriptions | jobs.<job_id>.steps.actions/download-artifact | 支持 |
<job_id>.docker | jobs.<job_id>.container | 支持 |
<job_id>.final-tasks | jobs.<job_id>.steps.if | 支持 |
<job_id>.requirements | jobs.<job_id>.runs-on | 支持 |
<job_id>.tasks | jobs.<job_id>.steps | 支持 |
<job_id>.variables | jobs.<job_id>.env | 支持 |
阶段 | jobs.<job_id>.needs | 支持 |
stages.<stage_id>.final | jobs.<job_id>.if | 支持 |
stages.<stage_id>.jobs | 作业 | 支持 |
stages.<stage_id>.jobs.<job_id> | jobs.<job_id> | 支持 |
stages.<stage_id>.manual | jobs.<job_id>.environment | 支持 |
触发器 | on | 支持 |
依赖项 | jobs.<job_id>.steps.<gh cli step> | 部分支持 |
分支 | 不适用 | 不支持 |
deployment.deployment-permissions | 不适用 | 不支持 |
environment-permissions | 不适用 | 不支持 |
通知 | 不适用 | 不支持 |
plan-permissions | 不适用 | 不支持 |
release-naming | 不适用 | 不支持 |
存储库 | 不适用 | 不支持 |
有关支持的 Bamboo 概念和插件映射的更多信息，请参阅github/gh-actions-importer存储库。
GitHub Actions 导入程序使用下表中的映射将默认的 Bamboo 环境变量转换为 GitHub Actions 中最接近的等效项。
| Bamboo | GitHub Actions |
|---|
bamboo.agentId | ${{ github.runner_name }} |
bamboo.agentWorkingDirectory | ${{ github.workspace }} |
bamboo.buildKey | ${{ github.workflow }}-${{ github.job }} |
bamboo.buildNumber | ${{ github.run_id }} |
bamboo.buildPlanName | ${{ github.repository }}-${{ github.workflow }}-${{ github.job } |
bamboo.buildResultKey | ${{ github.workflow }}-${{ github.job }}-${{ github.run_id }} |
bamboo.buildResultsUrl | ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} |
bamboo.build.working.directory | ${{ github.workspace }} |
bamboo.deploy.project | ${{ github.repository }} |
bamboo.ManualBuildTriggerReason.userName | ${{ github.actor }} |
bamboo.planKey | ${{ github.workflow }} |
bamboo.planName | ${{ github.repository }}-${{ github.workflow }} |
bamboo.planRepository.branchDisplayName | ${{ github.ref }} |
bamboo.planRepository.<position>.branch | ${{ github.ref }} |
bamboo.planRepository.<position>.branchName | ${{ github.ref }} |
bamboo.planRepository.<position>.name | ${{ github.repository }} |
bamboo.planRepository.<position>.repositoryUrl | ${{ github.server }}/${{ github.repository }} |
bamboo.planRepository.<position>.revision | ${{ github.sha }} |
bamboo.planRepository.<position>.username | ${{ github.actor}} |
bamboo.repository.branch.name | ${{ github.ref }} |
bamboo.repository.git.branch | ${{ github.ref }} |
bamboo.repository.git.repositoryUrl | ${{ github.server }}/${{ github.repository }} |
bamboo.repository.pr.key | ${{ github.event.pull_request.number }} |
bamboo.repository.pr.sourceBranch | ${{ github.event.pull_request.head.ref }} |
bamboo.repository.pr.targetBranch | ${{ github.event.pull_request.base.ref }} |
bamboo.resultsUrl | ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} |
bamboo.shortJobKey | ${{ github.job }} |
bamboo.shortJobName | ${{ github.job }} |
bamboo.shortPlanKey | ${{ github.workflow }} |
bamboo.shortPlanName | ${{ github.workflow }} |
注意
未知变量将转换为${{ env.<variableName> }}，并且必须在env下替换或添加才能正常运行。例如，${bamboo.jira.baseUrl}将变为${{ env.jira_baseUrl }}。
任务中使用的系统变量将转换为等效的 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.