XHGit · 产品文档

软件包与制品

软件包的发布、安装、关联仓库、权限与清理。

01

阅读导览

软件包用于给包管理器提供有版本的依赖与制品,支持个人或组织拥有者。它与 Git 源码、发布附件和 Actions 临时产物分别管理。把软件包关联到仓库有助于查找来源,但不会把拥有者级软件包自动变成仓库文件。

02

找到软件包与安装说明

  1. 打开个人或组织主页的软件包入口,地址形式为 /拥有者/-/packages。
  2. 选择需要的软件包类型、名称和版本,检查描述、文件、发布时间和关联仓库。
  3. 从包详情页复制该生态的源配置和安装命令,替换为自己的运行环境。
  4. 固定需要的版本,先在测试项目中安装并验证,再用于正式项目。

仓库“软件包”页显示与该仓库关联的包,不一定代表拥有者名下的全部软件包。入口缺失时先确认站点已启用软件包服务以及当前账号的访问权限。

03

准备发布权限与凭据

  1. 确认目标拥有者是自己的账号,或有权发布的组织。
  2. 在应用设置创建合适的访问令牌。下载使用软件包读取权限,发布与删除需要软件包写入权限。
  3. 按包管理器要求配置认证,优先使用客户端凭据存储、交互输入或自动化密钥。
  4. CI 中将凭据存入 Actions Secrets,不要写到仓库文件、镜像层或构建日志。

权限由账号、令牌范围和目标拥有者共同决定,不能仅凭一个名为“Token”的字符串发布到任意组织。开启双重验证后,也应使用适用的令牌或客户端认证方式。详见集成与令牌。

04

发布一个通用文件包

通用包适合托管没有专用包格式的版本化文件。下面全部使用测试值,curl 会提示输入密码,此处应输入具有软件包写入权限的测试令牌:

curl --fail --user TEST_USER --upload-file ./demo.zip \
  https://git.example.test/api/packages/team/generic/demo/0.1.0/demo.zip
  1. 先确认本地文件内容、版本名和目标拥有者。
  2. 上传成功后进入拥有者软件包页,打开 demo 的 0.1.0 版本。
  3. 下载同一文件,比较大小或校验值,确认发布的是预期产物。

失败时先读 HTTP 状态与返回信息,不要直接通过删除已有正式版本来“解决”重复上传。

05

接入语言与容器生态

当前提供 Alpine、Arch、Cargo、Chef、Composer、Conan、Conda、容器镜像、CRAN、Debian、Generic、Go、Helm、Maven、npm、NuGet、Pub、PyPI、RPM、RubyGems、Swift、Terraform 和 Vagrant 接口。

每种生态对包名、版本、认证和上传格式都有自己的要求。各语言软件包接入逐项说明源地址、安装方式与凭据要点。某个生态有接口不代表任意文件改个后缀就能上传,也不代表服务自动构建这个语言的项目。

06

关联仓库并管理版本

具有包管理权限的成员可以进入包设置,按页面提供的操作关联到同一拥有者下的仓库。关联后从仓库软件包入口能更容易找到对应制品;包本身仍归个人或组织拥有。

包详情页可以查看版本列表和该版本的文件。发布前约定稳定版本、预览版本与快照版本的命名方式。已经被他人依赖的版本应保持可追溯,修复后优先发布新版本,避免悄悄替换文件导致相同版本产生不同内容。

07

设置可见性与清理规则

可见性和可访问范围取决于拥有者、包设置及站点策略,关联公开仓库不能代替实际权限检查。私有包需要客户端携带有效凭据,浏览器登录状态通常不能直接供命令行客户端使用。

个人的软件包设置或组织对应设置提供当前可用的清理规则。先限定包类型、匹配规则和保留范围,使用预览检查将被影响的版本,再保存。清理可能影响仍被项目引用的旧版本,设置保留规则前应了解依赖使用情况。

08

区分三类下载产物

面向用户长期下载的安装包可以放在版本发布,面向包管理器的版本依赖放在软件包,供开发者检查一次任务结果的文件放在Actions 产物。三者保留策略和认证入口不同。

遇到 401/403 时检查身份、令牌的软件包范围与拥有者;404 时核对包类型、名称、版本和读取权限;内容格式错误时使用生态自己的打包工具重新生成。避免把真实令牌、完整认证头或含密码的源地址贴进公开议题。