Workflow:Langchain ai Langchain Release Process
| Knowledge Sources | |
|---|---|
| Domains | CI_CD, Release_Management, Package_Publishing |
| Last Updated | 2026-02-11 15:00 GMT |
Overview
End-to-end process for releasing a LangChain package from code change through CI validation to PyPI publication using the monorepo's automated release pipeline.
Description
This workflow describes the complete release lifecycle for any package in the LangChain monorepo. The process uses GitHub Actions with a reusable release workflow (_release.yml) that handles building the distribution, generating release notes, publishing to Test PyPI for validation, running pre-release checks (unit tests, integration tests, compatibility tests), and finally publishing to production PyPI. The pipeline uses OpenID Connect trusted publishing for secure, credential-free PyPI uploads and enforces that releases only occur from the master branch.
Usage
Execute this workflow when a package has accumulated changes that are ready for a new release. This applies to any package in the monorepo: langchain-core, langchain, partner integrations (langchain-openai, langchain-anthropic, etc.), langchain-text-splitters, or langchain-tests. The workflow is triggered manually via GitHub Actions workflow dispatch with the target package's working directory.
Execution Steps
Step 1: Version Bump and Changelog
Update the version number in the package's pyproject.toml file. The version follows semantic versioning: major for breaking changes, minor for new features, patch for bug fixes. Review the git log since the last release tag to identify all changes that should be documented. Ensure all changes are committed and pushed to the master branch.
Key considerations:
- Version is the single source of truth in pyproject.toml
- Release tags follow the format {package-name}=={version} (e.g., langchain-openai==1.2.0)
- Only the master branch is allowed for releases (safety check in the pipeline)
- Pre-release versions use suffixes like rc1, beta1
Step 2: Trigger the Release Workflow
Manually dispatch the _release.yml GitHub Actions workflow, specifying the package's working directory (e.g., libs/partners/openai). The workflow runs with minimal permissions following the principle of least privilege. It validates that the current branch is master before proceeding.
Key considerations:
- Release is intentionally manual to prevent accidental publishes
- A dangerous-nonmaster-release flag exists for exceptional cases but should rarely be used
- The workflow accepts the working directory as an input parameter
- Concurrent releases of the same package are automatically serialized
Step 3: Build the Distribution Package
The pipeline builds the Python distribution using uv build, producing both source distribution (sdist) and wheel files. The build job extracts the package name and version from pyproject.toml and uploads the built artifacts to GitHub for subsequent pipeline stages.
Key considerations:
- Build runs in an isolated environment with minimal dependencies
- Build artifacts are uploaded as GitHub Actions artifacts for traceability
- The package name and version are extracted automatically for tagging
Step 4: Generate Release Notes
The pipeline automatically generates release notes by examining the git log between the previous release tag and the current commit. It identifies the most recent tag matching the package name pattern and produces a changelog of all commits since that tag. For first releases, a note about the initial release is generated.
Key considerations:
- Release notes are generated from commit messages, so conventional commits format is important
- Pre-release tags are handled correctly to find the previous stable release
- The release notes become part of the GitHub Release object
Step 5: Publish to Test PyPI
The built package is published to Test PyPI (test.pypi.org) using OpenID Connect trusted publishing. This validates that the package can be installed from a package index before going to production. The skip-existing flag prevents failures if the same version was previously published to Test PyPI.
Key considerations:
- Trusted publishing uses OIDC tokens, no manual API keys needed
- Test PyPI publication validates the package metadata and structure
- The skip-existing flag handles re-runs gracefully
Step 6: Run Pre-Release Validation
The pipeline installs the package from Test PyPI and runs a comprehensive validation suite. This includes importing the package to verify it loads correctly, running the full unit test suite, testing with minimum dependency versions to ensure compatibility, and running integration tests with live API keys for all supported providers.
Key considerations:
- Caching is explicitly disabled to catch dependency resolution issues
- Minimum version testing ensures backward compatibility with older dependencies
- Integration tests use provider-specific API keys stored as GitHub secrets
- Tests run against the published package, not the source code, to catch packaging issues
Step 7: Run Compatibility Tests
Additional compatibility tests verify that the released package works with the latest langchain-core. This catches potential incompatibilities between independently versioned packages in the monorepo.
Key considerations:
- Ensures that core API changes do not break partner packages
- Tests both directions: new package with current core, and current package with new core
- Pydantic v1/v2 compatibility is also verified
Step 8: Publish to Production PyPI
After all validation passes, the package is published to production PyPI (pypi.org) using the same trusted publishing mechanism. A GitHub Release is created with the generated release notes and the release tag. The release becomes immediately available for pip install.
Key considerations:
- Production PyPI publishing only proceeds if all prior steps succeed
- The GitHub Release provides a permanent record of the release
- Tag format is {package-name}=={version} for precise identification
- Users can immediately install the new version via pip or uv