GitLab 使用指南

概述

GitLab 是一个完整的 DevOps 平台,提供从项目规划、源代码管理到 CI/CD、监控的全流程功能。本指南将帮助您全面了解 GitLab 的核心功能,包括项目管理、CI/CD 配置和权限管理。

GitLab 简介

核心功能

GitLab 提供了完整的 DevOps 工具链:

• 源代码管理: Git 仓库托管
• 项目管理: Issues、Milestones、Boards
• CI/CD: 内置持续集成和持续部署
• 代码审查: Merge Request 工作流
• 安全扫描: SAST、DAST、依赖扫描
• 容器注册: Docker 镜像仓库
• 监控: 性能监控和告警

版本对比

功能	Free	Premium	Ultimate
私有仓库	✓	✓	✓
CI/CD	400分钟/月	10000分钟/月	无限
代码审查	✓	✓	✓
安全扫描	-	✓	✓
合规管理	-	-	✓

项目管理

创建项目

通过网页创建

# 1. 访问 GitLab 实例
# 2. 点击 "New project"
# 3. 选择创建方式:
#    - Create blank project: 空白项目
#    - Create from template: 从模板创建
#    - Import project: 导入项目
# 4. 填写项目信息:
#    - Project name: my-project
#    - Project slug: my-project (URL 路径)
#    - Visibility: Public/Internal/Private

通过命令行创建

# 使用 GitLab CLI (glab)
glab repo create my-project --public

# 或手动创建
mkdir my-project
cd my-project
git init
git remote add origin https://gitlab.com/username/my-project.git
git add .
git commit -m "Initial commit"
git push -u origin main

项目设置

基本设置

# Settings -> General

Project settings:
  - Name: 项目名称
  - Description: 项目描述
  - Topics: 标签
  
Visibility:
  - Public: 所有人可见
  - Internal: 登录用户可见
  - Private: 仅项目成员可见
  
Features:
  - Issues: 启用 Issue 追踪
  - Repository: 启用代码仓库
  - Wiki: 启用 Wiki
  - Snippets: 启用代码片段

合并请求设置

# Settings -> Merge requests

Merge method:
  - Merge commit: 创建合并提交
  - Merge commit with semi-linear history: 半线性合并
  - Fast-forward merge: 快进合并

Merge checks:
  ☑ All discussions must be resolved
  ☑ Pipelines must succeed
  ☑ Allow merge commits
  ☑ Allow squash commits

Squash commit message:
  - Use commit message
  - Use merge request title

Issue 管理

创建 Issue

# 使用 GitLab CLI
glab issue create \
  --title "实现用户认证功能" \
  --description "## 功能描述\n添加用户登录和注册功能" \
  --label "feature" \
  --milestone "v1.0"

# 或通过网页创建
# Issues -> New issue

Issue 模板

创建 .gitlab/issue_templates/ 目录:

<!-- .gitlab/issue_templates/Feature.md -->
---
name: 功能请求
about: 建议新功能
title: '[FEATURE] '
labels: feature
---

## 功能描述
清晰描述需要实现的功能

## 业务价值
说明这个功能的价值

## 实现建议
提供实现思路

## 验收标准
- [ ] 标准1
- [ ] 标准2

## 相关资料
- 设计稿
- 参考链接

<!-- .gitlab/issue_templates/Bug.md -->
---
name: Bug 报告
about: 报告问题
title: '[BUG] '
labels: bug
---

## Bug 描述
清晰描述遇到的问题

## 复现步骤
1. 步骤1
2. 步骤2
3. 步骤3

## 期望行为
描述期望的结果

## 实际行为
描述实际的结果

## 环境信息
- GitLab 版本:
- 浏览器:
- 操作系统:

## 截图
如有必要,添加截图

Issue Board

# 创建 Issue Board
# Issues -> Boards -> Create new board

# Board 配置
Board name: Sprint Board

Lists:
  - Open: 所有未分配的 Issue
  - In Progress: 进行中
  - Review: 代码审查
  - Testing: 测试中
  - Done: 已完成

# 使用标签过滤
Labels:
  - backend
  - frontend
  - bug
  - feature

Milestone 管理

# 创建 Milestone
glab milestone create "v1.0" \
  --title "Version 1.0" \
  --description "第一个正式版本" \
  --due-date "2024-12-31"

# 查看 Milestone
glab milestone list

# 将 Issue 分配到 Milestone
glab issue update <issue-id> --milestone "v1.0"

CI/CD 配置

.gitlab-ci.yml 基础

基本结构

# .gitlab-ci.yml

stages:
  - build
  - test
  - deploy

variables:
  NODE_VERSION: "18"

before_script:
  - echo "Start CI/CD Pipeline"

build:
  stage: build
  image: node:${NODE_VERSION}
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 week

test:
  stage: test
  image: node:${NODE_VERSION}
  script:
    - npm ci
    - npm test
  coverage: '/Lines\s*:\s*(\d+\.?\d*)%/'
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml

deploy:
  stage: deploy
  script:
    - ./deploy.sh
  environment:
    name: production
    url: https://example.com
  only:
    - main
  when: manual

完整 CI/CD 流水线

# .gitlab-ci.yml

stages:
  - lint
  - test
  - build
  - security
  - deploy_staging
  - deploy_production

variables:
  DOCKER_IMAGE: ${CI_REGISTRY_IMAGE}:${CI_COMMIT_SHA}
  DOCKER_TLS_CERTDIR: ""

.lint_template: &lint_template
  image: node:18
  cache:
    paths:
      - node_modules/
    key:
      files:
        - package-lock.json

lint:
  <<: *lint_template
  stage: lint
  script:
    - npm ci
    - npm run lint
  only:
    - merge_requests

test:unit:
  <<: *lint_template
  stage: test
  script:
    - npm ci
    - npm test -- --coverage
  coverage: '/Lines\s*:\s*(\d+\.?\d*)%/'
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml
      junit: junit.xml
  only:
    - merge_requests
    - main

test:e2e:
  stage: test
  image: cypress/browsers:latest
  script:
    - npm ci
    - npm run e2e
  artifacts:
    paths:
      - cypress/videos/
      - cypress/screenshots/
    when: on_failure
  only:
    - main

build:docker:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker login -u ${CI_REGISTRY_USER} -p ${CI_REGISTRY_PASSWORD} ${CI_REGISTRY}
    - docker build -t ${DOCKER_IMAGE} .
    - docker push ${DOCKER_IMAGE}
  only:
    - main
    - tags

security:sast:
  stage: security
  include:
    - template: Security/SAST.gitlab-ci.yml

security:dependency_scan:
  stage: security
  include:
    - template: Security/Dependency-Scanning.gitlab-ci.yml

security:container_scan:
  stage: security
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker pull ${DOCKER_IMAGE}
    - docker run --rm -v /var/run/docker.sock:/var/run/docker.sock
      aquasec/trivy image ${DOCKER_IMAGE}
  allow_failure: true
  only:
    - main

deploy:staging:
  stage: deploy_staging
  image: alpine:latest
  script:
    - apk add --no-cache curl
    - curl -X POST ${STAGING_DEPLOY_HOOK}
  environment:
    name: staging
    url: https://staging.example.com
  only:
    - main
  when: manual

deploy:production:
  stage: deploy_production
  image: alpine:latest
  script:
    - apk add --no-cache curl
    - curl -X POST ${PRODUCTION_DEPLOY_HOOK}
  environment:
    name: production
    url: https://example.com
  only:
    - main
  when: manual
  needs:
    - deploy:staging

环境变量管理

# Settings -> CI/CD -> Variables

# 定义环境变量
Variables:
  - Key: DATABASE_URL
    Value: postgresql://...
    Protected: true
    Masked: true
    
  - Key: API_KEY
    Value: secret-api-key
    Protected: true
    Masked: true
    
  - Key: NODE_ENV
    Value: production
    Protected: false

# 在 CI/CD 中使用变量
deploy:
  stage: deploy
  script:
    - echo "Deploying to ${ENVIRONMENT}"
    - ./deploy.sh
  variables:
    ENVIRONMENT: production

缓存和产物

# 缓存配置
cache:
  paths:
    - node_modules/
    - .npm/
  key:
    files:
      - package-lock.json
    prefix: ${CI_COMMIT_REF_SLUG}

# 产物配置
artifacts:
  paths:
    - dist/
    - build/
  exclude:
    - dist/**/*.map
  expire_in: 1 week
  when: always

自动部署

# 自动部署到 staging
deploy:staging:auto:
  stage: deploy_staging
  script:
    - ./deploy.sh staging
  environment:
    name: staging
    url: https://staging.example.com
  only:
    - main
  except:
    - schedules

# 定时部署到 production
deploy:production:scheduled:
  stage: deploy_production
  script:
    - ./deploy.sh production
  environment:
    name: production
    url: https://example.com
  only:
    - schedules

权限管理

用户角色

角色	权限
Guest	查看 Issue、评论
Reporter	查看代码、拉取代码
Developer	推送代码、创建 MR
Maintainer	管理分支、合并 MR
Owner	完全控制权限

项目成员管理

# 添加项目成员
# Settings -> Members -> Invite member

# 通过 API 添加
curl --request POST \
  --header "PRIVATE-TOKEN: <your-access-token>" \
  --data "user_id=<user-id>" \
  --data "access_level=30" \
  "https://gitlab.com/api/v4/projects/<project-id>/members"

组权限管理

# Groups -> Settings -> General

Permissions:
  Default role: Developer
  
Group features:
  ☑ Wiki
  ☑ Issues
  ☑ Merge requests
  ☑ CI/CD
  
Share with group lock:
  ☑ Prevent sharing projects with other groups

受保护分支

# Settings -> Repository -> Protected branches

Branch: main
Allowed to merge:
  - Maintainers
  
Allowed to push:
  - No one
  
Allowed to force push:
  - Disabled
  
Code owner approval:
  ☑ Require approval from code owners

受保护标签

# Settings -> Repository -> Protected tags

Tag: v*
Allowed to create:
  - Maintainers

Tag: release-*
Allowed to create:
  - Maintainers
  - Developers

Merge Request 工作流

创建 MR

# 使用 GitLab CLI
glab mr create \
  --title "feat: 添加用户认证功能" \
  --description "## 变更内容\n- 添加登录功能\n- 添加注册功能\n\n## 测试\n- [ ] 单元测试\n- [ ] 集成测试" \
  --source-branch feature/auth \
  --target-branch main \
  --assignee @me \
  --label feature

# 或通过网页创建
# Merge Requests -> New merge request

MR 模板

创建 .gitlab/merge_request_templates/ 目录:

<!-- .gitlab/merge_request_templates/Default.md -->
## 变更类型
- [ ] 新功能
- [ ] Bug 修复
- [ ] 重构
- [ ] 文档更新
- [ ] 其他

## 变更描述
描述本次变更的内容

## 相关 Issue
Closes #

## 测试计划
- [ ] 单元测试
- [ ] 集成测试
- [ ] 手动测试

## 检查清单
- [ ] 代码遵循项目规范
- [ ] 已添加测试
- [ ] 文档已更新
- [ ] 无性能问题
- [ ] 无安全问题

## 截图
如有 UI 变更,添加截图

代码审查

# 查看 MR 列表
glab mr list

# 查看 MR 详情
glab mr view <mr-id>

# 审查 MR
glab mr review <mr-id> --approve
glab mr review <mr-id> --comment "代码看起来不错!"

# 请求修改
glab mr review <mr-id> --request-changes

# 合并 MR
glab mr merge <mr-id> --squash

最佳实践

项目结构

project/
├── .gitlab/
│   ├── issue_templates/
│   │   ├── Bug.md
│   │   └── Feature.md
│   └── merge_request_templates/
│       └── Default.md
├── .gitlab-ci.yml
├── README.md
├── CONTRIBUTING.md
├── CHANGELOG.md
├── LICENSE
└── src/

CI/CD 最佳实践

# 使用锚点复用配置
.scripts: &scripts
  - npm ci
  - npm run build

.job_template: &job_template
  image: node:18
  cache:
    paths:
      - node_modules/

build:
  <<: *job_template
  script: *scripts

# 使用 needs 优化依赖
test:unit:
  stage: test
  needs: []

test:integration:
  stage: test
  needs: ["build"]

deploy:
  stage: deploy
  needs: ["test:unit", "test:integration"]

安全最佳实践

# 安全扫描配置
include:
  - template: Security/SAST.gitlab-ci.yml
  - template: Security/Dependency-Scanning.gitlab-ci.yml
  - template: Security/License-Scanning.gitlab-ci.yml
  - template: Security/Secret-Detection.gitlab-ci.yml

# 安全策略
security_scan:
  stage: security
  script:
    - echo "Running security scans"
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == "main"

总结

GitLab 提供了完整的 DevOps 平台:

核心优势:

• 一体化平台: 从规划到部署全流程覆盖
• 内置 CI/CD: 无需第三方服务
• 安全功能: 完善的安全扫描工具
• 灵活配置: 高度可定制的工作流

最佳实践:

• 使用 Issue 模板规范问题报告
• 使用 MR 模板提高代码审查效率
• 配置完善的 CI/CD 流水线
• 定期进行安全扫描
• 合理设置权限和分支保护

通过合理使用 GitLab 的各项功能,可以构建高效的 DevOps 工作流,提高团队协作效率。