Skip to content

Commit 9f6be66

Browse files
macayavenmacayaven
authored
Merge pull request #3 from macayaven/feature/npm-packages-for-fork
Feature/npm packages for fork
2 parents 7231a22 + f3d074a commit 9f6be66

File tree

23 files changed

+2234
-48
lines changed

23 files changed

+2234
-48
lines changed

‎.github/workflows/publish-npm.yml‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
name: Publish to NPM
2+
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
registry:
7+
description: 'Choose NPM registry'
8+
required: true
9+
default: 'public'
10+
type: choice
11+
options:
12+
- public
13+
- github-packages
14+
suffix:
15+
description: 'Package suffix (e.g., openshift-ai)'
16+
required: true
17+
default: 'openshift-ai'
18+
type: string
19+
20+
jobs:
21+
publish:
22+
runs-on: ubuntu-latest
23+
permissions:
24+
contents: read
25+
packages: write
26+
27+
steps:
28+
- name: Checkout
29+
uses: actions/checkout@v4
30+
with:
31+
fetch-depth: 0
32+
33+
- name: Setup Node.js
34+
uses: actions/setup-node@v4
35+
with:
36+
node-version: '20'
37+
registry-url: ${{ steps.registry.outputs.url }}
38+
39+
- name: Setup Go
40+
uses: actions/setup-go@v5
41+
with:
42+
go-version: '1.24'
43+
44+
- name: Configure registry
45+
id: registry
46+
run: |
47+
if [ "${{ github.event.inputs.registry }}" = "github-packages" ]; then
48+
echo "url=https://npm.pkg.github.com/" >> $GITHUB_OUTPUT
49+
echo "scope=@macayaven" >> $GITHUB_OUTPUT
50+
echo "config=//npm.pkg.github.com/:_authToken=${{ secrets.GITHUB_TOKEN }}" >> $GITHUB_OUTPUT
51+
else
52+
echo "url=https://registry.npmjs.org/" >> $GITHUB_OUTPUT
53+
echo "scope=" >> $GITHUB_OUTPUT
54+
echo "config=//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" >> $GITHUB_OUTPUT
55+
fi
56+
57+
- name: Get version
58+
id: version
59+
run: |
60+
VERSION=$(git describe --tags --always --dirty)
61+
echo "version=$VERSION" >> $GITHUB_OUTPUT
62+
echo "npm_version=$(echo $VERSION | sed 's/^v//')" >> $GITHUB_OUTPUT
63+
64+
- name: Prepare packages
65+
run: |
66+
chmod +x ./prepare-fork-npm.sh
67+
./prepare-fork-npm.sh "${{ github.event.inputs.suffix }}"
68+
69+
- name: Update versions
70+
run: |
71+
find npm -name "package.json" -exec sed -i 's/"version": ".*"/"version": "${{ steps.version.outputs.npm_version }}"/' {} \;
72+
73+
- name: Build
74+
run: |
75+
make build-all-platforms
76+
77+
- name: Copy binaries
78+
run: |
79+
make npm-copy-binaries
80+
81+
- name: Setup .npmrc
82+
run: |
83+
cat > ~/.npmrc << EOF
84+
${{ steps.registry.outputs.config }}
85+
EOF
86+
87+
- name: Publish platform packages
88+
run: |
89+
set -e
90+
91+
platforms=("darwin-amd64" "darwin-arm64" "linux-amd64" "linux-arm64" "windows-amd64" "windows-arm64")
92+
93+
for platform in "${platforms[@]}"; do
94+
package_name="kubernetes-mcp-server-${{ github.event.inputs.suffix }}-$platform"
95+
echo "📦 Publishing $package_name..."
96+
97+
cd "npm/kubernetes-mcp-server-$platform"
98+
npm publish --tag latest
99+
cd ../..
100+
101+
echo "✅ Published $package_name"
102+
done
103+
104+
- name: Publish main package
105+
run: |
106+
echo "📦 Publishing main package..."
107+
108+
# Copy required files
109+
cp README.md LICENSE npm/kubernetes-mcp-server/
110+
111+
cd npm/kubernetes-mcp-server
112+
npm publish --tag latest
113+
cd ../..
114+
115+
echo "✅ Published main package"
116+
117+
- name: Summary
118+
run: |
119+
echo "## 🎉 Publishing Complete!" >> $GITHUB_STEP_SUMMARY
120+
echo "" >> $GITHUB_STEP_SUMMARY
121+
echo "### 📦 Package Details" >> $GITHUB_STEP_SUMMARY
122+
echo "- **Registry**: ${{ github.event.inputs.registry }}" >> $GITHUB_STEP_SUMMARY
123+
echo "- **Package**: `kubernetes-mcp-server-${{ github.event.inputs.suffix }}`" >> $GITHUB_STEP_SUMMARY
124+
echo "- **Version**: ${{ steps.version.outputs.version }}" >> $GITHUB_STEP_SUMMARY
125+
echo "" >> $GITHUB_STEP_SUMMARY
126+
echo "### 🚀 Installation" >> $GITHUB_STEP_SUMMARY
127+
if [ "${{ github.event.inputs.registry }}" = "github-packages" ]; then
128+
echo '```bash' >> $GITHUB_STEP_SUMMARY
129+
echo 'npm config set @macayaven:registry https://npm.pkg.github.com/' >> $GITHUB_STEP_SUMMARY
130+
echo 'npm install @macayaven/kubernetes-mcp-server' >> $GITHUB_STEP_SUMMARY
131+
echo '```' >> $GITHUB_STEP_SUMMARY
132+
else
133+
echo '```bash' >> $GITHUB_STEP_SUMMARY
134+
echo 'npm install kubernetes-mcp-server-${{ github.event.inputs.suffix }}' >> $GITHUB_STEP_SUMMARY
135+
echo '```' >> $GITHUB_STEP_SUMMARY
136+
fi
137+
echo "" >> $GITHUB_STEP_SUMMARY
138+
echo "### ✅ OpenShift AI Features" >> $GITHUB_STEP_SUMMARY
139+
echo "- 📊 Data Science Projects" >> $GITHUB_STEP_SUMMARY
140+
echo "- 🤖 Models" >> $GITHUB_STEP_SUMMARY
141+
echo "- 🚀 Applications" >> $GITHUB_STEP_SUMMARY
142+
echo "- 🧪 Experiments" >> $GITHUB_STEP_SUMMARY
143+
echo "- ⚡ Pipelines" >> $GITHUB_STEP_SUMMARY

‎GITHUB_ACTIONS_PUBLISHING.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
# GitHub Actions Publishing Guide
2+
3+
## 🚀 Automated NPM Publishing
4+
5+
This repository includes a GitHub Actions workflow that allows you to publish packages to NPM with manual triggering.
6+
7+
### 📋 Workflow Features
8+
9+
- **Manual Trigger**: Choose when to publish
10+
- **Registry Selection**: Public NPM or GitHub Packages
11+
- **Custom Suffix**: Define package naming (e.g., `openshift-ai`)
12+
- **Version Management**: Automatic version from git tags
13+
- **Multi-Platform**: Publishes all platform-specific packages
14+
- **Security**: Uses encrypted secrets for authentication
15+
16+
### 🔧 Setup Required
17+
18+
#### 1. Repository Secrets
19+
Go to **Settings → Secrets and variables → Actions** and add:
20+
21+
**For Public NPM Publishing:**
22+
- `NPM_TOKEN`: Your npm access token with publish permissions
23+
24+
**For GitHub Packages Publishing:**
25+
- `GITHUB_TOKEN`: Your GitHub personal access token with `write:packages` scope
26+
27+
#### 2. Token Creation
28+
29+
**Public NPM Token:**
30+
1. Go to [npmjs.com](https://www.npmjs.com/settings/tokens)
31+
2. Click "Generate New Token"
32+
3. Select "Automation" type
33+
4. Enable "Publish" permissions
34+
5. Copy the token
35+
36+
**GitHub Token:**
37+
1. Go to [GitHub Settings](https://github.com/settings/tokens)
38+
2. Click "Generate new token (classic)"
39+
3. Select scopes: `repo`, `write:packages`
40+
4. Copy the token
41+
42+
### 🎮 How to Use
43+
44+
#### 1. Go to Actions
45+
1. Navigate to **Actions** tab in your repository
46+
2. Select **"Publish to NPM"** workflow from the left sidebar
47+
3. Click **"Run workflow"** button
48+
49+
#### 2. Configure Publishing
50+
Fill in the workflow parameters:
51+
52+
- **registry**: Choose `public` or `github-packages`
53+
- **suffix**: Enter your package suffix (e.g., `openshift-ai`)
54+
55+
#### 3. Run and Monitor
56+
1. Click **"Run workflow"** to start publishing
57+
2. Monitor progress in real-time
58+
3. Check the summary for installation instructions
59+
60+
### 📦 Publishing Options
61+
62+
#### Option 1: Public NPM Registry
63+
- **Registry**: `https://registry.npmjs.org/`
64+
- **Package Name**: `kubernetes-mcp-server-{suffix}`
65+
- **Installation**: `npm install kubernetes-mcp-server-{suffix}`
66+
- **Visibility**: Public to everyone
67+
68+
#### Option 2: GitHub Packages Registry
69+
- **Registry**: `https://npm.pkg.github.com/`
70+
- **Package Name**: `@macayaven/kubernetes-mcp-server`
71+
- **Installation**: Requires registry configuration
72+
- **Visibility**: Private to your account
73+
74+
### 🔄 Workflow Process
75+
76+
1. **Checkout**: Downloads your code
77+
2. **Setup**: Configures Node.js and Go
78+
3. **Configure**: Sets up NPM registry and authentication
79+
4. **Version**: Gets version from git tags
80+
5. **Prepare**: Runs `prepare-fork-npm.sh` with your suffix
81+
6. **Build**: Compiles binaries for all platforms
82+
7. **Copy**: Moves binaries to npm packages
83+
8. **Publish**: Uploads all packages to NPM
84+
9. **Summary**: Creates GitHub Actions summary
85+
86+
### 📊 What Gets Published
87+
88+
#### Platform Packages (7 total)
89+
- `kubernetes-mcp-server-{suffix}-darwin-amd64`
90+
- `kubernetes-mcp-server-{suffix}-darwin-arm64`
91+
- `kubernetes-mcp-server-{suffix}-linux-amd64`
92+
- `kubernetes-mcp-server-{suffix}-linux-arm64`
93+
- `kubernetes-mcp-server-{suffix}-windows-amd64`
94+
- `kubernetes-mcp-server-{suffix}-windows-arm64`
95+
96+
#### Main Package (1 total)
97+
- `kubernetes-mcp-server-{suffix}` (with optionalDependencies)
98+
99+
### 🎯 Example Usage
100+
101+
#### Publishing to Public NPM with OpenShift AI suffix:
102+
1. **Run workflow** with:
103+
- registry: `public`
104+
- suffix: `openshift-ai`
105+
106+
2. **Result**: Users can install with:
107+
```bash
108+
npm install kubernetes-mcp-server-openshift-ai
109+
```
110+
111+
#### Publishing to GitHub Packages:
112+
1. **Run workflow** with:
113+
- registry: `github-packages`
114+
- suffix: `openshift-ai`
115+
116+
2. **Result**: Users can install with:
117+
```bash
118+
npm config set @macayaven:registry https://npm.pkg.github.com/
119+
npm install @macayaven/kubernetes-mcp-server
120+
```
121+
122+
### 🔍 Troubleshooting
123+
124+
#### Common Issues
125+
126+
**Authentication Failed (401/403)**
127+
- Check that secrets are correctly set
128+
- Verify tokens have required permissions
129+
- Ensure tokens haven't expired
130+
131+
**Publish Failed (409 Conflict)**
132+
- Version already exists
133+
- Check if you need to increment version
134+
- Git tag may already be published
135+
136+
**Build Failed**
137+
- Check workflow logs for build errors
138+
- Ensure Go version compatibility
139+
- Verify all dependencies are available
140+
141+
**Registry Configuration Error**
142+
- Verify registry URL is correct
143+
- Check .npmrc file format
144+
- Ensure token is properly encoded
145+
146+
### 📝 Workflow File
147+
148+
The workflow is defined in `.github/workflows/publish-npm.yml` and includes:
149+
150+
- **Manual triggering** with configurable parameters
151+
- **Multi-platform support** for all major OS/architectures
152+
- **Security best practices** using GitHub secrets
153+
- **Comprehensive logging** and error handling
154+
- **Automatic summaries** with installation instructions
155+
156+
### 🎉 Benefits
157+
158+
- **One-click publishing** - no local setup required
159+
- **Consistent process** - same steps every time
160+
- **Version management** - automatic from git tags
161+
- **Multi-registry support** - public npm or GitHub Packages
162+
- **Security** - tokens encrypted and managed by GitHub
163+
- **Transparency** - full logs and progress tracking
164+
165+
### 📚 Additional Resources
166+
167+
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
168+
- [NPM Documentation](https://docs.npmjs.com/)
169+
- [Semantic Versioning](https://semver.org/)
170+
- [OpenShift AI Documentation](https://docs.redhat.com/en-us/openshift_data_science/)
171+
172+
---
173+
174+
*This workflow makes publishing your OpenShift AI enhanced MCP server as simple as clicking a button!* 🚀

‎INSTALLATION.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Installation Instructions for @macayaven/kubernetes-mcp-server
2+
3+
## Method 1: Using GitHub Packages (Recommended)
4+
5+
### Step 1: Configure npm registry
6+
```bash
7+
npm config set @macayaven:registry https://npm.pkg.github.com/
8+
```
9+
10+
### Step 2: Authenticate with GitHub Packages
11+
```bash
12+
# Create a GitHub personal access token with 'read:packages' scope
13+
# Then login:
14+
npm login --scope=@macayaven --registry=https://npm.pkg.github.com
15+
```
16+
17+
### Step 3: Install the package
18+
```bash
19+
npm install @macayaven/kubernetes-mcp-server
20+
```
21+
22+
## Method 2: One-time installation with registry flag
23+
```bash
24+
npm install @macayaven/kubernetes-mcp-server --registry=https://npm.pkg.github.com
25+
```
26+
27+
## Method 3: Using npx (one-time execution)
28+
```bash
29+
npx --registry=https://npm.pkg.github.com @macayaven/kubernetes-mcp-server
30+
```
31+
32+
## Method 4: Direct tarball installation
33+
```bash
34+
npm install https://npm.pkg.github.com/download/@macayaven/kubernetes-mcp-server/0.0.53-127-gee20cd9/kubernetes-mcp-server-0.0.53-127-gee20cd9.tgz
35+
```
36+
37+
## Notes
38+
- GitHub Packages requires authentication for both public and private repositories
39+
- Users need a GitHub account to install packages from GitHub Packages
40+
- The packages are scoped to @macayaven and only available on GitHub Packages registry

0 commit comments

Comments
 (0)