Understanding GitHub Actions Working Directory

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

1. Use working-directory Option: Set the working-directory explicitly for custom workflows.
2. Avoid Hardcoding Paths: Use environment variables like GITHUB_WORKSPACE and RUNNER_TEMP for compatibility.
3. Extract Tags Dynamically: Use GITHUB_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!

Comments

[Adam]

Very helpful, thanks!

[Okoro chimezie bright]

Nice work thanks for sharing