Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. πŸ”₯

feat(go-sdk): add release tagging convention and publish workflow

firecrawl-spring[bot]82b0f301b44b
diff --git a/.github/workflows/publish-go-sdk.yml b/.github/workflows/publish-go-sdk.yml
new file mode 100644
index 000000000..052e2f2e1
--- /dev/null
+++ b/.github/workflows/publish-go-sdk.yml
@@ -0,0 +1,94 @@
+name: Publish Go SDK
+
+on:
+ workflow_dispatch:
+ push:
+ branches:
+ - main
+ paths:
+ - 'apps/go-sdk/**'
+ - '.github/workflows/publish-go-sdk.yml'
+
+# Go modules are "published" by pushing a git tag. For modules living in a
+# monorepo subdirectory, the tag MUST be prefixed with the subdir path β€”
+# e.g. apps/go-sdk/v2.0.0 β€” for the Go module proxy to resolve it.
+#
+# This workflow reads Version from apps/go-sdk/version.go, checks whether the
+# corresponding tag already exists, and if not creates+pushes it, then warms
+# the proxy.golang.org cache to trigger pkg.go.dev indexing.
+jobs:
+ publish:
+ name: Tag and index on pkg.go.dev
+ runs-on: blacksmith-2vcpu-ubuntu-2404
+ permissions:
+ contents: write
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+
+ - name: Set up Go
+ uses: actions/setup-go@v5
+ with:
+ go-version: "1.23"
+ cache-dependency-path: apps/go-sdk/go.sum
+
+ - name: Build and vet
+ working-directory: ./apps/go-sdk
+ run: |
+ go build ./...
+ go vet ./...
+
+ - name: Read SDK version
+ id: version
+ working-directory: ./apps/go-sdk
+ run: |
+ VERSION=$(grep -E '^const Version = ' version.go | sed -E 's/.*"([^"]+)".*/\1/')
+ if [ -z "$VERSION" ]; then
+ echo "Failed to parse Version from apps/go-sdk/version.go" >&2
+ exit 1
+ fi
+ TAG="apps/go-sdk/v${VERSION}"
+ echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+ echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+ echo "Resolved version: ${VERSION} (tag: ${TAG})"
+
+ - name: Check if tag already exists
+ id: tag_check
+ run: |
+ TAG="${{ steps.version.outputs.tag }}"
+ if git rev-parse -q --verify "refs/tags/${TAG}" >/dev/null; then
+ echo "exists=true" >> "$GITHUB_OUTPUT"
+ echo "Tag ${TAG} already exists β€” skipping publish."
+ else
+ echo "exists=false" >> "$GITHUB_OUTPUT"
+ fi
+
+ - name: Create and push tag
+ if: steps.tag_check.outputs.exists == 'false'
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: |
+ TAG="${{ steps.version.outputs.tag }}"
+ git config user.name "github-actions[bot]"
+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+ git tag -a "${TAG}" -m "Release Go SDK ${TAG}"
+ git push origin "${TAG}"
+
+ - name: Warm Go module proxy (triggers pkg.go.dev indexing)
+ if: steps.tag_check.outputs.exists == 'false'
+ run: |
+ MODULE="github.com/firecrawl/firecrawl/apps/go-sdk"
+ VERSION="v${{ steps.version.outputs.version }}"
+ # Force a module-proxy fetch; pkg.go.dev discovers modules from proxy.golang.org.
+ # Retry a few times because the tag may take a moment to be visible to the proxy.
+ for i in 1 2 3 4 5; do
+ if curl -fsSL "https://proxy.golang.org/${MODULE}/@v/${VERSION}.info" -o /dev/null; then
+ echo "Module ${MODULE}@${VERSION} fetched from proxy.golang.org"
+ exit 0
+ fi
+ echo "Attempt $i: proxy not yet aware of ${VERSION}; sleeping 30s"
+ sleep 30
+ done
+ echo "::warning::proxy.golang.org did not resolve ${MODULE}@${VERSION} yet; pkg.go.dev will pick it up on the next fetch."
diff --git a/apps/go-sdk/README.md b/apps/go-sdk/README.md
index 0215dc460..360af0b64 100644
--- a/apps/go-sdk/README.md
+++ b/apps/go-sdk/README.md
@@ -313,6 +313,49 @@ firecrawl.String("test") // *string
firecrawl.Float64(0.5) // *float64
```
+## Releases
+
+The Go SDK lives in a monorepo subdirectory, so releases follow Go's
+[nested module tagging](https://go.dev/ref/mod#vcs-version) convention. Tags
+**must** be prefixed with the module subdirectory path:
+
+```
+apps/go-sdk/v2.0.0
+```
+
+A bare `v2.0.0` tag will not be resolvable by the Go module proxy.
+
+### Release workflow
+
+The SDK version is the single source of truth in
+[`version.go`](./version.go):
+
+```go
+const Version = "2.0.0"
+```
+
+To cut a release:
+
+1. Bump the `Version` constant in `apps/go-sdk/version.go`
+2. Merge to `main`
+3. The [`publish-go-sdk`](../../.github/workflows/publish-go-sdk.yml) workflow
+ will automatically:
+ - create the `apps/go-sdk/v{Version}` tag on the merge commit,
+ - push it to the repository,
+ - warm `proxy.golang.org` to trigger indexing on
+ [pkg.go.dev](https://pkg.go.dev/github.com/firecrawl/firecrawl/apps/go-sdk).
+
+The workflow is idempotent: if the tag already exists, it is a no-op.
+
+### Consuming a specific version
+
+```bash
+go get github.com/firecrawl/firecrawl/apps/[email protected]
+```
+
+Users pin via the semantic version suffix; they never reference the
+`apps/go-sdk/` tag prefix directly β€” Go's toolchain handles the translation.
+
## License
MIT
diff --git a/apps/go-sdk/http_client.go b/apps/go-sdk/http_client.go
index 39bb80feb..49fbfa75f 100644
--- a/apps/go-sdk/http_client.go
+++ b/apps/go-sdk/http_client.go
@@ -95,6 +95,7 @@ func (h *httpClient) doJSON(ctx context.Context, method, url string, body interf
req.Header.Set("Authorization", "Bearer "+h.apiKey)
req.Header.Set("Content-Type", "application/json")
+ req.Header.Set("User-Agent", "firecrawl-go/"+Version)
// Apply client-level headers.
for k, v := range h.extraHeaders {
req.Header.Set(k, v)
diff --git a/apps/go-sdk/version.go b/apps/go-sdk/version.go
new file mode 100644
index 000000000..08d6a2488
--- /dev/null
+++ b/apps/go-sdk/version.go
@@ -0,0 +1,9 @@
+package firecrawl
+
+// Version is the SDK version. It is used as the source of truth for release
+// tags (apps/go-sdk/v{Version}) and as the User-Agent suffix on API requests.
+//
+// Bump this when preparing a new release. The publish-go-sdk GitHub workflow
+// reads this value and creates the corresponding monorepo-prefixed tag on
+// merge to main.
+const Version = "2.0.0"