{"id":49884186,"url":"https://github.com/leodhb/kestra-gitops","last_synced_at":"2026-05-15T17:10:05.914Z","repository":{"id":338924165,"uuid":"1159652932","full_name":"leodhb/kestra-gitops","owner":"leodhb","description":"Boilerplate for versioning Kestra flows with local Docker validation and automatic deployment via GitHub Actions.","archived":false,"fork":false,"pushed_at":"2026-02-17T06:48:49.000Z","size":67,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"prod","last_synced_at":"2026-02-17T10:50:05.940Z","etag":null,"topics":["gitops","kestra","kestra-workflows"],"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/leodhb.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-17T01:44:33.000Z","updated_at":"2026-02-17T06:48:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/leodhb/kestra-gitops","commit_stats":null,"previous_names":["leodhb/kestra-gitops"],"tags_count":null,"template":true,"template_full_name":null,"purl":"pkg:github/leodhb/kestra-gitops","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leodhb%2Fkestra-gitops","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leodhb%2Fkestra-gitops/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leodhb%2Fkestra-gitops/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leodhb%2Fkestra-gitops/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leodhb","download_url":"https://codeload.github.com/leodhb/kestra-gitops/tar.gz/refs/heads/prod","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leodhb%2Fkestra-gitops/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33073030,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T11:35:32.926Z","status":"ssl_error","status_checked_at":"2026-05-15T11:35:31.362Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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":["gitops","kestra","kestra-workflows"],"created_at":"2026-05-15T17:10:02.586Z","updated_at":"2026-05-15T17:10:05.906Z","avatar_url":"https://github.com/leodhb.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kestra GitOps Boilerplate\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub Actions](https://img.shields.io/badge/CI-GitHub%20Actions-blue)](https://github.com/features/actions)\n[![Kestra](https://img.shields.io/badge/Kestra-Latest-purple)](https://kestra.io)\n\n\u003e 🎯 **Template Repository**: [Use this template](../../generate) to create your own Kestra GitOps repository with automatic validation and deployment.\n\nBoilerplate for versioning Kestra flows with local Docker validation and automatic deployment via GitHub Actions.\n\n## Prerequisites\n\n- Docker installed and running\n- Node.js and npm (for automatic Git hooks)\n- A Kestra instance (self-hosted or cloud)\n\n\u003e **Note**: This is a template repository. After creating your repo from this template, replace example flows in `kestra/flows/company/` with your own flows.\n\n## Initial Setup\n\n### 1. Local Setup\n\n```bash\n# Clone the repository\ngit clone \u003cyour-repo\u003e\ncd kestra-gitops\n\n# Install dependencies (automatically configures hooks)\nnpm install\n\n# Validate everything is OK\nnpm run validate\n```\n\nAfter `npm install`, the **pre-commit hook** is automatically installed via Husky. Every time you commit, validation (`scripts/validate.sh`) runs automatically.\n\n### 2. GitHub Environment Configuration (Required for Deployment)\n\nBefore pushing to `prod` branch, configure the **Production** environment in GitHub:\n\n1. Go to your repository **Settings** → **Environments** → **New environment**\n2. Create environment named: `Production`\n3. Add the following **secrets**:\n   - `KESTRA_HOST`: Your Kestra server URL (e.g., `https://kestra.example.com`)\n   - `KESTRA_USER`: Email or username for authentication\n   - `KESTRA_PASSWORD`: Password for authentication\n\n**Without these secrets configured, deployments will fail.** This is expected behavior - the template requires you to configure your own Kestra instance.\n\nFor detailed instructions, see: **[docs/adding-environments.md](docs/adding-environments.md)**\n\n## Project Structure\n\n```\nkestra-gitops/\n├── bin/\n│   └── kestra.sh                 # Docker wrapper for Kestra CLI\n├── scripts/\n│   └── validate.sh               # Validation script (pre-commit)\n├── kestra/\n│   ├── flows/                    # Flows organized by namespace\n│   │   └── company/\n│   │       └── hello_world.yml   # Example flow (replace with yours)\n│   └── files/                    # Namespace files (optional)\n│       └── company/\n│           └── example.txt       # Example file (replace with yours)\n├── .husky/\n│   └── pre-commit                # Automatic validation hook\n├── .github/\n│   └── workflows/\n│       └── kestra-deploy.yml     # Deployment pipeline\n├── docs/\n│   ├── adding-environments.md    # How to add new environments\n│   └── adding-flows.md           # How to add new flows\n├── docker-compose.kestra.yml     # Local Kestra (development)\n├── package.json                  # npm/Husky configuration\n└── README.MD\n```\n\n## How It Works\n\n### Folder Convention → Namespace\n\nThe folder structure automatically determines the flow namespace:\n\n```\nkestra/flows/company/hello_world.yml\n             └─────┘ └─────────┘\n             namespace  flow id\n             (/ becomes .)\n```\n\nIn the flow YAML:\n```yaml\nid: hello_world\nnamespace: company\n```\n\n### Local Validation\n\nThe `scripts/validate.sh` script validates:\n\n1. **Structure**: `id` and `namespace` match file path/name\n2. **Syntax**: executes `flow validate --local` in ephemeral Docker container\n\n#### Validation Modes\n\n**Full validation** (validates all flows):\n```bash\nnpm run validate\n# or\n./scripts/validate.sh\n```\n\n**Selective validation** (validates only specific files):\n```bash\n./scripts/validate.sh --files kestra/flows/company/example.yml kestra/flows/company/other.yml\n```\n\n**Performance optimization**: The pre-commit hook automatically validates only the files you changed, making commits much faster. Full validation runs in CI/CD.\n\n**How selective validation works:**\n- Pre-commit hook detects staged `.yml`/`.yaml` files in `kestra/flows/`\n- Passes only those files to the validation script\n- Skips files structure validation (runs only in full mode)\n- Significantly faster for development workflow\n\n### Automatic Deployment (CI/CD)\n\nAfter configuring the GitHub Environment (see [Initial Setup](#2-github-environment-configuration-required-for-deployment)):\n\n- Push to **`prod`** branch → automatic deployment to Production\n- Pull requests → validation only (no deployment)\n- Only changed namespaces are deployed (optimized for performance)\n\n## Useful Commands\n\n### Manual Validation\n\n```bash\n# Validate all flows (runs complete validation)\nnpm run validate\n\n# Validate specific files only (much faster for development)\n./scripts/validate.sh --files kestra/flows/company/example.yml\n\n# Validate multiple specific files\n./scripts/validate.sh --files \\\n  kestra/flows/company/flow1.yml \\\n  kestra/flows/company/flow2.yml\n```\n\n### Git Hooks\n\nThe project uses **Husky** to run automatic validation before each commit:\n- ✅ Validates folder/namespace structure\n- ✅ Validates YAML syntax of flows\n- ⚡ Only validates files you changed (fast!)\n- ❌ Blocks commit if there are errors\n\nTo bypass (use with caution):\n```bash\ngit commit --no-verify -m \"message\"\n```\n\n### Validate Flow Syntax\n\n```bash\n./bin/kestra.sh flow validate --local kestra/flows/company/hello_world.yml\n```\n\n### Start Local Kestra\n\n```bash\ndocker compose -f docker-compose.kestra.yml up -d\n```\n\nAccess at: `http://localhost:8080`\n\n### Create Local Alias\n\n```bash\nalias kestra='./bin/kestra.sh'\nkestra --version\n```\n\n## GitHub Actions Deployment\n\n### How It Works\n\n- Push to **`prod`** branch → automatic deployment to Production environment\n- Pull requests → validation only (no deployment)\n- The workflow dynamically discovers changed namespaces and deploys only what changed\n\n### Adding More Environments\n\nTo add staging, dev, or other environments, see: **[docs/adding-environments.md](docs/adding-environments.md)**\n\n## Adding New Flows\n\nFollow the folder convention and see the complete guide at: **[docs/adding-flows.md](docs/adding-flows.md)**\n\nQuick example:\n\n```bash\n# 1. Create structure\nmkdir -p kestra/flows/company/pipelines\n\n# 2. Create flow\ncat \u003e kestra/flows/company/pipelines/daily_sync.yml \u003c\u003c 'EOF'\nid: daily_sync\nnamespace: company.pipelines\n\ntasks:\n  - id: sync\n    type: io.kestra.plugin.core.log.Log\n    message: \"Syncing...\"\nEOF\n\n# 3. Validate\n./scripts/validate.sh\n\n# 4. Commit\ngit add kestra/flows/company/pipelines/daily_sync.yml\ngit commit -m \"Add daily sync pipeline\"\ngit push origin prod\n```\n\n## Documentation\n\n- **[Adding Environments](docs/adding-environments.md)** - How to create staging, dev, etc\n- **[Adding Flows](docs/adding-flows.md)** - Conventions and best practices\n\n## Environment Architecture\n\nThere is no environment separation by folders in the repository. The same code is deployed to different servers, determined by the GitHub Environment of the branch:\n\n```\nRepository (same flow structure)\n  │\n  ├─ branch prod ──────→ Kestra Production (via environment Production)\n  │\n  └─ branch staging ───→ Kestra Staging (via environment Staging, when created)\n```\n\n---\n\n**Initial setup**: validate everything works by running `npm run validate` ✅\n\n## Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleodhb%2Fkestra-gitops","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleodhb%2Fkestra-gitops","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleodhb%2Fkestra-gitops/lists"}