The orchestration of continuous integration and continuous delivery (CI/CD) pipelines within GitHub Actions relies heavily on the precise management of the filesystem. At the core of this process is the working directory, a conceptual and physical location on the runner's disk where the shell executes commands and interacts with the repository's source code. Understanding the nuances of the working directory is not merely a matter of convenience; it is a technical requirement for ensuring that scripts, binaries, and configuration files are accessed correctly. When a workflow is triggered, GitHub Actions provisions a runner—either GitHub-hosted or self-hosted—and prepares an environment where the repository is cloned. The default behavior of the system is to operate from the topmost level of the repository tree, but as projects grow in complexity, particularly in monorepo architectures, the need for granular control over the execution path becomes critical. Failure to align the working directory with the actual location of project assets often results in "file not found" errors or the execution of scripts in the wrong context, leading to catastrophic pipeline failures.
The Anatomy of the GitHub Actions Runner Filesystem
The filesystem of a GitHub Actions runner is structured to isolate different types of data, ranging from the actual source code to temporary artifacts and tool caches. For those utilizing GitHub-hosted runners, the environment follows a predictable pattern that allows developers to reference absolute paths when necessary, although relative paths are generally preferred.
The primary location where the repository is checked out and where most operations occur is defined by the path /home/runner/work/<repository-name>/<repository-name>. This double-nested structure is a characteristic of how GitHub handles the workspace. For example, in a project named my-project, the structure appears as follows:
/home/runner/work/
├── my-project
│ └── my-project (repository files reside here)
This specific hierarchy ensures that the runner can manage multiple versions or branches of a repository without overlapping files. The impact of this structure is that any command executed without an explicit working directory will target this innermost folder. If a developer attempts to access a file using an absolute path without accounting for this double-folder nesting, the workflow will fail to locate the target asset.
Beyond the primary workspace, the runner maintains several other critical directories that serve specialized purposes:
/home/runner/work/<repo>/<repo>: This is the default working directory for workflows, acting as the home for the cloned source code./home/runner/work/_actions: This directory is dedicated to storing downloaded action files, ensuring that third-party actions are cached and available for execution./home/runner/work/_temp: This serves as temporary file storage for workflows, providing a volatile area for data that does not need to persist across jobs./opt/hostedtoolcache: This is the tool cache for reusable dependencies, allowing the runner to quickly restore tools like Node.js, Go, or Python without re-downloading them from the internet.
Comprehensive Environment Variables for Path Resolution
To avoid the fragility of hardcoding absolute paths, GitHub Actions provides a set of built-in environment variables. These variables act as dynamic pointers, ensuring that workflows remain portable across different runners and repository names.
| Variable | Description | Equivalent Path/Value |
|---|---|---|
GITHUB_WORKSPACE |
The default working directory of the repository. | /home/runner/work/<repo>/<repo> |
RUNNER_TEMP |
Path to a directory used for temporary files. | /home/runner/work/_temp |
RUNNER_TOOL_CACHE |
Directory used for cached tools and dependencies. | /opt/hostedtoolcache |
GITHUB_ACTION_PATH |
The path to the action's files when using custom or third-party actions. | Variable based on action location |
GITHUB_ENV |
File path used for exporting environment variables to subsequent steps. | Specific to the runner instance |
GITHUB_PATH |
File path used for appending to the system PATH for subsequent steps. | Specific to the runner instance |
GITHUB_REF |
The full reference (branch or tag) that triggered the workflow. | e.g., refs/heads/main |
The use of GITHUB_WORKSPACE is particularly vital. Because the absolute path includes the repository name, which can change or be renamed, referencing GITHUB_WORKSPACE ensures that the script always points to the root of the current checkout regardless of the environment. Similarly, RUNNER_TEMP allows for the creation of temporary files without cluttering the main source directory, which is essential for maintaining a clean workspace and avoiding conflicts during concurrent job executions.
Hierarchical Control of the Working Directory
GitHub Actions offers a tiered approach to defining the working directory. This allows developers to set a broad default and then narrow that focus as they move from the workflow level to individual jobs and finally to specific steps.
Workflow-Level Defaults
At the highest level of a workflow file, a global default can be established. This is most effective when all jobs in the entire workflow are intended to operate within a common directory structure, such as a shared source folder.
To implement this, the defaults section is used at the top of the YAML configuration:
yaml
defaults:
run:
working-directory: ./global-scripts
When this is configured, every run command across every job in the workflow will execute from the ./global-scripts directory. This eliminates the need to repeatedly specify the directory for every step, reducing boilerplate code and making the YAML file more readable.
Job-Level Defaults
For workflows with multiple jobs that require different contexts, the working-directory can be defined at the job level. This is particularly useful in complex projects or monorepos where one job might handle the frontend in one directory and another job handles the backend in another.
The implementation follows this structure:
yaml
jobs:
example-job:
runs-on: ubuntu-latest
defaults:
run:
working-directory: ./job-scripts
steps:
- name: Run job-level script
run: ./script.sh
In this scenario, all run commands within example-job will execute from ./job-scripts. The impact of this configuration is that it creates a localized context for the job, ensuring that all subsequent steps are aligned with the necessary files without requiring individual step overrides.
Step-Level Overrides
The most granular control is achieved by specifying the working-directory for a specific step. This takes precedence over both job-level and workflow-level defaults. This is the ideal solution for tasks that are outliers—such as running a single cleanup script located in a utility folder while the rest of the job operates in the source directory.
The configuration for a step-level override is as follows:
yaml
steps:
- name: Run step-level script
run: ./script.sh
working-directory: ./step-scripts
In this instance, only this specific step will execute from ./step-scripts. Once this step completes, the runner reverts to the default directory specified at the job or workflow level for the next step.
Relative Pathing and Root Context
A common point of confusion for developers new to GitHub Actions is whether the working directory starts at the system root (/) or the repository root. In GitHub Actions, the working directory is relative to the root of your repository.
This means that you do not need to start your paths with a leading slash. For example, if you have a directory named repo at the root of your project, you can specify it simply as repo.
Consider a scenario where a developer needs to execute a script in a nested directory. The correct approach is to use a relative path:
yaml
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Run a multi-line script
run: |
echo Add your commands here
echo Use a new line for each command
working-directory: repo
In this example, the working-directory is set to repo. This tells the runner to change the current directory to the repo folder before executing the echo commands. Because the path is relative to the repository root, the runner correctly resolves the location without needing the full absolute path.
Best Practices for Advanced Path Management
To ensure that workflows are robust, portable, and maintainable, certain engineering standards should be followed regarding directory management.
Avoid Hardcoding Absolute Paths
Hardcoding a path like /home/runner/work/my-repo/my-repo is a dangerous practice. If the repository is renamed or if the workflow is moved to a self-hosted runner with a different filesystem layout, the hardcoded path will break. Instead, always use environment variables.
The use of GITHUB_WORKSPACE allows the workflow to adapt to the environment dynamically. For example, instead of referencing a fixed path, a developer should use:
bash
cd $GITHUB_WORKSPACE/my-folder
Dynamic Path Construction with GITHUB_REF
In advanced scenarios, the directory path might depend on the branch or tag that triggered the workflow. By using the GITHUB_REF variable, developers can dynamically construct paths to target specific versions of the code or specific deployment directories. This prevents the need for static pathing and allows the workflow to be more flexible.
Manual Cleanup for Self-Hosted Runners
While GitHub-hosted runners are ephemeral and destroyed after each run, self-hosted runners are persistent. This introduces a significant risk: storage exhaustion. Because the runner continues to download actions into /home/runner/work/_actions and store temporary files in /home/runner/work/_temp, the disk can fill up over time.
Developers using self-hosted runners must implement manual cleanup scripts. These scripts should target the _temp and _actions directories to ensure that old artifacts are purged, maintaining the health and stability of the hosting machine.
Path Management Summary Table
The following table summarizes the relationship between the different directory configurations and their impact on the workflow execution.
| Configuration Level | Syntax Location | Scope of Impact | Precedence |
|---|---|---|---|
| Workflow Level | defaults: run: working-directory |
Entire Workflow | Lowest |
| Job Level | jobs.<job_id>.defaults.run.working-directory |
Specific Job | Medium |
| Step Level | steps.<step_id>.working-directory |
Single Step | Highest |
Technical Analysis of Directory Resolution
The resolution of the working directory in GitHub Actions follows a specific inheritance chain. When a run command is encountered, the runner checks for a working-directory attribute at the step level. If absent, it looks at the job level. If still not found, it defaults to the workflow level. If no defaults are specified at any level, the runner defaults to the root of the repository, which is the path provided by GITHUB_WORKSPACE.
This inheritance model provides the flexibility required for monorepos. In a monorepo, you might have a structure like:
/root
├── frontend/
├── backend/
└── shared/
You can set a workflow-level default to ./shared for general utilities, a job-level default to ./frontend for the UI build process, and a step-level override to ./backend for a specific database migration script. This layered approach minimizes redundancy and ensures that each command is executed in the context of the files it needs to manipulate.