b4l-project-template/GITEA-ACTIONS-SETUP.md

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. Add Repository Variables

1. Go to Repository Settings:
   • Navigate to your repository → Settings → Variables
2. Add Worker Email Variable:
   • Name: WORKER_EMAIL
   • Value: Email for git commits (e.g., ci-bot@your-domain.com)
   • Click "Add Variable"
3. Add Worker Username Variable:
   • Name: WORKER_USERNAME
   • Value: Username for git commits (e.g., CI Auto-Sort Bot)
   • Click "Add Variable"

5. 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:

name: Auto-Sort Files
on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

Infinite Loop Prevention

The workflow uses the [skip actions] flag in commit messages to prevent infinite loops:

• When files are moved, the commit message includes [skip actions]
• This prevents the workflow from triggering again on its own commits
• Standard Gitea Actions approach for preventing recursive execution

Authentication Method

The workflow uses token-based authentication and dynamically detects the repository URL:

- name: Checkout repository
  uses: actions/checkout@v4
  with:
    token: ${{ secrets.CI_BOT_TOKEN }}

The push operation automatically detects the repository URL:

# Get the repository URL dynamically
REPO_URL=$(git config --get remote.origin.url)
# Supports both HTTPS and SSH repository URLs

🧪 Testing the Setup

1. Create Test Files

Create test files with the correct prefixes:

# 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

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:

# 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:

# 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:

- 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
• WORKER_EMAIL variable added to repository
• WORKER_USERNAME variable 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! 🎉