# Git插件异常：无法检出分支'main'，起始点'origin/main'

- **ID:** `cicd/jenkins-pipeline-checkout-failed-git`
- **领域:** cicd
- **类别:** build_error
- **错误码:** `GIT_CHECKOUT_FAILED`
- **验证级别:** ai_generated
- **修复率:** 84%

## 根因

Jenkins Git插件无法检出，因为分支或提交引用丢失、远程仓库不可达，或工作空间存在之前中止构建的陈旧锁文件。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| Jenkins 2.440 | active | — | — |
| Git Plugin 5.2.0 | active | — | — |
| Git 2.40 | active | — | — |

## 解决方案

1. ```
   Clean workspace and retry: add `cleanWs()` in pipeline or `git clean -fdx` before checkout, and ensure branch exists: `git branch -r | grep origin/main`
   ```
2. ```
   Use shallow clone with depth 1 to avoid stale refs: `checkout([$class: 'GitSCM', branches: [[name: '*/main']], extensions: [[$class: 'CloneOption', depth: 1, noTags: true, shallow: true]])`
   ```
3. ```
   Force fetch remote refs before checkout: `git fetch origin +refs/heads/main:refs/remotes/origin/main --force` in pipeline script
   ```

## 无效尝试

- **** — Workspace deletion alone doesn't fix remote connectivity issues or stale git refs; lock files may reoccur. (50% 失败率)
- **** — Plugin reinstall doesn't affect remote repo state or local git configuration; overkill for checkout issue. (70% 失败率)
- **** — Timeout increase doesn't resolve missing branches or authentication failures; only delays failure. (60% 失败率)