The integration of package managers into continuous integration and deployment pipelines is a foundational element of modern software engineering. While npm has long been the default tool for Node.js projects, Yarn has carved out a significant niche, particularly for its speed, reliability, and workspace management capabilities. However, configuring Yarn within GitHub Actions is not a static process; it has evolved dramatically from clever workarounds utilizing underlying Docker images to sophisticated, version-locked workflows managed by Corepack and dedicated actions. Understanding this evolution is critical for engineers aiming to optimize build times, ensure deterministic builds, and maintain robust CI/CD pipelines. The current landscape involves distinct strategies depending on whether a project utilizes the classic Yarn ecosystem or has migrated to Yarn Berry (version 2+), each presenting unique configuration requirements and performance implications.

The Legacy Approach: Leveraging Docker Base Images

In the early days of GitHub Actions, the platform offered limited built-in support for package managers other than npm. Engineers faced a dilemma when migrating projects that relied heavily on Yarn. The solution often involved a deep understanding of the underlying infrastructure powering the actions. GitHub Actions are, at their core, Docker containers. The standard actions/npm action was built upon a Docker base image, specifically node:10-slim. A critical characteristic of the -slim variant of the Node.js Docker image is that it includes Yarn pre-installed. This architectural detail allowed engineers to bypass the explicit naming of the action and simply override the command execution.

Instead of relying on an action dedicated solely to Yarn, which was often unavailable or outdated, developers could configure the actions/npm action to run Yarn commands. This was achieved by introducing a runs parameter to specify the executable. The configuration structure resembled a traditional workflow definition where actions were chained together. For instance, an installation step would look like this:

yaml action "install" { uses = "actions/[email protected]" runs = "yarn" args = "install" }

This approach allowed the entire workflow to be constructed using a single action type, merely changing the runs and args parameters for each step. A complete workflow for building, testing, and publishing could be defined as follows:

```yaml
workflow "build, test and publish on release" {
on = "push"
resolves = "publish"
}

install with yarn

action "install" {
uses = "actions/[email protected]"
runs = "yarn"
args = "install"
}

build with yarn

action "build" {
needs = "install"
uses = "actions/[email protected]"
runs = "yarn"
args = "build"
}

test with yarn

action "test" {
needs = "build"
uses = "actions/[email protected]"
runs = "yarn"
args = "test"
}

filter for a new tag

action "check for new tag" {
needs = "Test"
uses = "actions/bin/filter@master"
args = "tag"
}

publish with npm

action "publish" {
needs = "check for new tag"
uses = "actions/[email protected]"
args = "publish"
secrets = ["NPMAUTHTOKEN"]
}
```

While this method was functional and "delightfully simple" for its time, it relied on implicit assumptions about the base image. As Node.js versions evolved and GitHub Actions modernized, this hack became obsolete, replaced by more robust and explicit configuration methods.

Modern Node.js Setup and Basic Yarn Installation

As GitHub Actions matured, the actions/setup-node action became the standard for configuring the Node.js environment. This action handles the installation of Node.js to a specified version and, importantly, can also manage Yarn. However, simply setting up Node.js does not guarantee the use of the desired Yarn version or the optimal installation behavior.

The basic pattern for installing dependencies involves setting up the Node environment and then running the install command with specific flags. The --frozen-lockfile flag is critical in this context. It ensures that the yarn.lock file is not modified during installation. This is a safety mechanism for CI environments; if the lockfile were to change in CI, it would indicate a discrepancy between the local development environment and the CI environment, typically caused by adding a package to package.json without updating the lockfile locally. Using this flag prevents silent changes to the lockfile that could lead to inconsistent builds.

yaml steps: - name: Set up Node.js ⚙️ uses: actions/setup-node@v2 with: node-version: '16.x' - name: Install dependencies 📦 run: yarn install --frozen-lockfile

While this approach is straightforward, it lacks caching. Without caching, every CI run must download and install all dependencies from scratch. For large projects or monorepos, this can result in significant inefficiencies. The actions/setup-node action does provide some caching capabilities, but for Yarn specifically, additional configuration is often required to achieve optimal performance, particularly when dealing with older versions of Yarn or specific workspace structures.

Performance Optimization: Caching Yarn Dependencies

One of the most significant bottlenecks in CI pipelines is the installation of dependencies. In a large monorepo managed with Yarn workspaces, a single yarn install command at the root level is sufficient to install dependencies for all clients. However, on a clean CI runner, this process can be extremely slow. For example, a local install might take only 5 seconds if node_modules are already present, whereas the same operation in CI could take approximately 4.5 minutes. To mitigate this, GitHub Actions recommends caching the Yarn cache directory.

Implementing this cache requires a two-step process. First, the path to the Yarn cache directory must be determined and stored in an output variable. Second, the actions/cache action is used to restore the cache based on a key derived from the operating system and the content of the yarn.lock file. This ensures that the cache is invalidated only when dependencies change.

```yaml
- name: Get yarn cache directory path
id: yarn-cache-dir-path
run: echo "::set-output name=dir::$(yarn cache dir)"

• uses: actions/cache@v2
  id: yarn-cache # use this to check for cache-hit (steps.yarn-cache.outputs.cache-hit != 'true')
  with:
  path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
  key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
  restore-keys: |
  ${{ runner.os }}-yarn-
  ```

This configuration allows subsequent yarn install commands to leverage the cached packages, drastically reducing installation time. The restore-keys mechanism provides a fallback, allowing the pipeline to use a partial cache if an exact match is not found. This strategy is particularly effective for projects that have not migrated to Yarn Berry, as the caching behavior and directory structures differ significantly between the two versions.

Migrating to Yarn Modern (Berry) and Corepack

The landscape of Yarn changed fundamentally with the release of Yarn 2, also known as Yarn Berry. This version introduced a new architecture, including a zero-install approach and a different caching mechanism. Managing Yarn Berry in GitHub Actions requires a different set of tools and configurations. The migration process begins with ensuring the local environment is up to date. This involves using Node.js version 18 or higher, enabling Corepack, and setting the Yarn version to the latest stable release.

bash corepack enable yarn set version stable yarn install

Corepack is a tool bundled with Node.js that allows for the management of package manager versions. By enabling Corepack, developers can pin the exact version of Yarn used in their project within the package.json file. This ensures that all developers and CI runners use the same version, eliminating version mismatch issues. The package.json file will include a packageManager field:

json { "packageManager": "[email protected]" }

Additionally, the migration often involves configuring the .yarnrc.yml file. For projects that prefer the traditional node_modules folder structure for compatibility with certain tools, the nodeLinker option can be set:

```yaml

.yarnrc.yml

nodeLinker: node-modules
```

Once the local environment is configured, the GitHub Actions workflow must be updated to support Yarn Berry. The classic caching methods used for older Yarn versions are not directly applicable. Instead, specialized actions designed for Yarn Berry are recommended.

The Setup Yarn Berry Action

To address the specific needs of Yarn Berry, the threeal/setup-yarn-action (Setup Yarn Berry Action) has been developed. This action is designed to set up Yarn to a specified version and install dependencies with built-in cache support. It is important to note that this action only supports Yarn 2+ (Berry). If a project is still using the classic version of Yarn, migration to Berry is suggested to leverage these modern features.

The action offers several key features:
- Sets up Yarn to a specified version.
- Installs dependencies for the current Node.js project with cache support.

The input parameters for this action are straightforward:

Using this action simplifies the CI configuration significantly. It handles the complexity of version management and caching, allowing developers to focus on their build and test steps. This represents a shift from manual cache configuration to automated, version-aware setup, aligning with the broader trend towards deterministic and reproducible builds in CI/CD pipelines.

Deployment and GitHub Pages Integration

Beyond installation and testing, CI pipelines often include deployment steps. For projects hosted on GitHub Pages, configuring the homepage field in package.json is essential. This ensures that the build process correctly infers the public URL and sets up assets and routing accordingly.

json { "scripts": { "build": "...", "predeploy": "yarn build", "deploy": "gh-pages -d build" }, "homepage": "https://MichaelCurrin.github.io/my-app/" }

The predeploy script ensures that the build is always executed before the deployment step. The gh-pages npm package is commonly used for deploying to GitHub Pages. To use this in a GitHub Actions workflow, the package must be added as a development dependency:

bash yarn add --dev gh-pages

The deployment step in the workflow then runs the yarn deploy command. Authentication is handled via the GITHUB_TOKEN secret, which is automatically provided by GitHub Actions. This eliminates the need for manual token generation and storage.

yaml jobs: build-deploy: - name: Install packages run: yarn install --frozen-lockfile - name: Deploy GitHub Pages 🚀 run: yarn deploy env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

This integration demonstrates how Yarn workflows can be seamlessly extended to include deployment tasks, leveraging the power of GitHub Actions for end-to-end automation.

Conclusion

The journey of integrating Yarn into GitHub Actions reflects the broader evolution of the Node.js ecosystem. From early hacks that exploited the contents of Docker base images to sophisticated, Corepack-driven workflows, the tools and techniques available to developers have become increasingly robust and automated. For legacy projects, careful management of the node_modules cache remains essential for performance. For modern projects using Yarn Berry, dedicated actions and Corepack provide a streamlined, deterministic approach to dependency management. As CI/CD practices continue to mature, the emphasis on speed, reliability, and reproducibility will drive further innovations in how package managers are integrated into automated pipelines. Understanding these nuances allows engineering teams to build faster, more reliable software.

Sources

1. Johnny Reilly: GitHub Actions and Yarn
2. Threeal: Setup Yarn Action
3. Dylants Blog: Yarn Modern 2+ and GitHub Actions
4. Michael Currin: Code Cookbook - GitHub Actions Yarn
5. Dev.to: How to Cache node_modules in GitHub Actions with Yarn