GitHub 配置文件语法

dctc_青龙

## 引言

GitHub作为全球最大的代码托管平台，提供了丰富的配置文件系统来定义仓库行为、自动化工作流和开发规范。这些配置文件以YAML、JSON或纯文本格式存在，通过声明式配置实现仓库管理自动化、CI/CD流程定义、代码质量检查等功能。理解并正确使用这些配置文件，是高效使用GitHub的基础技能。

本文系统讲解GitHub核心配置文件的语法和使用方法，涵盖.gitignore、GitHub Actions、Dependabot、GitHub Pages等常用配置。这些配置文件的正确设置可以显著提升开发效率、保证代码质量和实现自动化运维。

## .gitignore文件配置

### 基础语法

.gitignore文件用于指定Git版本控制系统忽略的文件和目录。每个条目可以指向具体文件、通配符或目录：

```gitignore

secret.txt
passwords.json

node_modules/
build/
dist/

*.log
*.tmp
*.swp

!important.log

logs/*.log

**/temp/
```

### 模式匹配规则

| 模式 | 含义 | 示例 |
|------|------|------|
| 空行 | 忽略，用于分隔分组 | - |
| #开头 | 注释行 | # 忽略编译产物 |
| /结尾 | 目录 | build/ |
| /开头 | 相对于.gitignore所在目录 | /config.ini |
| **/ | 任意目录层级 | **/node_modules/ |
| * | 任意字符（不含/） | *.log |
| ? | 单个任意字符 | file?.txt |
| [] | 字符集 | [abc].txt |

### 全局.gitignore

用户可以配置全局忽略规则，作用于所有本地仓库：

```bash
touch ~/.gitignore_global

git config --global core.excludesFile ~/.gitignore_global
```

常用全局忽略配置：

```gitignore

.DS_Store
Thumbs.db
desktop.ini

.vscode/
.idea/
*.swp
*.swo

*.log
*.tmp
*.temp
```

## GitHub Actions工作流配置

### 工作流文件结构

GitHub Actions工作流使用YAML格式，存放在仓库的.github/workflows/目录下：

```yaml

name: CI Pipeline

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning'

env:
  NODE_VERSION: '18'

jobs:
  build:
    # 运行环境
    runs-on: ubuntu-latest
   
    # 环境变量（job级别）
    env:
      NODE_ENV: production
   
    # 步骤
    steps:
      # 检出代码
      - name: Checkout code
        uses: actions/checkout@v4
      
      # 设置Node.js环境
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
      
      # 安装依赖
      - name: Install dependencies
        run: npm ci
      
      # 运行测试
      - name: Run tests
        run: npm test
      
      # 构建
      - name: Build
        run: npm run build
```

### 常用触发器配置

```yaml
on:
  # push事件
  push:
    branches:
      - main          # 仅main分支
      - 'feature/*'   # feature开头的分支
      - 'releases/v*' # 版本分支
    tags:
      - 'v*'         # 所有标签
    paths:
      - 'src/**'     # src目录下的文件变化
      - '*.js'        # JavaScript文件变化
    paths-ignore:
      - 'docs/**'    # 忽略文档变化
  
  # pull_request事件
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]
  
  # 定时任务
  schedule:
    - cron: '0 0 * * *'  # 每天午夜
  
  # 仓库事件
  repository_dispatch:
    types: [custom_event]
  
  # 外部事件
  workflow_call:
```

### 条件执行与矩阵构建

```yaml
jobs:
  # 条件执行
  test:
    runs-on: ubuntu-latest
    if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
    steps:
      - run: echo "Running tests"
  
  # 矩阵构建
  matrix-test:
    strategy:
      matrix:
        node-version: [14, 16, 18, 20]
        operating-system: [ubuntu-latest, windows-latest]
      fail-fast: false  # 一个失败是否取消其他
      max-parallel: 2
    runs-on: ${{ matrix.operating-system }}
    steps:
      - name: Setup Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm test
```

### 环境变量与Secrets

```yaml
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://example.com
      # 环境保护规则
      deployment_branch: main
    env:
      # 环境变量（公开）
      APP_NAME: my-app
    steps:
      - name: Deploy
        run: |
          echo "Deploying to ${{ vars.ENVIRONMENT_URL }}"
          echo "Token: ${{ secrets.API_TOKEN }}"
```

Secrets和Variables在仓库设置的Secrets and variables中配置。

## Dependabot配置

### 基础配置

Dependabot自动检测依赖更新并创建PR：

```yaml
version: 2
updates:
  # npm依赖更新
  - package-ecosystem: npm
    directory: /
    schedule:
      interval: weekly
      day: monday
      time: '09:00'
      timezone: Asia/Shanghai
    open-pull-requests-limit: 10
    commit-message:
      prefix: fix
      prefix-development: chore
    labels:
      - dependencies
      - automated
    reviewers:
      - team/frontend
    groups:
      minor:
        patterns:
          - '*'
        update-types:
          - minor
          - patch
      major:
        patterns:
          - '*'
        update-types:
          - major
  
  # GitHub Actions更新
  - package-ecosystem: github-actions
    directory: /
    schedule:
      interval: weekly
```

### 群组配置

```yaml
updates:
  - package-ecosystem: pip
    directory: /
    groups:
      # 核心依赖
      core:
        patterns:
          - django
          - requests
        update-types:
          - minor
          - patch
      # 数据处理
      data:
        patterns:
          - pandas
          - numpy
        update-types:
          - patch
```

## GitHub Pages配置

### 基础配置

```yaml
name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      
      - name: Setup Pages
        uses: actions/configure-pages@v4
      
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './dist'
      
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
```

### Pages配置

在repository settings中配置：

- Source: Deploy from a branch 或 GitHub Actions
- Branch: main /docs 或 root
- Theme: 选择主题或上传自定义主题

## 其他重要配置

### GitHub配置文件

```yaml
contact_links:
  - name: 文档
    url: https://docs.example.com
    about: 访问项目文档
  - name: 问题反馈
    url: https://github.com/user/repo/issues
    about: 报告Bug或功能请求
```

### 模板文件

```yaml
name: Bug Report
description: 报告一个Bug帮助我们改进
labels: [bug]
body:
  - type: markdown
    attributes:
      value: |
        请描述你遇到的Bug
  - type: textarea
    id: description
    attributes:
      label: Bug描述
      placeholder: 详细描述Bug...
    validations:
      required: true
  - type: input
    id: version
    attributes:
      label: 版本号
      placeholder: v1.0.0
  - type: dropdown
    id: os
    attributes:
      label: 操作系统
      options:
        - Windows
        - macOS
        - Linux
    validations:
      required: true
```

### CODEOWNERS文件

```yaml

* @default-reviewer

/src @frontend-team
/api @backend-team
/docs @docs-team

*.js @js-expert
*.py @python-team
*.go @go-team

/terraform @infra-team
/.github @devops-team
```

### 安全策略

```yaml

## 报告漏洞

请发送邮件至 security@example.com

请包括：
- 问题描述
- 重现步骤
- 影响范围
- 建议修复方案

## 响应时间

我们将在48小时内确认收到报告，
在7天内提供初步修复计划。

## 公开披露

漏洞修复后公开披露
```

## 配置验证与调试

### 语法验证

```bash
yamllint .github/workflows/

actionlint

gh workflow run test.yml --dry-run
```

### 本地测试

```bash
brew install act

act -l  # 列出可用的工作流
act      # 运行工作流
```

## 总结

GitHub配置文件是现代软件开发的基础设施。.gitignore规范版本控制范围，GitHub Actions实现自动化CI/CD，Dependabot自动化依赖更新，CODEOWNERS定义代码审查责任，GitHub Pages托管文档和网站。

掌握这些配置文件的语法和最佳实践，可以显著提升开发效率、保证代码质量、实现自动化运维。建议在项目中建立统一的配置文件规范，促进团队协作和最佳实践落地。

---

**您在GitHub配置过程中遇到过哪些问题？对于特定配置文件的语法有哪些疑问？期待在评论区分享您的经验。**