If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/temporalio/temporal shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 28+ active contributors
• Distributed ownership (top contributor 28% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live temporalio/temporal repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/temporalio/temporal.

What it runs against: a local clone of temporalio/temporal — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in temporalio/temporal | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of temporalio/temporal. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/temporalio/temporal.git
#   cd temporal
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of temporalio/temporal and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "temporalio/temporal(\\.git)?\\b" \\
  && ok "origin remote is temporalio/temporal" \\
  || miss "origin remote is not temporalio/temporal (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"
test -f ".github/workflows/run-tests.yml" \\
  && ok ".github/workflows/run-tests.yml" \\
  || miss "missing critical file: .github/workflows/run-tests.yml"
test -f ".github/CODEOWNERS" \\
  && ok ".github/CODEOWNERS" \\
  || miss "missing critical file: .github/CODEOWNERS"
test -f ".goreleaser.yml" \\
  && ok ".goreleaser.yml" \\
  || miss "missing critical file: .goreleaser.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/temporalio/temporal"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Temporal is a durable execution platform and service that enables developers to build resilient, scalable applications by automatically handling intermittent failures, retries, and state management for long-running workflows. Written primarily in Go (~25MB), it originated as a fork of Uber's Cadence and provides a server that executes units of application logic called Workflows with built-in fault tolerance and event sourcing capabilities. Monolithic service organized as a Go application with server/subsystems architecture. Core structure includes: API servers (gRPC), persistence layer with database adapters (CQL for Cassandra, PLpgSQL for PostgreSQL), workflow execution engine, and CLI/tooling in .github/actions/. GitHub Actions in .github/workflows/ orchestrate multi-stage builds (build-binaries, build-docker-images, promote-*-image workflows), indicating containerized deployment as primary target.

Backend engineers and platform teams building microservices, data pipelines, and distributed systems who need reliable workflow orchestration without manually managing retries, timeouts, and failure recovery. DevOps engineers also use it to deploy and operate the Temporal server infrastructure.

Production-ready and actively developed. The project is mature (originated from Cadence at Uber), has comprehensive CI/CD workflows visible in .github/workflows/ (build-and-publish.yml, run-tests.yml, release.yml), uses codecov integration for coverage tracking, and maintains release automation (.goreleaser.yml). Active maintenance evidenced by multiple workflow files, well-structured GitHub Actions, and governance files (CODEOWNERS, CONTRIBUTING.md).

Low risk for a stable service. The codebase is large (25MB Go) with strong automation (15+ GitHub workflows), but requires careful coordination across multiple components (gRPC services, database adapters for CQL and PLpgSQL). Risk factors: complexity of distributed system semantics, database schema migrations (PLpgSQL files present), and dependency on external datastores (Cassandra/PostgreSQL support evident). No single-maintainer risk given corporate backing by Temporal Technologies.

Active release and CI/CD improvements: auto-approve workflows (auto-approve-cicd-release-pr.yml), test optimization (optimize-test-sharding.yml), flaky test reporting (flaky-tests-report.yml), and Docker image promotion pipelines (promote-server-image.yml, promote-admin-tools-image.yml) are all present and maintained. Version management and dependency checking workflows (check-release-dependencies.yml, trigger-version-info-service.yml) indicate ongoing release cycle activity.

Clone and use local Temporal via Homebrew or Docker: brew install temporal && temporal server start-dev. For source development: git clone https://github.com/temporalio/temporal && cd temporal && make (inferred from Makefile presence). See .github/workflows/run-tests.yml for CI test patterns and Dockerfile for containerized setup.

Daily commands: make command (Makefile present at root) for local builds; Docker images via .github/actions/build-docker-images/action.yml and scripts/main.go; temporal server start-dev for running locally post-installation.

• README.md — Entry point documentation describing Temporal as a durable execution platform; essential context for understanding the system's purpose and design philosophy.
• Makefile — Build automation and development workflow definition; defines how to compile, test, and deploy the Temporal service.
• .github/workflows/run-tests.yml — Primary CI/CD pipeline; defines test execution strategy, coverage requirements, and integration test orchestration.
• .github/CODEOWNERS — Ownership matrix for critical components; essential for understanding review responsibilities and component governance.
• .goreleaser.yml — Release artifact generation configuration; defines build targets, versioning, and distribution strategy across platforms.
• api/adminservice/v1/service.pb.go — Core gRPC service definitions; the primary API contract exposed by the Temporal service to clients.
• .github/copilot-instructions.md — Codebase-specific development guidelines and conventions; critical for maintaining consistency across contributions.

• Admin Service (api/adminservice/) — Exposes user-facing gRPC APIs for workflow management,

Add a New gRPC Service Endpoint

1. Define the new service method in a .proto file under api/<service>/ (e.g., api/myservice/v1/service.proto) (api/adminservice/v1/service.pb.go)
2. Generate Go stubs by running protoc or using the Makefile proto target (Makefile)
3. Implement the service interface in the server code, following the gRPC server stub pattern in service_grpc.pb.go (api/adminservice/v1/service_grpc.pb.go)
4. Add integration tests in .github/workflows/features-integration.yml if this is a user-facing API (.github/workflows/features-integration.yml)
5. Update CODEOWNERS to assign review responsibility for the new service package (.github/CODEOWNERS)

Add a New Message Type for Domain Entity

1. Define the protobuf message in api/<domain>/v1/message.proto (e.g., api/cluster/v1/message.proto) (api/cluster/v1/message.pb.go)
2. Generate the Go message code and helpers by running make proto or protoc (api/cluster/v1/message.go-helpers.pb.go)
3. Use the generated message type in service request/response definitions (request_response.pb.go) (api/adminservice/v1/request_response.pb.go)
4. Add serialization/deserialization tests to validate the new message type

Extend CI/CD Pipeline with New Test Stage

1. Create a new workflow file under .github/workflows/ (e.g., my-feature-tests.yml) or modify run-tests.yml (.github/workflows/run-tests.yml)
2. Define test jobs, Docker image dependencies, and parallelization strategy (.github/workflows/features-integration.yml)
3. Add build steps and artifact caching to optimize execution time (.github/actions/build-binaries/action.yml)
4. Update Makefile with corresponding local test target for developer parity (Makefile)

Add a New Code Quality Linting Rule

1. Update .golangci.yml with the new linter configuration and rule settings (.github/.golangci.yml)
2. Add the linter invocation to the linters.yml workflow to enforce in CI (.github/workflows/linters.yml)
3. Document the rationale and any exceptions in CONTRIBUTING.md (CONTRIBUTING.md)
4. Run make lint locally to validate configuration before committing (Makefile)

• Protocol Buffers & gRPC — Enables efficient, language-agnostic service communication; required for supporting multiple client SDKs (Go, Java, Python, etc.)
• Go — Provides concurrency primitives (goroutines, channels) essential for managing distributed workflow execution; fast compilation and deployment
• Docker & Container Orchestration — Standardizes deployment across cloud providers; simplifies multi-node cluster setup and scaling
• GitHub Actions — Native CI/CD for the repository; enables per-commit testing, linting, and automated releases

• Protocol Buffer-first API design

  • Why: Ensures language-agnostic interoperability and tight schema versioning
  • Consequence: Requires .proto file updates and code generation for any API change; adds build complexity but enforces API stability

• Monolithic repository with multiple API versions (v1, v2)

  • Why: Centralizes all service code and reduces coordination overhead; simplifies shared domain logic
  • Consequence: Large codebase requires careful ownership management (CODEOWNERS); version migration paths must be maintained

• Comprehensive CI/CD pipeline with multiple specialized workflows

  • Why: Catches regressions across features, platforms, and integration scenarios early
  • Consequence: Workflow maintenance overhead; longer time-to-feedback on certain code paths if not optimized

• Does not provide a UI; administration and monitoring are CLI and API-driven
• Does not handle authentication/authorization at the service level (delegated to deployment infrastructure)
• Does not guarantee real-time workflow execution (eventual consistency model for distributed state)

Database initialization required: Temporal server depends on Cassandra or PostgreSQL with pre-initialized schemas (see PLpgSQL files). Port conflicts: temporal server start-dev uses port 8233 by default for Web UI. gRPC services on 7233 (worker), 7234 (frontend), 7235 (matching) etc.—review Dockerfile and action.yml for exact port assignments. Environment setup: some workflows reference version-info-service and admin-tools images suggesting external service dependencies. Test sharding optimization present (optimize-test-sharding.yml) meaning test execution is non-trivial; review CI config before running full test suite locally.

• Durability and Event Sourcing — Temporal stores workflow execution history as immutable events, allowing replays and recovery—understanding this event log model is fundamental to reasoning about workflow semantics and failure handling
• Workflow Replay and Determinism — Temporal replays workflow code deterministically from stored events; contributors must understand this constraint to avoid introducing non-deterministic logic that breaks failure recovery
• Activity Execution and Retries — Temporal decouples workflow logic from side effects via Activities with built-in retry policies; essential for understanding how to structure fault-tolerant work units
• gRPC and Protocol Buffers — Temporal uses gRPC for inter-service communication and client SDKs; contributors working on API changes or new endpoints must understand proto definitions and gRPC semantics
• Pluggable Persistence Layer — Temporal abstracts storage backend (Cassandra vs PostgreSQL) through an adapter pattern visible in CQL and PLpgSQL files; understanding this abstraction is crucial for database subsystem work
• Namespace Isolation and Multi-tenancy — Temporal supports multiple isolated namespaces within a single deployment (mentioned in README CLI example); this isolation model affects persistence layer design and query scoping
• Binary Release and Artifact Promotion — The .goreleaser.yml and promote-*-image workflows indicate a sophisticated artifact management strategy across dev/staging/production; understanding this pipeline is essential for maintainers and deployment engineers

• temporalio/samples-go — Official Go SDK examples demonstrating workflow patterns and best practices for Temporal SDK usage
• temporalio/samples-java — Official Java SDK examples providing polyglot workflow samples for JVM-based applications
• temporalio/cli — Command-line tooling for interacting with Temporal servers (referenced in README as temporal CLI commands)
• uber/cadence — Predecessor project from Uber upon which Temporal was forked; important for understanding lineage and architectural decisions
• temporalio/web — Web UI referenced in README (http://localhost:8233) for visualizing and managing workflows and executions

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for GitHub Actions workflow validation

The repo has 15+ GitHub Actions workflows (.github/workflows/*.yml) but no dedicated CI validation beyond actionlint. Adding a workflow that validates YAML structure, required secrets, and job dependencies would catch misconfigurations early. The actionlint-matcher.json exists but isn't fully leveraged. This is high-value because workflow failures are blocking and expensive.

• [ ] Create .github/workflows/validate-workflows.yml that runs yamllint on all workflows in .github/workflows/
• [ ] Add workflow validation to check for required environment variables and secrets referenced in build-and-publish.yml, release.yml, and run-tests.yml
• [ ] Add tests for custom GitHub Actions in .github/actions/* (build-binaries, build-docker-images, get-job-id) to validate action.yml schema
• [ ] Document validation rules in CONTRIBUTING.md

Add integration tests for protobuf code generation consistency

The api/ directory contains many generated protobuf files (*pb.go, *pb.mock.go, *_grpc.pb.go). Without tests validating regeneration, proto changes risk producing stale generated code. A test that regenerates protos and diffs against committed files would catch developer oversights and could be integrated into pre-commit hooks.

• [ ] Create a test file proto_generation_test.go in the root or api/ directory
• [ ] Add a make target (already has Makefile) that regenerates all protos in api/adminservice, api/archiver, api/batch, etc.
• [ ] Write test that runs the make target and asserts no diff against committed *pb.go and *_grpc.pb.go files
• [ ] Document regeneration steps in CONTRIBUTING.md (currently missing proto workflow details)

Create CONTRIBUTING.md section for local development setup with Docker

The repo has extensive Docker infrastructure (.dockerignore, build-docker-images action, docker-build-manual.yml) but CONTRIBUTING.md lacks a 'Local Development' section with Docker Compose setup. New contributors cannot easily spin up a local Temporal instance for testing. Adding a docker-compose.yml template and setup guide reduces friction significantly.

• [ ] Create docker-compose.yml in repo root with services for Temporal server, PostgreSQL, and Elasticsearch (matching production dependencies inferred from workflows)
• [ ] Add 'Local Development' section to CONTRIBUTING.md with: docker-compose up instructions, required Go version (inferred from .goreleaser.yml), and how to run make test
• [ ] Reference existing Dockerfile patterns from build-docker-images action to ensure consistency
• [ ] Add docker-compose.yml to .gitignore variations (.env.local support for credentials)

• Add integration tests for the PLpgSQL schema migrations visible in the file structure—currently no test files listed alongside schema files, a common gap in database-backed services
• Document the gRPC service definitions and API contracts—no .proto file paths visible in structure despite Go being primary language, suggesting protobuf documentation could be improved in contributing guide
• Create a troubleshooting guide for common Docker and database connectivity issues in deployment—evidenced by multiple promote-*-image workflows and docker-build-manual.yml suggesting users struggle with image promotion and database setup

The Temporal repository shows reasonable security hygiene with automated tooling in place (govulncheck, GitHub Actions, code coverage), but lacks visibility into actual dependencies, workflow configurations, and generated code sources. The main security concerns are blind spots due to missing files in the analysis rather than obvious critical vulnerabilities. Recommended actions: provide go.mod/go.sum for dependency auditing, review all GitHub Actions workflows for security best practices, validate proto file sources, and ensure Docker build processes follow security hardening practices.

• Medium · Missing Dependency Vulnerability Checks — Repository root (go.mod/go.sum not provided). The repository appears to be a Go service (Temporal) but no go.mod or go.sum files were provided in the file structure. Without dependency information, it's impossible to verify if known vulnerable packages are being used. The .github/workflows/govulncheck.yml exists, suggesting vulnerability scanning is in place, but the actual dependencies are not visible for analysis. Fix: Ensure govulncheck and dependabot are regularly run in CI/CD. Provide go.mod and go.sum files for dependency analysis. Keep all dependencies updated to latest secure versions.
• Low · Generated Code Files Not Validated — api/ directory (*.pb.go, *_grpc.pb.go files). The codebase contains numerous auto-generated protobuf files (*pb.go, *_grpc.pb.go, *pb.mock.go). While these are typically safe when generated from controlled .proto files, the source .proto files are not visible in the provided file structure. If .proto files are not properly validated, they could introduce security issues. Fix: Ensure .proto files are version controlled and reviewed in pull requests. Use signed commits for proto file modifications. Regularly audit protobuf code generation tools for vulnerabilities.
• Low · Workflow File Security Configuration — .github/workflows/. Multiple GitHub Actions workflows exist (.github/workflows/*.yml) but their contents are not provided. Workflows can be attack vectors if they use untrusted actions, lack input validation, or have overly permissive permissions. Fix: Audit all workflow files for: using specific action versions (not @main), minimizing GITHUB_TOKEN permissions, validating external inputs, and using branch protection rules.
• Low · Docker Build Scripts Present — .github/actions/build-docker-images/scripts/. Docker build scripts exist (.github/actions/build-docker-images/scripts/main.go) but without content review, potential security issues in image construction, layer caching, or secret handling cannot be assessed. Fix: Review Dockerfile and build scripts for: use of minimal base images, non-root user execution, layer caching of sensitive data, and secrets not baked into images.
• Low · Codecov Configuration Visible — .github/.codecov.yml. A .codecov.yml file exists in .github/, which may contain sensitive configuration or tokens if misconfigured. Fix: Ensure codecov configuration does not contain hardcoded tokens. Use repository secrets for authentication and rotate tokens regularly.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.