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 theworking-directory at different levels in your workflow file. Here’s how:

Workflow Level

Define thedefault-working-directory for the entire workflow in thedefaults section:

defaults:run:working-directory:./global-scripts

Effect: Allrun commands in the workflow will execute from the./global-scripts directory unless overridden.

Job Level

Set theworking-directory for all steps within a specific job:

jobs:example-job:runs-on:ubuntu-latestdefaults:run:working-directory:./job-scriptssteps:-name:Run job-level scriptrun:./script.sh

Effect: Allrun commands in theexample-job will execute from the./job-scripts directory.

Step Level

Set theworking-directory for an individual step:

steps:-name:Run step-level scriptrun:./script.shworking-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:

Example Usage

Accessing a Tag Dynamically

If your workflow is triggered by a tag, you can extract the tag name fromGITHUB_REF:

steps:-name:Extract Tag Namerun:echo "Tag:${GITHUB_REF#refs/tags/}"

You can use this dynamic value to construct paths:

steps:-name:Run with Dynamic Tag Pathrun:echo "Using path /home/runner/work/_actions/my-actions/my-actions/v1/"

Referencing the Repository Workspace

steps:-name:Use Workspacerun:ls $GITHUB_WORKSPACE

Storing Temporary Files

steps:-name:Create Temp Filerun:echo "Temporary data" > $RUNNER_TEMP/temp.txt

Using Cached Tools

steps:-name:Check Tool Cacherun:ls $RUNNER_TOOL_CACHE

Where Do Action Files Go?

Path

/home/runner/work/_actions

Example Structure

For the actionactions/checkout@v4:

/home/runner/work/_actions/├── actions│   └── checkout│       └── v4(action files)

Accessing Custom Files

If you have a custom filehello-world.py included in a custom actionmy-actions/my-actions@v1:

/home/runner/work/_actions/├── my-actions│   └── my-actions│       └── v1│           └── hello-world.py

Example Workflow Step

steps:-name:Run custom Python scriptrun: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

Best Practices

1. Useworking-directory Option: Set theworking-directory explicitly for custom workflows.
2. Avoid Hardcoding Paths: Use environment variables likeGITHUB_WORKSPACE andRUNNER_TEMP for compatibility.
3. Extract Tags Dynamically: UseGITHUB_REF to dynamically determine tags and construct paths.
4. 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!