particle-os-tools/.forgejo/README.md

Forgejo Actions for apt-layer

This directory contains Forgejo Actions workflows for automated compilation and testing of the apt-layer tool.

Workflows

1. compile-apt-layer.yml - Main Compilation Workflow

Triggers:

• Push to main or master branch (when src/apt-layer/ files change)
• Pull requests to main or master branch
• Manual trigger via workflow_dispatch

What it does:

1. Sets up Ubuntu environment with required dependencies (jq, dos2unix, bash)
2. Compiles apt-layer using src/apt-layer/compile.sh
3. Compiles installer with latest paths.json using src/apt-layer/compile-installer.sh
4. Validates both compiled scripts (syntax, functionality)
5. Creates a detailed compilation report
6. Uploads artifacts (compiled scripts and report)
7. Automatically commits both compiled scripts to the repository (only on main/master)

Output:

• Compiled apt-layer.sh in the repository root
• Compiled install-apt-layer.sh with embedded paths.json in the repository root
• Compilation report as an artifact
• Both compiled scripts as artifacts

2. test-compile.yml - Test Compilation Workflow

Triggers:

• Manual trigger only (workflow_dispatch)

What it does:

1. Tests compilation without affecting the main repository
2. Creates apt-layer-test.sh for testing purposes
3. Validates the test compilation
4. Uploads test script as an artifact

Use case: Testing compilation changes before pushing to main branch

How to Use

Automatic Compilation

1. Make changes to files in src/apt-layer/
2. Commit and push to main/master branch
3. Forgejo will automatically:
   • Detect the changes
   • Run the compilation workflow
   • Compile apt-layer
   • Commit the compiled script back to the repository
   • Provide artifacts for download

Manual Testing

1. Go to your Forgejo repository
2. Navigate to Actions tab
3. Select "Test apt-layer Compilation"
4. Click "Run workflow"
5. Download the test script from the artifacts

Viewing Results

• Actions tab: See workflow runs and logs
• Artifacts: Download compiled scripts and reports
• Repository: The compiled apt-layer.sh will be in the root directory

Dependencies

The workflows automatically install:

• jq - JSON processing
• dos2unix - Line ending conversion
• bash - Script execution

Configuration

Path-based Triggers

The main workflow only triggers when these paths change:

• src/apt-layer/** - Any apt-layer source files (including config and templates)
• .forgejo/workflows/compile-apt-layer.yml - The workflow itself

Branch Protection

The auto-commit feature only works on:

• main branch
• master branch

Artifact Retention

• Compilation reports: 30 days
• Compiled scripts: 30 days
• Test scripts: 7 days

Troubleshooting

Common Issues

1. Compilation fails:

   • Check the workflow logs for specific errors
   • Verify all dependencies are available
   • Check JSON syntax in config files

2. Auto-commit doesn't work:

   • Ensure you're on main/master branch
   • Check repository permissions for Actions
   • Verify the workflow has write access

3. Test workflow fails:

   • Use the test workflow to debug compilation issues
   • Check artifact downloads for the test script

Manual Compilation

If you need to compile locally:

# Compile apt-layer
cd src/apt-layer
chmod +x compile.sh
./compile.sh -o ../../apt-layer.sh

# Compile installer with latest paths.json
chmod +x compile-installer.sh
./compile-installer.sh -o ../../install-apt-layer.sh

Benefits

1. Automated Quality Assurance: Every commit is automatically compiled and tested
2. Consistent Builds: Same environment and dependencies every time
3. Artifact Management: Easy access to compiled scripts and reports
4. Version Control: Compiled scripts are tracked in git
5. Testing: Separate test workflow for safe experimentation

Security

• Workflows run in isolated Ubuntu environments
• No sensitive data is exposed in logs
• Compiled scripts are validated before commit
• Artifacts have limited retention periods