修改spec文件适配新Git仓库下的在线HTML文档包构建

背景概述 #

• 团队已将产品内置帮助文档的交付位置从SVN迁移至Git，所有源内容文件在Git中统一管理
• 构建产品包必须包含两个核心文件：空文件write_tar和RPM规格文件sh_doc.spec
• 原SVN交付规则：路径为SVN\branches<drop-folder>，文件夹命名格式为<release-codename>_<release #.#>
• 新Git交付规则：每个产品单独创建独立仓库，交付分支命名格式为<product>-<major.minor-version#>.x
• 已验证：测试仓库与正式新仓库均配置了Jenkins构建系统所需的相同SSH密钥
• 现状：测试仓库sh_doc搭配旧格式分支<release-codename>_<release #.#>可正常构建；正式新仓库（命名格式help-<product-name>）构建失败，推测需修改sh_doc.spec，但因脚本由离职人员编写，暂不清楚具体修改点

成功构建的BDF配置（敏感信息已脱敏） #

name: sh_doc
  repo:
    uri: ssh://git@code.xxxxxxxx.net:#####/doctest/sh_doc.git
    branch: <release-codename>_<##.##>
    point: <removed>
    scm: git

失败构建的BDF配置 #

name: sh_doc
  repo:
    uri: ssh://git@code.xxxxxxxx.net:#####/doctest/help-newrepo.git
    branch: <product>-<##.##>.x
    point: xxxxxxxxxxxxbaf0a06c2ff0e622bd3fa88187
    scm: git

构建错误日志 #

核心错误为401未授权：

[08/10 13:42:42.298] DEBUG   requests.packages.urllib3.connectionpool: “GET /projects/doctest/repos/help-newrepo/raw/sh_doc.spec?at=xxxxxxxxxxbaf0a06c2ff0e622bd3fa88187 HTTP/1.1” **401** 3514

完整日志上下文：

[08/10 13:42:42.125] DEBUG   BitbucketGitRepository: Fetching raw url: https://code.xxxxxxx.net/projects/doctest/repos/help-newrepo/raw/sh_doc.spec?at=xxxxxxxxxxbaf0a06c2ff0e622bd3fa88187
[08/10 13:42:42.127] DEBUG   BitbucketClient: For repo: ssh://git@code.xxxxxxx.net:#####/doctest/help-newrepo.git
    ['doctest', 'help-newrepo']
[08/10 13:42:42.127] INFO    requests.packages.urllib3.connectionpool: Starting new HTTPS connection (1): code.xxxxxxx.net
[08/10 13:42:42.129] INFO    requests.packages.urllib3.connectionpool: Starting new HTTPS connection (1): code.xxxxxxx.net
/usr/lib/python2.6/site-packages/requests/packages/urllib3/util/ssl_.py:##: InsecurePlatformWarning: A true SSLContext object is not available. This prevents urllib3 from configuring SSL appropriately and may cause certain SSL connections to fail. For more information, see https://urllib3.readthedocs.org/en/latest/security.html#insecureplatformwarning.
  InsecurePlatformWarning
[08/10 13:42:42.298] DEBUG   requests.packages.urllib3.connectionpool: "GET /projects/doctest/repos/help-newrepo/raw/sh_doc.spec?at=xxxxxxxxxxxxbaf0a06c2ff0e622bd3fa88187 HTTP/1.1" 401 3514
[08/10 13:42:42.302] DEBUG   BitbucketGitRepository: Raw output failed. Falling back to local repo for sh_doc.spec
[08/10 13:42:42.302] DEBUG   BitbucketGitRepository: Initializing new repo: /tmp/tmpXXXXXRv-bannow-repos/help-newrepo.git

现有sh_doc.spec文件内容 #

Name:sh_doc
Version:0.1
Release:1%{?dist}
Summary:SH documentation
License:proprietary
Source: %{name}-%{version}.tar.gz
Autoreq: 0

%define _prefix /opt/tms/web2/html

%define debug_package %{nil}

%description
Holder for SH docs

%prep
%setup -q

%build

%install
rm -rf $RPM_BUILD_ROOT

dirs="\
help_xx \
"

srcdir=$RPM_BUILD_DIR/%{name}-%{version}
tgtdir=$RPM_BUILD_ROOT/%{_prefix}

for dir in $dirs ; do
    mkdir -p $tgtdir/${dir}gz
    (cd $srcdir/$dir ; tar cf - . --exclude=.svn --exclude=.git) | (cd $tgtdir/${dir}gz ; tar xvf -; find $tgtdir/${dir}gz -type f ! -name '*.gz' -exec gzip -9 "{}" \;)
done

%files
%defattr(-,root,root,-)
%{_prefix}/help_xxgz

排查结论与修改建议 #

1. 401错误根源 #

构建系统尝试通过HTTPS拉取sh_doc.spec时未通过认证，尽管SSH密钥已配置，但当前构建逻辑在拉取raw文件时未使用SSH认证，而是默认走HTTPS且未携带有效凭证。测试仓库能成功是因为旧分支对应的拉取逻辑适配了sh_doc仓库名，新仓库名help-<product-name>触发了未适配的路径逻辑。

2. spec文件核心修改点 #

• 调整Name字段：当前spec中Name:sh_doc与新仓库名help-newrepo不匹配，需将Name修改为新仓库的名称（如help-newrepo），确保%{name}变量能正确指向新仓库的源码包和目录。
• 验证Source路径：Source: %{name}-%{version}.tar.gz依赖与Name一致的源码包命名，若新仓库的源码包命名规则已变更，需同步修改Source字段指向正确的包路径。
• 检查srcdir变量：srcdir=$RPM_BUILD_DIR/%{name}-%{version}依赖%{name}对应解压后的目录名，修改Name后该变量会自动指向新仓库的源码目录，无需额外调整。

3. 构建逻辑补充适配 #

确认Jenkins构建脚本中是否存在基于仓库名的分支或路径判断逻辑，旧逻辑针对sh_doc仓库做了特殊适配，需同步更新脚本中的仓库名判断，确保拉取spec文件时优先使用SSH方式而非HTTPS。

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