Skip to content

Automate Go integration releases #558

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
paul-paliychuk merged 1 commit into from
Jul 10, 2026
Merged

Automate Go integration releases #558

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 13 additions & 4 deletions .github/workflows/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,13 +25,19 @@ Triggered by a published GitHub release or manual dispatch. Routes by language:
- **Python → PyPI** (test → build → publish via trusted publishing / OIDC).
- **TypeScript → npm** (`npm ci` → build → test → `npm publish`, via trusted
publishing / OIDC).
- **Go → GitHub + Go proxy** (manual dispatch → test → scoped tag + GitHub Release →
`proxy.golang.org` verification).

**Tag scheme:** `zep-<framework>-<language>-v<version>` — e.g. `zep-adk-python-v0.2.0`,
`zep-mastra-typescript-v0.1.0`. Manual dispatch takes `framework` + `language` inputs.

**Go modules** are not released by this workflow — a Go module is versioned by a git tag
matching its module subpath: `integrations/<framework>/go/vX.Y.Z`, consumed via
`go get github.com/getzep/zep/integrations/<framework>/go@vX.Y.Z`.
**Go modules** use a git tag matching the module subpath:
`integrations/<framework>/go/vX.Y.Z`. To release one, run this workflow manually from
`main`, choose the framework and `go`, and enter the version without the `v` prefix. After
the Go checks pass and the protected `release` environment is approved, the workflow
creates the scoped tag and GitHub Release and verifies the module through the public Go
proxy. For example, ADK version `0.1.0` is consumed with
`go get github.com/getzep/zep/integrations/adk/go@v0.1.0`.

## Setup requirements

Expand Down Expand Up @@ -62,11 +68,14 @@ workflow.
2. Add a `paths-filter` entry under the matching language in `test-integrations.yml`
(e.g. `pydantic-ai: ['integrations/pydantic-ai/python/**']`).
3. Python: configure PyPI trusted publishing. TypeScript: configure npm trusted publishing.
4. Release by tagging `zep-<framework>-<language>-v<version>` (or the Go module-path tag).
4. Python/TypeScript: publish a release tag using `zep-<framework>-<language>-v<version>`.
Go: manually dispatch `release-integrations.yml`; do not create the tag yourself.

## Troubleshooting

- **Package not detected:** verify the `paths-filter` entry matches the package directory.
- **Tests fail on PR:** check dependencies and language/version compatibility.
- **Release fails:** confirm PyPI or npm trusted publishing is configured with environment
`release`.
- **Go tag already exists:** versions are immutable. Re-run only when the tag points to the
same commit; otherwise choose a new version.
217 changes: 206 additions & 11 deletions .github/workflows/release-integrations.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@ name: Release Integration Packages

# Tag scheme: zep-<framework>-<language>-v<version>
# e.g. zep-adk-python-v0.2.0, zep-mastra-typescript-v0.1.0
# Go modules are NOT released here — they are versioned by a tag matching the module
# subpath, integrations/<framework>/go/vX.Y.Z, consumed via
# Go modules are tested, tagged, and released from workflow_dispatch. Their tags match
# the module subpath, integrations/<framework>/go/vX.Y.Z, consumed via
# go get github.com/getzep/zep/integrations/<framework>/go@vX.Y.Z

on:
Expand All @@ -21,6 +21,10 @@ on:
options:
- python
- typescript
- go
version:
description: 'Go version without the v prefix (required for Go, e.g. 0.1.0)'
required: false

permissions:
contents: read
Expand All @@ -32,26 +36,217 @@ jobs:
outputs:
framework: ${{ steps.detect.outputs.framework }}
language: ${{ steps.detect.outputs.language }}
version: ${{ steps.detect.outputs.version }}
steps:
- name: Detect framework + language
id: detect
env:
EVENT_NAME: ${{ github.event_name }}
INPUT_FRAMEWORK: ${{ github.event.inputs.framework }}
INPUT_LANGUAGE: ${{ github.event.inputs.language }}
INPUT_VERSION: ${{ github.event.inputs.version }}
RELEASE_TAG: ${{ github.event.release.tag_name }}
run: |
if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
echo "framework=${{ github.event.inputs.framework }}" >> "$GITHUB_OUTPUT"
echo "language=${{ github.event.inputs.language }}" >> "$GITHUB_OUTPUT"
if [[ "$EVENT_NAME" == "workflow_dispatch" ]]; then
FRAMEWORK="$INPUT_FRAMEWORK"
LANGUAGE="$INPUT_LANGUAGE"
VERSION="$INPUT_VERSION"
else
TAG="${{ github.event.release.tag_name }}"
TAG="$RELEASE_TAG"
# zep-<framework>-<language>-v<version>
if [[ $TAG =~ ^zep-(.+)-(python|typescript)-v.*$ ]]; then
echo "framework=${BASH_REMATCH[1]}" >> "$GITHUB_OUTPUT"
echo "language=${BASH_REMATCH[2]}" >> "$GITHUB_OUTPUT"
if [[ $TAG =~ ^zep-([a-z0-9][a-z0-9-]*)-(python|typescript)-v(.+)$ ]]; then
FRAMEWORK="${BASH_REMATCH[1]}"
LANGUAGE="${BASH_REMATCH[2]}"
VERSION="${BASH_REMATCH[3]}"
elif [[ $TAG =~ ^integrations/([a-z0-9][a-z0-9-]*)/go/v(.+)$ ]]; then
# Go releases created with GITHUB_TOKEN do not recursively trigger this
# workflow. Recognize externally-created Go releases so they no-op cleanly.
FRAMEWORK="${BASH_REMATCH[1]}"
LANGUAGE="go"
VERSION="${BASH_REMATCH[2]}"
else
echo "Tag '$TAG' does not match zep-<framework>-<language>-v<version>."
echo "Go modules release via the tag integrations/<framework>/go/vX.Y.Z, not this workflow."
echo "Tag '$TAG' does not match a supported integration release tag."
exit 1
fi
fi

if [[ ! "$FRAMEWORK" =~ ^[a-z0-9][a-z0-9-]*$ ]]; then
echo "Invalid framework key '$FRAMEWORK'."
exit 1
fi
if [[ ! "$LANGUAGE" =~ ^(python|typescript|go)$ ]]; then
echo "Unsupported integration language '$LANGUAGE'."
exit 1
fi
{
echo "framework=$FRAMEWORK"
echo "language=$LANGUAGE"
echo "version=$VERSION"
} >> "$GITHUB_OUTPUT"

# ---------------------------------------------- Go → scoped tag + GitHub Release
validate-go:
if: github.event_name == 'workflow_dispatch' && needs.detect.outputs.language == 'go'
needs: detect
runs-on: ubuntu-latest
outputs:
framework: ${{ steps.metadata.outputs.framework }}
module: ${{ steps.metadata.outputs.module }}
package_dir: ${{ steps.metadata.outputs.package_dir }}
tag: ${{ steps.metadata.outputs.tag }}
version: ${{ steps.metadata.outputs.version }}
steps:
- name: Validate release metadata
id: metadata
env:
FRAMEWORK: ${{ needs.detect.outputs.framework }}
VERSION: ${{ needs.detect.outputs.version }}
run: |
if [[ "$GITHUB_REF" != "refs/heads/main" ]]; then
echo "Go releases must be dispatched from main (got '$GITHUB_REF')."
exit 1
fi
if [[ ! "$FRAMEWORK" =~ ^[a-z0-9][a-z0-9-]*$ ]]; then
echo "Invalid framework key '$FRAMEWORK'."
exit 1
fi
if [[ ! "$VERSION" =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$ ]]; then
echo "Invalid Go semantic version '$VERSION' (expected e.g. 0.1.0 or 1.2.0-rc.1)."
exit 1
fi
if [[ "$VERSION" == *-* ]]; then
IFS='.' read -ra PRERELEASE_IDENTIFIERS <<< "${VERSION#*-}"
for identifier in "${PRERELEASE_IDENTIFIERS[@]}"; do
if [[ "$identifier" =~ ^[0-9]+$ && "$identifier" == 0* && "$identifier" != "0" ]]; then
echo "Invalid numeric prerelease identifier '$identifier': leading zeroes are not allowed."
exit 1
fi
done
fi

PACKAGE_DIR="integrations/$FRAMEWORK/go"
MODULE="github.com/$GITHUB_REPOSITORY/$PACKAGE_DIR"
MAJOR="${VERSION%%.*}"
if (( MAJOR >= 2 )); then
MODULE="$MODULE/v$MAJOR"
fi

{
echo "framework=$FRAMEWORK"
echo "module=$MODULE"
echo "package_dir=$PACKAGE_DIR"
echo "tag=$PACKAGE_DIR/v$VERSION"
echo "version=v$VERSION"
} >> "$GITHUB_OUTPUT"

- uses: actions/checkout@v4
with:
ref: ${{ github.sha }}

- name: Validate Go module path
env:
EXPECTED_MODULE: ${{ steps.metadata.outputs.module }}
PACKAGE_DIR: ${{ steps.metadata.outputs.package_dir }}
run: |
if [[ ! -f "$PACKAGE_DIR/go.mod" ]]; then
echo "Go module $PACKAGE_DIR/go.mod does not exist."
exit 1
fi
ACTUAL_MODULE="$(awk '$1 == "module" { print $2; exit }' "$PACKAGE_DIR/go.mod")"
if [[ "$ACTUAL_MODULE" != "$EXPECTED_MODULE" ]]; then
echo "go.mod declares '$ACTUAL_MODULE'; expected '$EXPECTED_MODULE'."
exit 1
fi

- name: Test Go integration
uses: ./.github/actions/test-go
with:
package: ${{ steps.metadata.outputs.framework }}
go-version: '1.26'

publish-go:
if: github.event_name == 'workflow_dispatch' && needs.detect.outputs.language == 'go'
needs: [detect, validate-go]
runs-on: ubuntu-latest
environment:
name: release
url: https://github.com/${{ github.repository }}/releases
permissions:
contents: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
ref: ${{ github.sha }}

- name: Create scoped tag and GitHub Release
env:
FRAMEWORK: ${{ needs.validate-go.outputs.framework }}
GH_TOKEN: ${{ github.token }}
MODULE: ${{ needs.validate-go.outputs.module }}
PACKAGE_DIR: ${{ needs.validate-go.outputs.package_dir }}
TAG: ${{ needs.validate-go.outputs.tag }}
VERSION: ${{ needs.validate-go.outputs.version }}
run: |
TAG_EXISTS=false
TAG_REF="$(git ls-remote --tags origin "refs/tags/$TAG")"
if [[ -n "$TAG_REF" ]]; then
TAG_EXISTS=true
git fetch origin "refs/tags/$TAG:refs/tags/$TAG"
TAG_SHA="$(git rev-list -n 1 "$TAG")"
if [[ "$TAG_SHA" != "$GITHUB_SHA" ]]; then
echo "Tag '$TAG' already points to $TAG_SHA, not $GITHUB_SHA."
exit 1
fi
fi

if gh release view "$TAG" >/dev/null 2>&1; then
echo "Release '$TAG' already exists at the validated commit; continuing verification."
exit 0
fi

NOTES_FILE="$(mktemp)"
printf '%s\n\n' "Go module: \`$MODULE\`" > "$NOTES_FILE"
# shellcheck disable=SC2016 # Markdown fences are intentionally literal.
printf 'Install with:\n\n```bash\ngo get %s@%s\n```\n\n' "$MODULE" "$VERSION" >> "$NOTES_FILE"
printf '[Changelog](https://github.com/%s/blob/%s/%s/CHANGELOG.md)\n' \
"$GITHUB_REPOSITORY" "$TAG" "$PACKAGE_DIR" >> "$NOTES_FILE"

RELEASE_ARGS=(
"$TAG"
--title "Zep $FRAMEWORK Go integration $VERSION"
--notes-file "$NOTES_FILE"
--latest=false
)
if [[ "$TAG_EXISTS" == "true" ]]; then
RELEASE_ARGS+=(--verify-tag)
else
RELEASE_ARGS+=(--target "$GITHUB_SHA")
fi
gh release create "${RELEASE_ARGS[@]}"

- name: Set up Go
uses: actions/setup-go@v5
with:
go-version: '1.26'

- name: Register and verify module with the Go proxy
env:
MODULE: ${{ needs.validate-go.outputs.module }}
VERSION: ${{ needs.validate-go.outputs.version }}
run: |
for attempt in {1..6}; do
if GOPROXY=https://proxy.golang.org GO111MODULE=on go list -m "$MODULE@$VERSION"; then
exit 0
fi
if (( attempt < 6 )); then
echo "Go proxy has not resolved $MODULE@$VERSION yet; retrying in 10 seconds."
sleep 10
fi
done
echo "Go proxy did not resolve $MODULE@$VERSION after 6 attempts."
exit 1

# ---------------------------------------------------------------- Python → PyPI
test-python:
if: needs.detect.outputs.language == 'python'
Expand Down
5 changes: 3 additions & 2 deletions integrations/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -159,8 +159,9 @@ go vet ./... && go test ./... && golangci-lint run
- **Release:** `.github/workflows/release-integrations.yml`. Tag scheme encodes language:
**`zep-<framework>-<language>-v<version>`** (e.g. `zep-adk-python-v0.2.0`,
`zep-mastra-typescript-v0.1.0`). Python → PyPI, TypeScript → npm.
**Go exception:** Go modules are versioned by a tag matching the module subpath —
`integrations/<framework>/go/vX.Y.Z` — consumed via
**Go exception:** manually dispatch the workflow from `main` with the framework and
version. After tests and release-environment approval, it creates the module-path tag and
GitHub Release: `integrations/<framework>/go/vX.Y.Z`. Consumers install it via
`go get github.com/getzep/zep/integrations/<framework>/go@vX.Y.Z`.

## Quality bar
Expand Down
7 changes: 4 additions & 3 deletions integrations/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,9 +55,10 @@ full per-language commands and the CI/release setup.

## Release

Each package releases independently via `.github/workflows/release-integrations.yml`, tag
scheme `zep-<framework>-<language>-v<version>` (Python → PyPI, TypeScript → npm; Go is
versioned by the module-path tag `integrations/<framework>/go/vX.Y.Z`).
Each package releases independently via `.github/workflows/release-integrations.yml`.
Python and TypeScript use `zep-<framework>-<language>-v<version>` release tags. For Go,
manually dispatch the workflow from `main` with the framework and version; after validation
it creates the module-path tag `integrations/<framework>/go/vX.Y.Z` and GitHub Release.

## Support

Expand Down
Loading