Principle:Langchain ai Langchain Release Preparation

Overview

A standardized workflow for preparing and publishing a LangChain partner package release through a multi-stage CI pipeline with safety checks.

Description

The Release Preparation principle defines the end-to-end process for releasing a LangChain partner package to PyPI. The release pipeline is designed with multiple stages and security boundaries to prevent compromised dependencies from gaining access to publishing credentials.

Pipeline stages:

1. Build: The package is built in an isolated environment with read-only repository permissions. The version is extracted from pyproject.toml and the built wheel is uploaded as a CI artifact.
2. Release Notes: Git tags are analyzed to determine the previous release, and a changelog is generated from commit messages between the two versions.
3. Test PyPI Publish: The built package is published to Test PyPI first as a dry run, using trusted publishing (OIDC) for authentication.
4. Pre-release Checks: The package is installed from the built wheel (not from source) and the full unit test suite is run. This catches issues like missing dependencies or broken imports. Minimum dependency versions are also tested. For partner packages, integration tests are run with real API credentials.
5. Dependent Testing (core only): For langchain-core releases, the latest published versions of partner packages are tested against the new core to catch breaking changes.
6. PyPI Publish: After all checks pass, the package is published to production PyPI using trusted publishing.
7. GitHub Release: A Git tag is created and a GitHub Release is published with the generated changelog.

Security design:

• The build stage is explicitly separated from the publish stage to prevent a compromised build dependency from accessing PyPI credentials.
• Trusted publishing (OIDC) eliminates the need for long-lived API tokens.
• The dangerous-nonmaster-release flag must be explicitly set to release from non-master branches.

Safety checks:

• Pre-release dependency check ensures no dependencies allow prerelease versions.
• Unit tests are run against the built wheel (not editable install) to catch packaging issues.
• Minimum dependency version testing catches backward-incompatible dependency updates.

Usage

Apply this principle when:

• Releasing a new version of any LangChain partner package.
• Understanding why a release failed at a specific pipeline stage.
• Designing release workflows for new packages in the monorepo.
• Auditing the security model of the release pipeline.

Theoretical Basis

The pipeline follows the defense-in-depth principle for software supply chain security. Each stage operates with minimal permissions, and the publish step only executes after all validation stages pass.

1. Trigger: workflow_dispatch with (working-directory, release-version)
2. Build: uv build -> upload artifact
3. Release Notes: git log between tags -> generate changelog
4. Test PyPI: publish to test.pypi.org (skip-existing)
5. Pre-release Checks:
   a. Install from wheel
   b. Run unit tests
   c. Test minimum dependency versions
   d. Run integration tests (partner packages)
6. Dependent Testing (core releases only):
   a. Install new core with published partners
   b. Run partner integration tests
7. PyPI Publish: publish to pypi.org
8. GitHub Release: tag + release notes

Related Pages

• Implementation:Langchain_ai_Langchain_Release_Workflow_Dispatch