Solving the "Unable to locate executable file: yarn" Error in GitHub Actions

In the dynamic world of software development, continuous integration and deployment play a pivotal role. GitHub Actions, a cornerstone in this landscape, empowers developers to automate and streamline their workflow processes. However, it's not without its challenges. A frequent and vexing hurdle that many developers face is the "Unable to locate executable file: yarn" error. This particular issue is especially prevalent in the realm of self-hosted runners, leading to a significant roadblock that causes both frustration and delays in the development process.

This error message typically pops up when GitHub Actions workflows are configured to run on self-hosted runners that lack certain pre-installed tools, one of which is yarn. Yarn, a popular package manager, plays a crucial role in managing project dependencies and executing scripts. Its absence in the execution environment of a self-hosted runner can halt the workflow, thereby impeding the smooth progress of continuous integration and deployment.

Understanding the nuances of this error and exploring effective solutions is essential for maintaining an efficient and hassle-free CI/CD pipeline. In this blog post, we'll delve into the causes behind this error and introduce DimeRun, a novel approach to circumvent this issue, enhancing both the efficiency and reliability of GitHub Actions.

Understanding the Error

The "Unable to locate executable file: yarn" error in GitHub Actions is more than just a simple hiccup; it's a symptom of a fundamental difference in the environments between official GitHub runners and self-hosted ones. This distinction is crucial in understanding why this error occurs and how it affects your workflows.

GitHub Actions is a powerful automation tool that allows developers to create, test, and deploy their code right from GitHub. It uses runners to execute your jobs - these runners are essentially servers with the GitHub Actions runner application installed. There are two types of runners: GitHub-hosted and self-hosted.

The official GitHub-hosted runners are pre-configured environments managed by GitHub. They come equipped with a wide range of tools and languages, including yarn, a fast, reliable, and secure dependency management tool widely used in JavaScript projects. This comprehensive setup ensures that most common dependencies are readily available, streamlining the CI/CD process significantly.

On the other hand, self-hosted runners are set up and maintained by users, providing more control over the tools, operating system, and hardware used in the CI/CD process. While this offers the flexibility to tailor the environment to specific needs, it also comes with the responsibility of ensuring that all necessary tools are installed and configured correctly. In cases where yarn is not installed on these self-hosted runners, the system is unable to execute tasks that require yarn, leading to the aforementioned error.

This discrepancy in environments is the crux of the issue. When workflows are migrated from GitHub-hosted to self-hosted runners without ensuring parity in the toolset, it's common to encounter this error. Tools and dependencies that were available out-of-the-box on GitHub's servers might be missing in the custom setup of a self-hosted runner. As a result, workflows that function flawlessly in a GitHub-hosted environment may fail when executed on a self-hosted runner, unless the environment is meticulously configured to match.

The Role of Self-Hosted Runners and ARC

The shift towards self-hosted runners in GitHub Actions is driven by a desire for greater control and enhanced performance in CI/CD environments. Many organizations choose this route for several compelling reasons. By hosting their own runners, they gain the ability to customize the environment to their specific needs, lower the overall costs, and potentially improve build and deployment times by leveraging their own infrastructure.

The Actions Runner Controller (ARC) emerges as a pivotal tool in this scenario, particularly for organizations leveraging Kubernetes. ARC facilitates the management of self-hosted runners on Kubernetes, offering a scalable and efficient way to handle GitHub Actions workflows. It automates the deployment and management of runners, making it easier to maintain and scale runners as per the demand of the workflow.

However, this approach introduces a notable challenge: environmental consistency. While ARC provides the mechanisms to deploy runners dynamically in a Kubernetes cluster, it does not inherently solve the issue of ensuring that these runners are equipped with the necessary tools and configurations. Consequently, if the container images used in Kubernetes don't have the same toolset - notably, the absence of yarn - as the GitHub-hosted runners, the error in question arises.

Introducing DimeRun

Enter DimeRun, a revolutionary service designed to bridge the gap between the customizable nature of self-hosted runners and the reliability of official GitHub runners. DimeRun stands out by offering virtual machine (VM) based runners that replicate the environment of GitHub's official runners. This replication ensures that essential tools, including yarn, are readily available, effectively addressing the common error encountered in self-hosted setups.

DimeRun's approach is a game-changer for organizations struggling with the complexities of setting up and maintaining self-hosted runners. By offering an environment identical to that of GitHub's official runners, DimeRun removes the burden of manually configuring and updating the running environment. This not only streamlines the setup process but also significantly reduces the likelihood of encountering errors related to missing tools or incompatible configurations.

Benefits of DimeRun

DimeRun's VM-based runners bring a host of advantages. Firstly, they offer cost-effectiveness, making it an attractive option for businesses looking to optimize their expenditure on CI/CD processes. By leveraging DimeRun, organizations can enjoy the economic benefits of self-hosted runners without the hefty investment in infrastructure and maintenance.

Moreover, DimeRun enhances performance and reliability. The VM-based runners are designed to provide faster processing speeds, ensuring that workflows are executed more efficiently. This increase in speed can be a critical factor in reducing the time-to-market for software products. Additionally, DimeRun offers persistent disks, which enhance the stability and reliability of the runners, ensuring consistent performance over time.

Conclusion

In conclusion, DimeRun emerges as an optimal solution for businesses that seek the efficiency and customization of self-hosted runners but wish to avoid the complexities and maintenance hassles associated with them. By choosing DimeRun, organizations can circumvent the common 'Unable to locate executable file: yarn' error, ensuring smooth and efficient workflows in their CI/CD pipelines. DimeRun not only simplifies the setup process but also brings enhanced performance, reliability, and cost-effectiveness, making it a compelling choice for modern software development needs.

Tutorial: How to start a self-hosted GitHub Actions runner in 1 minute

If you prefer to watch a video, the first 30 seconds of the video below shows how to start a GitHub Actions runner on DimeRun:

First of all, open https://beta.dime.run/ and type in your username and password. You will see something like this:

Click "New runner". You have a few options and will be guided through the process.

The first step is to choose if the runner is for a personal repository or an organization.

Here I'm choosing "an organzation". If you choose "a personal repository", it will ask for the repository URL afterwards.

When you choose to start the runner for an organization, you will then have two choices. GitHub allows you to create the runner for all repositories in the organzation. Alternatively, you can also create the runner for a specific repository under that organization.

Next you will be asked to provide your organization name. If you choose to start the runner for a specific repository, you will be asked for the repository URL instead.

Finally you will be provided with a page like this:

Clicking on the first button will bring you to a GitHub settings page.

When running a self-hosted runner on your own machines, you also go to this settings page to get the commands to configure and start the runner. Now with DimeRun, we will be running the commands for you. But you still need to provide us with the correct command arguments.

Click on the ./config.sh line to copy the command, and go back to DimeRun and paste it.

After pasting the config line, you also get to choose a product. Then create "Start runner" and the runner will be started after a while. You will also be able to see it on GitHub.

To use the runner, change your workflow file to something like

runs-on: dimerun-d3-ubuntu2204

See this file for an example: https://github.com/dimerun/demo-pd/blob/main/.github/workflows/demo.yaml