如何通过Octopus API根据项目名称获取仓库名及对应环境分支名？

所有接口请求均需要在请求头携带X-Octopus-ApiKey字段，值为你在Octopus后台生成的API密钥，请求基础地址为你的Octopus实例根地址。

步骤1：根据项目名称获取项目唯一ID #

调用项目查询接口，按名称精确匹配目标项目：

GET /api/projects?name={你要查询的项目名称}

从返回的Items数组中找到名称完全匹配的项目，记录其Id字段值，格式通常为Projects-xxx。

如果你使用的Octopus版本不支持name精确匹配参数，可以替换为partialName做模糊查询，之后手动从返回结果中筛选目标项目即可。

步骤2：查询项目关联的版本控制仓库信息 #

拿到项目ID后，调用版本控制配置接口获取仓库信息：

GET /api/projects/{上一步拿到的项目ID}/version-control-configuration

返回结果中：

• 若对接的是外部Git仓库（Github、Gitlab、自建Git服务等），RepositoryUrl字段为仓库完整地址，可从地址中解析出仓库名称
• 若使用Octopus内置Git仓库，RepositoryName字段会直接返回仓库名称

针对2022年之前发布的旧版Octopus，版本控制配置直接包含在项目详情的VersionControl字段中，直接调用GET /api/projects/{项目ID}即可获取对应信息，无需单独调用上述接口。

步骤3：查询各部署环境对应的关联分支 #

Octopus中分支和部署环境的绑定关系是通过「通道（Channel）」做关联的，需要按以下顺序查询映射：

1. 先拉取全量环境列表，记录每个环境的ID和名称对应关系

   GET /api/environments
   

2. 拉取目标项目下的所有通道配置

   GET /api/projects/{项目ID}/channels
   

3. 每个通道的返回字段中：
   • Name为通道名称，多数团队会直接按部署环境命名通道（如开发、测试、生产）
   • Rules数组中的BranchFilter字段为该通道绑定的分支匹配规则，常见值如main、develop、release/*
   • LifecycleId字段关联的生命周期规则中，会配置该通道允许部署到的环境ID列表，和第一步拿到的环境列表做匹配，就能得到「部署环境-对应关联分支」的映射关系。

最简调用示例（PowerShell） #

# 替换为你自己的实例配置
$octopusUrl = "https://你的octopus实例访问地址"
$apiKey = "API-你生成的API密钥"
$targetProjectName = "要查询的项目名称"
$requestHeader = @{ "X-Octopus-ApiKey" = $apiKey }

# 查询项目ID
$projectInfo = Invoke-RestMethod -Uri "$octopusUrl/api/projects?name=$targetProjectName" -Headers $requestHeader | Select-Object -First 1
if (-not $projectInfo) { Write-Error "未找到指定名称的项目"; exit 1 }
$projectId = $projectInfo.Id

# 查询关联仓库信息
$repoInfo = Invoke-RestMethod -Uri "$octopusUrl/api/projects/$projectId/version-control-configuration" -Headers $requestHeader
Write-Host "=== 关联仓库信息 ==="
Write-Host "仓库地址：$($repoInfo.RepositoryUrl)"

# 查询环境、通道及分支映射
$envList = Invoke-RestMethod -Uri "$octopusUrl/api/environments" -Headers $requestHeader | Select-Object -ExpandProperty Items
$channelList = Invoke-RestMethod -Uri "$octopusUrl/api/projects/$projectId/channels" -Headers $requestHeader | Select-Object -ExpandProperty Items
Write-Host "`n=== 环境分支对应关系 ==="
foreach ($channel in $channelList) {
    $branchRules = $channel.Rules.BranchFilter -Join "、"
    Write-Host "通道[$($channel.Name)] 关联分支：$branchRules"
}

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