# GitLab CI/CD

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/zh-cn/help/idea/llms.txt).

IntelliJ IDEA 可识别  `.gitlab-ci.yml`  文件并为其提供编码辅助，您可以在其中为 GitLab CI/CD 流水线定义指令。 有关更多详细信息，请参阅 [GitLab 文档](https://docs.gitlab.com/topics/build_your_application/)。

Procedure: 启用 GitLab 插件

此功能性依赖于 [GitLab](https://plugins.jetbrains.com/plugin/22857-gitlab) 插件，该插件默认在 IntelliJ IDEA 中捆绑并启用。 如果相关功能不可用，请确保您没有禁用插件。

1. 按 `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)) 打开设置，然后选择  `插件` 。

2. 找到  GitLab  插件并点击   启用  。

## 功能

支持以下功能：

* [语法高亮](configuring-colors-and-fonts.html) IntelliJ IDEA 为 GitLab CI/CD 配置文件的所有组件提供语法高亮显示。 可以为配置的不同部分自定义配色方案： * 配置文件的 YAML 结构： `设置 | 编辑器 | 配色方案 | YAML` * [CI/CD 变量表达式](https://docs.gitlab.com/ci/jobs/job_rules/#cicd-variable-expressions)： `设置 | 编辑器 | 配色方案 | GitLab CI 表达式` * [shell 脚本受限标识符](#shell-injections)： `设置 | 编辑器 | 配色方案 | Shell 脚本`

* [检查](https://www.jetbrains.com/zh-cn/help/inspectopedia/GitLab-CI-CD.html) IntelliJ IDEA 可帮助实时检测 GitLab CI/CD 配置文件中的配置问题。 这包括重复的作业用法、未定义的作业和未定义的阶段。

* [代码补全](auto-completing-code.html) 获取流水线配置语法、关键字和 CI/CD 变量的补全建议。 ![流水线配置语法的代码补全](https://resources.jetbrains.com/help/img/idea/2026.3/gitlab-ci-completion.png)

* [代码导航](navigating-through-the-source-code.html#go_to_declaration) 在 CI/CD 配置文件中快速在 `stage` 和 `job` 的声明与用法之间导航。

* [快速文档](viewing-reference-information.html) 将鼠标悬停在符号上，或使用 文档 工具窗口（ `Ctrl+Q` (Windows), `F1` (macOS), `⌃ J` (IntelliJ IDEA Classic (macOS)), `⌘ I` (macOS System Shortcuts), `Ctrl+Q` (XWin), `Ctrl+Q` (GNOME), `Ctrl+Q` (KDE), `Ctrl+Q` (Emacs), `Ctrl+Q` (Sublime Text), `Ctrl+Q` (Sublime Text (macOS)), `Ctrl+K, I` (Visual Studio), `⌘ K, I` (Visual Studio (macOS)), `Ctrl+Q` (NetBeans), `Alt+Middle-Click` (Eclipse), `⌥ Middle-Click` (Eclipse (macOS))）查看快速文档，其中包括指向官方 GitLab CI 参考的链接。 ![GitLab CI 配置的快速文档](https://resources.jetbrains.com/help/img/idea/2026.3/gitlab-ci-quick-doc.png)

* [查找用法](find-highlight-usages.html) 直接在配置文件中搜索 `stage` 和 `job` 符号的用法。

* [重命名重构](rename-refactorings.html) 可以通过应用重命名重构（ `Shift+F6` (Windows), `⇧ F6` (macOS), `⇧ F6` (IntelliJ IDEA Classic (macOS)), `⌘ ⌥ R` (macOS System Shortcuts), `Shift+F6` (XWin), `Shift+F6` (GNOME), `Shift+F6` (KDE), `Shift+F6` (Emacs), `Shift+F6` (Sublime Text), `⇧ F6` (Sublime Text (macOS)), `Ctrl+R, R` (Visual Studio), `⌘ R, R` (Visual Studio (macOS)), `Ctrl+R` (NetBeans), `Alt+Shift+R` (Eclipse), `⇧ F6` (Eclipse (macOS))）更改声明和用法中 `stage` 和 `job` 符号的名称。

* Shell 脚本语言注入检测 IntelliJ IDEA 会自动检测配置文件的 `before_script` 、 `script` 和 `after_script` 块中的 shell 脚本受限标识符，并将其标记为 Inject 语言：Shell 脚本 。 IDE 会将这些代码段视为功能完整的 Shell 脚本。 可以编辑 shell 脚本片段、解释它们，并受益于特定于语言的功能，例如语法高亮显示和代码补全。 可以在配置文件的 injected 部分使用 switch shell 脚本注入 意图操作禁用此行为。 请注意，开启或关闭 shell 脚本受限标识符会影响整个项目。 ![GitLab CI 配置文件中的 shell 脚本受限标识符](https://resources.jetbrains.com/help/img/idea/2026.3/shell-script-injection-gitlab-ci.png)

## 故障排除

### 缺失的编码辅助功能

为确保完全支持 GitLab CI/CD，请检查  `.gitlab-ci.yml`  文件是否使用了正确的 JSON 架构。

IntelliJ IDEA 会自动加载热门架构设置，包括 GitLab 的 CI 架构（通常名称为  `gitlab-ci` ）。

如果代码补全、检查或导航等功能缺失或未按预期工作，问题可能与 JSON 架构配置有关。

Procedure: 配置 JSON 架构

* 在编辑器中打开  `.gitlab-ci.yml`  文件，并检查右下角的 JSON 架构微件。 确保已选择  `gitlab-ci` 。

![JSON 架构微件](https://resources.jetbrains.com/help/img/idea/2026.3/gitlab-ci-json-schema.png)

* 如果未列出该架构：

1.  从 [https://gitlab.com/gitlab-org/gitlab/-/raw/master/app/assets/javascripts/editor/schema/ci.json](https://gitlab.com/gitlab-org/gitlab/-/raw/master/app/assets/javascripts/editor/schema/ci.json) 手动下载。

2.  在 IntelliJ IDEA 中，转到  `设置 | 语言＆框架 | 架构和 DTD | JSON 架构映射`  并 [添加自定义 JSON 架构映射](json.html#ws_json_schema_add_custom_procedure)。

3.  使用 JSON 架构微件将添加的架构分配给  `.gitlab-ci.yml`  文件。