GitHub CLI 离线验证构建证明时遇到的编码问题解析

在软件开发过程中，构建证明（attestation）是一种重要的安全机制，它能够验证二进制文件的来源和构建过程。GitHub CLI 提供了相关功能来生成和验证这些证明。然而，在使用过程中，开发者可能会遇到一些意料之外的问题。

问题现象

当开发者尝试使用 GitHub CLI 进行离线验证时，可能会遇到如下错误信息：

Error: failed to find recognized issuer from bundle content: failed to create custom verifier: proto: syntax error (line 1:1): invalid value �

这个错误表明系统在解析信任根文件时遇到了编码问题，具体表现为文件开头出现了无效的 UTF-8 字符。

问题根源

经过深入分析，我们发现这个问题与 Windows 系统下 PowerShell 的默认编码行为有关：

1. PowerShell 默认使用 UTF-16 LE 编码处理输出流
2. 当开发者使用重定向操作符（>）保存信任根文件时，文件会被保存为 UTF-16 LE 格式
3. GitHub CLI 的验证工具期望输入文件是标准的 UTF-8 编码

解决方案

针对这个问题，我们提供了几种可行的解决方案：

方案一：使用 PowerShell Core

PowerShell Core（pwsh）默认使用 UTF-8 编码，可以避免这个问题：

gh attestation trusted-root > trusted_root.jsonl

方案二：显式设置编码

在传统 PowerShell 中，可以显式设置输出编码：

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
gh attestation trusted-root > trusted_root.jsonl

方案三：使用 Out-File 命令

虽然这种方法可能会产生 BOM（字节顺序标记），但在某些情况下也可行：

gh attestation trusted-root | Out-File -Encoding utf8 trusted_root.jsonl

最佳实践建议

1. 环境一致性：在 CI/CD 管道中，确保所有步骤使用相同的 shell 环境
2. 编码检查：在关键步骤后检查文件的编码格式
3. 文档记录：在团队内部文档中记录这些技术细节，方便新成员快速上手
4. 测试验证：在部署前进行充分的测试验证，确保整个流程的可靠性

技术背景

理解这个问题需要一些编码知识：

• UTF-8：互联网标准编码，向后兼容 ASCII
• UTF-16：Windows 系统常用编码，使用 2 或 4 字节表示字符
• BOM：字节顺序标记，用于标识文本的字节顺序和编码

在跨平台开发中，编码问题是一个常见的挑战。开发者需要了解不同平台的默认行为，并采取适当的预防措施。

通过理解这些技术细节和解决方案，开发者可以更顺利地使用 GitHub CLI 进行构建证明的离线验证，确保软件供应链的安全性和可靠性。