# Jenkins Organization Folder REST API 接口文档

Organization Folder 是 Jenkins 中用于自动扫描整个组织（如 GitHub Organization、GitLab Group、Bitbucket Team）并为每个仓库自动创建 Multibranch Pipeline 的项目类型 。[1]

***

## URL 层级结构

Organization Folder 比普通 Multibranch Pipeline 多一层嵌套，其层级结构为 ：[2][3]

```
{JENKINS_URL}
  └── /job/{ORG_FOLDER_NAME}              ← Organization Folder 层
        └── /job/{REPO_NAME}              ← Multibranch Pipeline 层（仓库）
              └── /job/{BRANCH_NAME}      ← 分支层
                    └── /{BUILD_NUMBER}   ← 构建层
```

***

## 一、获取组织与仓库信息

### 1.1 获取 Organization Folder 下所有仓库

| 项目 | 说明 |
|-----|------|
| **请求地址** | `GET {JENKINS_URL}/job/{ORG_FOLDER_NAME}/api/json` |
| **返回内容** | 该组织下所有已扫描的仓库列表（即 Multibranch Pipeline 列表）|

**常用参数**：
```
?tree=jobs[name,url,_class]&depth=1
```

### 1.2 获取某仓库下所有分支

| 项目 | 说明 |
|-----|------|
| **请求地址** | `GET {JENKINS_URL}/job/{ORG_FOLDER_NAME}/job/{REPO_NAME}/api/json` |
| **返回内容** | 该仓库下所有分支及其 Job 信息 |

**示例请求**：
```
GET {JENKINS_URL}/job/my-github-org/job/my-repo/api/json?tree=jobs[name,url,lastBuild[number,result]]
```

### 1.3 获取某分支的所有构建信息

| 项目 | 说明 |
|-----|------|
| **请求地址** | `GET {JENKINS_URL}/job/{ORG_FOLDER_NAME}/job/{REPO_NAME}/job/{BRANCH_NAME}/api/json` |
| **常用参数** | `?tree=builds[number,result,timestamp,duration]&depth=1` |

> **注意**：分支名中的 `/` 需要编码为 `%2F`，例如 `feature/login` → `feature%2Flogin`

***

## 二、触发分支构建

### 2.1 无参数构建

| 项目 | 说明 |
|-----|------|
| **请求地址** | `POST {JENKINS_URL}/job/{ORG_FOLDER_NAME}/job/{REPO_NAME}/job/{BRANCH_NAME}/build` |
| **认证** | 需要 Basic Auth（用户名 + API Token）|

### 2.2 带参数构建

| 项目 | 说明 |
|-----|------|
| **请求地址** | `POST {JENKINS_URL}/job/{ORG_FOLDER_NAME}/job/{REPO_NAME}/job/{BRANCH_NAME}/buildWithParameters` |
| **参数传递** | Query String 或 Form Data |

**示例**：
```
POST {JENKINS_URL}/job/my-github-org/job/my-repo/job/main/buildWithParameters?ENV=production&VERSION=1.0.0
```

### 2.3 获取构建号

构建触发后，从 `Location` Header 获取队列 ID，再查询实际构建号：

| 步骤 | 请求地址 |
|-----|---------|
| 获取队列项 | 响应 Header `Location` → `{JENKINS_URL}/queue/item/{QUEUE_ID}/` |
| 查询构建号 | `GET {JENKINS_URL}/queue/item/{QUEUE_ID}/api/json` |
| 返回字段 | `executable.number` 即为构建号 |

***

## 三、实时查看 Console 输出

### 3.1 获取完整日志

| 项目 | 说明 |
|-----|------|
| **请求地址** | `GET {JENKINS_URL}/job/{ORG_FOLDER_NAME}/job/{REPO_NAME}/job/{BRANCH_NAME}/{BUILD_NUMBER}/consoleText` |
| **返回格式** | 纯文本 |

### 3.2 增量实时获取

| 项目 | 说明 |
|-----|------|
| **请求地址** | `GET {JENKINS_URL}/job/{ORG_FOLDER_NAME}/job/{REPO_NAME}/job/{BRANCH_NAME}/{BUILD_NUMBER}/logText/progressiveText?start={OFFSET}` |
| **响应 Header** | `X-Text-Size`（下次偏移量）、`X-More-Data`（是否继续）|

***

## 四、组织扫描操作

### 4.1 触发组织扫描（发现新仓库/分支）

| 项目 | 说明 |
|-----|------|
| **扫描整个组织** | `POST {JENKINS_URL}/job/{ORG_FOLDER_NAME}/build` |
| **扫描单个仓库** | `POST {JENKINS_URL}/job/{ORG_FOLDER_NAME}/job/{REPO_NAME}/build` |

扫描操作会检测新增/删除的仓库和分支，并自动更新 Jenkins Job 结构 。[1]

### 4.2 查看扫描日志

| 项目 | 说明 |
|-----|------|
| **组织扫描日志** | `GET {JENKINS_URL}/job/{ORG_FOLDER_NAME}/computation/consoleText` |
| **仓库扫描日志** | `GET {JENKINS_URL}/job/{ORG_FOLDER_NAME}/job/{REPO_NAME}/indexing/consoleText` |

***

## 五、完整 URL 路径汇总

| 功能 | 请求方法 | URL 模板 |
|-----|---------|---------|
| 组织下所有仓库 | GET | `/job/{ORG}/api/json` |
| 仓库下所有分支 | GET | `/job/{ORG}/job/{REPO}/api/json` |
| 分支构建列表 | GET | `/job/{ORG}/job/{REPO}/job/{BRANCH}/api/json` |
| 单次构建详情 | GET | `/job/{ORG}/job/{REPO}/job/{BRANCH}/{NUM}/api/json` |
| 触发分支构建 | POST | `/job/{ORG}/job/{REPO}/job/{BRANCH}/build` |
| 带参数构建 | POST | `/job/{ORG}/job/{REPO}/job/{BRANCH}/buildWithParameters` |
| 完整日志 | GET | `/job/{ORG}/job/{REPO}/job/{BRANCH}/{NUM}/consoleText` |
| 增量日志 | GET | `/job/{ORG}/job/{REPO}/job/{BRANCH}/{NUM}/logText/progressiveText?start={OFFSET}` |
| 扫描组织 | POST | `/job/{ORG}/build` |
| 扫描仓库 | POST | `/job/{ORG}/job/{REPO}/build` |

> **特殊字符处理**：分支名中的 `/` 编码为 `%2F`，`#` 编码为 `%23`

[1](https://www.jenkins.io/doc/book/pipeline/pipeline-as-code/)
[2](https://plugins.jenkins.io/branch-api/)
[3](https://github.com/jenkinsci/branch-api-plugin)
[4](https://www.jenkins.io/doc/book/using/remote-access-api/)
[5](https://note.com/wa_k77/n/nad2af1ac6d95)
[6](https://stackoverflow.com/questions/55260693/jenkins-create-folder-with-rest-api-in-groovy-script)
[7](https://www.postman.com/api-evangelist/jenkins/folder/cu1b5xc/organization)
[8](https://www.kaizenprogrammer.com/entry/2017/03/20/130721)
[9](https://stackoverflow.com/questions/51428735/list-all-folders-under-jenkins-with-their-path)
[10](https://jenkins-job-builder.readthedocs.io/en/latest/project_githuborg.html)
[11](https://stackoverflow.com/questions/44054789/in-jenkins-how-to-build-job-which-is-inside-folder-using-rest-api)
[12](https://www.youtube.com/watch?v=BcUSfG4A9AI)
[13](https://stackoverflow.com/questions/38507358/how-to-use-jenkins-github-organization-folder-with-github-protected-branches)
[14](https://github.com/jenkinsci/folder-auth-plugin/blob/master/docs/rest-api.adoc)
[15](https://plugins.jenkins.io/cloudbees-folder/)
[16](https://community.jenkins.io/t/failing-to-build-in-an-github-organization-folder-repo/31760)
[17](https://qiita.com/Sho2010@github/items/2a9c13d2f67e754cfb4f)
[18](https://stackoverflow.com/questions/37615638/specify-the-git-url-location-of-jenkinsfile-in-a-github-organization-job)
[19](https://github.com/jenkinsci/branch-api-plugin/blob/master/src/main/java/jenkins/branch/OrganizationFolder.java)
[20](https://jenkinsci.github.io/job-dsl-plugin/)