detached 3433b85

docs: add setup-gordon action implementation plan

commit
3433b85fe9c965c2f262f32ce20418bb6f2b12f9
author
brice · · 2026-03-19 04:24 UTC
parent
1c96035
signature
unsigned
1 file · +184 -0
Unified
UnifiedSplit
A docs/superpowers/plans/2026-03-19-setup-gordon-action.md +184 -0
@@ -0,0 +1,184 @@
1+# setup-gordon Action Implementation Plan
2+
3+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
4+
5+**Goal:** Create a composite GitHub Action that installs the Gordon CLI binary into the runner's PATH.
6+
7+**Architecture:** Single composite action with a shell script that detects OS/arch, downloads the correct release archive, extracts the binary, and verifies it works. Documentation updated to reference the action.
8+
9+**Tech Stack:** GitHub Actions composite, bash, curl, tar
10+
11+---
12+
13+### Task 1: Create the setup-gordon composite action
14+
15+**Files:**
16+- Create: `.github/actions/setup-gordon/action.yml`
17+
18+**Context:**
19+- Official releases are `.tar.gz` archives: `gordon_{os}_{arch}.tar.gz` (e.g. `gordon_linux_amd64.tar.gz`)
20+- Archives contain a single `gordon` binary at root
21+- Release URL pattern: `https://github.com/bnema/gordon/releases/download/{tag}/gordon_{os}_{arch}.tar.gz`
22+- Latest release tag can be resolved via: `gh release view --json tagName -q .tagName` or curl redirect on `/releases/latest`
23+- Supported OS: linux, darwin. Supported arch: amd64, arm64.
24+- Runner arch mapping: `X64` → `amd64`, `ARM64` → `arm64`
25+
26+- [ ] **Step 1: Create action.yml**
27+
28+```yaml
29+name: 'Setup Gordon'
30+description: 'Install the Gordon CLI binary into the runner PATH'
31+author: 'Gordon Contributors'
32+
33+branding:
34+ icon: 'download-cloud'
35+ color: 'blue'
36+
37+inputs:
38+ version:
39+ description: 'Gordon version to install (e.g. "v2.0.0" or "latest")'
40+ required: false
41+ default: 'latest'
42+
43+outputs:
44+ version:
45+ description: 'The version that was installed'
46+ value: ${{ steps.install.outputs.version }}
47+ path:
48+ description: 'Path to the installed binary'
49+ value: ${{ steps.install.outputs.path }}
50+
51+runs:
52+ using: 'composite'
53+ steps:
54+ - name: Install Gordon CLI
55+ id: install
56+ shell: bash
57+ run: |
58+ set -euo pipefail
59+
60+ # Determine OS
61+ case "$RUNNER_OS" in
62+ Linux) OS="linux" ;;
63+ macOS) OS="darwin" ;;
64+ *) echo "::error::Unsupported OS: $RUNNER_OS"; exit 1 ;;
65+ esac
66+
67+ # Determine architecture
68+ case "$RUNNER_ARCH" in
69+ X64) ARCH="amd64" ;;
70+ ARM64) ARCH="arm64" ;;
71+ *) echo "::error::Unsupported architecture: $RUNNER_ARCH"; exit 1 ;;
72+ esac
73+
74+ # Resolve version
75+ VERSION="${{ inputs.version }}"
76+ if [[ "$VERSION" == "latest" ]]; then
77+ VERSION=$(curl -fsSL -o /dev/null -w '%{redirect_url}' "https://github.com/bnema/gordon/releases/latest" | grep -oP '[^/]+$')
78+ if [[ -z "$VERSION" ]]; then
79+ echo "::error::Failed to resolve latest Gordon version"
80+ exit 1
81+ fi
82+ fi
83+
84+ echo "Installing Gordon ${VERSION} (${OS}/${ARCH})..."
85+
86+ # Download and extract
87+ ARCHIVE="gordon_${OS}_${ARCH}.tar.gz"
88+ URL="https://github.com/bnema/gordon/releases/download/${VERSION}/${ARCHIVE}"
89+ INSTALL_DIR="/usr/local/bin"
90+
91+ curl -fsSL "$URL" -o "/tmp/${ARCHIVE}"
92+ tar -xzf "/tmp/${ARCHIVE}" -C "$INSTALL_DIR" gordon
93+ chmod +x "${INSTALL_DIR}/gordon"
94+ rm -f "/tmp/${ARCHIVE}"
95+
96+ # Verify
97+ INSTALLED_VERSION=$("${INSTALL_DIR}/gordon" version 2>&1 || echo "unknown")
98+ echo "Gordon installed: ${INSTALLED_VERSION}"
99+
100+ # Set outputs
101+ echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
102+ echo "path=${INSTALL_DIR}/gordon" >> "$GITHUB_OUTPUT"
103+```
104+
105+- [ ] **Step 2: Commit**
106+
107+```bash
108+git add .github/actions/setup-gordon/action.yml
109+git commit -m "feat: add setup-gordon composite GitHub Action"
110+```
111+
112+---
113+
114+### Task 2: Update GitHub Actions deployment documentation
115+
116+**Files:**
117+- Modify: `docs/deployment/github-actions.md`
118+
119+**Context:**
120+- Replace all manual `curl + chmod` install blocks with `uses: bnema/gordon/.github/actions/setup-gordon@main`
121+- Keep the rest of each workflow identical (checkout, build-and-deploy steps, env vars)
122+- Add a dedicated section documenting the action inputs/outputs
123+- All examples must use `${{ secrets.GORDON_REMOTE }}` for the remote URL
124+
125+- [ ] **Step 1: Replace "Install Gordon Binary" section (lines 37-46)**
126+
127+Replace the manual curl instructions with:
128+
129+```markdown
130+### 3. Setup Gordon CLI
131+
132+Add this step to your workflow to install the Gordon binary:
133+
134+\```yaml
135+- name: Setup Gordon
136+ uses: bnema/gordon/.github/actions/setup-gordon@main
137+ # with:
138+ # version: latest # optional, default: latest
139+\```
140+```
141+
142+- [ ] **Step 2: Update "Deploy on Tag Push" example (lines 54-79)**
143+
144+Replace the `Install Gordon` step with the setup-gordon action step.
145+
146+- [ ] **Step 3: Update "Continuous Deploy on Main" example (lines 85-114)**
147+
148+Replace the `Install Gordon` step with the setup-gordon action step.
149+
150+- [ ] **Step 4: Update "Manual Dispatch" example (lines 120-152)**
151+
152+Replace the `Install Gordon` step with the setup-gordon action step.
153+
154+- [ ] **Step 5: Update "Monorepo" example (lines 158-195)**
155+
156+Replace the `Install Gordon` step with the setup-gordon action step.
157+
158+- [ ] **Step 6: Add setup-gordon Action Reference section**
159+
160+After the "Recommended: gordon push" section and before "Alternative: Docker-based Workflow", add:
161+
162+```markdown
163+### setup-gordon Action Reference
164+
165+#### Inputs
166+
167+| Input | Required | Default | Description |
168+|-------|----------|---------|-------------|
169+| `version` | No | `latest` | Gordon version to install (`v2.0.0`, `latest`) |
170+
171+#### Outputs
172+
173+| Output | Description |
174+|--------|-------------|
175+| `version` | The version actually installed |
176+| `path` | Path to the installed binary |
177+```
178+
179+- [ ] **Step 7: Commit**
180+
181+```bash
182+git add docs/deployment/github-actions.md
183+git commit -m "docs: update GitHub Actions guide to use setup-gordon action"
184+```
@@ -0,0 +1,184 @@
1+# setup-gordon Action Implementation Plan
2+
3+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
4+
5+**Goal:** Create a composite GitHub Action that installs the Gordon CLI binary into the runner's PATH.
6+
7+**Architecture:** Single composite action with a shell script that detects OS/arch, downloads the correct release archive, extracts the binary, and verifies it works. Documentation updated to reference the action.
8+
9+**Tech Stack:** GitHub Actions composite, bash, curl, tar
10+
11+---
12+
13+### Task 1: Create the setup-gordon composite action
14+
15+**Files:**
16+- Create: `.github/actions/setup-gordon/action.yml`
17+
18+**Context:**
19+- Official releases are `.tar.gz` archives: `gordon_{os}_{arch}.tar.gz` (e.g. `gordon_linux_amd64.tar.gz`)
20+- Archives contain a single `gordon` binary at root
21+- Release URL pattern: `https://github.com/bnema/gordon/releases/download/{tag}/gordon_{os}_{arch}.tar.gz`
22+- Latest release tag can be resolved via: `gh release view --json tagName -q .tagName` or curl redirect on `/releases/latest`
23+- Supported OS: linux, darwin. Supported arch: amd64, arm64.
24+- Runner arch mapping: `X64` → `amd64`, `ARM64` → `arm64`
25+
26+- [ ] **Step 1: Create action.yml**
27+
28+```yaml
29+name: 'Setup Gordon'
30+description: 'Install the Gordon CLI binary into the runner PATH'
31+author: 'Gordon Contributors'
32+
33+branding:
34+ icon: 'download-cloud'
35+ color: 'blue'
36+
37+inputs:
38+ version:
39+ description: 'Gordon version to install (e.g. "v2.0.0" or "latest")'
40+ required: false
41+ default: 'latest'
42+
43+outputs:
44+ version:
45+ description: 'The version that was installed'
46+ value: ${{ steps.install.outputs.version }}
47+ path:
48+ description: 'Path to the installed binary'
49+ value: ${{ steps.install.outputs.path }}
50+
51+runs:
52+ using: 'composite'
53+ steps:
54+ - name: Install Gordon CLI
55+ id: install
56+ shell: bash
57+ run: |
58+ set -euo pipefail
59+
60+ # Determine OS
61+ case "$RUNNER_OS" in
62+ Linux) OS="linux" ;;
63+ macOS) OS="darwin" ;;
64+ *) echo "::error::Unsupported OS: $RUNNER_OS"; exit 1 ;;
65+ esac
66+
67+ # Determine architecture
68+ case "$RUNNER_ARCH" in
69+ X64) ARCH="amd64" ;;
70+ ARM64) ARCH="arm64" ;;
71+ *) echo "::error::Unsupported architecture: $RUNNER_ARCH"; exit 1 ;;
72+ esac
73+
74+ # Resolve version
75+ VERSION="${{ inputs.version }}"
76+ if [[ "$VERSION" == "latest" ]]; then
77+ VERSION=$(curl -fsSL -o /dev/null -w '%{redirect_url}' "https://github.com/bnema/gordon/releases/latest" | grep -oP '[^/]+$')
78+ if [[ -z "$VERSION" ]]; then
79+ echo "::error::Failed to resolve latest Gordon version"
80+ exit 1
81+ fi
82+ fi
83+
84+ echo "Installing Gordon ${VERSION} (${OS}/${ARCH})..."
85+
86+ # Download and extract
87+ ARCHIVE="gordon_${OS}_${ARCH}.tar.gz"
88+ URL="https://github.com/bnema/gordon/releases/download/${VERSION}/${ARCHIVE}"
89+ INSTALL_DIR="/usr/local/bin"
90+
91+ curl -fsSL "$URL" -o "/tmp/${ARCHIVE}"
92+ tar -xzf "/tmp/${ARCHIVE}" -C "$INSTALL_DIR" gordon
93+ chmod +x "${INSTALL_DIR}/gordon"
94+ rm -f "/tmp/${ARCHIVE}"
95+
96+ # Verify
97+ INSTALLED_VERSION=$("${INSTALL_DIR}/gordon" version 2>&1 || echo "unknown")
98+ echo "Gordon installed: ${INSTALLED_VERSION}"
99+
100+ # Set outputs
101+ echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
102+ echo "path=${INSTALL_DIR}/gordon" >> "$GITHUB_OUTPUT"
103+```
104+
105+- [ ] **Step 2: Commit**
106+
107+```bash
108+git add .github/actions/setup-gordon/action.yml
109+git commit -m "feat: add setup-gordon composite GitHub Action"
110+```
111+
112+---
113+
114+### Task 2: Update GitHub Actions deployment documentation
115+
116+**Files:**
117+- Modify: `docs/deployment/github-actions.md`
118+
119+**Context:**
120+- Replace all manual `curl + chmod` install blocks with `uses: bnema/gordon/.github/actions/setup-gordon@main`
121+- Keep the rest of each workflow identical (checkout, build-and-deploy steps, env vars)
122+- Add a dedicated section documenting the action inputs/outputs
123+- All examples must use `${{ secrets.GORDON_REMOTE }}` for the remote URL
124+
125+- [ ] **Step 1: Replace "Install Gordon Binary" section (lines 37-46)**
126+
127+Replace the manual curl instructions with:
128+
129+```markdown
130+### 3. Setup Gordon CLI
131+
132+Add this step to your workflow to install the Gordon binary:
133+
134+\```yaml
135+- name: Setup Gordon
136+ uses: bnema/gordon/.github/actions/setup-gordon@main
137+ # with:
138+ # version: latest # optional, default: latest
139+\```
140+```
141+
142+- [ ] **Step 2: Update "Deploy on Tag Push" example (lines 54-79)**
143+
144+Replace the `Install Gordon` step with the setup-gordon action step.
145+
146+- [ ] **Step 3: Update "Continuous Deploy on Main" example (lines 85-114)**
147+
148+Replace the `Install Gordon` step with the setup-gordon action step.
149+
150+- [ ] **Step 4: Update "Manual Dispatch" example (lines 120-152)**
151+
152+Replace the `Install Gordon` step with the setup-gordon action step.
153+
154+- [ ] **Step 5: Update "Monorepo" example (lines 158-195)**
155+
156+Replace the `Install Gordon` step with the setup-gordon action step.
157+
158+- [ ] **Step 6: Add setup-gordon Action Reference section**
159+
160+After the "Recommended: gordon push" section and before "Alternative: Docker-based Workflow", add:
161+
162+```markdown
163+### setup-gordon Action Reference
164+
165+#### Inputs
166+
167+| Input | Required | Default | Description |
168+|-------|----------|---------|-------------|
169+| `version` | No | `latest` | Gordon version to install (`v2.0.0`, `latest`) |
170+
171+#### Outputs
172+
173+| Output | Description |
174+|--------|-------------|
175+| `version` | The version actually installed |
176+| `path` | Path to the installed binary |
177+```
178+
179+- [ ] **Step 7: Commit**
180+
181+```bash
182+git add docs/deployment/github-actions.md
183+git commit -m "docs: update GitHub Actions guide to use setup-gordon action"
184+```

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. Elsewhere: into the side panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 7

Tags 106

↑↓ moveenter openesc close