Understanding GitHub Actions Working Directory
GitHub Actions provides a powerful platform for automating workflows directly within your GitHub repository. A key part of understanding how workflows operate is knowing where files are stored during execution. In this article, we'll explore the default working directory, where action files are downloaded, and how you can manage these paths effectively.
Default Working Directory
Path
/home/runner/work/<repository-name>/<repository-name>
Example Structure
/home/runner/work/
├── my-project
│ └── my-project (repository files go here)
Setting Working Directory
You can set the working-directory
at different levels in your workflow file. Here’s how:
Workflow Level
Define the default-working-directory
for the entire workflow in the defaults
section:
defaults:
run:
working-directory: ./global-scripts
Effect: All run
commands in the workflow will execute from the ./global-scripts
directory unless overridden.
Job Level
Set the working-directory
for all steps within a specific job:
jobs:
example-job:
runs-on: ubuntu-latest
defaults:
run:
working-directory: ./job-scripts
steps:
- name: Run job-level script
run: ./script.sh
Effect: All run
commands in the example-job
will execute from the ./job-scripts
directory.
Step Level
Set the working-directory
for an individual step:
steps:
- name: Run step-level script
run: ./script.sh
working-directory: ./step-scripts
Effect: Only this specific step will execute from the ./step-scripts
directory.
Environment Variables Related to Paths
GitHub Actions runners expose several environment variables that you can use to dynamically reference paths during workflows. These include:
Variable | Description |
---|---|
GITHUB_WORKSPACE |
The default working directory of the repository. Equivalent to /home/runner/work/<repo>/<repo> . |
RUNNER_TEMP |
Path to a directory for temporary files. Equivalent to /home/runner/work/_temp . |
RUNNER_TOOL_CACHE |
Directory for cached tools and dependencies. Equivalent to /opt/hostedtoolcache . |
GITHUB_ACTION_PATH |
Path to the action's files when using a custom or third-party action. |
GITHUB_ENV |
File path for exporting environment variables for subsequent steps. |
GITHUB_PATH |
File path for appending to the system PATH for subsequent steps. |
GITHUB_REF |
The full reference (branch or tag) that triggered the workflow. |
Example Usage
Accessing a Tag Dynamically
If your workflow is triggered by a tag, you can extract the tag name from GITHUB_REF
:
steps:
- name: Extract Tag Name
run: echo "Tag: ${GITHUB_REF#refs/tags/}"
You can use this dynamic value to construct paths:
steps:
- name: Run with Dynamic Tag Path
run: echo "Using path /home/runner/work/_actions/my-actions/my-actions/v1/"
Referencing the Repository Workspace
steps:
- name: Use Workspace
run: ls $GITHUB_WORKSPACE
Storing Temporary Files
steps:
- name: Create Temp File
run: echo "Temporary data" > $RUNNER_TEMP/temp.txt
Using Cached Tools
steps:
- name: Check Tool Cache
run: ls $RUNNER_TOOL_CACHE
Where Do Action Files Go?
Path
/home/runner/work/_actions
Example Structure
For the action actions/checkout@v4
:
/home/runner/work/_actions/
├── actions
│ └── checkout
│ └── v4 (action files)
Accessing Custom Files
If you have a custom file hello-world.py
included in a custom action my-actions/my-actions@v1
:
/home/runner/work/_actions/
├── my-actions
│ └── my-actions
│ └── v1
│ └── hello-world.py
Example Workflow Step
steps:
- name: Run custom Python script
run: python /home/runner/work/_actions/my-actions/my-actions/v1/hello-world.py
Temporary and Cache Directories
Temporary Directory
/home/runner/work/_temp
Example 1 Structure
/home/runner/work/
├── _temp
└── (temporary files)
Tool Cache Directory
/opt/hostedtoolcache
Example 2 Structure
/opt/hostedtoolcache/
├── (cached tools and dependencies)
Cleaning Up Directories
All files and directories created during a workflow run are ephemeral and automatically cleaned up on GitHub-hosted runners. For self-hosted runners, you may need to manage cleanup manually to avoid storage issues.
Summary of Key Paths
Path | Purpose |
---|---|
/home/runner/work/<repo>/<repo> |
Default working directory for workflows. |
/home/runner/work/_actions |
Directory for downloaded action files. |
/home/runner/work/_temp |
Temporary file storage for workflows. |
/opt/hostedtoolcache |
Tool cache for reusable dependencies. |
Best Practices
-
Use
working-directory
Option: Set theworking-directory
explicitly for custom workflows. -
Avoid Hardcoding Paths: Use environment variables like
GITHUB_WORKSPACE
andRUNNER_TEMP
for compatibility. -
Extract Tags Dynamically: Use
GITHUB_REF
to dynamically determine tags and construct paths. - Clean Up for Self-Hosted Runners: Implement cleanup scripts to manage storage effectively.
By understanding the directory structure of GitHub Actions runners, you can design workflows that are more efficient, portable, and easier to debug. Happy automating!
Top comments (2)
Very helpful, thanks!
Nice work thanks for sharing