Skip to content

Commit 76d151c

Browse files
xuezhaojunxuezhaojun
committed
release: add CI workflow, Makefile, README, and bump opencode-slack-plugin to v0.1.1
- Add GitHub Actions workflow for automated npm publish via OIDC trusted publishing - Add Makefile with build, typecheck, publish, and release targets - Add repo-level README with plugin list, quick start, and release instructions - Update AGENTS.md with release process documentation - Rename package to @kubeopencode/opencode-slack-plugin - Bump version to 0.1.1 Signed-off-by: xuezhaojun <xuezhaokeepgoing@gmail.com>
1 parent 349668f commit 76d151c

7 files changed

Lines changed: 324 additions & 17 deletions

File tree

‎.github/workflows/publish.yaml‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
name: Publish to npm
2+
3+
on:
4+
push:
5+
tags:
6+
# e.g. opencode-slack-plugin/v0.1.0
7+
- "*/v*"
8+
9+
permissions:
10+
contents: read
11+
id-token: write # Required for npm OIDC trusted publishing
12+
13+
jobs:
14+
publish:
15+
runs-on: ubuntu-latest
16+
environment: release
17+
steps:
18+
- uses: actions/checkout@v4
19+
20+
- uses: actions/setup-node@v4
21+
with:
22+
# Node 24 ships with npm 11.5.1+ which is required for OIDC trusted publishing
23+
node-version: "24"
24+
registry-url: "https://registry.npmjs.org"
25+
26+
# Extract plugin directory from tag (e.g. "opencode-slack-plugin/v0.1.0" -> "opencode-slack-plugin")
27+
- name: Determine plugin directory
28+
id: meta
29+
run: |
30+
TAG="${GITHUB_REF#refs/tags/}"
31+
PLUGIN_DIR="${TAG%/v*}"
32+
VERSION="${TAG#*/v}"
33+
echo "plugin_dir=${PLUGIN_DIR}" >> "$GITHUB_OUTPUT"
34+
echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
35+
echo "Publishing ${PLUGIN_DIR} v${VERSION}"
36+
37+
- name: Install dependencies
38+
working-directory: ${{ steps.meta.outputs.plugin_dir }}
39+
run: npm ci
40+
41+
- name: Typecheck
42+
working-directory: ${{ steps.meta.outputs.plugin_dir }}
43+
run: npm run typecheck
44+
45+
- name: Build
46+
working-directory: ${{ steps.meta.outputs.plugin_dir }}
47+
run: npm run build
48+
49+
- name: Verify version matches tag
50+
working-directory: ${{ steps.meta.outputs.plugin_dir }}
51+
run: |
52+
PKG_VERSION=$(node -p "require('./package.json').version")
53+
TAG_VERSION="${{ steps.meta.outputs.version }}"
54+
if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
55+
echo "::error::package.json version ($PKG_VERSION) does not match tag version ($TAG_VERSION)"
56+
exit 1
57+
fi
58+
59+
# No NPM_TOKEN needed — OIDC trusted publishing handles authentication
60+
- name: Publish to npm
61+
working-directory: ${{ steps.meta.outputs.plugin_dir }}
62+
run: npm publish --access public

‎AGENTS.md‎

Lines changed: 74 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -186,24 +186,35 @@ Both can also be set in `opencode.json`:
186186

187187
```
188188
kubeopencode-plugins/
189-
AGENTS.md # This file
190-
opencode-slack-plugin/ # Slack Socket Mode integration
191-
src/index.ts # Plugin source
192-
package.json # npm package config
189+
README.md # Project overview and quick start
190+
AGENTS.md # This file (AI agent dev guidelines)
191+
Makefile # Build and release targets
192+
.github/workflows/publish.yaml # CI: automated npm publish on tag
193+
opencode-slack-plugin/ # Slack Socket Mode integration
194+
src/index.ts # Plugin source
195+
package.json # npm package config (@kubeopencode scope)
193196
tsconfig.json
194-
dist/ # Built output (tsup)
195-
README.md # Setup instructions
197+
dist/ # Built output (tsup)
198+
README.md # Setup instructions
196199
```
197200
198201
## Development
199202
200203
### Building a Plugin
201204
205+
Use the Makefile at the repo root:
206+
207+
```bash
208+
make install # npm install
209+
make typecheck # tsc --noEmit
210+
make build # tsup -> dist/
211+
make clean # remove dist/
212+
```
213+
214+
To target a specific plugin (when multiple plugins exist):
215+
202216
```bash
203-
cd opencode-slack-plugin
204-
npm install
205-
npm run typecheck # tsc --noEmit
206-
npm run build # tsup -> dist/
217+
make build PLUGIN_DIR=opencode-slack-plugin
207218
```
208219

209220
### Testing Locally
@@ -233,13 +244,65 @@ metadata:
233244
name: my-agent
234245
spec:
235246
plugins:
236-
- name: "opencode-slack-plugin"
247+
- name: "@kubeopencode/opencode-slack-plugin"
237248
credentials:
238249
- secretRef:
239250
name: slack-credentials
240251
# ...
241252
```
242253

254+
## Release Process
255+
256+
Releases are automated via GitHub Actions using **npm OIDC Trusted Publishing**. No npm tokens or secrets are required — authentication uses short-lived OIDC credentials tied to the specific workflow.
257+
258+
### How to release a plugin
259+
260+
1. **Bump the version** in the plugin's `package.json`:
261+
262+
```bash
263+
cd opencode-slack-plugin
264+
npm version patch # or minor / major
265+
```
266+
267+
2. **Commit and push** the version bump:
268+
269+
```bash
270+
git add -A
271+
git commit -s -m "release: opencode-slack-plugin v0.1.1"
272+
git push origin main
273+
```
274+
275+
3. **Tag and push** to trigger CI:
276+
277+
```bash
278+
make release # reads version from package.json, creates and pushes tag
279+
```
280+
281+
The tag format is `<plugin-dir>/v<version>` (e.g. `opencode-slack-plugin/v0.1.0`). This supports independent versioning per plugin.
282+
283+
### What CI does
284+
285+
The `.github/workflows/publish.yaml` workflow:
286+
287+
1. Extracts the plugin directory and version from the git tag
288+
2. Runs `npm ci` → `typecheck` → `build`
289+
3. Verifies `package.json` version matches the tag version
290+
4. Publishes to npm with OIDC authentication and provenance attestation
291+
292+
### First-time setup for a new plugin
293+
294+
OIDC Trusted Publishing requires the package to already exist on npm:
295+
296+
1. Publish v0.1.0 manually: `npm login && make publish PLUGIN_DIR=my-new-plugin`
297+
2. On npmjs.com, go to the package settings and add a Trusted Publisher:
298+
- Owner: `kubeopencode`, Repository: `kubeopencode-plugins`
299+
- Workflow: `publish.yaml`, Environment: `release`
300+
3. Ensure the `release` environment exists in the GitHub repo settings
301+
302+
### npm package naming
303+
304+
All plugins are published under the `@kubeopencode` npm scope (e.g. `@kubeopencode/opencode-slack-plugin`). The `package.json` `name` field must use this scoped format.
305+
243306
## Style Guide
244307

245308
- TypeScript, ESM (`"type": "module"`)

‎Makefile‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# kubeopencode-plugins Makefile
2+
3+
PLUGIN_DIR := opencode-slack-plugin
4+
5+
.PHONY: install build typecheck clean publish publish-dry release
6+
7+
## Install dependencies
8+
install:
9+
cd $(PLUGIN_DIR) && npm install
10+
11+
## Type-check without emitting
12+
typecheck:
13+
cd $(PLUGIN_DIR) && npm run typecheck
14+
15+
## Build the plugin (tsup -> dist/)
16+
build:
17+
cd $(PLUGIN_DIR) && npm run build
18+
19+
## Remove build artifacts
20+
clean:
21+
rm -rf $(PLUGIN_DIR)/dist
22+
23+
## Dry-run publish (verify what will be published)
24+
publish-dry: build
25+
cd $(PLUGIN_DIR) && npm publish --access public --dry-run
26+
27+
## Publish to npm under @kubeopencode scope (manual)
28+
publish: build
29+
cd $(PLUGIN_DIR) && npm publish --access public
30+
31+
## Tag and push to trigger automated publish via GitHub Actions
32+
## Usage: make release PLUGIN_DIR=opencode-slack-plugin
33+
release:
34+
@VERSION=$$(cd $(PLUGIN_DIR) && node -p "require('./package.json').version") && \
35+
TAG="$(PLUGIN_DIR)/v$$VERSION" && \
36+
echo "Creating tag: $$TAG" && \
37+
git tag -a "$$TAG" -m "Release $(PLUGIN_DIR) v$$VERSION" && \
38+
git push origin "$$TAG"

‎README.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# kubeopencode-plugins
2+
3+
First-party plugins for [KubeOpenCode](https://github.com/kubeopencode/kubeopencode) — a Kubernetes-native AI Agent Platform built on [OpenCode](https://opencode.ai).
4+
5+
Each plugin is an independent npm package published under the `@kubeopencode` scope. Plugins follow the [OpenCode plugin API](https://opencode.ai/docs) and can be installed into any KubeOpenCode Agent via `spec.plugins`.
6+
7+
## Plugins
8+
9+
| Plugin | npm | Description |
10+
|--------|-----|-------------|
11+
| [opencode-slack-plugin](./opencode-slack-plugin/) | [`@kubeopencode/opencode-slack-plugin`](https://www.npmjs.com/package/@kubeopencode/opencode-slack-plugin) | Slack Socket Mode integration — chat with your Agent from Slack threads |
12+
13+
## Quick Start
14+
15+
### Install in KubeOpenCode
16+
17+
Declare the plugin in your Agent spec:
18+
19+
```yaml
20+
apiVersion: kubeopencode.io/v1alpha1
21+
kind: Agent
22+
metadata:
23+
name: my-agent
24+
spec:
25+
plugins:
26+
- name: "@kubeopencode/opencode-slack-plugin"
27+
target: server
28+
credentials:
29+
- secretRef:
30+
name: slack-credentials
31+
```
32+
33+
### Install in standalone OpenCode
34+
35+
Add to your `opencode.json`:
36+
37+
```json
38+
{
39+
"plugin": ["@kubeopencode/opencode-slack-plugin"]
40+
}
41+
```
42+
43+
## Development
44+
45+
### Prerequisites
46+
47+
- Node.js >= 22
48+
- npm
49+
50+
### Build
51+
52+
```bash
53+
make install # install dependencies
54+
make typecheck # type-check (tsc --noEmit)
55+
make build # build (tsup -> dist/)
56+
```
57+
58+
### Build a specific plugin
59+
60+
```bash
61+
make build PLUGIN_DIR=opencode-slack-plugin
62+
```
63+
64+
## Release
65+
66+
Releases are automated via GitHub Actions using [npm OIDC Trusted Publishing](https://docs.npmjs.com/trusted-publishers/) — no npm tokens required.
67+
68+
### Publishing a new version
69+
70+
1. Update the version in the plugin's `package.json`:
71+
72+
```bash
73+
cd opencode-slack-plugin
74+
npm version patch # or minor / major
75+
```
76+
77+
2. Commit and push:
78+
79+
```bash
80+
git add -A
81+
git commit -s -m "release: opencode-slack-plugin v0.1.1"
82+
git push origin main
83+
```
84+
85+
3. Tag and push to trigger CI:
86+
87+
```bash
88+
make release # or: make release PLUGIN_DIR=opencode-slack-plugin
89+
```
90+
91+
This creates a git tag `opencode-slack-plugin/v0.1.1` and pushes it. GitHub Actions will automatically build, verify, and publish to npm with provenance.
92+
93+
### Tag format
94+
95+
Tags follow the pattern `<plugin-dir>/v<version>`, e.g. `opencode-slack-plugin/v0.1.0`. This supports independent versioning when more plugins are added.
96+
97+
### First-time setup for a new plugin
98+
99+
OIDC Trusted Publishing requires the package to already exist on npm. For a brand-new plugin:
100+
101+
1. Publish the first version manually:
102+
103+
```bash
104+
npm login
105+
make publish PLUGIN_DIR=my-new-plugin
106+
```
107+
108+
2. Configure Trusted Publisher on [npmjs.com](https://www.npmjs.com):
109+
- Go to the package settings > Trusted Publisher
110+
- Owner: `kubeopencode`
111+
- Repository: `kubeopencode-plugins`
112+
- Workflow: `publish.yaml`
113+
- Environment: `release`
114+
115+
3. Create a `release` environment in GitHub repo settings (if not already done).
116+
117+
After this one-time setup, all subsequent releases are fully automated.
118+
119+
## Repository Structure
120+
121+
```
122+
kubeopencode-plugins/
123+
README.md # This file
124+
AGENTS.md # AI agent development guidelines
125+
Makefile # Build and release targets
126+
.github/workflows/publish.yaml # CI: automated npm publish on tag
127+
opencode-slack-plugin/ # Slack Socket Mode plugin
128+
src/index.ts
129+
package.json
130+
tsconfig.json
131+
dist/
132+
README.md
133+
```
134+
135+
## Contributing
136+
137+
1. Each plugin lives in its own directory at the repo root
138+
2. Use TypeScript with ESM (`"type": "module"`)
139+
3. Use `@opencode-ai/plugin` as a peer dependency
140+
4. See [AGENTS.md](./AGENTS.md) for detailed plugin architecture and conventions
141+
142+
## License
143+
144+
MIT

‎opencode-slack-plugin/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,13 +46,13 @@ Your machine (MacBook / Linux / K8s Pod)
4646

4747
### 2. Install the Plugin
4848

49-
#### From npm (once published)
49+
#### From npm
5050

5151
Add to your `opencode.json`:
5252

5353
```json
5454
{
55-
"plugin": ["opencode-slack-plugin"]
55+
"plugin": ["@kubeopencode/opencode-slack-plugin"]
5656
}
5757
```
5858

‎opencode-slack-plugin/package-lock.json‎

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎opencode-slack-plugin/package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
2-
"name": "opencode-slack-plugin",
3-
"version": "0.1.0",
2+
"name": "@kubeopencode/opencode-slack-plugin",
3+
"version": "0.1.1",
44
"type": "module",
55
"license": "MIT",
66
"description": "OpenCode plugin that connects to Slack via Socket Mode — zero port exposure, runs inside your OpenCode process",

0 commit comments

Comments
 (0)