{"id":28455508,"url":"https://github.com/observiq/otel-distro-builder","last_synced_at":"2025-06-27T02:32:22.568Z","repository":{"id":285119039,"uuid":"946189241","full_name":"observIQ/otel-distro-builder","owner":"observIQ","description":"Build custom OpenTelemetry Collector Distributions from manifest files with a local build utility, Docker, Google Cloud Build, or a GitHub Action.","archived":false,"fork":false,"pushed_at":"2025-06-20T17:23:59.000Z","size":182,"stargazers_count":20,"open_issues_count":7,"forks_count":1,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-06-20T18:33:36.638Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/observIQ.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"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}},"created_at":"2025-03-10T18:48:32.000Z","updated_at":"2025-06-14T23:34:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"7e9853f9-2be0-4e80-a09c-634161dbfc14","html_url":"https://github.com/observIQ/otel-distro-builder","commit_stats":null,"previous_names":["observiq/otel-distro-builder"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/observIQ/otel-distro-builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/observIQ%2Fotel-distro-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/observIQ%2Fotel-distro-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/observIQ%2Fotel-distro-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/observIQ%2Fotel-distro-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/observIQ","download_url":"https://codeload.github.com/observIQ/otel-distro-builder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/observIQ%2Fotel-distro-builder/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262177822,"owners_count":23270941,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2025-06-06T22:09:34.172Z","updated_at":"2025-06-27T02:32:22.553Z","avatar_url":"https://github.com/observIQ.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 OpenTelemetry Distribution Builder\n\n\u003cdiv align=\"center\"\u003e\n\n[![GitHub Release](https://img.shields.io/github/v/release/observIQ/otel-distro-builder)](https://github.com/observIQ/otel-distro-builder/releases)\n[![Apache 2.0 License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n\nBuild custom OpenTelemetry Collector Distributions from manifest files with a local build utility, Docker, Google Cloud Build, or a GitHub Action.\n\n[Quick Start](#-quick-start) • [Documentation](#-documentation) • [Examples](#-examples)\n\n\u003c/div\u003e\n\n## 🤔 Why OpenTelemetry Distribution Builder?\n\nBuilt on top of the [OpenTelemetry Collector Builder (OCB)](https://github.com/open-telemetry/opentelemetry-collector/tree/main/cmd/builder), it uses a `manifest.yaml` to define the components you need, then automates packaging for multiple platforms and manages version releases via GitHub.\n\nWhile OCB (OpenTelemetry Collector Builder) focuses on building single collector binaries, the OpenTelemetry Distribution Builder provides a complete distribution management solution:\n\n- 🔨 Builds multi-platform binaries using OCB under the hood\n- 📦 Generates installation packages following OTel community best practices\n- 🚀 Automates versioned releases through GitHub Actions\n- 🔄 Simplifies updates through manifest-based configuration\n\nIt handles all the complex aspects of managing your own distribution that have historically made building custom collectors challenging. With the OpenTelemetry Distribution Builder, you can focus on defining your components while the tooling takes care of the rest.\n\n## ✨ Features\n\n- 🎯 **Custom Component Selection**: Build distributions with exactly the components you need\n- 🌐 **Multi-Platform Support**: Build for multiple architectures (amd64, arm64)\n- 📦 **Multiple Package Formats**: Generate APK, DEB, RPM, and TAR.GZ packages\n- 🔄 **GitHub Actions Integration**: Seamless CI/CD integration\n- 🚀 **Automated Releases**: Streamlined versioning and release process\n- 🔍 **Platform-Specific Builds**: Optimize for your target environment\n\n## 🚀 Quick Start\n\n1. **Create a new repository**\n2. **Add your manifest file** (`manifest.yaml`):\n\n   ```yaml\n   dist:\n     name: my-otelcol\n     description: My Custom OpenTelemetry Collector Distro\n     # ...\n   extensions:\n     -  # ...\n   exporters:\n     -  # ...\n   processors:\n     -  # ...\n   receivers:\n     -  # ...\n   connectors:\n     -  # ...\n   providers:\n     -  # ...\n   ```\n\n3. **Set up GitHub Actions** (`.github/workflows/build.yml`):\n\n```yaml\nname: OpenTelemetry Distribution Build\n\non:\n   push:\n     tags:\n       - \"v*\"\n   workflow_dispatch:\n\n  permissions:\n    contents: write # This is required for creating/modifying releases\n\n  jobs:\n    build:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      # Build the OpenTelemetry distribution using this custom action\n      - uses: observiq/otel-distro-builder@v1\n        with:\n          manifest: \"./manifest.yaml\"\n\n      # Create a GitHub Release and attach the build artifacts\n      # This makes the artifacts available for download from the Releases page\n      - name: Create Release\n        uses: softprops/action-gh-release@v2\n        with:\n          files: ${{ github.workspace }}/artifacts/*\n```\n\n4. **Trigger a build**:\n\n   ```bash\n   git tag v1.0.0 \u0026\u0026 git push --tags\n   ```\n\n5. **(Optional) Build with Docker**:\n\n   ```bash\n   docker pull ghcr.io/observiq/otel-distro-builder:main\n   docker run --rm -v $(pwd):/workspace -v $(pwd)/build:/build ghcr.io/observiq/otel-distro-builder:main \\\n     --manifest /workspace/manifest.yaml\n   ```\n\n## 📚 Documentation\n\nTo view detailed guides, see the [docs](./docs) directory.\n\n### GitHub Action Configuration\n\n#### Inputs\n\n| Input       | Description           | Default           |\n| ----------- | --------------------- | ----------------- |\n| `manifest`  | Path to manifest file | `./manifest.yaml` |\n| `platforms` | Target platforms      | `linux/amd64`     |\n\n#### Outputs\n\nAll generated packages and binaries are available in the `${{ github.workspace }}/artifacts/*` folder.\n\n### Docker Usage\n\n```bash\n# Pull the latest version\ndocker pull ghcr.io/observiq/otel-distro-builder:latest\n\n# Pull specific version\ndocker pull ghcr.io/observiq/otel-distro-builder:v1.0.5\n\n# Run a build\ndocker run --rm -v $(pwd):/workspace -v $(pwd)/build:/build ghcr.io/observiq/otel-distro-builder:main \\\n  --manifest /workspace/manifest.yaml \\\n  # Optional\n  --artifacts /workspace/artifacts \\\n  --goos linux \\\n  --goarch amd64 \\\n  --ocb-version 0.121.0 \\\n  --go-version 1.22.1 \\ \n  --supervisor-version 0.122.0\n```\n\n## 🛠️ Development\n\n### Prerequisites\n\n- Python 3\n- Docker\n- Make\n\n### Available Commands\n\n```bash\n# Show all commands\nmake help\n\n# Setup development environment\nmake setup\n\n# Run tests\nmake test\n\n# Run linting\nmake lint\n\n```\n\n### Build Scripts\n\n#### `run_cloud_build.sh`\n\nTriggers a build using Google Cloud Build:\n\n```bash\n./scripts/run_cloud_build.sh -m manifest.yaml -p project_id -b artifact_bucket\n```\n\nOptions:\n\n- `-m`: Path to manifest file (required)\n- `-p`: Google Cloud project ID\n- `-b`: Artifact bucket name\n\n#### `run_local_build.sh`\n\nThis script is used to build a custom OpenTelemetry Collector distribution using a local Docker container:\n\n```bash\n./scripts/run_local_build.sh -m manifest.yaml [-o output_dir] [-v ocb_version] [-g go_version]\n\n# Optionally, run it with\nmake build-local # to get the latest version of the otelcol and ocb\n# Or\nmake build output_dir=./artifacts ocb_version=0.121.0 go_version=1.22.1 supervisor_version=0.122.0\n```\n\nOptions:\n\n- `-m`: Path to manifest file (required)\n- `-o`: Directory to store build artifacts (default: ./artifacts)\n- `-v`: OpenTelemetry Collector Builder version (default: auto-detected from manifest)\n- `-g`: Go version to use for building (default: 1.24.1)\n\nThe artifacts will be saved to the specified output directory (default: `./artifacts`).\n\n## 📁 Project Structure\n\n```text\notel-distro-builder/\n├── builder/                # Builder application\n│   ├── src/               # Core builder code\n│   ├── templates/         # Build templates\n│   ├── tests/            # Test suite\n│   └── Dockerfile        # Builder image definition\n├── action/                # GitHub Action\n├── scripts/              # Build scripts\n└── Makefile              # Development commands\n```\n\n## 🔧 Build Process\n\n1. **Builder Image Preparation**: Build and push to registry\n2. **Manifest Processing**: Upload and validate manifest configuration\n3. **Build Execution**:\n   - Download OpenTelemetry Collector Builder (OCB)\n   - Generate Go source files\n   - Build platform-specific packages\n   - Create SBOMs and checksums\n4. **Artifact Management**: Upload to GitHub, Google Cloud Storage, or save locally\n\n## 📦 Build Artifacts\n\nThe builder produces:\n\n- 📦 Binary packages (APK, DEB, RPM)\n- 📚 Source tarball\n- 🔧 Raw binary\n- 📋 SBOM files\n- 🔍 Checksums\n- 📝 Build metadata\n\n### Storage Locations\n\n- **Local builds**: `./artifacts` directory\n- **Cloud builds**: `gs://\u003cbucket\u003e/\u003cbuild_id\u003e/`\n\n## 🔢 Versioning\n\nWe follow semantic versioning. The builder is available in several forms:\n\n- GitHub Action: Use `@v1` for latest 1.x version, or `@v1.0.5` for specific versions\n- Docker Image: Use `main` for latest, or version tags like `v1.0.5`\n- Container Registry: `ghcr.io/observiq/otel-distro-builder:main` or `ghcr.io/observiq/otel-distro-builder:v1.0.5`\n\n## 📚 Examples\n\nCheck out our example workflows in `.github/workflows/examples/` for common use cases:\n\n- Multi-platform builds\n- Container publishing\n- Custom package configurations\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## 📄 License\n\nThis project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  Made with ❤️ by the Bindplane team\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobserviq%2Fotel-distro-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fobserviq%2Fotel-distro-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobserviq%2Fotel-distro-builder/lists"}