Skip to content

Commit 263bd96

Browse files
huangyiirenehuangyiirene
authored
Merge pull request #105 from objectstack-ai/copilot/add-github-workflows
2 parents cf2e9d9 + ec48824 commit 263bd96

36 files changed

+880
-70
lines changed

‎.github/WORKFLOWS.md‎

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
# GitHub Workflows Documentation
2+
3+
This document describes all the GitHub Actions workflows configured for the ObjectQL repository.
4+
5+
## Core CI/CD Workflows
6+
7+
### 🔨 [ci.yml](workflows/ci.yml)
8+
**Purpose:** Main continuous integration pipeline
9+
**Triggers:** Push to `main`, Pull Requests
10+
**What it does:**
11+
- Runs on Node.js 18.x and 20.x
12+
- Installs dependencies with pnpm
13+
- Builds all packages
14+
- Runs test suite across all packages
15+
- Sets up Redis and MongoDB for driver tests
16+
17+
### 📊 [coverage.yml](workflows/coverage.yml) ✨ NEW
18+
**Purpose:** Test coverage tracking and reporting
19+
**Triggers:** Push to `main`, Pull Requests
20+
**What it does:**
21+
- Runs tests with coverage collection
22+
- Uploads coverage reports to Codecov
23+
- Provides coverage insights on PRs
24+
- Tracks coverage trends over time
25+
26+
### ✅ [typecheck.yml](workflows/typecheck.yml)
27+
**Purpose:** TypeScript type checking
28+
**Triggers:** Push to `main`, Pull Requests
29+
**What it does:**
30+
- Runs TypeScript compiler in build mode
31+
- Ensures no type errors across the monorepo
32+
- Fast feedback on type safety
33+
34+
## Release & Publishing
35+
36+
### 🚀 [release.yml](workflows/release.yml)
37+
**Purpose:** Automated package publishing
38+
**Triggers:** Push to `main`
39+
**What it does:**
40+
- Uses Changesets for version management
41+
- Creates release PRs automatically
42+
- Publishes packages to npm when merged
43+
- Requires NPM_TOKEN secret
44+
45+
### 📝 [changelog-preview.yml](workflows/changelog-preview.yml) ✨ NEW
46+
**Purpose:** Preview changelog before release
47+
**Triggers:** Pull Requests
48+
**What it does:**
49+
- Shows what changes will be included in next release
50+
- Reminds contributors to add changesets
51+
- Comments on PRs with changelog preview
52+
53+
## Code Quality & Security
54+
55+
### 🔒 [codeql.yml](workflows/codeql.yml)
56+
**Purpose:** Security scanning with CodeQL
57+
**Triggers:** Push to `main`, Pull Requests, Weekly schedule
58+
**What it does:**
59+
- Scans JavaScript/TypeScript code for vulnerabilities
60+
- Runs security analysis
61+
- Creates security alerts for issues found
62+
63+
### 🔍 [dependency-review.yml](workflows/dependency-review.yml)
64+
**Purpose:** Dependency security review
65+
**Triggers:** Pull Requests
66+
**What it does:**
67+
- Reviews new/updated dependencies
68+
- Checks for known vulnerabilities
69+
- Fails on moderate or higher severity issues
70+
- Comments on PRs with findings
71+
72+
### ✓ [validate-metadata.yml](workflows/validate-metadata.yml)
73+
**Purpose:** Validate ObjectQL metadata files
74+
**Triggers:** Changes to `*.object.yml`, `*.validation.yml`, etc.
75+
**What it does:**
76+
- Validates YAML syntax for metadata files
77+
- Ensures metadata follows ObjectQL schema
78+
- Prevents invalid metadata from being merged
79+
80+
## Documentation
81+
82+
### 📚 [deploy-docs.yml](workflows/deploy-docs.yml)
83+
**Purpose:** Deploy documentation to GitHub Pages
84+
**Triggers:** Push to `main` (docs changes), Manual dispatch
85+
**What it does:**
86+
- Builds VitePress documentation site
87+
- Deploys to GitHub Pages
88+
- Makes docs available at objectql.org
89+
90+
### 🔗 [link-checker.yml](workflows/link-checker.yml) ✨ NEW
91+
**Purpose:** Check for broken links in documentation
92+
**Triggers:** Push/PR with doc changes, Weekly schedule, Manual
93+
**What it does:**
94+
- Scans all Markdown files for links
95+
- Checks if links are accessible
96+
- Reports broken links
97+
- Prevents dead links in documentation
98+
99+
## Repository Automation
100+
101+
### 🏷️ [labeler.yml](workflows/labeler.yml)
102+
**Purpose:** Auto-label PRs based on files changed
103+
**Triggers:** Pull Requests (opened, synchronized, reopened)
104+
**What it does:**
105+
- Adds labels like `📦 dependencies`, `🏗️ foundation`, `🔌 drivers`
106+
- Based on file paths changed
107+
- Helps with PR organization and filtering
108+
109+
### 📏 [pr-size-labeler.yml](workflows/pr-size-labeler.yml) ✨ NEW
110+
**Purpose:** Label PRs by size
111+
**Triggers:** Pull Requests (opened, synchronized, reopened)
112+
**What it does:**
113+
- Adds size labels: `size/XS`, `size/S`, `size/M`, `size/L`, `size/XL`
114+
- XS: ≤10 lines, S: ≤50, M: ≤200, L: ≤500, XL: >500
115+
- Ignores lock files and markdown
116+
- Encourages smaller, reviewable PRs
117+
118+
### 👋 [welcome.yml](workflows/welcome.yml) ✨ NEW
119+
**Purpose:** Welcome first-time contributors
120+
**Triggers:** First issue or PR from a new contributor
121+
**What it does:**
122+
- Posts welcoming message on first issue
123+
- Provides PR checklist for first-time contributors
124+
- Links to documentation and guidelines
125+
126+
### 🗑️ [stale.yml](workflows/stale.yml)
127+
**Purpose:** Manage stale issues and PRs
128+
**Triggers:** Daily schedule, Manual dispatch
129+
**What it does:**
130+
- **Issues:** Mark stale after 60 days, close after 14 more days
131+
- **PRs:** Mark stale after 30 days, close after 7 more days
132+
- Exempts labeled issues: `pinned`, `security`, `roadmap`
133+
- Helps keep issue tracker organized
134+
135+
### 🧹 [cleanup-runs.yml](workflows/cleanup-runs.yml) ✨ NEW
136+
**Purpose:** Clean up old workflow runs
137+
**Triggers:** Weekly schedule (Sunday), Manual dispatch
138+
**What it does:**
139+
- Deletes workflow runs older than 30 days
140+
- Keeps minimum of 6 recent runs
141+
- Saves storage space
142+
- Reduces clutter
143+
144+
## Dependency Management
145+
146+
### 🤖 [auto-approve-dependabot.yml](workflows/auto-approve-dependabot.yml) ✨ NEW
147+
**Purpose:** Streamline Dependabot PR approvals
148+
**Triggers:** Dependabot Pull Requests
149+
**What it does:**
150+
- Auto-approves patch and minor version updates
151+
- Comments on major version updates for review
152+
- Speeds up dependency update process
153+
- Still requires CI to pass before merge
154+
155+
## Performance Testing
156+
157+
### ⚡ [benchmark.yml](workflows/benchmark.yml) ✨ NEW
158+
**Purpose:** Track performance benchmarks
159+
**Triggers:** Push to `main`, Pull Requests, Manual
160+
**What it does:**
161+
- Runs benchmark scripts (if configured)
162+
- Tracks performance over time
163+
- Alerts on significant regressions
164+
- Ready for when benchmarks are implemented
165+
166+
---
167+
168+
## Configuration Files
169+
170+
### [labeler.yml](labeler.yml)
171+
Configuration for the PR auto-labeler, mapping file paths to labels.
172+
173+
### [markdown-link-check-config.json](markdown-link-check-config.json) ✨ NEW
174+
Configuration for the link checker, including patterns to ignore (localhost, example.com).
175+
176+
---
177+
178+
## Required Secrets
179+
180+
The following secrets need to be configured in repository settings:
181+
182+
- `NPM_TOKEN` - For publishing packages to npm (required by release.yml)
183+
- `CODECOV_TOKEN` - For uploading coverage reports (optional for coverage.yml)
184+
185+
---
186+
187+
## Workflow Status Badges
188+
189+
Add these badges to your README to show workflow status:
190+
191+
```markdown
192+
[![CI](https://github.com/objectstack-ai/objectql/actions/workflows/ci.yml/badge.svg)](https://github.com/objectstack-ai/objectql/actions/workflows/ci.yml)
193+
[![Coverage](https://codecov.io/gh/objectstack-ai/objectql/branch/main/graph/badge.svg)](https://codecov.io/gh/objectstack-ai/objectql)
194+
[![Type Check](https://github.com/objectstack-ai/objectql/actions/workflows/typecheck.yml/badge.svg)](https://github.com/objectstack-ai/objectql/actions/workflows/typecheck.yml)
195+
[![CodeQL](https://github.com/objectstack-ai/objectql/actions/workflows/codeql.yml/badge.svg)](https://github.com/objectstack-ai/objectql/actions/workflows/codeql.yml)
196+
```
197+
198+
---
199+
200+
## Contributing
201+
202+
When contributing to ObjectQL:
203+
204+
1. **Write tests** - The CI workflow will run them
205+
2. **Add a changeset** - Use `pnpm changeset` for user-facing changes
206+
3. **Check types** - Run `pnpm tsc -b` locally
207+
4. **Update docs** - If you change APIs or add features
208+
209+
The workflows will automatically:
210+
- Run tests and type checks
211+
- Label your PR by size and files changed
212+
- Welcome you if it's your first contribution
213+
- Preview the changelog
214+
- Check for broken links in docs
215+
216+
---
217+
218+
**Legend:**
219+
- ✨ NEW = Recently added workflows
220+
- All workflows include proper timeouts and error handling
221+
- All workflows are optimized for fast feedback

‎.github/WORKFLOW_ENHANCEMENTS.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Workflow Enhancement Opportunities
2+
3+
This document tracks potential future improvements for GitHub workflows.
4+
5+
## Low Priority Enhancements
6+
7+
### 1. Replace Third-Party Actions with GitHub Script
8+
9+
Some workflows currently use third-party actions that could be replaced with `actions/github-script@v7` for improved security and reduced external dependencies:
10+
11+
#### pr-size-labeler.yml
12+
- **Current:** Uses `codelytv/pr-size-labeler@v1`
13+
- **Status:** CodelyTV is a reputable organization, action works well
14+
- **Future:** Could implement with github-script (~50 lines)
15+
- **Benefit:** One less external dependency
16+
- **Priority:** Low (current solution is secure and well-maintained)
17+
18+
#### changelog-preview.yml
19+
- **Current:** Uses `thollander/actions-comment-pull-request@v2`
20+
- **Status:** Popular action, widely used in ecosystem
21+
- **Future:** Could use github-script for commenting
22+
- **Benefit:** One less external dependency
23+
- **Priority:** Low (current solution is simple and reliable)
24+
25+
#### benchmark.yml
26+
- **Current:** Uses `benchmark-action/github-action-benchmark@v1`
27+
- **Status:** Specialized benchmark tool with historical tracking
28+
- **Future:** Custom implementation would be complex (100+ lines)
29+
- **Benefit:** Full control over benchmark storage/comparison
30+
- **Priority:** Very Low (current solution provides features that would be hard to replicate)
31+
32+
### 2. Coverage Integration Enhancements
33+
34+
- **Current:** Basic Codecov integration
35+
- **Future Options:**
36+
- Add coverage badges to README
37+
- Set minimum coverage thresholds
38+
- Block PRs that decrease coverage
39+
- Generate coverage reports as PR comments
40+
41+
### 3. Benchmark Integration
42+
43+
- **Current:** Infrastructure ready but no benchmarks implemented
44+
- **Future:**
45+
- Add benchmark scripts to key packages
46+
- Define performance budgets
47+
- Alert on regressions
48+
49+
### 4. Advanced PR Automation
50+
51+
- **Future Ideas:**
52+
- Auto-assign reviewers based on files changed
53+
- Auto-label based on commit message keywords
54+
- Integration with project boards
55+
- Automatic milestone assignment
56+
57+
## Security Considerations
58+
59+
All current third-party actions:
60+
- ✅ Are from reputable sources
61+
- ✅ Have limited permissions
62+
- ✅ Handle non-sensitive operations
63+
- ✅ Don't have write access to code
64+
- ✅ Are properly scoped with explicit permissions
65+
66+
## Maintenance Notes
67+
68+
- Review third-party action versions quarterly
69+
- Monitor for security advisories
70+
- Consider migration to github-script if:
71+
- Action becomes unmaintained
72+
- Security vulnerability is discovered
73+
- Significant breaking changes occur
74+
75+
## Implementation Priority
76+
77+
1. **High:** None currently
78+
2. **Medium:** Coverage enhancements, Benchmark implementation
79+
3. **Low:** Replace third-party actions with github-script
80+
81+
---
82+
83+
*Last Updated: 2026-01-15*
84+
*Next Review: 2026-04-15*

‎.github/markdown-link-check-config.json‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
{
2+
"ignorePatterns": [
3+
{
4+
"pattern": "^http://localhost"
5+
},
6+
{
7+
"pattern": "^https://localhost"
8+
},
9+
{
10+
"pattern": "^http://127.0.0.1"
11+
},
12+
{
13+
"pattern": "^https://example.com"
14+
},
15+
{
16+
"pattern": "^https://www.google.com/search"
17+
},
18+
{
19+
"pattern": "^https://objectql.org"
20+
},
21+
{
22+
"pattern": "^https://www.objectql.org"
23+
},
24+
{
25+
"pattern": "^https://www.npmjs.com/package/@objectql/"
26+
},
27+
{
28+
"pattern": "^https://github.com/.*/releases/tag/.*%40"
29+
},
30+
{
31+
"pattern": "^mailto:"
32+
},
33+
{
34+
"pattern": "^https://img.shields.io/"
35+
},
36+
{
37+
"pattern": "^https://www.typescriptlang.org"
38+
},
39+
{
40+
"pattern": "^https://badge.fury.io/"
41+
},
42+
{
43+
"pattern": "^https://unpkg.com/"
44+
},
45+
{
46+
"pattern": "^https://cdn.jsdelivr.net/"
47+
},
48+
{
49+
"pattern": "^https://discord.gg/"
50+
}
51+
],
52+
"replacementPatterns": [],
53+
"httpHeaders": [
54+
{
55+
"urls": ["https://github.com"],
56+
"headers": {
57+
"Accept-Encoding": "zstd, br, gzip, deflate"
58+
}
59+
}
60+
],
61+
"timeout": "20s",
62+
"retryOn429": true,
63+
"retryCount": 3,
64+
"fallbackRetryDelay": "30s",
65+
"aliveStatusCodes": [200, 206]
66+
}

0 commit comments

Comments
 (0)