Skip to content

Commit 662a6b6

Browse files
openhands-agentopenhands-agent
committed
Add GitHub Packages publishing workflow
- Remove npm publishing and keep only GitHub Packages (most GitHub-native) - Update package name to @openhands/typescript-client - Add GitHub Actions workflow for automated publishing on tag push - Update documentation and installation instructions - Add .npmrc configuration for GitHub Packages scope Co-authored-by: openhands <openhands@all-hands.dev>
1 parent 2d507ef commit 662a6b6

File tree

6 files changed

+270
-17
lines changed

6 files changed

+270
-17
lines changed

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

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
name: Publish to GitHub Packages
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*'
7+
workflow_dispatch:
8+
inputs:
9+
version:
10+
description: 'Version to publish (without v prefix)'
11+
required: true
12+
type: string
13+
14+
permissions:
15+
contents: read
16+
packages: write
17+
18+
jobs:
19+
publish:
20+
runs-on: ubuntu-latest
21+
22+
steps:
23+
- name: Checkout code
24+
uses: actions/checkout@v4
25+
26+
- name: Setup Node.js
27+
uses: actions/setup-node@v4
28+
with:
29+
node-version: 20.x
30+
cache: 'npm'
31+
registry-url: 'https://npm.pkg.github.com'
32+
scope: '@openhands'
33+
34+
- name: Install dependencies
35+
run: npm ci
36+
37+
- name: Run tests
38+
run: npm test
39+
40+
- name: Build package
41+
run: npm run build
42+
43+
- name: Extract version from tag or input
44+
id: version
45+
run: |
46+
if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
47+
echo "VERSION=${{ github.event.inputs.version }}" >> $GITHUB_OUTPUT
48+
else
49+
echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
50+
fi
51+
52+
- name: Update package version
53+
run: npm version ${{ steps.version.outputs.VERSION }} --no-git-tag-version
54+
55+
- name: Publish to GitHub Packages
56+
run: npm publish --access public
57+
env:
58+
NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
59+
60+
- name: Create GitHub Release (for tag pushes only)
61+
if: github.event_name == 'push'
62+
uses: softprops/action-gh-release@v1
63+
with:
64+
tag_name: ${{ github.ref_name }}
65+
name: Release ${{ github.ref_name }}
66+
draft: false
67+
prerelease: false
68+
generate_release_notes: true
69+
body: |
70+
## Installation from GitHub Packages
71+
72+
```bash
73+
npm install @openhands/typescript-client@${{ steps.version.outputs.VERSION }} --registry=https://npm.pkg.github.com
74+
```
75+
76+
Or add to your `.npmrc`:
77+
```
78+
@openhands:registry=https://npm.pkg.github.com
79+
```
80+
81+
Then install normally:
82+
```bash
83+
npm install @openhands/typescript-client@${{ steps.version.outputs.VERSION }}
84+
```
85+
86+
## Usage
87+
88+
```typescript
89+
import { RemoteConversation } from '@openhands/typescript-client';
90+
91+
const conversation = new RemoteConversation({
92+
baseUrl: 'http://localhost:8000',
93+
apiKey: 'your-api-key'
94+
});
95+
96+
await conversation.start();
97+
```

‎.github/workflows/release.yml‎

Lines changed: 43 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,10 @@ on:
55
tags:
66
- 'v*'
77

8+
permissions:
9+
contents: write
10+
packages: write
11+
812
jobs:
913
release:
1014
runs-on: ubuntu-latest
@@ -13,12 +17,13 @@ jobs:
1317
- name: Checkout code
1418
uses: actions/checkout@v4
1519

16-
- name: Use Node.js 20.x
20+
- name: Setup Node.js for GitHub Packages
1721
uses: actions/setup-node@v4
1822
with:
1923
node-version: 20.x
2024
cache: 'npm'
21-
registry-url: 'https://registry.npmjs.org'
25+
registry-url: 'https://npm.pkg.github.com'
26+
scope: '@openhands'
2227

2328
- name: Install dependencies
2429
run: npm ci
@@ -29,27 +34,52 @@ jobs:
2934
- name: Build package
3035
run: npm run build
3136

32-
- name: Publish to npm
37+
- name: Extract version from tag
38+
id: version
39+
run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
40+
41+
- name: Update package version
42+
run: npm version ${{ steps.version.outputs.VERSION }} --no-git-tag-version
43+
44+
- name: Publish to GitHub Packages
3345
run: npm publish --access public
3446
env:
35-
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
47+
NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
3648

3749
- name: Create GitHub Release
38-
uses: actions/create-release@v1
39-
env:
40-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
50+
uses: softprops/action-gh-release@v1
4151
with:
42-
tag_name: ${{ github.ref }}
43-
release_name: Release ${{ github.ref }}
52+
tag_name: ${{ github.ref_name }}
53+
name: Release ${{ github.ref_name }}
4454
draft: false
4555
prerelease: false
56+
generate_release_notes: true
4657
body: |
47-
## Changes
58+
## Installation from GitHub Packages
4859
49-
See [CHANGELOG.md](CHANGELOG.md) for details.
60+
### Option 1: Configure .npmrc (Recommended)
61+
Add to your `.npmrc` file:
62+
```
63+
@openhands:registry=https://npm.pkg.github.com
64+
```
5065
51-
## Installation
66+
Then install:
67+
```bash
68+
npm install @openhands/typescript-client@${{ steps.version.outputs.VERSION }}
69+
```
5270
71+
### Option 2: Direct install with registry flag
5372
```bash
54-
npm install @openhands/agent-server-typescript-client@${{ github.ref_name }}
73+
npm install @openhands/typescript-client@${{ steps.version.outputs.VERSION }} --registry=https://npm.pkg.github.com
74+
```
75+
76+
## Usage
77+
78+
```typescript
79+
import { RemoteConversation } from '@openhands/typescript-client';
80+
81+
const conversation = new RemoteConversation({
82+
baseUrl: 'http://localhost:8000',
83+
apiKey: 'your-api-key'
84+
});
5585
```

‎.npmrc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
@openhands:registry=https://npm.pkg.github.com

‎PUBLISHING.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Publishing Guide
2+
3+
This document explains how to publish the OpenHands TypeScript Client to GitHub Packages.
4+
5+
## Overview
6+
7+
The package is published exclusively to **GitHub Packages** for GitHub-native integration.
8+
9+
## Automated Publishing (Recommended)
10+
11+
### Prerequisites
12+
13+
- **GitHub Token**: Automatically provided by GitHub Actions as `GITHUB_TOKEN`
14+
15+
### Publishing Process
16+
17+
1. **Create and push a version tag**:
18+
```bash
19+
git tag v1.0.0
20+
git push origin v1.0.0
21+
```
22+
23+
2. **The GitHub Action will automatically**:
24+
- Run tests
25+
- Build the package
26+
- Update package.json version
27+
- Publish to GitHub Packages
28+
- Create a GitHub release with installation instructions
29+
30+
## Manual Publishing
31+
32+
### Setup
33+
34+
1. **Configure npm for GitHub Packages**:
35+
```bash
36+
npm login --registry=https://npm.pkg.github.com
37+
# Username: your-github-username
38+
# Password: your-github-token
39+
```
40+
41+
### Publishing Steps
42+
43+
1. **Update version**:
44+
```bash
45+
npm version patch # or minor, major
46+
```
47+
48+
2. **Build the package**:
49+
```bash
50+
npm run build
51+
```
52+
53+
3. **Run tests**:
54+
```bash
55+
npm test
56+
```
57+
58+
4. **Publish to GitHub Packages**:
59+
```bash
60+
npm publish --registry=https://npm.pkg.github.com --access public
61+
```
62+
63+
## Installation Instructions for Users
64+
65+
### From GitHub Packages
66+
67+
#### Option 1: Configure .npmrc (Recommended)
68+
Add to your `.npmrc` file:
69+
```
70+
@openhands:registry=https://npm.pkg.github.com
71+
```
72+
73+
Then install:
74+
```bash
75+
npm install @openhands/typescript-client
76+
```
77+
78+
#### Option 2: Direct install with registry flag
79+
```bash
80+
npm install @openhands/typescript-client --registry=https://npm.pkg.github.com
81+
```
82+
83+
## Troubleshooting
84+
85+
### Authentication Issues
86+
87+
- **GitHub Packages**: Ensure the `GITHUB_TOKEN` has `packages:write` permission
88+
89+
### Version Conflicts
90+
91+
If you encounter version conflicts, ensure:
92+
- The version in `package.json` matches the git tag
93+
- The version doesn't already exist in the registry
94+
95+
### Build Failures
96+
97+
Common issues:
98+
- TypeScript compilation errors: Fix in source code
99+
- Test failures: Ensure all tests pass before publishing
100+
- Missing dependencies: Run `npm ci` to install exact versions
101+
102+
## Workflow Files
103+
104+
- `.github/workflows/release.yml`: Main release workflow (GitHub Packages)
105+
- `.github/workflows/publish-github-packages.yml`: GitHub Packages only workflow with manual trigger

‎README.md‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,26 @@
1414
A TypeScript client library for the OpenHands Agent Server API. Mirrors the structure and functionality of the Python [OpenHands Software Agent SDK](https://github.com/OpenHands/software-agent-sdk),
1515
but only supports remote conversations.
1616

17+
## Installation
18+
19+
This package is published to GitHub Packages. You have two installation options:
20+
21+
### Option 1: Configure .npmrc (Recommended)
22+
Add this to your `.npmrc` file:
23+
```
24+
@openhands:registry=https://npm.pkg.github.com
25+
```
26+
27+
Then install normally:
28+
```bash
29+
npm install @openhands/typescript-client
30+
```
31+
32+
### Option 2: Direct install with registry flag
33+
```bash
34+
npm install @openhands/typescript-client --registry=https://npm.pkg.github.com
35+
```
36+
1737
## Quick Start
1838

1939
### Start an AgentServer
@@ -29,7 +49,7 @@ docker run -p 8000:8000 -p 8001:8001 \
2949
### Creating a Conversation
3050

3151
```typescript
32-
import { Conversation, Agent, Workspace } from '@openhands/agent-server-typescript-client';
52+
import { Conversation, Agent, Workspace } from '@openhands/typescript-client';
3353

3454
const agent = new Agent({
3555
llm: {
@@ -242,7 +262,7 @@ The library includes comprehensive TypeScript type definitions:
242262
The client includes proper error handling with custom error types:
243263

244264
```typescript
245-
import { HttpError } from '@openhands/agent-server-typescript-client';
265+
import { HttpError } from '@openhands/typescript-client';
246266

247267
try {
248268
await conversation.sendMessage('Hello');

‎package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"name": "@openhands/agent-server-typescript-client",
2+
"name": "@openhands/typescript-client",
33
"version": "0.1.0",
44
"description": "TypeScript client for OpenHands Agent Server",
55
"main": "dist/index.js",
@@ -50,6 +50,6 @@
5050
],
5151
"repository": {
5252
"type": "git",
53-
"url": "https://github.com/All-Hands-AI/agent-server-typescript-client.git"
53+
"url": "https://github.com/OpenHands/typescript-client.git"
5454
}
5555
}

0 commit comments

Comments
 (0)