快速上手

想快速在GitLab上创建一个新项目？跟着下面这几步走，几分钟就能搞定。

• 首先，登录你的GitLab账户。
• 点击页面右上角的 New project 按钮，你可以选择创建一个空白项目（Create blank project），或者从其他平台直接导入（Import project）。
• 接下来，填写项目的基本信息：Project name（项目名称）和 Project slug（项目路径，通常会自动与名称保持一致）。
• 设置项目的可见性级别（Visibility Level）：Private（仅项目成员可见）、Internal（所有登录用户可见）、Public（完全公开）。根据你的项目性质选择合适的选项。
• 这里有个小技巧：可以勾选 Initialize repository with a README 选项，它会帮你自动生成初始提交，让仓库立刻“活”起来。
• 最后，点击 Create project，你的项目就创建完成了。

创建后的初始化与本地推送

项目创建好了，下一步就是把本地代码和这个远程仓库关联起来。别担心，操作很直观。

• 进入你刚创建的项目，在 Code 页面找到并复制仓库地址。GitLab支持HTTPS和SSH两种协议。
• 现在，在本地初始化并关联远程仓库。有两种主流方式：
  • 方式一（使用HTTPS协议）：

    git clone https://gitlab.example.com/namespace/project.git
    cd project
    # 编辑你的文件后
    git add .
    git commit -m "init"
    git push -u origin main

  • 方式二（使用SSH协议，速度更快，但需要提前将SSH公钥添加到GitLab账户）：

    git clone git@gitlab.example.com:namespace/project.git
    cd project
    # 编辑你的文件后
    git add .
    git commit -m "init"
    git push -u origin main

• 如果你的代码已经在本地，只是需要关联到一个新的空远程仓库，可以在项目根目录执行：

  git init
  git remote add origin git@gitlab.example.com:namespace/project.git
  git add .
  git commit -m "init"
  git branch -M main
  git push -u origin main

• 一个良好的习惯是，在项目初期就添加 .gitignore 文件来排除不必要的文件，并编写清晰的 README.md 文档。这能极大地方便后续的团队协作和项目维护。

进阶设置与最佳实践

当项目步入正轨，或者你开始管理多个项目时，下面这些进阶设置能让你的工作流更高效、更规范。

• 善用组（Group）与子组（Subgroup）：这是管理多项目和权限的利器。可以按业务功能、团队或微服务来划分组，将相关项目放在一起，权限管理一目了然，也便于未来扩展。
• 设置保护分支（Protected Branches）：这是保证代码主干（如main/master分支）清洁的关键。进入项目 Settings → Repository → Protected Branches，选择要保护的分支（例如main），将其设置为仅允许Maintainers角色进行合并（Merge），并禁止直接推送（Push）。更严谨的做法是启用 Merge requests only，并勾选要求CI/CD流水线通过后才能合并，实现自动化门禁。
• 启用合并请求审批（Merge Request Approvals）：在 Settings → Merge request approvals 中，可以配置最少审批人数，甚至可以指定 代码所有者（Code Owners）。当修改涉及特定文件时，会自动要求指定人员审批，这能有效提升代码质量和知识共享。
• 规范需求与迭代管理：充分利用GitLab内置的 议题（Issues）、看板（Issue Board） 和 史诗（Epics） 功能。将它们与固定的迭代节奏（Iteration Cadence）结合，就能形成一个从需求提出到代码交付的完整闭环，让项目管理清晰可控。
• 命名与文档规范：项目名称尽量使用英文，避免中文字符可能带来的兼容性问题。对于内部项目，优先选择Private可见性以保障安全。别忘了，一个配置得当的 .gitignore 和一份清晰的 README 文档，是专业项目的“标配”。

自动化创建与常见问题

对于需要批量操作或集成到自动化流程的场景，GitLab的API就派上用场了。当然，过程中也可能遇到一些小麻烦，这里一并给出排查思路。

• 通过API创建项目：如果你需要通过脚本自动化创建项目，可以使用下面的cURL命令示例：

  curl --request POST \
  --header "PRIVATE-TOKEN: " \
  --data "name=my-project" \
  --data "visibility=private" \
  "https://gitlab.example.com/api/v4/projects"

  记得将 替换为你自己的Personal Access Token。
• 常见问题排查：
  • 推送被拒绝或提示无权限：首先检查你是否使用了SSH方式且已将公钥正确添加到GitLab账户。如果问题依旧，可以尝试切换为HTTPS协议，并在推送时输入用户名和密码（或访问令牌）。
  • 分支受保护无法推送：这说明目标分支（如main）已按上述最佳实践设置了保护。正确的做法是创建一个新的特性分支进行开发，然后通过提交合并请求（Merge Request）的方式来发起代码变更。
  • 导入项目失败：确认源仓库的地址是否正确且当前有访问权限。如果是从需要认证的私有仓库导入，确保提供了有效的凭据，例如使用Personal Access Token进行认证。