GitHub 使用指南

概述

GitHub 是全球最大的代码托管平台,为开发者提供了强大的协作工具和丰富的功能。本指南将帮助您全面了解 GitHub 的核心功能,包括仓库管理、Issue 追踪、Pull Request 工作流以及 GitHub Actions 自动化。

GitHub 简介

核心功能

GitHub 提供了以下核心功能:

• Git 仓库托管: 安全可靠的代码存储
• 协作开发: Pull Request 和代码审查
• 项目管理: Issues、Projects 和 Milestones
• 持续集成: GitHub Actions 自动化工作流
• 安全功能: Dependabot、安全警报
• 社区功能: Discussions、Wiki

账户类型

类型	适用场景	特点
Personal	个人开发者	免费私有仓库
Organization	团队协作	统一管理、权限控制
Enterprise	企业级应用	高级安全功能、合规性

仓库管理

创建仓库

通过网页创建

# 1. 访问 GitHub.com
# 2. 点击右上角 "+" 按钮
# 3. 选择 "New repository"
# 4. 填写仓库信息:
#    - Repository name: my-project
#    - Description: 项目描述
#    - Public/Private: 公开/私有
#    - Initialize with README: 初始化 README
#    - Add .gitignore: 选择模板
#    - Choose a license: 选择许可证

通过命令行创建

# 创建本地仓库并推送到 GitHub
mkdir my-project
cd my-project
git init
git add .
git commit -m "Initial commit"

# 使用 GitHub CLI 创建远程仓库
gh repo create my-project --public --source=. --push

# 或手动添加远程仓库
git remote add origin https://github.com/username/my-project.git
git branch -M main
git push -u origin main

仓库设置

基本设置

# Settings 选项

General:
  - Repository name: 仓库名称
  - Description: 描述
  - Website: 项目网站
  - Topics: 标签(便于搜索)
  
Features:
  - Wikis: 启用 Wiki
  - Issues: 启用 Issues
  - Discussions: 启用讨论
  - Projects: 启用项目看板
  
Danger Zone:
  - Change visibility: 更改可见性
  - Transfer: 转移仓库
  - Archive: 归档仓库
  - Delete: 删除仓库

分支保护规则

# Settings -> Branches -> Add rule

Branch name pattern: main

Rules:
  ☑ Require a pull request before merging
    ☑ Require approvals: 1
    ☑ Dismiss stale pull request approvals
    ☑ Require review from Code Owners
    
  ☑ Require status checks to pass before merging
    ☑ Require branches to be up to date
    Status checks:
      - ci/build
      - ci/test
      
  ☑ Require signed commits
  ☑ Include administrators

仓库模板

# 创建模板仓库
# Settings -> Template repository

# 使用模板创建新仓库
gh repo create new-project --template username/template-repo

# 或在网页上点击 "Use this template"

Issue 和 PR

Issue 管理

创建 Issue

# 使用 GitHub CLI 创建 Issue
gh issue create --title "修复登录页面错误" --body "描述问题详情"

# 带标签和指派人
gh issue create \
  --title "添加用户个人资料功能" \
  --body "## 功能描述\n实现用户个人资料页面" \
  --label "enhancement,feature" \
  --assignee @me

Issue 模板

创建 .github/ISSUE_TEMPLATE/ 目录:

<!-- .github/ISSUE_TEMPLATE/bug_report.md -->
---
name: Bug 报告
about: 报告一个 Bug
title: '[BUG] '
labels: bug
assignees: ''
---

## Bug 描述
清晰简洁地描述这个 Bug

## 复现步骤
1. 访问 '...'
2. 点击 '...'
3. 滚动到 '...'
4. 看到错误

## 期望行为
描述你期望发生什么

## 实际行为
描述实际发生了什么

## 截图
如果适用,添加截图帮助解释问题

## 环境信息
 - OS: [e.g. macOS, Windows]
 - Browser: [e.g. Chrome, Safari]
 - Version: [e.g. 22]

<!-- .github/ISSUE_TEMPLATE/feature_request.md -->
---
name: 功能请求
about: 建议一个新功能
title: '[FEATURE] '
labels: enhancement
assignees: ''
---

## 功能描述
清晰简洁地描述你想要的功能

## 问题背景
这个功能要解决什么问题

## 建议方案
描述你建议的解决方案

## 替代方案
描述你考虑过的其他方案

## 附加信息
其他相关信息或截图

Issue 看板

# 使用 Projects 功能管理 Issue

# 创建项目
gh project create --owner @me --title "Q1 开发计划"

# 添加 Issue 到项目
gh project item-add <project-number> --url <issue-url>

# 查看项目列表
gh project list

Pull Request 工作流

创建 PR

# 创建特性分支
git checkout -b feature/user-profile

# 进行开发
git add .
git commit -m "feat: add user profile component"
git push origin feature/user-profile

# 创建 PR
gh pr create \
  --title "feat: 添加用户个人资料功能" \
  --body "## 变更内容\n- 添加个人资料页面\n- 实现头像上传\n\n## 测试计划\n- [ ] 单元测试\n- [ ] 手动测试" \
  --base main \
  --head feature/user-profile

PR 模板

创建 .github/pull_request_template.md:

## 变更类型
- [ ] Bug 修复
- [ ] 新功能
- [ ] 重构
- [ ] 文档更新
- [ ] 其他

## 变更描述
清晰描述本次 PR 的变更内容

## 相关 Issue
Closes #

## 测试计划
- [ ] 单元测试已添加/更新
- [ ] 所有测试通过
- [ ] 手动测试完成

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

## 检查清单
- [ ] 代码遵循项目规范
- [ ] 已添加必要的注释
- [ ] 文档已更新
- [ ] 无新的警告

代码审查

# 查看待审查的 PR
gh pr list --state open --reviewer @me

# 审查 PR
gh pr review <pr-number> \
  --approve \
  --body "代码看起来不错!"

# 或请求修改
gh pr review <pr-number> \
  --request-changes \
  --body "请修复以下问题:\n- 变量命名不规范\n- 缺少单元测试"

# 添加评论
gh pr comment <pr-number> --body "建议使用更明确的变量名"

合并 PR

# 合并 PR
gh pr merge <pr-number> --squash

# 或使用其他合并方式
gh pr merge <pr-number> --merge      # 创建合并提交
gh pr merge <pr-number> --rebase     # Rebase 合并

# 删除分支
gh pr merge <pr-number> --delete-branch

CODEOWNERS

创建 .github/CODEOWNERS 文件:

# 默认所有者
* @team-lead

# 前端代码
/src/**/*.js @frontend-team
/src/**/*.css @frontend-team
/src/**/*.vue @frontend-team

# 后端代码
/api/**/*.go @backend-team
/api/**/*.py @backend-team

# 文档
/docs/ @documentation-team
README.md @documentation-team

# 配置文件
*.yml @devops-team
Dockerfile @devops-team
.github/ @devops-team

# 测试
/tests/ @qa-team

Actions 自动化

GitHub Actions 基础

工作流文件结构

# .github/workflows/ci.yml
name: CI                    # 工作流名称

on:                         # 触发条件
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:                       # 任务定义
  build:                    # 任务名称
    runs-on: ubuntu-latest  # 运行环境
    
    steps:                  # 步骤
      - name: Checkout      # 步骤名称
        uses: actions/checkout@v3
        
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Run tests
        run: npm test

常用工作流

CI/CD 流水线

# .github/workflows/ci-cd.yml
name: CI/CD Pipeline

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run linter
        run: npm run lint
      
      - name: Run tests
        run: npm test -- --coverage
      
      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          file: ./coverage/lcov.info

  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'
      
      - name: Build
        run: |
          npm ci
          npm run build
      
      - name: Upload artifact
        uses: actions/upload-artifact@v3
        with:
          name: build
          path: dist/

  deploy:
    needs: build
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - name: Download artifact
        uses: actions/download-artifact@v3
        with:
          name: build
          path: dist/
      
      - name: Deploy to production
        run: |
          # 部署脚本
          echo "Deploying to production..."

自动发布

# .github/workflows/release.yml
name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Build
        run: |
          npm ci
          npm run build
      
      - name: Create Release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref }}
          release_name: Release ${{ github.ref }}
          body: |
            ## 变更内容
            - 变更1
            - 变更2
          draft: false
          prerelease: false
      
      - name: Publish to npm
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

依赖更新

# .github/dependabot.yml
version: 2
updates:
  # npm 依赖
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 10
    reviewers:
      - "username"
    labels:
      - "dependencies"
  
  # GitHub Actions
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5

Secrets 管理

# 使用 GitHub CLI 设置 Secrets
gh secret set NPM_TOKEN
# 然后输入 token 值

# 从文件设置
gh secret set GCP_KEY < gcp-key.json

# 列出所有 Secrets
gh secret list

# 删除 Secret
gh secret delete NPM_TOKEN

# 在工作流中使用 Secrets
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        env:
          API_KEY: ${{ secrets.API_KEY }}
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
        run: |
          # 使用环境变量
          ./deploy.sh

自定义 Actions

# .github/actions/setup/action.yml
name: 'Setup Environment'
description: 'Setup development environment'
inputs:
  node-version:
    description: 'Node.js version'
    required: false
    default: '18'
outputs:
  cache-hit:
    description: 'Whether cache was hit'
    value: ${{ steps.cache.outputs.cache-hit }}

runs:
  using: 'composite'
  steps:
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: ${{ inputs.node-version }}
    
    - name: Cache dependencies
      id: cache
      uses: actions/cache@v3
      with:
        path: node_modules
        key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
    
    - name: Install dependencies
      if: steps.cache.outputs.cache-hit != 'true'
      run: npm ci
      shell: bash

# 使用自定义 Action
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup environment
        uses: ./.github/actions/setup
        with:
          node-version: '18'

最佳实践

仓库管理

## README 结构

# 项目名称

简短的项目描述

## 功能特性

- 功能1
- 功能2

## 快速开始

### 安装
\`\`\`bash
npm install my-project
\`\`\`

### 使用
\`\`\`javascript
import { myFunction } from 'my-project';
\`\`\`

## 文档

详细文档请访问 [文档站点](https://docs.example.com)

## 贡献指南

请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)

## 许可证

[MIT](LICENSE)

工作流优化

# 使用矩阵策略并行测试
jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node: [16, 18, 20]
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node }}
      - run: npm ci
      - run: npm test

# 使用缓存加速构建
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Cache dependencies
        uses: actions/cache@v3
        with:
          path: |
            node_modules
            ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-

总结

GitHub 提供了完整的开发协作平台:

核心优势:

• 丰富的功能: 代码托管、协作、自动化一站式解决
• 强大的社区: 开源项目聚集地
• 完善的工具: GitHub CLI、Actions、Packages
• 安全可靠: Dependabot、安全警报

最佳实践:

• 使用 Issue 模板规范问题报告
• 使用 PR 模板提高代码审查效率
• 配置分支保护规则保护主分支
• 使用 GitHub Actions 实现自动化
• 定期更新依赖保证安全性

通过合理使用 GitHub 的各项功能,可以显著提高开发效率和代码质量。