filetree-pro
Version:
A powerful file tree generator for VS Code and Cursor. Generate beautiful file trees in multiple formats with smart exclusions and custom configurations.
385 lines (264 loc) • 8.82 kB
Markdown
# 🔄 CI/CD Pipeline Explained
## 📋 Overview
Your CI/CD pipeline has **4 stages** that run in different scenarios:
| Stage | Runs On | Purpose |
| -------------------- | ----------------------------- | ------------------------ |
| 🧪 **Test** | PRs, Pushes to main, Releases | Validate code quality |
| 📦 **Package** | PRs, Pushes to main, Releases | Build VSIX extension |
| 🚀 **Publish** | Releases only | Publish to marketplaces |
| 📎 **Release Asset** | Releases only | Upload to GitHub release |
## 🎯 Workflow Triggers
### 1. **Pull Requests to `main`**
```yaml
on:
pull_request:
branches: [main]
```
**What Runs:**
- ✅ Build & Test (validate code)
- ✅ Package Extension (test packaging works)
- ❌ Publish (skip - not ready for production)
- ❌ Release Asset (skip - no release yet)
**Use Case:** Pre-merge validation
### 2. **Push to `main` Branch**
```yaml
on:
push:
branches: [main]
```
**What Runs:**
- ✅ Build & Test
- ✅ Package Extension (creates VSIX)
- ❌ Publish (skip - no release event)
- ❌ Release Asset (skip - no release event)
**Use Case:** Post-merge validation and artifact creation
### 3. **GitHub Release Created**
```yaml
on:
release:
types: [published]
```
**What Runs:**
- ✅ Build & Test
- ✅ Package Extension
- ✅ Publish to VS Code Marketplace
- ✅ Publish to Open VSX Registry
- ✅ Upload VSIX to GitHub Release
**Use Case:** Production deployment
## 🔍 Job Conditions Explained
### **Test Job** - No Conditions ✅
```yaml
test:
runs-on: ubuntu-latest
# No if condition - ALWAYS RUNS
```
- Runs on: PRs, pushes, releases
- Purpose: Validate code before anything else
### **Package Job** - Conditional ⚙️
```yaml
package:
needs: test
if: |
github.event_name == 'pull_request' ||
(github.ref == 'refs/heads/main' && github.event_name == 'push') ||
github.event_name == 'release'
```
**Runs When:**
- ✅ Pull request (to test packaging)
- ✅ Push to main (to create artifact)
- ✅ Release event (for publishing)
**Skips When:**
- ❌ Push to other branches (dev, feature branches)
### **Publish Job** - Releases Only 🚀
```yaml
publish:
needs: [test, package]
if: github.event_name == 'release' && github.event.action == 'published'
environment: production
```
**Runs When:**
- ✅ **ONLY** on GitHub release creation
**Skips When:**
- ❌ Pull requests
- ❌ Branch pushes (including main)
**Why:** Publishing to marketplaces should only happen on intentional releases, not automatic merges.
### **Release Asset Job** - Releases Only 📎
```yaml
release-asset:
needs: [test, package]
if: github.event_name == 'release' && github.event.action == 'published'
```
**Runs When:**
- ✅ **ONLY** on GitHub release creation
**Skips When:**
- ❌ Pull requests
- ❌ Branch pushes
**Why:** Only upload VSIX to release page when creating a release.
## 🎬 Example Scenarios
### Scenario 1: Developer Creates PR
```
dev/feature-branch → PR to main
```
**Pipeline:**
1. ✅ Build & Test (27s) - Validates code
2. ✅ Package Extension (15s) - Tests packaging
3. ⏭️ Publish - Skipped (not a release)
4. ⏭️ Release Asset - Skipped (not a release)
**Result:** Developer knows code works and extension packages correctly
### Scenario 2: PR Merged to Main
```
git push origin main
```
**Pipeline:**
1. ✅ Build & Test (27s)
2. ✅ Package Extension (15s) - Creates VSIX artifact
3. ⏭️ Publish - Skipped (not a release)
4. ⏭️ Release Asset - Skipped (not a release)
**Result:** VSIX artifact available for 10 days (testing purposes)
### Scenario 3: Create GitHub Release
```
GitHub UI: Create new release v0.2.0
```
**Pipeline:**
1. ✅ Build & Test (27s)
2. ✅ Package Extension (15s)
3. ✅ Publish to VS Code Marketplace (30s)
4. ✅ Publish to Open VSX (20s)
5. ✅ Upload VSIX to Release (5s)
**Result:** Extension live in both marketplaces + VSIX downloadable from GitHub
## 🚨 Troubleshooting
### Issue: "Jobs are skipped on PR"
**Old Behavior (Before Fix):**
```yaml
if: (github.ref == 'refs/heads/main' && github.event_name == 'push') || github.event_name == 'release'
```
- ❌ Skipped all PRs
- ❌ No packaging validation before merge
**New Behavior (After Fix):**
```yaml
if: |
github.event_name == 'pull_request' ||
(github.ref == 'refs/heads/main' && github.event_name == 'push') ||
github.event_name == 'release'
```
- ✅ Runs on PRs for validation
- ✅ Catches packaging issues early
### Issue: "Package job runs but Publish is skipped"
**This is CORRECT behavior!**
Publishing should **only** happen on releases:
```yaml
if: github.event_name == 'release' && github.event.action == 'published'
```
**To publish:**
1. Go to GitHub → Releases
2. Click "Create a new release"
3. Choose tag version (e.g., `v0.2.0`)
4. Click "Publish release"
5. Pipeline automatically publishes to marketplaces
### Issue: "How do I test the full pipeline?"
**Create a test release:**
```bash
# 1. Create and push a tag
git tag v0.2.0-beta
git push origin v0.2.0-beta
# 2. Create release on GitHub using this tag
# 3. Mark as "pre-release" for testing
```
**Or use `workflow_dispatch` for manual runs:**
```yaml
on:
workflow_dispatch:
inputs:
environment:
description: 'Environment to deploy'
required: true
default: 'staging'
```
## 📊 Workflow Diagram
```
┌─────────────────┐
│ Trigger Event │
└────────┬────────┘
│
┌────┴────┐
│ Test │ ← Always runs
└────┬────┘
│
┌────┴────┐
│ Package │ ← Runs on PRs, main, releases
└────┬────┘
│
├─────────────────────┬─────────────────────┐
│ │ │
┌────┴────┐ ┌─────┴──────┐ ┌──────┴───────┐
│ Publish │ │ Publish │ │Upload Release│
│ VSCE │ │ Open VSX │ │ Asset │
└─────────┘ └────────────┘ └──────────────┘
│ │ │
└─────────────────────┴─────────────────────┘
Only on releases
```
## 🎯 Best Practices
### 1. **Branch Strategy**
```
feature/* → dev → main → release
```
- Feature branches: Local development
- `dev` branch: Integration testing
- `main` branch: Stable, tested code
- Releases: Production deployments
### 2. **Release Workflow**
```bash
# 1. Merge to main
git checkout main
git merge dev
# 2. Update version in package.json
npm version patch # or minor, major
# 3. Push changes
git push origin main
git push origin --tags
# 4. Create GitHub release
# Go to GitHub UI and create release from tag
```
### 3. **Testing Before Release**
- ✅ Create PR → Test and Package run
- ✅ Merge to main → Package creates artifact
- ✅ Download artifact from GitHub Actions
- ✅ Test VSIX locally: `code --install-extension filetree-pro-x.x.x.vsix`
- ✅ If good, create release
## 🔒 Required Secrets
For publishing to work, set these in GitHub:
- **Settings → Secrets → Actions**
| Secret | Purpose | Get From |
| ---------- | ------------------- | ------------------------------------- |
| `VSCE_PAT` | VS Code Marketplace | https://marketplace.visualstudio.com/ |
| `OVSX_PAT` | Open VSX Registry | https://open-vsx.org/ |
## 📚 Additional Resources
- [GitHub Actions Contexts](https://docs.github.com/en/actions/learn-github-actions/contexts)
- [VS Code Publishing](https://code.visualstudio.com/api/working-with-extensions/publishing-extension)
- [Open VSX Publishing](https://github.com/eclipse/openvsx/wiki/Publishing-Extensions)
## 🎉 Summary
**Your pipeline is designed to:**
1. ✅ Test everything (PRs, pushes, releases)
2. ✅ Package on PRs (catch issues early)
3. ✅ Create artifacts on main (for testing)
4. ✅ Publish only on releases (intentional deployments)
**The "skipped jobs" are by design** - they only run when needed! 🚀