{"id":13405925,"url":"https://github.com/andrius/asterisk","last_synced_at":"2026-04-20T22:13:26.920Z","repository":{"id":42382460,"uuid":"58462586","full_name":"andrius/asterisk","owner":"andrius","description":"✨📞 Asterisk PBX in 🐳 Docker — Smallest Asterisk ever! 🚀","archived":false,"fork":false,"pushed_at":"2026-04-08T18:33:10.000Z","size":376,"stargazers_count":355,"open_issues_count":16,"forks_count":118,"subscribers_count":17,"default_branch":"main","last_synced_at":"2026-04-08T20:12:18.482Z","etag":null,"topics":["asterisk-pbx","docker","docker-image","voip"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andrius.png","metadata":{"files":{"readme":"README-cicd.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["andrius"]}},"created_at":"2016-05-10T13:14:04.000Z","updated_at":"2026-04-08T18:33:20.000Z","dependencies_parsed_at":"2026-01-11T02:02:42.722Z","dependency_job_id":null,"html_url":"https://github.com/andrius/asterisk","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/andrius/asterisk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrius%2Fasterisk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrius%2Fasterisk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrius%2Fasterisk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrius%2Fasterisk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrius","download_url":"https://codeload.github.com/andrius/asterisk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrius%2Fasterisk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32067849,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T21:26:33.338Z","status":"ssl_error","status_checked_at":"2026-04-20T21:26:22.081Z","response_time":94,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asterisk-pbx","docker","docker-image","voip"],"created_at":"2024-07-30T19:02:16.095Z","updated_at":"2026-04-20T22:13:26.913Z","avatar_url":"https://github.com/andrius.png","language":"Shell","funding_links":["https://github.com/sponsors/andrius"],"categories":["Shell","Containers"],"sub_categories":[],"readme":"# GitHub Workflows Documentation\n\n## 🎯 Overview\n\nThis repository implements an automated Asterisk release discovery and Docker image build system using GitHub Actions. The system features a **per-release branch strategy** that creates individual branches and pull requests for each new Asterisk version, enabling granular review and deployment control.\n\n### Key Features\n\n- **🔍 Automated Discovery**: Daily scanning for new Asterisk releases from downloads.asterisk.org\n- **🌿 Per-Release Branches**: Individual `asterisk-{VERSION}` branches for each new release\n- **🚫 Collision Detection**: Prevents duplicate branches and PRs\n- **🏗️ Matrix Building**: Automated Docker image generation across multiple architectures\n- **🧪 Local Testing**: Comprehensive testing with `nektos/act`\n\n## 🏗️ Workflow Architecture\n\n```\n┌─────────────────────┐    ┌──────────────────────┐    ┌─────────────────────┐\n│   discover-releases │───▶│   build-images       │───▶│  build-single-image │\n│   (Daily @ 20:00)   │    │   (Manual/On-demand) │    │  (Reusable)         │\n└─────────────────────┘    └──────────────────────┘    └─────────────────────┘\n         │                           │                           │\n         ▼                           ▼                           ▼\n┌─────────────────────┐    ┌──────────────────────┐    ┌─────────────────────┐\n│ Per-release PRs     │    │ Matrix generation    │    │ Individual builds   │\n│ asterisk-22.6.0     │    │ Multi-arch support   │    │ Docker image output │\n│ asterisk-23.0.0     │    │ Filtered building    │    │ Health checks       │\n└─────────────────────┘    └──────────────────────┘    └─────────────────────┘\n```\n\n## 🎨 Per-Release Branch Strategy\n\n### Concept\n\nInstead of creating bulk PRs with multiple versions, the system creates **one branch per Asterisk release**:\n\n- **Branch naming**: `asterisk-{VERSION}`\n- **Individual PRs**: Each version gets its own review process\n- **Collision detection**: Skips versions with existing branches\n- **Granular control**: Independent merge/close decisions\n\n### Example Scenarios\n\n#### Scenario 1: Multiple New Releases\n```bash\n# Discovery finds: 22.6.0, 23.0.0, 24.0.0-rc1\n# Result: 3 separate branches and PRs\n\n✅ Created: asterisk-22.6.0    → PR #123 \"Add Asterisk 22.6.0 (Stable Release)\"\n✅ Created: asterisk-23.0.0    → PR #124 \"Add Asterisk 23.0.0 (Stable Release)\"\n✅ Created: asterisk-24.0.0-rc1 → PR #125 \"Add Asterisk 24.0.0-rc1 (Release Candidate)\"\n\n# Maintainer can:\n# - Merge 22.6.0 + 23.0.0 immediately (stable)\n# - Hold 24.0.0-rc1 for testing (RC)\n```\n\n#### Scenario 2: Collision Prevention\n```bash\n# Discovery finds: 22.6.0, 23.0.0, 24.0.0-rc1\n# Existing branches: asterisk-22.6.0, asterisk-24.0.0-rc1\n\n⏭️ Skipped: 22.6.0 (branch asterisk-22.6.0 already exists)\n✅ Created: asterisk-23.0.0 → PR #126\n⏭️ Skipped: 24.0.0-rc1 (branch asterisk-24.0.0-rc1 already exists)\n\n# Result: Only 1 new PR created, no duplicate work\n```\n\n#### Scenario 3: Version Evolution\n```bash\n# Day 1: 24.0.0-rc1 discovered\n✅ Created: asterisk-24.0.0-rc1 → PR #127 (under review)\n\n# Day 5: 24.0.0 final released\n✅ Created: asterisk-24.0.0 → PR #128 (new PR)\n\n# Available options:\n# - Close PR #127 (superseded by final)\n# - Merge PR #128 (stable release)\n```\n\n## 📋 Workflow Details\n\n### 1. discover-releases.yml\n\n**Purpose**: Automated discovery of new Asterisk releases with per-release branch creation.\n\n**Triggers**:\n- **Schedule**: Daily at 20:00 UTC (`0 20 * * *`)\n- **Manual**: `workflow_dispatch` (no inputs required)\n- **Push**: Changes to workflow files or discovery scripts\n\n**Process**:\n1. **Fetch releases**: Updates `asterisk-releases.txt` and `asterisk-certified-releases.txt`\n2. **Generate YAML**: Creates `supported-asterisk-builds.yml` with `--updates-only` flag\n3. **Extract versions**: Parses `git diff` to find new versions in supported builds\n4. **Process individually**: For each new version:\n   - Check branch collision (local + remote)\n   - Create `asterisk-{VERSION}` branch if available\n   - Generate version-specific commit and PR\n5. **Handle release lists**: Direct commit to main for metadata-only updates\n\n**Outputs**:\n- Individual branches: `asterisk-22.6.0`, `asterisk-23.0.0`, etc.\n- Individual PRs with version-specific descriptions\n- Updated release metadata files\n\n### 2. build-images.yml\n\n**Purpose**: Matrix-based building of Docker images for supported Asterisk versions.\n\n**Triggers**:\n- **Manual**: `workflow_dispatch` with filtering options\n\n**Inputs**:\n```yaml\npush: false                    # Push to registry\nregistry: \"docker.io/andrius/asterisk\"  # Target registry\nmax_parallel: \"5\"             # Concurrent builds\nfilter_version: \"22.5.2\"      # Build specific version\nfilter_distribution: \"trixie\" # Build specific distribution\n```\n\n**Process**:\n1. **Validate branch**: Ensures running on `main` branch\n2. **Generate matrix**: Parses `asterisk/supported-asterisk-builds.yml`\n3. **Filter matrix**: Applies version/distribution filters\n4. **Build images**: Calls `build-single-image.yml` for each configuration\n5. **Generate report**: Comprehensive build status summary\n\n### 3. build-single-image.yml\n\n**Purpose**: Reusable workflow for building individual Asterisk Docker images.\n\n**Triggers**:\n- **Workflow call**: From `build-images.yml`\n- **Manual**: `workflow_dispatch` for testing\n\n**Inputs**:\n```yaml\nversion: \"22.5.2\"              # Asterisk version\ndistribution: \"trixie\"         # OS distribution\narchitecture: \"amd64\"          # Target architecture\nadditional_tags: \"latest,stable,22.x\"  # Additional Docker tags (comma-separated)\npush: false                    # Push to registry\nregistry: \"test.local/asterisk\" # Target registry\n```\n\n**Process**:\n1. **Validate config**: Checks `configs/generated/asterisk-{VERSION}-{DISTRIBUTION}.yml`\n2. **Generate Dockerfile**: Uses Jinja2 templates from configuration\n3. **Generate healthcheck**: Creates container health monitoring script\n4. **Build image**: Multi-stage Docker build with buildx\n5. **Test image**: Smoke tests (version check, healthcheck validation)\n6. **Report results**: Image size, tags, build status\n\n### 4. Git Version Support\n\n**Purpose**: Build Docker images from latest Asterisk development repository.\n\n**Usage**:\n```bash\n# Build from git HEAD (local)\n./scripts/build-asterisk.sh --git trixie\n\n# Build and push git version\n./scripts/build-asterisk.sh --git trixie --push --registry myregistry.com/asterisk\n```\n\n**Git Version Format**: `git-{SHA}` (e.g., `git-ff80666`)\n\n**Process**:\n1. **Fetch latest SHA**: Gets current HEAD from https://github.com/asterisk/asterisk.git\n2. **Generate config**: Creates `asterisk-git-master-{distribution}.yml` configuration\n3. **Build image**: Uses git-dev template variant for development builds\n4. **Tag image**: Creates `git-{SHA}_debian-{distribution}` tagged image\n\n**Git Workflow Integration**:\n- Git builds use special `git-dev` template with development-focused configuration\n- Automatic SHA detection ensures build reproducibility\n- Generated configs are automatically regenerated for each build\n\n### 5. Additional Tags Support\n\n**Purpose**: Apply semantic tags to Docker images for easier version management.\n\n**Configuration**: Add `additional_tags` property to version entries in `asterisk/supported-asterisk-builds.yml`:\n\n```yaml\nlatest_builds:\n  - version: \"22.5.2\"\n    additional_tags: \"latest,stable,22\"\n    os_matrix:\n      - os: \"debian\"\n        distribution: \"trixie\"\n        architectures: [\"amd64\", \"arm64\"]\n```\n\n**Tag Types**:\n- **`latest`**: Points to the most current stable release\n- **`stable`**: Alias for the latest stable production version\n- **`22`**: Major version tag for Asterisk 22.x series\n- **`23-rc`**: Release candidate tag for pre-releases\n- **`20-cert`**: Certified release tag for certified builds\n\n**Workflow Integration**:\n- Additional tags are extracted during matrix generation\n- Tags flow through build pipeline to Docker buildx\n- Registry prefixing applied automatically for all tags\n\n## 🧪 Testing with nektos/act\n\n### Setup\n\n#### Install nektos/act\n```bash\n# macOS\nbrew install act\n\n# Ubuntu/Debian\ncurl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash\n\n# As GitHub CLI extension\ngh extension install nektos/gh-act\n```\n\n#### Verify Installation\n```bash\ngh act --help\n# Should show comprehensive help output\n```\n\n### Test Payloads\n\nThe repository includes pre-configured test payloads in `.act/payloads/`:\n\n```\n.act/payloads/\n├── workflow_dispatch_discover_releases.json     # Test release discovery\n├── workflow_dispatch_build_images.json          # Test matrix building\n├── workflow_dispatch_build_single_image.json    # Test single image build\n├── workflow_call_build_single_image.json        # Test workflow call\n├── push_trigger.json                            # Test push triggers\n└── test_new_releases.json                       # Test new release simulation\n```\n\n### Testing Procedures\n\n#### 1. Validate All Workflows\n```bash\n# Syntax validation\ngh act --validate\n\n# Expected output:\n# time=\"...\" level=info msg=\"Using docker host ...\"\n# (No error messages = all workflows valid)\n```\n\n#### 2. Test Individual Workflows\n\n**Discover Releases Workflow**:\n```bash\n# Dry run (validation only)\ngh act workflow_dispatch \\\n  -W .github/workflows/discover-releases.yml \\\n  -e .act/payloads/workflow_dispatch_discover_releases.json \\\n  --dryrun\n\n# Expected: All steps succeed, no actual changes made\n```\n\n**Build Images Workflow**:\n```bash\n# Test matrix generation\ngh act workflow_dispatch \\\n  -W .github/workflows/build-images.yml \\\n  -e .act/payloads/workflow_dispatch_build_images.json \\\n  --dryrun\n\n# Expected: Matrix generation succeeds, build jobs configured\n```\n\n**Build Single Image Workflow**:\n```bash\n# Test single build\ngh act workflow_dispatch \\\n  -W .github/workflows/build-single-image.yml \\\n  -e .act/payloads/workflow_dispatch_build_single_image.json \\\n  --dryrun\n\n# Expected: Config validation, Dockerfile generation, build steps\n```\n\n#### 3. Comprehensive Test Suite\n\n**Run All Tests**:\n```bash\n# Execute comprehensive test suite\n./.act/test-workflows.sh\n\n# Expected output:\n# 🧪 Testing all workflows with nektos/act...\n# 📋 Testing discover-releases workflow...\n# 🏗️ Testing build-images workflow...\n# 🔨 Testing build-single-image workflow...\n# 📤 Testing push triggers...\n# ✅ Validating workflow syntax...\n# ✅ All workflow tests completed successfully!\n```\n\n#### 4. Debug Specific Issues\n\n**Verbose Testing**:\n```bash\n# Detailed debugging output\ngh act workflow_dispatch \\\n  -W .github/workflows/discover-releases.yml \\\n  -e .act/payloads/workflow_dispatch_discover_releases.json \\\n  --dryrun \\\n  --verbose\n\n# Shows detailed step execution and environment setup\n```\n\n**Test Specific Job**:\n```bash\n# Test only matrix preparation job\ngh act workflow_dispatch \\\n  -W .github/workflows/build-images.yml \\\n  -e .act/payloads/workflow_dispatch_build_images.json \\\n  --dryrun \\\n  -j prepare-matrix\n\n# Isolates specific job for debugging\n```\n\n### Common Testing Scenarios\n\n#### Test New Release Detection\n```bash\n# Simulate new releases being found\ngh act workflow_dispatch \\\n  -W .github/workflows/discover-releases.yml \\\n  -e .act/payloads/test_new_releases.json \\\n  --dryrun\n\n# Check output for version extraction and processing logic\n```\n\n#### Test Build Filtering\n```bash\n# Test specific version building\ngh act workflow_dispatch \\\n  -W .github/workflows/build-images.yml \\\n  -e .act/payloads/workflow_dispatch_build_images.json \\\n  --dryrun \\\n  --env FILTER_VERSION=\"22.5.2\"\n\n# Verifies filtering logic works correctly\n```\n\n#### Test Additional Tags Support\n```bash\n# Test build with additional tags\ngh act workflow_dispatch \\\n  -W .github/workflows/build-single-image.yml \\\n  -e .act/payloads/workflow_dispatch_build_single_image.json \\\n  --dryrun \\\n  --env ADDITIONAL_TAGS=\"latest,stable,22.x\"\n\n# Verify tags are processed and applied correctly\n```\n\n#### Test Git Version Builds\n```bash\n# Test git build functionality (local)\n./scripts/build-asterisk.sh --git trixie --dry-run\n\n# Expected output: git-{SHA} version detection and build setup\n```\n\n## 🚀 Usage Examples\n\n### Manual Workflow Triggers\n\n#### Trigger Release Discovery\n```bash\n# Manual release discovery run\ngh workflow run discover-releases.yml\n\n# Check run status\ngh run list --workflow=discover-releases.yml\n```\n\n#### Build Specific Version\n```bash\n# Build single version\ngh workflow run build-images.yml \\\n  -f filter_version=\"23.0.0\" \\\n  -f push=false\n\n# Build with push to registry\ngh workflow run build-images.yml \\\n  -f filter_version=\"22.5.2\" \\\n  -f filter_distribution=\"trixie\" \\\n  -f push=true \\\n  -f registry=\"your-registry.com/asterisk\"\n```\n\n#### Test Single Image Build\n```bash\n# Test individual image build\ngh workflow run build-single-image.yml \\\n  -f version=\"22.5.2\" \\\n  -f distribution=\"trixie\" \\\n  -f architecture=\"amd64\" \\\n  -f push=false\n\n# Test build with additional tags\ngh workflow run build-single-image.yml \\\n  -f version=\"22.5.2\" \\\n  -f distribution=\"trixie\" \\\n  -f architecture=\"amd64\" \\\n  -f additional_tags=\"latest,stable,22.x\" \\\n  -f push=true \\\n  -f registry=\"your-registry.com/asterisk\"\n```\n\n### Interpreting Results\n\n#### Successful Discovery Run\n```\n✅ New Releases Found!\n- 🔀 Action: Created individual Pull Requests per release\n- 🎯 Impact: New buildable Asterisk versions detected\n- 📊 Versions: 22.6.0 23.0.0 24.0.0-rc1\n- ⚙️ Next: Review and merge individual PRs to enable building\n```\n\n#### No New Releases\n```\nℹ️ No Changes\n- 🔀 Action: No updates needed\n- 📊 Status: All release data is current\n```\n\n#### Partial Processing (Collision Detection)\n```\n🔄 Processing new versions: 22.6.0 23.0.0\n⏭️ Skipping 22.6.0 - branch asterisk-22.6.0 already exists\n✅ Branch asterisk-23.0.0 available - creating PR for 23.0.0\n📊 Summary:\n  - New versions found: 2\n  - PRs created: 1\n  - Skipped (branch exists): 1\n```\n\n## 🔧 Maintenance and Development\n\n### Modifying Workflows Safely\n\n#### 1. Test Changes Locally First\n```bash\n# Always test workflow changes with act before committing\ngh act --validate\n\n# Test specific workflow\ngh act workflow_dispatch \\\n  -W .github/workflows/modified-workflow.yml \\\n  -e .act/payloads/test-payload.json \\\n  --dryrun\n```\n\n#### 2. Update Test Payloads\nWhen modifying workflow inputs, update corresponding payload files:\n```bash\n# Edit payload files to match new input schema\nvi .act/payloads/workflow_dispatch_build_images.json\n\n# Test with updated payload\ngh act workflow_dispatch \\\n  -W .github/workflows/build-images.yml \\\n  -e .act/payloads/workflow_dispatch_build_images.json \\\n  --dryrun\n```\n\n#### 3. Validate Before Deployment\n```bash\n# Run comprehensive test suite before merging\n./.act/test-workflows.sh\n\n# Ensure all workflows still pass validation\ngh act --validate\n```\n\n### Best Practices\n\n#### Workflow Development\n- **Always use `--dryrun` during development**\n- **Test all trigger conditions** (workflow_dispatch, push, schedule)\n- **Validate JSON payloads** before committing\n- **Use verbose output** (`--verbose`) for debugging\n\n#### Payload Management\n- **Keep payloads realistic** (use actual version numbers, valid distributions)\n- **Test edge cases** (empty inputs, invalid versions)\n- **Document payload purpose** in comments\n\n#### Testing Strategy\n- **Local first**: Test with act before GitHub\n- **Incremental**: Test individual jobs with `-j` flag\n- **Comprehensive**: Run full test suite before releases\n\n### Troubleshooting\n\n#### Common Issues\n\n**Workflow Validation Fails**:\n```bash\n# Check YAML syntax\ngh act --validate\n\n# Look for indentation, quotes, or structure issues\n# Fix and re-test\n```\n\n**Job Fails in Dry Run**:\n```bash\n# Run with verbose output\ngh act workflow_dispatch \\\n  -W .github/workflows/problematic-workflow.yml \\\n  -e .act/payloads/test-payload.json \\\n  --dryrun \\\n  --verbose\n\n# Check for missing dependencies, invalid paths, or logic errors\n```\n\n**Matrix Job Issues**:\n```bash\n# Test matrix generation separately\ngh act workflow_dispatch \\\n  -W .github/workflows/build-images.yml \\\n  -e .act/payloads/workflow_dispatch_build_images.json \\\n  --dryrun \\\n  -j prepare-matrix\n\n# Verify supported-asterisk-builds.yml parsing\n```\n\n**Path Issues**:\n```bash\n# Verify working directories and file paths\n# Check that referenced scripts and files exist\nls -la scripts/\nls -la asterisk/\nls -la configs/generated/\n```\n\n#### Debug Environment Variables\n```bash\n# Print all available environment variables\ngh act workflow_dispatch \\\n  -W .github/workflows/discover-releases.yml \\\n  -e .act/payloads/workflow_dispatch_discover_releases.json \\\n  --dryrun \\\n  --env DEBUG=true \\\n  --verbose\n```\n\n## 📚 Integration Points\n\n### With Build System\n- **Template Integration**: Workflows use templates from `templates/` directory\n- **Configuration Driven**: All builds based on YAML configurations\n- **Script Dependencies**: Relies on `scripts/` for core functionality\n\n### With Repository Structure\n- **Release Data**: Updates `asterisk/` directory files\n- **Generated Configs**: Uses `configs/generated/` for build specifications\n- **Template Processing**: Integrates with Jinja2 template system\n\n### With External Services\n- **downloads.asterisk.org**: Source of release information\n- **Docker Registry**: Target for built images\n- **GitHub API**: For PR creation and management\n\n---\n\n## 🎯 Quick Start\n\n1. **Install nektos/act**: `gh extension install nektos/gh-act`\n2. **Validate workflows**: `gh act --validate`\n3. **Run test suite**: `./.act/test-workflows.sh`\n4. **Test specific workflow**: `gh act workflow_dispatch -W .github/workflows/discover-releases.yml -e .act/payloads/workflow_dispatch_discover_releases.json --dryrun`\n\nFor questions or issues, consult the troubleshooting section or examine the comprehensive test outputs provided by the act testing framework.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrius%2Fasterisk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrius%2Fasterisk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrius%2Fasterisk/lists"}