b4l-project-template/ci

/ci

Continuous Integration configuration and automation scripts.

Purpose

This directory contains CI/CD configuration files and automation scripts for the project, including automated file organization, testing, and deployment workflows.

CI Workflows

Auto-Sort Files (auto-sort-files.yml)

Automatically organizes datasheets and images based on filename prefixes.

How It Works

1. Triggers: Runs on push to main/develop branches and pull requests
2. Detection: Scans the entire repository for files with specific prefixes
3. Organization: Moves files to their correct directories
4. Commit: Automatically commits the reorganized files

Supported Prefixes

• DS_: Datasheets → moved to docs/datasheets/
• IMG_: Images → moved to docs/images/

Example Usage

# User uploads files anywhere in the project:
/some-folder/DS_STM32F401_datasheet_2024-08-11.pdf
/random-location/IMG_pcb-layout_top-view_v1.0.0_2024-08-11.png

# CI automatically moves them to:
docs/datasheets/DS_STM32F401_datasheet_2024-08-11.pdf
docs/images/IMG_pcb-layout_top-view_v1.0.0_2024-08-11.png

Supported File Types

Datasheets (DS_):

• PDF, DOC, DOCX, TXT

Images (IMG_):

• PNG, JPG, JPEG, SVG, GIF, PDF, WEBP

Configuration

The workflow can be customized by editing auto-sort-files.yml:

• Add new file extensions
• Modify destination directories
• Add new prefix categories
• Adjust trigger conditions

Benefits of Auto-Sort System

For Users

• No manual organization: Upload files anywhere with correct prefix
• Consistent structure: Files automatically end up in the right place
• Reduced errors: No need to remember directory structures
• Time saving: Focus on content, not file management

For Teams

• Enforced standards: Automatic compliance with naming conventions
• Reduced conflicts: Files always in predictable locations
• Better collaboration: Team members can find files easily
• Documentation quality: Consistent organization improves documentation

For Maintenance

• Automated cleanup: Misplaced files are automatically corrected
• Audit trail: Git history shows when files were moved
• Scalability: Works regardless of project size
• Integration: Works with existing workflows and tools

Setup Instructions

Gitea Actions (Recommended)

This template is optimized for Gitea Actions. The workflow is already configured in .gitea/workflows/auto-sort-files.yml.

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:

auto-sort:
  stage: organize
  script:
    - # Copy the bash script from .gitea/workflows/auto-sort-files.yml
  only:
    - main
    - develop

Other CI Systems

The bash script in auto-sort-files.yml can be adapted for:

• Jenkins
• Azure DevOps
• CircleCI
• Travis CI
• Any system that can run bash scripts

Customization

Adding New Prefixes

To add new file type prefixes, modify the workflow:

# Example: Add CAD files with CAD_ prefix
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 Organization

For more sophisticated organization, add logic to sort into subdirectories:

# Example: 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/" ;;
  *) dest_dir="docs/datasheets/" ;;
esac

Best Practices

File Naming

• Always use the correct prefix (DS_, IMG_)
• Follow the established naming convention
• Include version numbers and dates
• Use descriptive filenames

Repository Management

• Review auto-sort commits regularly
• Manually organize files into subdirectories as needed
• Keep the CI workflow updated with project needs
• Monitor for any files that might be missed

Team Guidelines

• Train team members on prefix usage
• Document any custom prefixes or rules
• Include prefix requirements in contribution guidelines
• Set up notifications for auto-sort commits

Troubleshooting

Common Issues

1. Files not moving: Check filename prefix and extension
2. Permission errors: Ensure CI has write access to repository
3. Workflow not running: Check trigger conditions and branch names
4. Duplicate files: CI will not overwrite existing files

Debugging

• Check workflow logs in CI system
• Verify file extensions are supported
• Ensure files are not already in correct location
• Test bash script locally before deploying

Future Enhancements

• Add support for more file types
• Implement smart subdirectory sorting
• Add file validation and quality checks
• Integration with project management tools
• Automated file naming compliance checking