samples-go is the worked example set for the Temporal Go SDK

One directory per SDK capability, each with tests

samples-go is described as a repository containing several sample Workflow applications that demonstrate the various capabilities of the Temporal Server via the Temporal Go SDK, and the README is explicit about the organisation. Each sample demonstrates one feature of the SDK, together with tests. The tree confirms it at a glance. The top level is a long list of directories, one per concept, among them await-signals, batch-sliding-window, branch, cancellation, child-workflow, choice-exclusive, choice-multi, codec-server, cron, ctxpropagation, dsl, dynamic-workflows, eager-workflow-start, early-return, encryption, expense, external-env-conf, external-storage, fileprocessing, goroutine, memo, metrics, mutex, pickfirst, polling, and a family of nexus directories covering messaging, standalone activities, standalone operations, cancellation and context propagation. This shape is the reason to keep the repository around even once you know the SDK. When a question comes up about how a specific feature is meant to be used, the answer is usually a directory you can read in one sitting, with a test that shows the expected behaviour.

The rules the samples teach by example

Two warnings in the README stand out because they are the mistakes a newcomer makes and the samples are arranged to prevent. The first is about goroutines: do not use native go routines in Workflows, instead use Temporal coroutines through workflow.Go() to maintain a deterministic Workflow, and the coroutine examples are visible in the Goroutine, DSL, Recovery and PSO workflow examples. The second is about select: do not use the native Go select statement, instead use Go SDK Selectors through selector.Select(ctx) to maintain a deterministic Workflow, shown in the Pick First, Mutex, DSL and Timer examples. Determinism is not a stylistic preference in a durable execution engine. If a workflow branches on a timer or a channel, that decision has to be reproducible when the workflow replays after a crash, and a native goroutine or select introduces a decision the engine cannot reproduce. The samples exist to show the sanctioned alternative rather than only to describe it.

Authentication samples cover the four ways into Temporal Cloud

Four separate samples deal with connecting to Temporal Cloud, which tells you the SDK supports several credential models and that choosing between them is a real decision. The helloworldmtls sample is a basic workflow and activity using mTLS like Temporal Cloud. The dynamicmtls sample shows how to refresh mTLS credentials, which allows credentials to be refreshed without restarting the worker, and that is the point of a dynamic sample, since a certificate that expires should not take the worker down with it. The helloworld-apiKey sample uses an API Key to authenticate with Temporal Cloud. And the external-env-conf sample configures a client with an external configuration file, like TOML, decoupling connection settings from application code, which is what you want when the same binary runs against different clusters. The helloworld sample itself is the recommended starting point, and the README also notes a greetingslocal variant and a greetings application among the tree.

Retry, heartbeat and cancellation are separate samples for a reason

Three samples cover the parts of durable execution that are hardest to get right in production code. The retryactivity sample executes an unreliable Activity with a custom Retry Policy, so if the Activity Execution fails the Server schedules a retry based on that policy, and it also includes a Heartbeat, which enables it to resume from the Activity Execution's last reported progress when it retries. The cancellation sample shows how to cancel a Workflow Execution by calling CancelWorkflow and how to defer an Activity Execution that cleans up after the Workflow Execution has been cancelled, which is the part teams usually forget. The child-workflow sample shows how to execute a Child Workflow from a Parent Workflow Execution, and the child-workflow-continue-as-new sample makes a specific point: the call to Continue-As-New by a Child Workflow Execution is not visible to the parent, which receives a notification only when a Child Workflow Execution completes, fails or times out. That is the useful feature when you need to process a large set of data, since the child can iterate over the data calling Continue-As-New periodically without polluting the parent's history.

Encryption, codec servers and external storage

Three samples cover the payload side of things, and they build on each other. The encryption sample shows how to use encryption for Workflow and Activity data with the DataConverter API, and it also includes an example of stacking encoders, in that case encryption and compression. The codec-server sample demonstrates using a codec server to decode payloads for display in the Temporal CLI and Temporal Web, and the setup can be used for any kind of codec, with compression and encryption given as the common examples. The external-storage sample goes further and offloads large payloads to S3-compatible object storage, plus a codec server built on the SDK's payload HTTP handler so the Web UI and CLI can decode and download the externally stored payloads. The pattern across all three is the same: the workflow history can grow beyond what you want to keep, so payloads get transformed on the way in and reversed on the way out for display. The go.mod file shows the supporting dependencies, including the AWS SDK v2 and a gofakes3 implementation for local testing against S3-compatible storage.

Observability, sessions and the Nexus family

The samples cover the operational surfaces as well as the workflow features. The metrics sample and the opentelemetry, opentelemetry-v2 and datadog directories cover the telemetry integrations, and the go.mod shows the corresponding dependencies including the OpenTelemetry SDK with metric and trace exporters, the Prometheus client, uber-go/tally and the Jaeger client, along with the contrib packages for the Datadog and OpenTelemetry integrations. The logger-interceptor sample deals with logging. The fileprocessing sample demonstrates Sessions, which bind a set of Activity Executions to a specific Worker after the first Activity executes, a feature that matters when you want a particular worker to own a piece of work. The nexus family is the largest group of related directories, covering nexus, nexus-messaging, nexus-messaging-temporal-operation, nexus-standalone-activity, nexus-standalone-operations, nexus-cancelation, nexus-context-propagation and nexus-multiple-arguments, with the nexus-rpc/sdk-go in the dependency list. There is also a grpc-proxy directory, a lambda-worker directory, and a googleadk directory with the go.temporal.io/googleadk dependency.

The Makefile shows how the samples are checked

The repository has a build and verification story, and the Makefile is where it is written down. The main install target runs clean, staticcheck, errcheck, workflowcheck, bins and test in sequence, and ci-build runs staticcheck, errcheck, workflowcheck, bins and test. The bins target finds every main.go in the tree and builds each one, so every sample is compiled in CI rather than only the one you happen to be reading. The test target finds every directory containing a test file, runs go test with a 20 second timeout and the race detector, tees the output to test.log, and then fails the build if the log contains a failure line. The workflowcheck target is the interesting one for your own code: it installs go.temporal.io/sdk/contrib/tools/workflowcheck and runs it with -show-pos and a config file, and that tool checks workflows for the determinism problems the README warns about. The lint targets install staticcheck and errcheck at their latest versions, and the update-sdk target walks every go.mod in the tree and upgrades the Temporal SDK, which is how a repository with many modules keeps them in step.

What this repository is not, and how to run it

The limits are structural. This is a collection of example applications, one directory per concept, and the go.mod declares the module as github.com/temporalio/samples-go with the SDK pinned at go.temporal.io/sdk v1.49.0 and a Go version of 1.26.6. It is a reference to read and copy from, not a library to depend on, and a sample is a teaching artifact rather than production code with the error handling and observability you would want. The release history is also worth noting. The most recent releases are v1.3.0 from January 2021, v1.2.0 from November 2020 and v1.1.0 from October 2020, while the last push was on 2026-10-16, so the tags stopped years ago and the repository is maintained by commits rather than by releases. The licence is one GitHub cannot classify, so read the LICENSE file before copying code into a commercial project. To run anything, the README offers three paths: the VS Code Remote Containers route, running Temporal Server locally with the dev environment instructions, and cloning the repository afterwards. The helloworld sample is the recommended starting point.

Editorial conclusion

Adopt samples-go as the reference you read and copy from when you build a Go service on Temporal, since each directory isolates one SDK capability with tests you can run locally. Do not adopt it as a dependency, since it is a collection of example programs rather than a module you import, and do not treat a sample as production code. Verify first that the SDK version in go.mod, at 1.49.0, matches the server you run against, that the sample you copy does not use an API the project itself warns against, such as Cron Jobs where Schedules are recommended, and that the workflow check tool in the Makefile passes on your own workflow code.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. temporalio/samples-go on GitHub