From e3b480ec33d9d7429fa789c51a44ea9e648d0892 Mon Sep 17 00:00:00 2001
From: grabowski <berwn@buildfor.life>
Date: Mon, 11 Aug 2025 10:47:39 +0700
Subject: [PATCH] Convert CI auto-sort system to Gitea Actions

- Move workflow from ci/auto-sort-files.yml to .gitea/workflows/auto-sort-files.yml
- Update workflow to use CI_BOT_TOKEN secret for Gitea authentication
- Configure proper git push URL for Gitea repository
- Update ci/README.md with comprehensive Gitea Actions setup instructions
- Add GITEA-ACTIONS-SETUP.md with detailed configuration guide
- Update README.md to reference Gitea Actions setup documentation
- Remove old GitHub Actions workflow file
- Provide step-by-step token creation and repository secret configuration
- Include troubleshooting guide and security considerations
---
 {ci => .gitea/workflows}/auto-sort-files.yml |  18 +-
 GITEA-ACTIONS-SETUP.md                       | 211 +++++++++++++++++++
 README.md                                    |   6 +
 ci/README.md                                 |  40 +++-
 4 files changed, 259 insertions(+), 16 deletions(-)
 rename {ci => .gitea/workflows}/auto-sort-files.yml (87%)
 create mode 100644 GITEA-ACTIONS-SETUP.md

diff --git a/ci/auto-sort-files.yml b/.gitea/workflows/auto-sort-files.yml
similarity index 87%
rename from ci/auto-sort-files.yml
rename to .gitea/workflows/auto-sort-files.yml
index 5b9487c..56d730a 100644
--- a/ci/auto-sort-files.yml
+++ b/.gitea/workflows/auto-sort-files.yml
@@ -1,5 +1,5 @@
-# CI Auto-Sort Configuration for Datasheets and Images
-# This GitHub Actions workflow automatically moves files with specific prefixes to their correct directories
+# Gitea Actions Auto-Sort Configuration for Datasheets and Images
+# This workflow automatically moves files with specific prefixes to their correct directories
 
 name: Auto-Sort Files
 
@@ -18,7 +18,7 @@ jobs:
       uses: actions/checkout@v4
       with:
         fetch-depth: 0
-        token: ${{ secrets.GITHUB_TOKEN }}
+        token: ${{ secrets.CI_BOT_TOKEN }}
 
     - name: Auto-sort datasheets and images
       run: |
@@ -78,21 +78,19 @@ jobs:
     - name: Commit moved files
       if: steps.sort_files.outputs.files_moved == 'true'
       run: |
-        git config --local user.email "action@github.com"
-        git config --local user.name "GitHub Action Auto-Sort"
+        git config --local user.email "ci-bot@b4l.co.th"
+        git config --local user.name "B4L CI Auto-Sort Bot"
         git add docs/datasheets/ docs/images/
         git commit -m "Auto-sort: Move DS_ and IMG_ prefixed files to correct directories
         
         - Moved datasheet files (DS_*) to docs/datasheets/
         - Moved image files (IMG_*) to docs/images/
-        - Automated by CI auto-sort workflow"
+        - Automated by Gitea Actions auto-sort workflow"
         
     - name: Push changes
       if: steps.sort_files.outputs.files_moved == 'true'
-      uses: ad-m/github-push-action@master
-      with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        branch: ${{ github.ref }}
+      run: |
+        git push https://ci-bot:${{ secrets.CI_BOT_TOKEN }}@git.b4l.co.th/B4L/b4l-project-template.git HEAD:${{ github.ref_name }}
 
     - name: Create summary
       run: |
diff --git a/GITEA-ACTIONS-SETUP.md b/GITEA-ACTIONS-SETUP.md
new file mode 100644
index 0000000..6496a11
--- /dev/null
+++ b/GITEA-ACTIONS-SETUP.md
@@ -0,0 +1,211 @@
+# Gitea Actions Setup Guide
+
+This guide explains how to set up the CI auto-sort system for Gitea Actions.
+
+## 🚀 Quick Setup
+
+### 1. Enable Gitea Actions
+Ensure your Gitea instance has Actions enabled:
+- **Admin Panel**: Go to Site Administration → Actions
+- **Enable Actions**: Check "Enable Actions for this repository"
+- **Runner**: Ensure at least one runner is available
+
+### 2. Create CI Bot Token
+1. **Navigate to User Settings**:
+   - Click your profile → Settings → Applications
+2. **Generate New Token**:
+   - Token Name: `CI Auto-Sort Bot`
+   - Scopes: Select `repo` (Repository access)
+   - Click "Generate Token"
+3. **Copy Token**: Save the generated token securely
+
+### 3. Add Repository Secret
+1. **Go to Repository Settings**:
+   - Navigate to your repository → Settings → Secrets
+2. **Add New Secret**:
+   - Name: `CI_BOT_TOKEN`
+   - Value: Paste the token from step 2
+   - Click "Add Secret"
+
+### 4. Enable Repository Actions
+1. **Repository Settings**: Go to Settings → Actions
+2. **Enable Actions**: Check "Enable Actions"
+3. **Allow all actions**: Select appropriate action permissions
+
+## 🔧 Detailed Configuration
+
+### Token Permissions
+The `CI_BOT_TOKEN` requires these permissions:
+- **Repository**: Full access to repository contents
+- **Contents**: Read and write access to files
+- **Metadata**: Read repository metadata
+- **Pull requests**: Read pull request information (for PR triggers)
+
+### Workflow Configuration
+The workflow file is located at `.gitea/workflows/auto-sort-files.yml` and includes:
+
+```yaml
+name: Auto-Sort Files
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main ]
+```
+
+### Authentication Method
+The workflow uses token-based authentication:
+```yaml
+- name: Checkout repository
+  uses: actions/checkout@v4
+  with:
+    token: ${{ secrets.CI_BOT_TOKEN }}
+```
+
+## 🧪 Testing the Setup
+
+### 1. Create Test Files
+Create test files with the correct prefixes:
+```bash
+# Create a test datasheet
+echo "Test datasheet content" > DS_test-component_datasheet_2024-08-11.pdf
+
+# Create a test image
+echo "Test image content" > IMG_test-diagram_v1.0.0_2024-08-11.png
+```
+
+### 2. Commit and Push
+```bash
+git add .
+git commit -m "Test CI auto-sort system"
+git push
+```
+
+### 3. Verify Workflow Execution
+1. **Actions Tab**: Go to your repository → Actions
+2. **Check Workflow**: Look for "Auto-Sort Files" workflow
+3. **View Logs**: Click on the workflow run to see detailed logs
+4. **Verify Results**: Check if files were moved to correct directories
+
+## 📋 Troubleshooting
+
+### Common Issues
+
+#### Workflow Not Running
+- **Check Actions Enabled**: Verify Actions are enabled in repository settings
+- **Check Runner**: Ensure Gitea has available runners
+- **Check Triggers**: Verify push was to main/develop branch
+
+#### Permission Denied
+- **Token Scope**: Ensure token has `repo` scope
+- **Token Validity**: Check if token hasn't expired
+- **Secret Name**: Verify secret is named exactly `CI_BOT_TOKEN`
+
+#### Files Not Moving
+- **File Prefix**: Ensure files start with `DS_` or `IMG_`
+- **File Extensions**: Check supported extensions (PDF, PNG, JPG, etc.)
+- **Already Sorted**: Files already in correct location won't be moved
+
+### Debug Steps
+1. **Check Workflow Logs**:
+   - Go to Actions tab → Select workflow run → View logs
+2. **Verify Token**:
+   - Test token permissions with a simple git operation
+3. **Manual Test**:
+   - Run the bash script locally to test file detection
+
+## 🔒 Security Considerations
+
+### Token Security
+- **Scope Limitation**: Use minimal required scopes
+- **Regular Rotation**: Rotate tokens periodically
+- **Access Control**: Limit who can access repository secrets
+
+### Workflow Security
+- **Branch Protection**: Protect main branch from direct pushes
+- **Review Process**: Require PR reviews for workflow changes
+- **Audit Logs**: Monitor Actions execution logs
+
+## 🎯 Advanced Configuration
+
+### Custom File Types
+Add support for additional file types by modifying the workflow:
+
+```bash
+# Add CAD files
+find . -name "CAD_*.step" -o -name "CAD_*.sldprt" | while read file; do
+  if [[ "$file" != ./mechanical/cad/* ]]; then
+    filename=$(basename "$file")
+    move_file "$file" "mechanical/cad/$filename"
+  fi
+done
+```
+
+### Subdirectory Sorting
+Implement intelligent subdirectory sorting:
+
+```bash
+# Sort datasheets by component type
+case "$filename" in
+  DS_STM32*|DS_ESP32*) dest_dir="docs/datasheets/microcontrollers/" ;;
+  DS_LM*|DS_AMS*) dest_dir="docs/datasheets/power-management/" ;;
+  DS_USB*|DS_JST*) dest_dir="docs/datasheets/connectors/" ;;
+  *) dest_dir="docs/datasheets/" ;;
+esac
+```
+
+### Notification Integration
+Add notifications for successful sorts:
+
+```yaml
+- name: Notify on Slack
+  if: steps.sort_files.outputs.files_moved == 'true'
+  uses: 8398a7/action-slack@v3
+  with:
+    status: success
+    text: "Files automatically sorted by CI"
+  env:
+    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}
+```
+
+## 📊 Monitoring and Maintenance
+
+### Regular Checks
+- **Weekly**: Review auto-sort commits
+- **Monthly**: Check workflow execution statistics
+- **Quarterly**: Rotate CI bot token
+
+### Performance Optimization
+- **File Size Limits**: Monitor for large files that slow down workflow
+- **Execution Time**: Optimize script for large repositories
+- **Runner Resources**: Ensure adequate runner capacity
+
+## 🆘 Support
+
+### Getting Help
+- **Gitea Documentation**: https://docs.gitea.io/en-us/usage/actions/
+- **Repository Issues**: Use the issue tracker for template-specific problems
+- **Community**: Gitea community forums and Discord
+
+### Reporting Issues
+When reporting issues, include:
+- Gitea version
+- Workflow logs
+- Repository structure
+- Error messages
+- Steps to reproduce
+
+---
+
+## ✅ Setup Checklist
+
+- [ ] Gitea Actions enabled on instance
+- [ ] CI bot token created with `repo` scope
+- [ ] `CI_BOT_TOKEN` secret added to repository
+- [ ] Repository Actions enabled
+- [ ] Test files created and pushed
+- [ ] Workflow executed successfully
+- [ ] Files moved to correct directories
+- [ ] Team members trained on prefix usage
+
+**Once all items are checked, your CI auto-sort system is ready!** 🎉
diff --git a/README.md b/README.md
index 5debd90..58787d4 100644
--- a/README.md
+++ b/README.md
@@ -163,6 +163,12 @@ This project follows **Semantic Versioning 2.0.0** and **Harvard Data Management
 - **CI Auto-Sort**: Use DS_ prefix for datasheets, IMG_ prefix for images
 - **Examples**: `my-project_bom_v1.2.0_2024-08-04.csv`, `DS_STM32F401_datasheet_2024-08-11.pdf`
 
+### CI Auto-Sort System
+This template includes an automated file organization system:
+- **DS_ prefix**: Datasheets automatically moved to `docs/datasheets/`
+- **IMG_ prefix**: Images automatically moved to `docs/images/`
+- **Setup required**: See [GITEA-ACTIONS-SETUP.md](GITEA-ACTIONS-SETUP.md) for configuration
+
 ### Initial Setup
 ```bash
 # After creating your KiCad project
diff --git a/ci/README.md b/ci/README.md
index f813e66..0c55e22 100644
--- a/ci/README.md
+++ b/ci/README.md
@@ -67,18 +67,46 @@ The workflow can be customized by editing `auto-sort-files.yml`:
 
 ## Setup Instructions
 
-### GitHub Actions
-1. The workflow file is already configured in `.github/workflows/` (copy from `ci/auto-sort-files.yml`)
-2. Ensure repository has appropriate permissions for the action to commit
-3. The workflow will run automatically on pushes and pull requests
+### Gitea Actions (Recommended)
+This template is optimized for Gitea Actions. The workflow is already configured in `.gitea/workflows/auto-sort-files.yml`.
 
-### GitLab CI
+#### Required Setup:
+1. **Enable Gitea Actions** on your Gitea instance
+2. **Create CI Bot Token**:
+   - Go to your Gitea user settings → Applications → Generate New Token
+   - Name: `CI Auto-Sort Bot`
+   - Scopes: `repo` (full repository access)
+   - Copy the generated token
+3. **Add Repository Secret**:
+   - Go to your repository → Settings → Secrets
+   - Add new secret: `CI_BOT_TOKEN`
+   - Value: Paste the token from step 2
+4. **Enable Actions**: Go to repository Settings → Actions → Enable Actions
+
+#### Token Configuration:
+The workflow uses `${{ secrets.CI_BOT_TOKEN }}` to authenticate git operations. This token must have:
+- **Repository access**: Read and write permissions
+- **Contents permission**: To commit and push changes
+- **Actions permission**: To run workflows
+
+#### Verification:
+- Push a test file with DS_ or IMG_ prefix to verify the workflow runs
+- Check the Actions tab in your repository for workflow execution logs
+- Verify that files are automatically moved to correct directories
+
+### GitHub Actions (Alternative)
+If using GitHub instead of Gitea:
+1. Copy `.gitea/workflows/auto-sort-files.yml` to `.github/workflows/`
+2. Replace `CI_BOT_TOKEN` with `GITHUB_TOKEN` in the workflow
+3. Update the push URL to use GitHub's format
+
+### GitLab CI (Alternative)
 To adapt for GitLab CI, create `.gitlab-ci.yml`:
 ```yaml
 auto-sort:
   stage: organize
   script:
-    - # Copy the bash script from auto-sort-files.yml
+    - # Copy the bash script from .gitea/workflows/auto-sort-files.yml
   only:
     - main
     - develop