173 lines
4.7 KiB
Markdown
173 lines
4.7 KiB
Markdown
# Quick Start: License Sync Workflow
|
|
|
|
This guide helps you get started with the manual GPL license sync workflow that downloads and maintains multiple GPL licenses.
|
|
|
|
## For Template Users
|
|
|
|
If you're using this template repository, the license sync workflow is available for manual use:
|
|
|
|
1. **Create your repository from this template**
|
|
2. **Trigger the workflow manually when needed:**
|
|
- Go to Actions tab → Sync Licenses → Run workflow
|
|
- Automatic scheduling is disabled - you control when licenses are updated
|
|
|
|
The workflow downloads and syncs:
|
|
- GPL-3.0 (primary license in LICENSE file)
|
|
- GPL-2.0
|
|
- LGPL-3.0
|
|
- LGPL-2.1
|
|
|
|
All licenses are stored in the `licenses/` directory with the primary GPL-3.0 in the root LICENSE file.
|
|
|
|
**Note:** Automatic monthly updates are disabled. Licenses must be updated manually by triggering the workflow.
|
|
|
|
## For Enterprise Environments
|
|
|
|
If your organization has strict firewall rules, follow these steps:
|
|
|
|
### Step 1: Test Connectivity
|
|
|
|
Run the test script to check if your environment can access www.gnu.org:
|
|
|
|
```bash
|
|
./scripts/test-firewall.sh
|
|
```
|
|
|
|
### Step 2: Configure Firewall (if needed)
|
|
|
|
If the test fails, configure your firewall to allow:
|
|
|
|
- **Domain:** `www.gnu.org`
|
|
- **Protocol:** HTTPS
|
|
- **Port:** 443
|
|
|
|
See [docs/FIREWALL_CONFIGURATION.md](FIREWALL_CONFIGURATION.md) for detailed firewall configuration examples.
|
|
|
|
### Step 3: Retest
|
|
|
|
After configuring the firewall, run the test again:
|
|
|
|
```bash
|
|
./scripts/test-firewall.sh
|
|
```
|
|
|
|
All tests should pass before enabling the workflow.
|
|
|
|
## Manual Trigger
|
|
|
|
To manually run the workflow:
|
|
|
|
1. Go to your repository on GitHub
|
|
2. Click the **Actions** tab
|
|
3. Select **Sync Licenses** workflow
|
|
4. Click **Run workflow** button
|
|
5. Click **Run workflow** to confirm
|
|
|
|
## What Happens
|
|
|
|
When the workflow runs:
|
|
|
|
1. ✅ Tests connectivity to all license sources (www.gnu.org and ftp.gnu.org)
|
|
2. ✅ Downloads multiple GPL licenses (GPL-2.0, GPL-3.0, LGPL-2.1, LGPL-3.0)
|
|
3. ✅ Validates all downloaded licenses
|
|
4. ✅ Copies GPL-3.0 to root LICENSE file with copyright header
|
|
5. ✅ Stores additional licenses in `licenses/` directory
|
|
6. ✅ Commits and pushes if any licenses changed
|
|
|
|
## Viewing Results
|
|
|
|
After the workflow runs:
|
|
|
|
- Check the **Actions** tab for workflow status
|
|
- View detailed logs by clicking on the workflow run
|
|
- The LICENSE file will be created/updated in your repository
|
|
- See the workflow summary for detailed information
|
|
|
|
## Troubleshooting
|
|
|
|
### Workflow Fails with "Cannot resolve www.gnu.org"
|
|
|
|
**Cause:** DNS resolution is blocked or failing
|
|
|
|
**Solution:** Ensure DNS queries are allowed in your firewall
|
|
|
|
### Workflow Fails with "Cannot connect to www.gnu.org"
|
|
|
|
**Cause:** HTTPS connections to www.gnu.org are blocked
|
|
|
|
**Solution:** Configure firewall to allow HTTPS (port 443) to www.gnu.org
|
|
|
|
### Workflow Succeeds but LICENSE Not Committed
|
|
|
|
**Cause:** License content hasn't changed since last run
|
|
|
|
**Solution:** This is normal. The workflow only commits when changes are detected.
|
|
|
|
## Need Help?
|
|
|
|
- 📖 [Full Firewall Configuration Guide](FIREWALL_CONFIGURATION.md)
|
|
- 📖 [Implementation Summary](IMPLEMENTATION_SUMMARY.md)
|
|
- 📖 [Workflow Documentation](../.github/workflows/README.md)
|
|
- 📧 Contact: hello@mokoconsulting.tech
|
|
|
|
## Advanced Configuration
|
|
|
|
### Enable Automatic Updates
|
|
|
|
Automatic updates are currently disabled. To enable automatic monthly updates:
|
|
|
|
1. Edit `.github/workflows/download-license.yml`
|
|
2. Uncomment the `schedule` trigger:
|
|
```yaml
|
|
on:
|
|
workflow_dispatch: # Keep manual trigger
|
|
schedule: # Uncomment to enable automatic updates
|
|
- cron: '0 0 1 * *' # Run monthly
|
|
```
|
|
|
|
### Change Schedule
|
|
|
|
If you enable automatic updates, you can customize the schedule:
|
|
|
|
```yaml
|
|
schedule:
|
|
# Run weekly (every Monday at midnight)
|
|
- cron: '0 0 * * 1'
|
|
|
|
# Run daily at midnight
|
|
- cron: '0 0 * * *'
|
|
|
|
# Run quarterly (1st day of Jan, Apr, Jul, Oct)
|
|
- cron: '0 0 1 1,4,7,10 *'
|
|
```
|
|
|
|
### Use with Self-Hosted Runners
|
|
|
|
For self-hosted GitHub Actions runners:
|
|
|
|
1. Ensure the runner has internet access
|
|
2. Configure firewall on the runner host
|
|
3. Test connectivity using `./scripts/test-firewall.sh`
|
|
4. If using a proxy, configure it in the workflow:
|
|
|
|
```yaml
|
|
env:
|
|
HTTP_PROXY: http://proxy.example.com:8080
|
|
HTTPS_PROXY: http://proxy.example.com:8080
|
|
```
|
|
|
|
## Security Notes
|
|
|
|
- Workflow uses minimal permissions (`contents: write` only)
|
|
- Downloads only from trusted gnu.org domains
|
|
- Validates downloaded content before committing
|
|
- All steps are logged for audit purposes
|
|
|
|
## Best Practices
|
|
|
|
1. ✅ Test connectivity before deploying to production
|
|
2. ✅ Review firewall logs if workflow fails
|
|
3. ✅ Keep workflow file in version control
|
|
4. ✅ Monitor workflow runs in the Actions tab
|
|
5. ✅ Update firewall rules if gnu.org IPs change
|