Temporal Worker Integrations

Integrations for running Temporal workers on serverless and managed compute platforms, such as AWS Lambda and Google Cloud Run, built on top of the base SDKs (for example, sdk-go). Each integration is its own package with its own dependencies, tests, version and release cadence.

There are no packages here yet; the existing integrations are being moved here from the contrib directories of the Temporal SDK repositories, and are still published from there for now.

For now, samples for these integrations live in the per-language samples-<language> repositories (for example, samples-go), not in this repository.

Documentation

This top-level README is written to be human-friendly, and describes the overall design of this repository. Please exercise appropriate consideration for human readers when making changes to it.

For more concrete information on how to contribute, see CONTRIBUTING.md. For a highly detailed and normative guide meant for coding agents (but still human-readable), see AGENTS.md.

Each language subdirectory also contains a human-friendly README with targeted overviews and instructions for developers to get started with working with packages of that specific language.

Repository structure

Packages are organized by language, with all code for a specific language living under <language>/. Within each language subdirectory, this repository respects language-specific conventions for code structure to the extent possible.

In all languages except Go, each distributed package is a direct subdirectory of the language, <language>/<package>/. In Go, directory structure instead mirrors package import paths, so a package with path go.temporal.io/workerintegrations/a/b/c is defined within go/a/b/c.

Every package includes a typical language-native manifest file, alongside a custom file called integration.toml, which defines some extra metadata used by repository tooling (see scripts/lib/integration_toml.py for the precise schema). The LICENSE file is copied verbatim into each package, to ensure that it gets bundled in package distributions by each language's native package management tools.

On top of package code itself, each language subdirectory may also contain special shared resources starting with _ or .. For example, <language>/_shared with shared project config or <language>/_template with language-specific templates for creating new packages.

The top-level scripts/ directory contains repository-wide tooling scripts. See the Repository tooling section for more information.

Repository tooling

This repository contains extensive tooling for managing packages across all the different languages in a consistent manner. This includes scripts for running CI tasks and smoke tests, enforcing repository conventions, publishing releases, automatically setting up new packages, and more.

Most of the tooling is run automatically on-event (on PRs, on push, on release publication, etc.) or on-demand (dev scripts, manually triggered CI workflows). There's also a scheduled nightly test, which verifies each package's compatibility with the newest versions allowed by its declared dependency ranges; failures are tracked in automatically managed issues, one per failing package, which close once the package passes again.

The scripts/ directory is itself a standalone (unpublished) Python project, and includes its own tests.

Releases

Releases are cut per-package from the main branch, and are based on GitHub releases. Tags are directory-scoped in the Go-style format of <path>/<to>/<package>/vX.Y.Z. Release tags are immutable and cannot be moved or deleted once created.

Release notes are generated automatically from commit history, rather than relying on manual CHANGELOG files.

The recommended steps to create a new release are as follows:

1. Manually trigger a dry-run release CI workflow for the relevant language with the planned tag name, to confirm the validity of the release before the tag is actually created. (TODO: only Python has one so far) For example:

   gh workflow run release-<language>-dry-run.yml --ref main -f tag=<language>/<package>/v<version>

   The run's summary shows the commit it tested and whether to mark the release as a pre-release, for the next steps.

2. Generate release notes with scripts/release_notes.py, after fetching the existing tags. For example:

   git fetch --tags
   uv run --project scripts --locked python scripts/release_notes.py \
       <language>/<package>/v<version> --ref <tested-commit> > notes.md

3. Create a draft GitHub release (or pre-release when appropriate), targeting the commit tested in the dry run. For example:

   # Add --prerelease if the dry run's summary says to
   gh release create <language>/<package>/v<version> --target <tested-commit> --draft --notes-file notes.md

4. Publish the release from the draft, letting GitHub create the specified tag.

5. Monitor the CI workflows triggered automatically by the release publication, which will publish a new package version to the language-specific package registry (if relevant) and run smoke tests. (TODO: only Python has one so far)

   • If a job fails, re-run only the failed jobs, either on the run's page in GitHub Actions (click "Re-run jobs", then "Re-run failed jobs") or from the command line:

     gh run list --workflow release-<language>.yml   # find the run's ID
     gh run rerun <run-id> --failed

   • If the release workflow itself needs a fix, merge the fix and release the next version instead. Its release notes should then also cover the version that was never published: pass --since <last published release tag> to scripts/release_notes.py. It's also worth editing the unpublished version's release notes to say it wasn't published, and which version replaces it.