@@ -17,25 +17,25 @@ The plugin also exposes Prometheus-compatible metrics for monitoring repository
1717## Configuration Options
1818
1919| Parameter | Type | Required | Default | Description |
20- | ----------- | ------ | ---------- | --------- | ------------- |
20+ | --------- | ---- | -------- | ------- | ----------- |
2121| ` repo ` | String | Yes | - | Git repository URL (HTTPS, SSH, or file://) |
2222| ` ref ` | String | No | ` main ` | Git reference: branch name, tag, or commit SHA |
2323| ` path ` | String | Yes | - | Path to configuration file within the repository |
2424| ` clone_path ` | String | No | ` /tmp/fluentbit-git-repo ` | Local directory for git clone and state storage |
2525| ` poll_interval ` | Integer | No | ` 60 ` | Polling interval in seconds to check for updates |
2626
27-
2827The Git repository URL. Supports multiple protocols:
2928
3029- ** HTTPS** : ` https://github.com/user/repo.git `
3130- ** SSH** : ` git@github.com:user/repo.git `
3231- ** Local file** : ` file:///path/to/repo `
3332
3433For private repositories:
34+
3535- ** HTTPS** : Use personal access tokens in the URL: ` https://token@github.com/user/repo.git `
3636- ** SSH** : Configure SSH keys in ` ~/.ssh/ ` (requires ` id_rsa ` or ` id_ed25519 ` )
3737
38- #### ` ref `
38+ ### ` ref `
3939
4040The Git reference to track. Can be:
4141
@@ -50,13 +50,15 @@ The plugin monitors this reference for changes. When the commit SHA at this ref
5050Path to the configuration file within the repository, relative to the repository root.
5151
5252Examples:
53+
5354- ` fluent-bit.yaml `
5455- ` config/production.yaml `
5556- ` environments/prod/fluent-bit.conf `
5657
5758#### ` clone_path `
5859
5960Local directory where:
61+
6062- The Git repository is cloned
6163- SHA-based configuration files are stored
6264- The state file (` .last_sha ` ) is stored
@@ -68,6 +70,7 @@ The directory will be created if it doesn't exist. Must be writable by the Fluen
6870How frequently (in seconds) to check the remote repository for changes.
6971
7072Recommended values:
73+
7174- ** Development/Testing** : 5-10 seconds
7275- ** Production** : 60-300 seconds
7376
@@ -155,11 +158,13 @@ pipeline:
155158# ## State Persistence
156159
157160The plugin stores the last processed commit SHA in a state file :
158- ` ` `
161+
162+ ` ` ` shell
159163{clone_path}/.last_sha
160164` ` `
161165
162166This state file :
167+
163168- Persists across Fluent Bit restarts
164169- Prevents unnecessary reloads when restarting with unchanged configuration
165170- Contains a 40-character SHA-1 commit hash
@@ -178,11 +183,13 @@ When a configuration change is detected:
178183# ## Change Detection
179184
180185The plugin uses Git commit SHAs for change detection :
186+
181187- Fetches the commit SHA at the specified `ref`
182188- Compares with the last processed SHA from state file
183189- If different, triggers sync and reload
184190
185191This approach works with :
192+
186193- Branch updates (SHA changes when new commits are pushed)
187194- Tag updates (if tag is moved to a different commit)
188195- Direct SHA monitoring (only reloads if you manually update the `ref` parameter)
@@ -194,7 +201,7 @@ The plugin exposes Prometheus-compatible metrics for monitoring repository polli
194201# ## Available Metrics
195202
196203| Metric | Type | Labels | Description |
197- |--------| ------| --------| ------------- |
204+ | ------ | ---- | ------ | ----------- |
198205| `fluentbit_git_config_last_poll_timestamp_seconds` | Gauge | `name` | Unix timestamp of the last repository poll |
199206| `fluentbit_git_config_last_reload_timestamp_seconds` | Gauge | `name` | Unix timestamp of the last configuration reload |
200207| `fluentbit_git_config_poll_errors_total` | Counter | `name` | Total number of repository poll errors |
@@ -210,7 +217,8 @@ curl http://localhost:2020/api/v1/metrics/prometheus
210217` ` `
211218
212219Example output :
213- ` ` `
220+
221+ ` ` ` text
214222# HELP fluentbit_git_config_last_poll_timestamp_seconds Unix timestamp of last repository poll
215223# TYPE fluentbit_git_config_last_poll_timestamp_seconds gauge
216224fluentbit_git_config_last_poll_timestamp_seconds{name="git_config.0"} 1696349234
@@ -237,6 +245,7 @@ fluentbit_git_config_info{sha="abc123def",repo="https://github.com/myorg/configs
237245You can use these metrics with monitoring systems like Prometheus and Grafana :
238246
239247**Prometheus Alert Examples:**
248+
240249` ` ` yaml
241250groups:
242251 - name: fluent_bit_git_config
@@ -301,6 +310,7 @@ customs:
301310` ` `
302311
303312Requirements :
313+
304314- SSH keys configured in `~/.ssh/id_rsa` or `~/.ssh/id_ed25519`
305315- Proper permissions : ` chmod 600 ~/.ssh/id_rsa`
306316- Known hosts configured : ` ssh-keyscan github.com >> ~/.ssh/known_hosts`
@@ -322,6 +332,7 @@ The plugin is designed to be resilient to transient errors:
322332- **Too infrequent**: Delays detection of configuration changes
323333
324334Choose based on your requirements :
335+
325336- Critical production systems : 60-120 seconds
326337- Active development : 5-10 seconds
327338- Stable environments : 300-600 seconds
@@ -335,16 +346,17 @@ Choose based on your requirements:
335346# ## Repository Size
336347
337348Large repositories with extensive history may slow initial cloning. Consider :
349+
338350- Using shallow clones (future enhancement)
339351- Keeping configuration repositories small and focused
340352- Using separate repositories for configuration vs. application code
341353
342354# # Troubleshooting
343355
344-
345356# ## Authentication Failures
346357
347358For SSH :
359+
348360` ` ` bash
349361# Test SSH connection
350362ssh -T git@github.com
@@ -355,6 +367,7 @@ chmod 600 ~/.ssh/id_rsa
355367` ` `
356368
357369For HTTPS with token :
370+
358371` ` ` bash
359372# Test git access
360373git ls-remote https://token@github.com/user/repo.git
@@ -363,12 +376,14 @@ git ls-remote https://token@github.com/user/repo.git
363376# ## Changes Not Detected
364377
365378Enable debug logging to see polling activity :
379+
366380` ` ` yaml
367381service:
368382 log_level: debug
369383` ` `
370384
371385Check :
386+
372387- Remote repository actually has new commits
373388- ` ref` points to the branch/tag you expect
374389- Polling interval hasn't elapsed yet
@@ -378,6 +393,7 @@ Check:
378393# ## Reload Failures
379394
380395Check :
396+
381397- Configuration file syntax is valid
382398- All referenced plugins are available
383399- File paths and permissions are correct
@@ -386,11 +402,13 @@ Check:
386402# ## High Error Rates
387403
388404Monitor the error metrics :
405+
389406` ` ` bash
390407curl -s http://localhost:2020/api/v1/metrics/prometheus | grep -E "git_config_(poll|sync)_errors"
391408` ` `
392409
393410Common causes :
411+
394412- Network connectivity issues
395413- Authentication failures
396414- Repository access problems
0 commit comments