Skip to content

Commit f728594

Browse files
indacoindaco
authored
feat(contrib/extensions): add github-version-sync extension (#192)
* feat(contrib/extensions): add github-version-sync extension * feat(contrib/extensions/github-version-sync): support jaq as jq alternative * docs(contrib/extensions/github-version-sync): update README to use config key
1 parent c7e999d commit f728594

File tree

4 files changed

+407
-4
lines changed

4 files changed

+407
-4
lines changed

‎contrib/extensions/README.md‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,11 @@ This directory contains example extensions demonstrating how to build sley exten
77
88
## Available Extensions
99

10-
| Extension | Language | Hook | Description |
11-
| --------------------------------------- | -------- | --------- | ------------------------------------ |
12-
| [commit-validator](./commit-validator/) | Python | pre-bump | Validates conventional commit format |
13-
| [docker-tag-sync](./docker-tag-sync/) | Bash | post-bump | Tags and pushes Docker images |
10+
| Extension | Language | Hook | Description |
11+
| --------------------------------------------- | -------- | --------- | -------------------------------------------- |
12+
| [commit-validator](./commit-validator/) | Python | pre-bump | Validates conventional commit format |
13+
| [docker-tag-sync](./docker-tag-sync/) | Bash | post-bump | Tags and pushes Docker images |
14+
| [github-version-sync](./github-version-sync/) | Bash | pre-bump | Syncs version from GitHub repository release |
1415

1516
Each extension includes a complete `README.md` with usage examples and configuration options.
1617

@@ -24,13 +25,17 @@ sley extension install --url github.com/indaco/sley/contrib/extensions/commit-va
2425

2526
# Install docker-tag-sync (Bash)
2627
sley extension install --url github.com/indaco/sley/contrib/extensions/docker-tag-sync
28+
29+
# Install github-version-sync (Bash)
30+
sley extension install --url github.com/indaco/sley/contrib/extensions/github-version-sync
2731
```
2832

2933
Or from a local clone:
3034

3135
```bash
3236
sley extension install --path ./contrib/extensions/commit-validator
3337
sley extension install --path ./contrib/extensions/docker-tag-sync
38+
sley extension install --path ./contrib/extensions/github-version-sync
3439
```
3540

3641
## Management
@@ -51,6 +56,7 @@ For complete documentation, configuration examples, and troubleshooting:
5156
- **[Creating Extensions](https://sley.indaco.dev/extensions/#creating-an-extension)** - Build your own extensions
5257
- **[Commit Validator](https://sley.indaco.dev/extensions/commit-validator.html)** - Commit validation extension docs
5358
- **[Docker Tag Sync](https://sley.indaco.dev/extensions/docker-tag-sync.html)** - Docker tagging extension docs
59+
- **[GitHub Version Sync](https://sley.indaco.dev/extensions/github-version-sync.html)** - GitHub version sync extension docs
5460
- **[Plugin System](https://sley.indaco.dev/plugins/)** - Built-in plugins vs extensions comparison
5561

5662
## Using These Examples

‎contrib/extensions/github-version-sync/README.md‎

Lines changed: 247 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
1+
# GitHub Version Sync Extension
2+
3+
Syncs the `.version` file to the latest release from a GitHub repository before bumping.
4+
5+
## Features
6+
7+
- Fetches latest release from any public GitHub repository
8+
- Configurable tag prefix stripping (e.g., `v1.2.3` -> `1.2.3`)
9+
- Optional GitHub token for private repos or higher rate limits
10+
- Support for GitHub Enterprise via custom API URL
11+
- Works with `jq`/`jaq` for robust JSON parsing, falls back to basic shell parsing
12+
13+
## Requirements
14+
15+
- `curl` (standard on most systems)
16+
- `jq` or `jaq` (recommended, but not required)
17+
18+
## Installation
19+
20+
Install directly from the sley repository:
21+
22+
```bash
23+
sley extension install --url github.com/indaco/sley/contrib/extensions/github-version-sync
24+
```
25+
26+
Or from a local clone:
27+
28+
```bash
29+
sley extension install --path ./contrib/extensions/github-version-sync
30+
```
31+
32+
## Configuration
33+
34+
Add to your `.sley.yaml`. Extension settings are defined under the `config` key:
35+
36+
```yaml
37+
extensions:
38+
- name: github-version-sync
39+
path: .sley-extensions/github-version-sync
40+
enabled: true
41+
config:
42+
# Required: GitHub repository in "owner/repo" format
43+
repo: owner/repo
44+
45+
# Optional: Prefix to strip from tag (default: "v")
46+
strip-prefix: v
47+
48+
# Optional: GitHub token for private repos or rate limits
49+
github-token: ""
50+
51+
# Optional: GitHub API URL for Enterprise (default: "https://api.github.com")
52+
api-url: https://api.github.com
53+
```
54+
55+
### Configuration Options
56+
57+
All configuration options are specified under the `config` key and passed to the hook script as JSON:
58+
59+
- **`repo`** (required): GitHub repository in "owner/repo" format
60+
- **`strip-prefix`** (optional): Prefix to strip from tag names (default: `"v"`)
61+
- **`github-token`** (optional): GitHub token for private repos or higher rate limits
62+
- **`api-url`** (optional): GitHub API URL for Enterprise instances (default: `"https://api.github.com"`)
63+
64+
When using this extension, set `commit-parser: false` in your config. The extension sets the definitive version - no additional bump should be applied.
65+
66+
```yaml
67+
plugins:
68+
commit-parser: false # Let the extension control the version
69+
```
70+
71+
## Examples
72+
73+
### Basic Usage
74+
75+
Sync to a public repository:
76+
77+
```yaml
78+
plugins:
79+
commit-parser: false
80+
tag-manager:
81+
enabled: true
82+
83+
extensions:
84+
- name: github-version-sync
85+
path: .sley-extensions/github-version-sync
86+
enabled: true
87+
config:
88+
repo: indaco/sley
89+
```
90+
91+
```bash
92+
# Fetches latest sley release (e.g., v0.9.0)
93+
# Updates .version to 0.9.0
94+
sley bump auto
95+
```
96+
97+
### With GitHub Token
98+
99+
For private repositories or to avoid rate limits:
100+
101+
```yaml
102+
extensions:
103+
- name: github-version-sync
104+
path: .sley-extensions/github-version-sync
105+
enabled: true
106+
config:
107+
repo: myorg/private-repo
108+
github-token: "${GITHUB_TOKEN}" # Use environment variable
109+
```
110+
111+
### GitHub Enterprise
112+
113+
```yaml
114+
extensions:
115+
- name: github-version-sync
116+
path: .sley-extensions/github-version-sync
117+
enabled: true
118+
config:
119+
repo: myorg/myrepo
120+
api-url: https://github.mycompany.com/api/v3
121+
github-token: "${GHE_TOKEN}"
122+
```
123+
124+
### Custom Tag Format
125+
126+
If the upstream repo uses tags without `v` prefix:
127+
128+
```yaml
129+
extensions:
130+
- name: github-version-sync
131+
path: .sley-extensions/github-version-sync
132+
enabled: true
133+
config:
134+
repo: some/repo
135+
strip-prefix: "" # Don't strip any prefix
136+
```
137+
138+
### Documentation Site Workflow
139+
140+
Complete example for a docs site tracking a library:
141+
142+
```yaml
143+
# .sley.yaml
144+
path: .version
145+
146+
plugins:
147+
commit-parser: false
148+
tag-manager:
149+
enabled: true
150+
dependency-check:
151+
enabled: true
152+
auto-sync: true
153+
files:
154+
- path: package.json
155+
field: version
156+
format: json
157+
158+
extensions:
159+
- name: github-version-sync
160+
path: .sley-extensions/github-version-sync
161+
enabled: true
162+
config:
163+
repo: indaco/sley
164+
```
165+
166+
```bash
167+
# Sync docs version to latest sley release
168+
sley bump auto
169+
# 1. Fetches latest sley release (v0.9.0)
170+
# 2. Updates .version to 0.9.0
171+
# 3. Syncs package.json version
172+
# 4. Creates git tag v0.9.0
173+
```
174+
175+
## How It Works
176+
177+
1. Pre-bump hook receives the current project state
178+
2. Extension fetches the latest release from the configured GitHub repo
179+
3. Extracts the tag name and strips the configured prefix
180+
4. Writes the version to the `.version` file
181+
5. sley detects the change and uses this version (no additional bump applied)
182+
183+
## Error Handling
184+
185+
The extension will fail (and block the bump) if:
186+
187+
- The GitHub API request fails
188+
- The repository is not found or has no releases
189+
- Rate limit is exceeded (hint: use `github-token`)
190+
- The `.version` file cannot be written
191+
192+
## Troubleshooting
193+
194+
### "GitHub API rate limit exceeded"
195+
196+
GitHub limits unauthenticated requests to 60/hour. Set a token in your extension config:
197+
198+
```yaml
199+
extensions:
200+
- name: github-version-sync
201+
path: .sley-extensions/github-version-sync
202+
enabled: true
203+
config:
204+
repo: owner/repo
205+
github-token: "${GITHUB_TOKEN}"
206+
```
207+
208+
Create a token at: https://github.com/settings/tokens
209+
210+
### "Repository not found or no releases"
211+
212+
- Check the repo name is correct (`owner/repo` format)
213+
- Ensure the repository has at least one release (not just tags)
214+
- For private repos, ensure the token has `repo` scope
215+
216+
### "Version not changing"
217+
218+
Ensure `commit-parser: false` is set. Otherwise, sley may recalculate and override the version.
219+
220+
### Using with jq/jaq vs without
221+
222+
The extension works best with `jq` or `jaq` (a Rust alternative) installed for robust JSON parsing:
223+
224+
```bash
225+
# jq
226+
brew install jq # macOS
227+
apt-get install jq # Ubuntu/Debian
228+
apk add jq # Alpine
229+
230+
# jaq (Rust alternative)
231+
brew install jaq # macOS
232+
cargo install jaq # via Cargo
233+
```
234+
235+
Without `jq` or `jaq`, basic shell parsing is used (works for simple cases).
236+
237+
## Use Cases
238+
239+
- Documentation sites tracking a library's version
240+
- Projects that need to stay in sync with an upstream dependency
241+
- Monorepos where one package tracks another's release
242+
243+
## See Also
244+
245+
- [Extensions Overview](https://sley.indaco.dev/extensions/) - How extensions work
246+
- [dependency-check plugin](https://sley.indaco.dev/plugins/dependency-check) - Sync version to package.json
247+
- [tag-manager plugin](https://sley.indaco.dev/plugins/tag-manager) - Git tag automation

‎contrib/extensions/github-version-sync/extension.yaml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
name: github-version-sync
2+
version: 1.0.0
3+
description: Syncs the .version file to the latest release from a GitHub repository
4+
author: sley
5+
repository: https://github.com/indaco/sley/tree/main/contrib/extensions/github-version-sync
6+
entry: hook.sh
7+
hooks:
8+
- pre-bump

0 commit comments

Comments
 (0)