refactor(k8s): invert scheduler env var to make affinity default

Change ACTIONS_RUNNER_USE_KUBE_SCHEDULER to ACTIONS_RUNNER_DISABLE_KUBE_SCHEDULER to make affinity-based scheduling the first-class (default) implementation. Breaking Change: - OLD: Set ACTIONS_RUNNER_USE_KUBE_SCHEDULER=true to enable affinity (opt-in) - NEW: Affinity is enabled by default, set ACTIONS_RUNNER_DISABLE_KUBE_SCHEDULER=true to disable (opt-out) Code changes: - utils.ts: Rename constant and invert useKubeScheduler() logic - rwo-affinity-test.ts: Update tests to verify default affinity behavior - ADR 0135: Update to reflect opt-out model - README: Update guidance to reflect default behavior Co-authored-by: Sisyphus <[email protected]>
docs(adr,k8s): clarify RWX enables free scheduling, RWO requires affinity
2026-04-23 00:23:47 +02:00 · 2026-04-23 00:09:05 +02:00 · 2026-04-22 22:59:40 +02:00 · 2026-04-22 22:55:49 +02:00 · 2026-02-13 22:47:15 +01:00 · 2026-02-04 11:13:03 +01:00
60 changed files with 17476 additions and 19073 deletions
@@ -1,4 +0,0 @@
-dist/
-lib/
-node_modules/
-**/tests/**
@@ -1,56 +0,0 @@
-{
-  "plugins": ["@typescript-eslint"],
-  "extends": ["plugin:github/recommended"],
-  "parser": "@typescript-eslint/parser",
-  "parserOptions": {
-    "ecmaVersion": 9,
-    "sourceType": "module",
-    "project": "./tsconfig.json"
-  },
-  "rules": {
-    "eslint-comments/no-use": "off",
-    "import/no-namespace": "off",
-    "no-constant-condition": "off",
-    "no-unused-vars": "off",
-    "i18n-text/no-en": "off",
-    "@typescript-eslint/no-unused-vars": "error",
-    "@typescript-eslint/explicit-member-accessibility": ["error", {"accessibility": "no-public"}],
-    "@typescript-eslint/no-require-imports": "error",
-    "@typescript-eslint/array-type": "error",
-    "@typescript-eslint/await-thenable": "error",
-    "camelcase": "off",
-    "@typescript-eslint/explicit-function-return-type": ["error", {"allowExpressions": true}],
-    "@typescript-eslint/func-call-spacing": ["error", "never"],
-    "@typescript-eslint/no-array-constructor": "error",
-    "@typescript-eslint/no-empty-interface": "error",
-    "@typescript-eslint/no-explicit-any": "warn",
-    "@typescript-eslint/no-extraneous-class": "error",
-    "@typescript-eslint/no-floating-promises": "error",
-    "@typescript-eslint/no-for-in-array": "error",
-    "@typescript-eslint/no-inferrable-types": "error",
-    "@typescript-eslint/no-misused-new": "error",
-    "@typescript-eslint/no-namespace": "error",
-    "@typescript-eslint/no-non-null-assertion": "warn",
-    "@typescript-eslint/no-unnecessary-qualifier": "error",
-    "@typescript-eslint/no-unnecessary-type-assertion": "error",
-    "@typescript-eslint/no-useless-constructor": "error",
-    "@typescript-eslint/no-var-requires": "error",
-    "@typescript-eslint/prefer-for-of": "warn",
-    "@typescript-eslint/prefer-function-type": "warn",
-    "@typescript-eslint/prefer-includes": "error",
-    "@typescript-eslint/prefer-string-starts-ends-with": "error",
-    "@typescript-eslint/promise-function-async": "error",
-    "@typescript-eslint/require-array-sort-compare": "error",
-    "@typescript-eslint/restrict-plus-operands": "error",
-    "semi": "off",
-    "@typescript-eslint/semi": ["error", "never"],
-    "@typescript-eslint/type-annotation-spacing": "error",
-    "@typescript-eslint/unbound-method": "error",
-    "no-shadow": "off",
-    "@typescript-eslint/no-shadow": ["error"]
-  },
-  "env": {
-    "node": true,
-    "es6": true
-  }
-}
@@ -0,0 +1 @@
+*.png filter=lfs diff=lfs merge=lfs -text
@@ -0,0 +1,28 @@
+version: 2
+
+updates:
+  # Group updates into a single PR per workspace package
+  - package-ecosystem: npm
+    directory: "/packages/docker"
+    schedule:
+      interval: weekly
+    groups:
+      all-dependencies:
+        patterns:
+          - "*"
+  - package-ecosystem: npm
+    directory: "/packages/hooklib"
+    schedule:
+      interval: weekly
+    groups:
+      all-dependencies:
+        patterns:
+          - "*"
+  - package-ecosystem: npm
+    directory: "/packages/k8s"
+    schedule:
+      interval: weekly
+    groups:
+      all-dependencies:
+        patterns:
+          - "*"
@@ -6,14 +6,62 @@ on:
    paths-ignore:
    - '**.md'
  workflow_dispatch:
+
 jobs:
-  build:
+  format-and-lint:
+    name: Format & Lint Checks
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+        name: Install dependencies
+      - run: npm run bootstrap
+        name: Bootstrap the packages
+      - run: npm run build-all
+        name: Build packages
+      - run: npm run format-check
+        name: Check formatting
+      - name: Check linter
+        run: |
+          npm run lint
+          git diff --exit-code -- . ':!packages/k8s/tests/test-kind.yaml'
+
+  docker-tests:
+    name: Docker Hook Tests
+    runs-on: ubuntu-latest
+    needs: format-and-lint
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+        name: Install dependencies
+      - run: npm run bootstrap
+        name: Bootstrap the packages
+      - run: npm run build-all
+        name: Build packages
+      - name: Run Docker tests
+        run: npm run test --prefix packages/docker
+
+  k8s-tests:
+    name: Kubernetes Hook Tests
+    runs-on: ubuntu-latest
+    needs: format-and-lint
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: npm
      - run: sed -i "s|{{PATHTOREPO}}|$(pwd)|" packages/k8s/tests/test-kind.yaml
        name: Setup kind cluster yaml config
-      - uses: helm/[email protected]
+      - uses: helm/kind-action@v1.12.0
        with:
          config: packages/k8s/tests/test-kind.yaml
      - run: npm install
@@ -22,10 +70,5 @@ jobs:
        name: Bootstrap the packages
      - run: npm run build-all
        name: Build packages
-      - run: npm run format-check
-      - name: Check linter
-        run: |
-          npm run lint
-          git diff --exit-code -- ':!packages/k8s/tests/test-kind.yaml'
-      - name: Run tests
-        run: npm run test
+      - name: Run Kubernetes tests
+        run: npm run test --prefix packages/k8s
@@ -38,11 +38,11 @@ jobs:

    steps:
    - name: Checkout repository
-      uses: actions/checkout@v3
+      uses: actions/checkout@v5

    # Initializes the CodeQL tools for scanning.
    - name: Initialize CodeQL
-      uses: github/codeql-action/init@v2
+      uses: github/codeql-action/init@v3
      with:
        languages: ${{ matrix.language }}
        # If you wish to specify custom queries, you can do so here or in a config file.
@@ -56,7 +56,7 @@ jobs:
    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
    # If this step fails, then you should remove it and run the build manually (see below)
    - name: Autobuild
-      uses: github/codeql-action/autobuild@v2
+      uses: github/codeql-action/autobuild@v3

    # ℹ️ Command-line programs to run using the OS shell.
    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
@@ -69,4 +69,4 @@ jobs:
    #   ./location_of_script_within_repo/buildscript.sh

    - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v2
+      uses: github/codeql-action/analyze@v3
@@ -1,57 +1,74 @@
 name: CD - Release new version
+
 on:
  workflow_dispatch:
+
+permissions:
+  contents: write
+
 jobs:
  build:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v3
-      - run: npm install
-        name: Install dependencies
-      - run: npm run bootstrap
-        name: Bootstrap the packages
-      - run: npm run build-all
-        name: Build packages
-      - uses: actions/github-script@v6
-        id: releaseNotes
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v6
        with:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          node-version: 24
+          cache: npm
+      - name: Install dependencies
+        run: npm install
+
+      - name: Bootstrap the packages
+        run: npm run bootstrap
+
+      - name: Build packages
+        run: npm run build-all
+
+      - uses: actions/github-script@v8
+        id: releaseVersion
+        with:
+          result-encoding: string
          script: |
            const fs = require('fs');
-            const hookVersion = require('./package.json').version
-            var releaseNotes = fs.readFileSync('${{ github.workspace }}/releaseNotes.md', 'utf8').replace(/<HOOK_VERSION>/g, hookVersion)
-            console.log(releaseNotes)
-            core.setOutput('version', hookVersion);
-            core.setOutput('note', releaseNotes);
+            return require('./package.json').version
+
      - name: Zip up releases
        run: |
-          zip -r -j actions-runner-hooks-docker-${{ steps.releaseNotes.outputs.version }}.zip packages/docker/dist
-          zip -r -j actions-runner-hooks-k8s-${{ steps.releaseNotes.outputs.version }}.zip packages/k8s/dist
-      - uses: actions/create-release@v1
-        id: createRelease
-        name: Create ${{ steps.releaseNotes.outputs.version }} Hook Release
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          zip -r -j actions-runner-hooks-docker-${{ steps.releaseVersion.outputs.result }}.zip packages/docker/dist
+          zip -r -j actions-runner-hooks-k8s-${{ steps.releaseVersion.outputs.result }}.zip packages/k8s/dist
+
+      - name: Calculate SHA
+        id: sha
+        shell: bash
+        run: |
+          sha_docker=$(sha256sum actions-runner-hooks-docker-${{ steps.releaseVersion.outputs.result }}.zip | awk '{print $1}')
+          echo "Docker SHA: $sha_docker"
+          echo "docker-sha=$sha_docker" >> $GITHUB_OUTPUT
+          sha_k8s=$(sha256sum actions-runner-hooks-k8s-${{ steps.releaseVersion.outputs.result }}.zip | awk '{print $1}')
+          echo "K8s SHA: $sha_k8s"
+          echo "k8s-sha=$sha_k8s" >> $GITHUB_OUTPUT
+
+      - name: Create release notes
+        id: releaseNotes
+        uses: actions/github-script@v8
        with:
-          tag_name: "v${{ steps.releaseNotes.outputs.version }}"
-          release_name: "v${{ steps.releaseNotes.outputs.version }}"
-          body: |
-            ${{ steps.releaseNotes.outputs.note }}
-      - name: Upload K8s hooks
-        uses: actions/upload-release-asset@v1
+          script: |
+            const fs = require('fs');
+            var releaseNotes = fs.readFileSync('${{ github.workspace }}/releaseNotes.md', 'utf8').replace(/<HOOK_VERSION>/g, '${{ steps.releaseVersion.outputs.result }}')
+            releaseNotes = releaseNotes.replace(/<DOCKER_SHA>/g, '${{ steps.sha.outputs.docker-sha }}')
+            releaseNotes = releaseNotes.replace(/<K8S_SHA>/g, '${{ steps.sha.outputs.k8s-sha }}')
+            console.log(releaseNotes)
+            fs.writeFileSync('${{ github.workspace }}/finalReleaseNotes.md', releaseNotes);
+
+      - name: Create ${{ steps.releaseVersion.outputs.result }} Hook Release
        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          upload_url: ${{ steps.createRelease.outputs.upload_url }}
-          asset_path: ${{ github.workspace }}/actions-runner-hooks-k8s-${{ steps.releaseNotes.outputs.version }}.zip
-          asset_name: actions-runner-hooks-k8s-${{ steps.releaseNotes.outputs.version }}.zip
-          asset_content_type: application/octet-stream
-      - name: Upload docker hooks
-        uses: actions/upload-release-asset@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          upload_url: ${{ steps.createRelease.outputs.upload_url }}
-          asset_path: ${{ github.workspace }}/actions-runner-hooks-docker-${{ steps.releaseNotes.outputs.version }}.zip
-          asset_name: actions-runner-hooks-docker-${{ steps.releaseNotes.outputs.version }}.zip
-          asset_content_type: application/octet-stream
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create v${{ steps.releaseVersion.outputs.result }} \
+            --title "v${{ steps.releaseVersion.outputs.result }}" \
+            --repo ${{ github.repository }} \
+            --notes-file ${{ github.workspace }}/finalReleaseNotes.md \
+            --latest \
+            ${{ github.workspace }}/actions-runner-hooks-k8s-${{ steps.releaseVersion.outputs.result }}.zip \
+            ${{ github.workspace }}/actions-runner-hooks-docker-${{ steps.releaseVersion.outputs.result }}.zip
@@ -1 +1 @@
-* @actions/actions-runtime @actions/runner-akvelon
+* @actions/actions-compute @nikola-jokic
@@ -3,6 +3,24 @@ The Runner Container Hooks repo provides a set of packages that implement the co

 More information on how to implement your own hooks can be found in the [adr](https://github.com/actions/runner/pull/1891). The `examples` folder provides example inputs for each hook.

+### Note
+
+Thank you for your interest in this GitHub action, however, right now we are not taking contributions. 
+
+We continue to focus our resources on strategic areas that help our customers be successful while making developers' lives easier. While GitHub Actions remains a key part of this vision, we are allocating resources towards other areas of Actions and are not taking contributions to this repository at this time. The GitHub public roadmap is the best place to follow along for any updates on features we’re working on and what stage they’re in.
+
+We are taking the following steps to better direct requests related to GitHub Actions, including:
+
+1. We will be directing questions and support requests to our [Community Discussions area](https://github.com/orgs/community/discussions/categories/actions)
+
+2. High Priority bugs can be reported through Community Discussions or you can report these to our support team https://support.github.com/contact/bug-report.
+
+3. Security Issues should be handled as per our [security.md](security.md)
+
+We will still provide security updates for this project and fix major breaking changes during this time.
+
+You are welcome to still raise bugs in this repo.
+
 ## Background 

 Three projects are included in the `packages` folder
@@ -10,10 +28,6 @@ Three projects are included in the `packages` folder
 - docker: A hook implementation of the runner's docker implementation. More details can be found in the [readme](./packages/docker/README.md)
 - hooklib: a shared library which contains typescript definitions and utilities that the other projects consume

-### Requirements
-
-We welcome contributions.  See [how to contribute to get started](./CONTRIBUTING.md).
-
 ## License 

 This project is licensed under the terms of the MIT open source license. Please refer to [MIT](./LICENSE.md) for the full terms.
@@ -28,4 +42,4 @@ Find a bug? Please file an issue in this repository using the issue templates.

 ## Code of Conduct

-See our [Code of Conduct](./CODE_OF_CONDUCT.MD)
+See our [Code of Conduct](./CODE_OF_CONDUCT.MD)
@@ -0,0 +1,184 @@
+# ADR 0072: Using Ephemeral Containers
+
+**Date:** 27 March 2023
+
+**Status**: Rejected <!--Accepted|Rejected|Superceded|Deprecated-->
+
+## Context
+
+We are evaluating using Kubernetes [ephemeral containers](https://kubernetes.io/docs/concepts/workloads/pods/ephemeral-containers/) as a drop-in replacement for creating pods for [jobs that run in containers](https://docs.github.com/en/actions/using-jobs/running-jobs-in-a-container) and [service containers](https://docs.github.com/en/actions/using-containerized-services/about-service-containers).
+
+The main motivator behind using ephemeral containers is to eliminate the need for [Persistent Volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/). Persistent Volume implementations vary depending on the provider and we want to avoid building a dependency on it in order to provide our end-users a consistent experience.
+
+With ephemeral containers we could leverage [emptyDir volumes](https://kubernetes.io/docs/concepts/storage/volumes/#emptydir) which fits our use case better and its behaviour is consistent across providers.
+
+However, it's important to acknowledge that ephemeral containers were not designed to handle workloads but rather provide a mechanism to inspect running containers for debugging and troubleshooting purposes.
+
+## Evaluation
+
+The criteria that we are using to evaluate whether ephemeral containers are fit for purpose are:
+
+- Networking
+- Storage
+- Security
+- Resource limits
+- Logs
+- Customizability
+
+### Networking
+
+Ephemeral containers share the networking namespace of the pod they are attached to. This means that ephemeral containers can access the same network interfaces as the pod and can communicate with other containers in the same pod. However, ephemeral containers cannot have ports configured and as such the fields ports, livenessProbe, and readinessProbe are not available [^1][^2]
+
+In this scenario we have 3 containers in a pod:
+
+- `runner`: the main container that runs the GitHub Actions job
+- `debugger`: the first ephemeral container
+- `debugger2`: the second ephemeral container
+
+By sequentially opening ports on each of these containers and connecting to them we can demonstrate that the communication flow between the runner and the debuggers is feasible.
+
+<details>
+<summary>1. Runner -> Debugger communication</summary>
+
+![runner->debugger](./images/runner-debugger.png)
+</details>
+
+<details>
+<summary>2. Debugger -> Runner communication</summary>
+
+![debugger->runner](./images/debugger-runner.png)
+</details>
+
+<details>
+<summary>3. Debugger2 -> Debugger communication</summary>
+
+![debugger2->debugger](./images/debugger2-debugger.png)
+</details>
+
+### Storage
+
+An emptyDir volume can be successfully mounted (read/write) by the runner as well as the ephemeral containers. This means that ephemeral containers can share data with the runner and other ephemeral containers.
+
+<details>
+<summary>Configuration</summary>
+
+```yaml
+# Extracted from the values.yaml for the gha-runner-scale-set helm chart
+  spec:
+    containers:
+    - name: runner
+      image: ghcr.io/actions/actions-runner:latest
+      command: ["/home/runner/run.sh"]
+      volumeMounts:
+      - mountPath: /workspace
+        name: work-volume
+    volumes:
+      - name: work-volume
+        emptyDir:
+          sizeLimit: 1Gi
+```
+
+```bash
+# The API call to the Kubernetes API used to create the ephemeral containers
+
+POD_NAME="arc-runner-set-6sfwd-runner-k7qq6"
+NAMESPACE="arc-runners"
+
+curl -v "https://<IP>:<PORT>/api/v1/namespaces/$NAMESPACE/pods/$POD_NAME/ephemeralcontainers" \
+  -X PATCH \
+  -H 'Content-Type: application/strategic-merge-patch+json' \
+  --cacert <PATH_TO_CACERT> \
+  --cert <PATH_TO_CERT> \
+  --key <PATH_TO_CLIENT_KEY> \
+  -d '
+{
+    "spec":
+    {
+        "ephemeralContainers":
+        [
+            {
+                "name": "debugger",
+                "command": ["sh"],
+                "image": "ghcr.io/actions/actions-runner:latest",
+                "targetContainerName": "runner",
+                "stdin": true,
+                "tty": true,
+                "volumeMounts": [{
+                    "mountPath": "/workspace",
+                    "name": "work-volume",
+                    "readOnly": false
+                }]
+            },
+            {
+                "name": "debugger2",
+                "command": ["sh"],
+                "image": "ghcr.io/actions/actions-runner:latest",
+                "targetContainerName": "runner",
+                "stdin": true,
+                "tty": true,
+                "volumeMounts": [{
+                    "mountPath": "/workspace",
+                    "name": "work-volume",
+                    "readOnly": false
+                }]
+            }
+        ]
+    }
+}'
+```
+
+</details>
+
+<details>
+<summary>emptyDir volume mount</summary>
+
+![emptyDir volume mount](./images/emptyDir_volume.png)
+
+</details>
+
+### Security
+
+According to the [ephemeral containers API specification](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#ephemeralcontainer-v1-core) the configuration of the `securityContext` field is possible.
+
+Ephemeral containers share the same network namespace as the pod they are attached to. This means that ephemeral containers can access the same network interfaces as the pod and can communicate with other containers in the same pod.
+
+It is also possible for ephemeral containers to [share the process namespace](https://kubernetes.io/docs/tasks/configure-pod-container/share-process-namespace/) with the other containers in the pod. This is disabled by default.
+
+The above could have unpredictable security implications.
+
+### Resource limits
+
+Resources are not allowed for ephemeral containers. Ephemeral containers use spare resources already allocated to the pod. [^1] This is a major drawback as it means that ephemeral containers cannot be configured to have resource limits.
+
+There are no guaranteed resources for ad-hoc troubleshooting. If troubleshooting causes a pod to exceed its resource limit it may be evicted. [^3]
+
+### Logs
+
+Since ephemeral containers can share volumes with the runner container, it's possible to write logs to the same volume and have them available to the runner container.
+
+### Customizability
+
+Ephemeral containers can run any image and tag provided, they can be customized to run any arbitrary job. However, it's important to note that the following are not feasible:
+
+- Lifecycle is not allowed for ephemeral containers
+    - Ephemeral containers will stop when their command exits, such as exiting a shell, and they will not be restarted. Unlike `kubectl exec`, processes in Ephemeral Containers will not receive an `EOF` if their connections are interrupted, so shells won't automatically exit on disconnect. There is no API support for killing or restarting an ephemeral container. The only way to exit the container is to send it an OS signal. [^4]
+- Probes are not allowed for ephemeral containers.
+- Ports are not allowed for ephemeral containers.
+
+## Decision
+
+While the evaluation shows that ephemeral containers can be used to run jobs in containers, it's important to acknowledge that ephemeral containers were not designed to handle workloads but rather provide a mechanism to inspect running containers for debugging and troubleshooting purposes.
+
+Given the limitations of ephemeral containers, we decided not to use them outside of their intended purpose.
+
+## Consequences
+
+Proposal rejected, no further action required. This document will be used as a reference for future discussions.
+
+[^1]: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#ephemeralcontainer-v1-core
+
+[^2]: https://kubernetes.io/docs/concepts/workloads/pods/ephemeral-containers/
+
+[^3]: https://github.com/kubernetes/enhancements/blob/master/keps/sig-node/277-ephemeral-containers/README.md#notesconstraintscaveats
+
+[^4]: https://github.com/kubernetes/enhancements/blob/master/keps/sig-node/277-ephemeral-containers/README.md#ephemeral-container-lifecycle
@@ -0,0 +1,34 @@
+# ADR 0096: Hook extensions
+
+**Date:** 3 August 2023
+
+**Status**: Superceded [^1]
+
+## Context
+
+The current implementation of container hooks does not allow users to customize the pods created by the hook. While the implementation is designed to be used as is or as a starting point, building and maintaining a custom hook implementation just to specify additional fields is not a good user experience.
+
+## Decision
+
+We have decided to add hook extensions to the container hook implementation. This will allow users to customize the pods created by the hook by specifying additional fields. The hook extensions will be implemented in a way that is backwards-compatible with the existing hook implementation.
+
+To allow customization, the runner executing the hook should have `ACTIONS_RUNNER_CONTAINER_HOOK_TEMPLATE` environment variable pointing to a yaml file on the runner system. The extension specified in that file will be applied both for job pods, and container steps.
+
+If environment variable is set, but the file can't be read, the hook will fail, signaling incorrect configuration.
+
+If the environment variable does not exist, the hook will apply the default spec.
+
+In case the hook is able to read the extended spec, it will first create a default configuration, and then merged modified fields in the following way:
+
+1. The `.metadata` fields that will be appended if they are not reserved are `labels` and `annotations`.
+2. The pod spec fields except for `containers` and `volumes` are applied from the template, possibly overwriting the field.
+3. The volumes are applied in form of appending additional volumes to the default volumes.
+4. The containers are merged based on the name assigned to them:
+    1. If the name of the container *is not* "$job", the entire spec of the container will be added to the pod definition.
+    2. If the name of the container *is* "$job", the `name` and the `image` fields are going to be ignored and the spec will be applied so that `env`, `volumeMounts`, `ports` are appended to the default container spec created by the hook, while the rest of the fields are going to be applied to the newly created container spec.
+
+## Consequences
+
+The addition of hook extensions will provide a better user experience for users who need to customize the pods created by the container hook. However, it will require additional effort to provide the template to the runner pod, and configure it properly.
+
+[^1]: Superseded by [ADR 0134](0134-hook-extensions.md)
@@ -0,0 +1,41 @@
+# ADR 0134: Hook extensions
+
+**Date:** 20 February 2024
+
+**Status**: Accepted [^1]
+
+## Context
+
+The current implementation of container hooks does not allow users to customize the pods created by the hook. 
+While the implementation is designed to be used as is or as a starting point, building and maintaining a custom hook implementation just to specify additional fields is not a good user experience.
+
+## Decision
+
+We have decided to add hook extensions to the container hook implementation. 
+This will allow users to customize the pods created by the hook by specifying additional fields. 
+The hook extensions will be implemented in a way that is backwards-compatible with the existing hook implementation.
+
+To allow customization, the runner executing the hook should have `ACTIONS_RUNNER_CONTAINER_HOOK_TEMPLATE` environment variable pointing to a yaml file on the runner system. 
+The extension specified in that file will be applied both for job pods, and container steps.
+
+If environment variable is set, but the file can't be read, the hook will fail, signaling incorrect configuration.
+
+If the environment variable does not exist, the hook will apply the default spec.
+
+In case the hook is able to read the extended spec, it will first create a default configuration, and then merged modified fields in the following way:
+
+1. The `.metadata` fields that will be appended if they are not reserved are `labels` and `annotations`.
+2. The pod spec fields except for `containers` and `volumes` are applied from the template, possibly overwriting the field.
+3. The volumes are applied in form of appending additional volumes to the default volumes.
+4. The containers are merged based on the name assigned to them:
+   1. If the name of the container *is* "$job", the `name` and the `image` fields are going to be ignored and the spec will be applied so that `env`, `volumeMounts`, `ports` are appended to the default container spec created by the hook, while the rest of the fields are going to be applied to the newly created container spec.
+   2. If the name of the container *starts with* "$", and matches the name of the [container service](https://docs.github.com/en/actions/using-containerized-services/about-service-containers), the `name` and the `image` fields are going to be ignored and the spec will be applied to that service container, so that `env`, `volumeMounts`, `ports` are appended to the default container spec for service created by the hook, while the rest of the fields are going to be applied to the created container spec. 
+      If there is no container service with such name defined in the workflow, such spec extension will be ignored.  
+   3. If the name of the container *does not start with* "$", the entire spec of the container will be added to the pod definition.
+
+## Consequences
+
+The addition of hook extensions will provide a better user experience for users who need to customize the pods created by the container hook. 
+However, it will require additional effort to provide the template to the runner pod, and configure it properly.
+
+[^1]: Supersedes [ADR 0096](0096-hook-extensions.md)
@@ -0,0 +1,55 @@
+# ADR 0135: RWX volume strategy and RWO affinity fallback
+
+**Date:** 22 April 2026
+
+**Status**: Accepted
+
+## Context
+
+The Kubernetes hook implementation for GitHub Actions runners requires access to the runner's working directory (`_work`) within the dynamically created job pods. This shared access is typically managed via Persistent Volume Claims (PVCs).
+
+The choice of storage strategy significantly impacts pod scheduling. While ReadWriteOnce (RWO) volumes require job pods to be co-located on the same node as the runner pod, ReadWriteMany (RWX) volumes allow job pods to be scheduled freely across the cluster.
+
+Depending on the storage provider and cluster configuration, operators may choose between `ReadWriteMany` (RWX) or `ReadWriteOnce` (RWO) access modes. RWX is preferred because it allows the Kubernetes scheduler to place job pods on any available node, improving resource utilization and cluster flexibility. RWO restricts volume access to a single node at a time, requiring all pods using the volume to be pinned to that specific node.
+
+## Decision
+
+We have decided to establish `ReadWriteMany` (RWX) as the preferred storage strategy for the Kubernetes hook. RWX provides superior operational flexibility by enabling free scheduling of job pods across the cluster, as the shared volume is accessible from any node. This decoupling of job pods from the runner's node allows for better resource distribution and reduces the risk of node-level resource exhaustion.
+
+For environments where RWX is unavailable or undesirable, we support a `ReadWriteOnce` (RWO) fallback strategy. This fallback is implemented using node affinity to ensure that job pods are scheduled onto the same node as the runner pod that holds the RWO volume.
+
+### Operational Guidance
+
+1. **Preferred Model (RWX):** Operators should configure the runner with a PVC supporting `ReadWriteMany`.
+2. **Fallback Model (RWO):** If using `ReadWriteOnce`, the Kubernetes scheduler integration is enabled by default. Operators can optionally disable it by setting `ACTIONS_RUNNER_DISABLE_KUBE_SCHEDULER=true` (not recommended).
+3. **Node Selection:** By default, the hook applies a `requiredDuringSchedulingIgnoredDuringExecution` node affinity targeting the runner's current node (`kubernetes.io/hostname`).
+4. **Implementation Details:** 
+   - The hook determines the node name via `getCurrentNodeName()` and applies affinity in `packages/k8s/src/k8s/index.ts` (lines 101, 165).
+   - The scheduler is enabled by default. Setting `ACTIONS_RUNNER_DISABLE_KUBE_SCHEDULER=true` disables it, as defined in `packages/k8s/src/k8s/utils.ts` (line 16).
+   - The PVC claim name defaults to `${ACTIONS_RUNNER_POD_NAME}-work` unless overridden by `ACTIONS_RUNNER_CLAIM_NAME` (`packages/k8s/src/hooks/constants.ts`, lines 27-33).
+
+### Non-Recommendations
+
+We explicitly do **not** recommend the use of `spec.nodeName` for operator-driven scheduling. While the hook uses `nodeName` as a legacy fallback when `ACTIONS_RUNNER_DISABLE_KUBE_SCHEDULER` is set to `true` (`packages/k8s/src/k8s/index.ts`, lines 103, 167), this bypasses the Kubernetes scheduler and can lead to scheduling failures or resource imbalances. Operators should prefer the default affinity-based approach for RWO volumes.
+
+## Alternatives
+
+- **nodeName Bypass:** Directly setting `nodeName` bypasses the scheduler entirely. This was rejected as a recommendation because it prevents the scheduler from accounting for taints, tolerations, and resource pressure.
+- **Local Volumes:** Using local volumes tied to specific nodes. This is a subset of the RWO fallback and is supported via the affinity mechanism.
+
+## Consequences
+
+- **Flexibility:** RWX users benefit from the ability to schedule job pods on any node in the cluster, maximizing resource utilization.
+- **Node Coupling:** RWO users remain coupled to the node where the runner pod is running. The hook ensures job pods are scheduled on the same node via affinity (enabled by default) to maintain workspace integrity.
+- **Configuration:** Operators using RWO can rely on the default affinity-based scheduling. Setting `ACTIONS_RUNNER_DISABLE_KUBE_SCHEDULER=true` will fall back to legacy `nodeName` pinning (not recommended). RWX configurations do not require any special configuration for basic operation.
+
+## Migration Guidance
+
+Operators migrating from an RWO setup that relied on legacy `nodeName` behavior can continue by setting `ACTIONS_RUNNER_DISABLE_KUBE_SCHEDULER=true`, but should migrate to the default affinity-based scheduling for better scheduler integration:
+1. Remove the `ACTIONS_RUNNER_DISABLE_KUBE_SCHEDULER` environment variable to use the default affinity-based scheduling.
+2. Verify that the runner's ServiceAccount has the necessary permissions to list pods (to determine its own node).
+
+## Non-Goals
+
+- This ADR does not recommend `nodeName` as a primary or secondary configuration path for operators.
+- This ADR does not dictate specific storage providers (e.g., EBS vs. EFS vs. Azure Files), but rather the access mode strategy.
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e871545617a5df08ab48a37a0c0f441aef9e97da0a3bb8f66470be0f2246cfd4
+size 61897
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d733bd0d26cded6da8bbcf4e5dd274bb9d700b4fde5e11ccf1e528388147a995
+size 64665
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:39b5b4f5bc5419a701512d14ffa9a30e3288fe9403caf6ab8078eb905236205d
+size 341558
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:38bfd3f0f3613410245d4fc5a727b8b8203c8da3032f2630945edc7e3470efec
+size 59652
@@ -0,0 +1,122 @@
+const eslint = require('@eslint/js');
+const tseslint = require('@typescript-eslint/eslint-plugin');
+const tsparser = require('@typescript-eslint/parser');
+const globals = require('globals');
+const pluginJest = require('eslint-plugin-jest');
+
+module.exports = [
+  eslint.configs.recommended,
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      parser: tsparser,
+      parserOptions: {
+        ecmaVersion: 2018,
+        sourceType: 'module',
+        project: ['./tsconfig.json', './packages/*/tsconfig.json']
+      },
+      globals: {
+        ...globals.node,
+        ...globals.es6
+      }
+    },
+    plugins: {
+      '@typescript-eslint': tseslint,
+    },
+    rules: {
+      // Disabled rules from original config
+      'eslint-comments/no-use': 'off',
+      'import/no-namespace': 'off',
+      'no-constant-condition': 'off',
+      'no-unused-vars': 'off',
+      'i18n-text/no-en': 'off',
+      'camelcase': 'off',
+      'semi': 'off',
+      'no-shadow': 'off',
+
+      // TypeScript ESLint rules
+      '@typescript-eslint/no-unused-vars': 'error',
+      '@typescript-eslint/explicit-member-accessibility': ['error', { accessibility: 'no-public' }],
+      '@typescript-eslint/no-require-imports': 'error',
+      '@typescript-eslint/array-type': 'error',
+      '@typescript-eslint/await-thenable': 'error',
+      '@typescript-eslint/explicit-function-return-type': ['error', { allowExpressions: true }],
+      '@typescript-eslint/no-array-constructor': 'error',
+      '@typescript-eslint/no-empty-interface': 'error',
+      '@typescript-eslint/no-explicit-any': 'off', // Fixed: removed duplicate and kept only this one
+      '@typescript-eslint/no-extraneous-class': 'error',
+      '@typescript-eslint/no-floating-promises': 'error',
+      '@typescript-eslint/no-for-in-array': 'error',
+      '@typescript-eslint/no-inferrable-types': 'error',
+      '@typescript-eslint/no-misused-new': 'error',
+      '@typescript-eslint/no-namespace': 'error',
+      '@typescript-eslint/no-non-null-assertion': 'warn',
+      '@typescript-eslint/no-unnecessary-qualifier': 'error',
+      '@typescript-eslint/no-unnecessary-type-assertion': 'error',
+      '@typescript-eslint/no-useless-constructor': 'error',
+      '@typescript-eslint/no-var-requires': 'error',
+      '@typescript-eslint/prefer-for-of': 'warn',
+      '@typescript-eslint/prefer-function-type': 'warn',
+      '@typescript-eslint/prefer-includes': 'error',
+      '@typescript-eslint/prefer-string-starts-ends-with': 'error',
+      '@typescript-eslint/promise-function-async': 'error',
+      '@typescript-eslint/require-array-sort-compare': 'error',
+      '@typescript-eslint/restrict-plus-operands': 'error',
+      '@typescript-eslint/unbound-method': 'error',
+      '@typescript-eslint/no-shadow': ['error']
+    }
+  },
+  {
+    // Test files configuration - Fixed file pattern to match .ts files
+    files: ['**/*test*.ts', '**/*spec*.ts', '**/tests/**/*.ts'],
+    languageOptions: {
+      parser: tsparser,
+      parserOptions: {
+        ecmaVersion: 2018,
+        sourceType: 'module',
+        project: ['./tsconfig.json', './packages/*/tsconfig.json']
+      },
+      globals: {
+        ...globals.node,
+        ...globals.es6,
+        // Fixed Jest globals
+        describe: 'readonly',
+        it: 'readonly',
+        test: 'readonly',
+        expect: 'readonly',
+        beforeEach: 'readonly',
+        afterEach: 'readonly',
+        beforeAll: 'readonly',
+        afterAll: 'readonly',
+        jest: 'readonly'
+      }
+    },
+    plugins: {
+      '@typescript-eslint': tseslint,
+      jest: pluginJest
+    },
+    rules: {
+      // Disable no-undef for test files since Jest globals are handled above
+      'no-undef': 'off',
+      // Relax some rules for test files
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-non-null-assertion': 'off',
+      '@typescript-eslint/explicit-function-return-type': 'off'
+    }
+  },
+  {
+    files: ['**/jest.config.js', '**/jest.setup.js'],
+    languageOptions: {
+      globals: {
+        ...globals.node,
+        jest: 'readonly',
+        module: 'writable'
+      }
+    },
+    rules: {
+      '@typescript-eslint/no-require-imports': 'off',
+      '@typescript-eslint/no-var-requires': 'off',
+      'import/no-commonjs': 'off'
+    }
+  }
+];
@@ -0,0 +1,38 @@
+metadata:
+  annotations:
+    annotated-by: "extension"
+  labels:
+    labeled-by: "extension"
+spec:
+  restartPolicy: Never
+  containers:
+  - name: $job # overwrites job container
+    env:
+    - name: ENV1
+      value: "value1"
+    imagePullPolicy: Always
+    image: "busybox:1.28" # Ignored
+    command:
+    - sh
+    args:
+    - -c
+    - sleep 50
+  - name: $redis # overwrites redis service
+    env:
+      - name: ENV2
+        value: "value2"
+    image: "busybox:1.28" # Ignored
+    resources:
+      requests:
+        memory: "1Mi"
+        cpu: "1"
+      limits:
+        memory: "1Gi"
+        cpu: "2"
+  - name: side-car
+    image: "ubuntu:latest" # required
+    command:
+      - sh
+    args:
+      - -c
+      - sleep 60
@@ -4,7 +4,7 @@
  "state": {},
  "args": {
    "container": {
-      "image": "node:14.16",
+      "image": "node:22",
      "workingDirectory": "/__w/repo/repo",
      "createOptions": "--cpus 1",
      "environmentVariables": {
@@ -9,7 +9,7 @@
    }
  },
  "args": {
-    "image": "node:14.16",
+    "image": "node:22",
    "dockerfile": null,
    "entryPointArgs": [
      "-e",
@@ -1,6 +1,6 @@
 {
  "name": "hooks",
-  "version": "0.3.0",
+  "version": "0.8.1",
  "description": "Three projects are included - k8s: a kubernetes hook implementation that spins up pods dynamically to run a job - docker: A hook implementation of the runner's docker implementation  - A hook lib, which contains shared typescript definitions and utilities that the other packages consume",
  "main": "",
  "directories": {
@@ -8,10 +8,11 @@
  },
  "scripts": {
    "test": "npm run test --prefix packages/docker && npm run test --prefix packages/k8s",
-    "bootstrap": "npm install --prefix packages/hooklib && npm install --prefix packages/k8s && npm install --prefix packages/docker",
+    "bootstrap": "npm install --prefix packages/hooklib && npm ci --prefix packages/k8s && npm ci --prefix packages/docker",
    "format": "prettier --write '**/*.ts'",
    "format-check": "prettier --check '**/*.ts'",
    "lint": "eslint packages/**/*.ts",
+    "lint:fix": "eslint packages/**/*.ts --fix",
    "build-all": "npm run build --prefix packages/hooklib && npm run build --prefix packages/k8s && npm run build --prefix packages/docker"
  },
  "repository": {
@@ -25,12 +26,18 @@
  },
  "homepage": "https://github.com/actions/runner-container-hooks#readme",
  "devDependencies": {
-    "@types/jest": "^27.5.1",
-    "@types/node": "^17.0.23",
-    "@typescript-eslint/parser": "^5.18.0",
-    "eslint": "^8.12.0",
-    "eslint-plugin-github": "^4.3.6",
-    "prettier": "^2.6.2",
-    "typescript": "^4.6.3"
+    "@eslint/js": "^9.31.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.0.14",
+    "@typescript-eslint/eslint-plugin": "^8.37.0",
+    "@typescript-eslint/parser": "^8.37.0",
+    "eslint": "^9.31.0",
+    "eslint-plugin-github": "^6.0.0",
+    "globals": "^15.12.0",
+    "prettier": "^3.6.2",
+    "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "eslint-plugin-jest": "^29.0.1"
  }
 }
@@ -1,13 +1,26 @@
-// eslint-disable-next-line import/no-commonjs
 module.exports = {
  clearMocks: true,
+  preset: 'ts-jest',
  moduleFileExtensions: ['js', 'ts'],
  testEnvironment: 'node',
  testMatch: ['**/*-test.ts'],
  testRunner: 'jest-circus/runner',
+  verbose: true,
  transform: {
-    '^.+\\.ts$': 'ts-jest'
+    '^.+\\.ts$': [
+      'ts-jest',
+      {
+        tsconfig: 'tsconfig.test.json'
+      }
+    ],
+    // Transform ESM modules to CommonJS
+    '^.+\\.(js|mjs)$': ['babel-jest', {
+      presets: [['@babel/preset-env', { targets: { node: 'current' } }]]
+    }]
  },
-  setupFilesAfterEnv: ['./jest.setup.js'],
-  verbose: true
+  transformIgnorePatterns: [
+    // Transform these ESM packages
+    'node_modules/(?!(shlex|@kubernetes/client-node|openid-client|oauth4webapi|jose|uuid)/)'
+  ],
+  setupFilesAfterEnv: ['./jest.setup.js']
 }
@@ -5,25 +5,31 @@
  "main": "lib/index.js",
  "scripts": {
    "test": "jest --runInBand",
-    "build": "npx tsc && npx ncc build"
+    "build": "npx tsc && npx ncc build",
+    "format": "prettier --write '**/*.ts'",
+    "format-check": "prettier --check '**/*.ts'",
+    "lint": "eslint src/**/*.ts"
  },
  "author": "",
  "license": "MIT",
  "dependencies": {
-    "@actions/core": "^1.9.1",
-    "@actions/exec": "^1.1.1",
+    "@actions/core": "^2.0.2",
+    "@actions/exec": "^2.0.0",
    "hooklib": "file:../hooklib",
-    "uuid": "^8.3.2"
+    "shlex": "^3.0.0",
+    "uuid": "^11.1.0"
  },
  "devDependencies": {
-    "@types/jest": "^27.4.1",
-    "@types/node": "^17.0.23",
-    "@typescript-eslint/parser": "^5.18.0",
-    "@vercel/ncc": "^0.33.4",
-    "jest": "^27.5.1",
-    "ts-jest": "^27.1.4",
-    "ts-node": "^10.7.0",
-    "tsconfig-paths": "^3.14.1",
-    "typescript": "^4.6.3"
+    "@babel/core": "^7.25.2",
+    "@babel/preset-env": "^7.25.4",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.0.14",
+    "@typescript-eslint/parser": "^8.37.0",
+    "@vercel/ncc": "^0.38.3",
+    "jest": "^30.0.4",
+    "ts-jest": "^29.4.0",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.8.3"
  }
 }
@@ -43,18 +43,25 @@ export async function createContainer(

  if (args.environmentVariables) {
    for (const [key] of Object.entries(args.environmentVariables)) {
-      dockerArgs.push('-e')
-      dockerArgs.push(key)
+      dockerArgs.push('-e', key)
    }
  }

+  dockerArgs.push('-e', 'GITHUB_ACTIONS=true')
+  // Use same behavior as the runner https://github.com/actions/runner/blob/27d9c886ab9a45e0013cb462529ac85d581f8c41/src/Runner.Worker/Container/DockerCommandManager.cs#L150
+  if (!('CI' in (args.environmentVariables ?? {}))) {
+    dockerArgs.push('-e', 'CI=true')
+  }
+
  const mountVolumes = [
    ...(args.userMountVolumes || []),
    ...(args.systemMountVolumes || [])
  ]
  for (const mountVolume of mountVolumes) {
    dockerArgs.push(
-      `-v=${mountVolume.sourceVolumePath}:${mountVolume.targetVolumePath}`
+      `-v=${mountVolume.sourceVolumePath}:${mountVolume.targetVolumePath}${
+        mountVolume.readOnly ? ':ro' : ''
+      }`
    )
  }
  if (args.entryPoint) {
@@ -91,11 +98,12 @@ export async function containerPull(
  image: string,
  configLocation: string
 ): Promise<void> {
-  const dockerArgs: string[] = ['pull']
+  const dockerArgs: string[] = []
  if (configLocation) {
    dockerArgs.push('--config')
    dockerArgs.push(configLocation)
  }
+  dockerArgs.push('pull')
  dockerArgs.push(image)
  for (let i = 0; i < 3; i++) {
    try {
@@ -402,11 +410,16 @@ export async function containerRun(
  }
  if (args.environmentVariables) {
    for (const [key] of Object.entries(args.environmentVariables)) {
-      dockerArgs.push('-e')
-      dockerArgs.push(key)
+      dockerArgs.push('-e', key)
    }
  }

+  dockerArgs.push('-e', 'GITHUB_ACTIONS=true')
+  // Use same behavior as the runner https://github.com/actions/runner/blob/27d9c886ab9a45e0013cb462529ac85d581f8c41/src/Runner.Worker/Container/DockerCommandManager.cs#L150
+  if (!('CI' in (args.environmentVariables ?? {}))) {
+    dockerArgs.push('-e', 'CI=true')
+  }
+
  const mountVolumes = [
    ...(args.userMountVolumes || []),
    ...(args.systemMountVolumes || [])
@@ -443,7 +456,7 @@ export async function isContainerAlpine(containerId: string): Promise<boolean> {
    containerId,
    'sh',
    '-c',
-    "[ $(cat /etc/*release* | grep -i -e '^ID=*alpine*' -c) != 0 ] || exit 1"
+    `'[ $(cat /etc/*release* | grep -i -e "^ID=*alpine*" -c) != 0 ] || exit 1'`
  ]
  try {
    await runDockerCommand(dockerArgs)
@@ -31,16 +31,20 @@ export async function prepareJob(
    core.info('No containers exist, skipping hook invocation')
    exit(0)
  }
-  const networkName = generateNetworkName()
-  // Create network
-  await networkCreate(networkName)
+
+  let networkName = process.env.ACTIONS_RUNNER_NETWORK_DRIVER
+  if (!networkName) {
+    networkName = generateNetworkName()
+    // Create network
+    await networkCreate(networkName)
+  }

  // Create Job Container
  let containerMetadata: ContainerMetadata | undefined = undefined
  if (!container?.image) {
    core.info('No job container provided, skipping')
  } else {
-    setupContainer(container)
+    setupContainer(container, true)

    const configLocation = await registryLogin(container.registry)
    try {
@@ -174,9 +178,11 @@ function generateResponseFile(
  writeToResponseFile(responseFile, JSON.stringify(response))
 }

-function setupContainer(container): void {
-  container.entryPointArgs = [`-f`, `/dev/null`]
-  container.entryPoint = 'tail'
+function setupContainer(container, jobContainer = false): void {
+  if (!container.entryPoint && jobContainer) {
+    container.entryPointArgs = [`-f`, `/dev/null`]
+    container.entryPoint = 'tail'
+  }
 }

 function generateNetworkName(): string {
@@ -1,10 +1,10 @@
 /* eslint-disable @typescript-eslint/no-var-requires */
 /* eslint-disable @typescript-eslint/no-require-imports */
-/* eslint-disable import/no-commonjs */
 import * as core from '@actions/core'
 import { env } from 'process'
 // Import this way otherwise typescript has errors
 const exec = require('@actions/exec')
+const shlex = require('shlex')

 export interface RunDockerCommandOptions {
  workingDir?: string
@@ -17,6 +17,7 @@ export async function runDockerCommand(
  options?: RunDockerCommandOptions
 ): Promise<string> {
  options = optionsWithDockerEnvs(options)
+  args = fixArgs(args)
  const pipes = await exec.getExecOutput('docker', args, options)
  if (pipes.exitCode !== 0) {
    core.error(`Docker failed with exit code ${pipes.exitCode}`)
@@ -84,6 +85,10 @@ export function sanitize(val: string): string {
  return newNameBuilder.join('')
 }

+export function fixArgs(args: string[]): string[] {
+  return shlex.split(args.join(' '))
+}
+
 export function checkEnvironment(): void {
  if (!env.GITHUB_WORKSPACE) {
    throw new Error('GITHUB_WORKSPACE is not set')
@@ -40,21 +40,54 @@ describe('run script step', () => {
    definitions.runScriptStep.args.entryPoint = '/bin/bash'
    definitions.runScriptStep.args.entryPointArgs = [
      '-c',
-      `if [[ ! $(env | grep "^PATH=") = "PATH=${definitions.runScriptStep.args.prependPath}:"* ]]; then exit 1; fi`
+      `'if [[ ! $(env | grep "^PATH=") = "PATH=${definitions.runScriptStep.args.prependPath}:"* ]]; then exit 1; fi'`
    ]
    await expect(
      runScriptStep(definitions.runScriptStep.args, prepareJobResponse.state)
    ).resolves.not.toThrow()
  })

+  it("Should fix expansion and print correctly in container's stdout", async () => {
+    const spy = jest.spyOn(process.stdout, 'write').mockImplementation()
+
+    definitions.runScriptStep.args.entryPoint = 'echo'
+    definitions.runScriptStep.args.entryPointArgs = ['"Mona', 'the', `Octocat"`]
+    await expect(
+      runScriptStep(definitions.runScriptStep.args, prepareJobResponse.state)
+    ).resolves.not.toThrow()
+    expect(spy).toHaveBeenCalledWith(
+      expect.stringContaining('Mona the Octocat')
+    )
+
+    spy.mockRestore()
+  })
+
  it('Should have path variable changed in container with prepend path string array', async () => {
    definitions.runScriptStep.args.prependPath = ['/some/other/path']
    definitions.runScriptStep.args.entryPoint = '/bin/bash'
    definitions.runScriptStep.args.entryPointArgs = [
      '-c',
-      `if [[ ! $(env | grep "^PATH=") = "PATH=${definitions.runScriptStep.args.prependPath.join(
+      `'if [[ ! $(env | grep "^PATH=") = "PATH=${definitions.runScriptStep.args.prependPath.join(
        ':'
-      )}:"* ]]; then exit 1; fi`
+      )}:"* ]]; then exit 1; fi'`
+    ]
+    await expect(
+      runScriptStep(definitions.runScriptStep.args, prepareJobResponse.state)
+    ).resolves.not.toThrow()
+  })
+
+  it('Should confirm that CI and GITHUB_ACTIONS are set', async () => {
+    definitions.runScriptStep.args.entryPoint = '/bin/bash'
+    definitions.runScriptStep.args.entryPointArgs = [
+      '-c',
+      `'if [[ ! $(env | grep "^CI=") = "CI=true" ]]; then exit 1; fi'`
+    ]
+    await expect(
+      runScriptStep(definitions.runScriptStep.args, prepareJobResponse.state)
+    ).resolves.not.toThrow()
+    definitions.runScriptStep.args.entryPointArgs = [
+      '-c',
+      `'if [[ ! $(env | grep "^GITHUB_ACTIONS=") = "GITHUB_ACTIONS=true" ]]; then exit 1; fi'`
    ]
    await expect(
      runScriptStep(definitions.runScriptStep.args, prepareJobResponse.state)
@@ -31,7 +31,7 @@ export default class TestSetup {
  private get allTestDirectories() {
    const resp = [this.testdir, this.runnerMockDir, this.runnerOutputDir]

-    for (const [key, value] of Object.entries(this.runnerMockSubdirs)) {
+    for (const [, value] of Object.entries(this.runnerMockSubdirs)) {
      resp.push(`${this.runnerMockDir}/${value}`)
    }

@@ -42,12 +42,11 @@ export default class TestSetup {
    return resp
  }

-  public initialize(): void {
+  initialize(): void {
    env['GITHUB_WORKSPACE'] = this.workingDirectory
    env['RUNNER_NAME'] = 'test'
-    env[
-      'RUNNER_TEMP'
-    ] = `${this.runnerMockDir}/${this.runnerMockSubdirs.workTemp}`
+    env['RUNNER_TEMP'] =
+      `${this.runnerMockDir}/${this.runnerMockSubdirs.workTemp}`

    for (const dir of this.allTestDirectories) {
      fs.mkdirSync(dir, { recursive: true })
@@ -59,7 +58,7 @@ export default class TestSetup {
    )
  }

-  public teardown(): void {
+  teardown(): void {
    fs.rmdirSync(this.testdir, { recursive: true })
  }

@@ -108,21 +107,21 @@ export default class TestSetup {
    ]
  }

-  public createOutputFile(name: string): string {
+  createOutputFile(name: string): string {
    let filePath = path.join(this.runnerOutputDir, name || `${uuidv4()}.json`)
    fs.writeFileSync(filePath, '')
    return filePath
  }

-  public get workingDirectory(): string {
+  get workingDirectory(): string {
    return `${this.runnerMockDir}/_work/${this.projectName}/${this.projectName}`
  }

-  public get containerWorkingDirectory(): string {
+  get containerWorkingDirectory(): string {
    return `/__w/${this.projectName}/${this.projectName}`
  }

-  public initializeDockerAction(): string {
+  initializeDockerAction(): string {
    const actionPath = `${this.testdir}/_actions/example-handle/example-repo/example-branch/mock-directory`
    fs.mkdirSync(actionPath, { recursive: true })
    this.writeDockerfile(actionPath)
@@ -147,7 +146,7 @@ echo "::set-output name=time::$time"`
    fs.chmodSync(entryPointPath, 0o755)
  }

-  public getPrepareJobDefinition(): HookData {
+  getPrepareJobDefinition(): HookData {
    const prepareJob = JSON.parse(
      fs.readFileSync(
        path.resolve(__dirname + '/../../../examples/prepare-job.json'),
@@ -166,7 +165,7 @@ echo "::set-output name=time::$time"`
    return prepareJob
  }

-  public getRunScriptStepDefinition(): HookData {
+  getRunScriptStepDefinition(): HookData {
    const runScriptStep = JSON.parse(
      fs.readFileSync(
        path.resolve(__dirname + '/../../../examples/run-script-step.json'),
@@ -178,7 +177,7 @@ echo "::set-output name=time::$time"`
    return runScriptStep
  }

-  public getRunContainerStepDefinition(): HookData {
+  getRunContainerStepDefinition(): HookData {
    const runContainerStep = JSON.parse(
      fs.readFileSync(
        path.resolve(__dirname + '/../../../examples/run-container-step.json'),
@@ -1,4 +1,4 @@
-import { optionsWithDockerEnvs, sanitize } from '../src/utils'
+import { optionsWithDockerEnvs, sanitize, fixArgs } from '../src/utils'

 describe('Utilities', () => {
  it('should return sanitized image name', () => {
@@ -10,6 +10,37 @@ describe('Utilities', () => {
    expect(sanitize(validStr)).toBe(validStr)
  })

+  test.each([
+    [['"Hello', 'World"'], ['Hello World']],
+    [
+      [
+        'sh',
+        '-c',
+        `'[ $(cat /etc/*release* | grep -i -e "^ID=*alpine*" -c) != 0 ] || exit 1'`
+      ],
+      [
+        'sh',
+        '-c',
+        `[ $(cat /etc/*release* | grep -i -e "^ID=*alpine*" -c) != 0 ] || exit 1`
+      ]
+    ],
+    [
+      [
+        'sh',
+        '-c',
+        `'[ $(cat /etc/*release* | grep -i -e '\\''^ID=*alpine*'\\'' -c) != 0 ] || exit 1'`
+      ],
+      [
+        'sh',
+        '-c',
+        `[ $(cat /etc/*release* | grep -i -e '^ID=*alpine*' -c) != 0 ] || exit 1`
+      ]
+    ]
+  ])('should fix split arguments(%p, %p)', (args, expected) => {
+    const got = fixArgs(args)
+    expect(got).toStrictEqual(expected)
+  })
+
  describe('with docker options', () => {
    it('should augment options with docker environment variables', () => {
      process.env.DOCKER_HOST = 'unix:///run/user/1001/docker.sock'
@@ -0,0 +1,6 @@
+{
+  "compilerOptions": {
+    "allowJs": true
+  },
+  "extends": "./tsconfig.json"
+}
@@ -3,7 +3,7 @@
  "version": "0.1.0",
  "description": "",
  "main": "lib/index.js",
-  "types": "index.d.ts",
+  "types": "lib/index.d.ts",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "build": "tsc",
@@ -14,15 +14,14 @@
  "author": "",
  "license": "MIT",
  "devDependencies": {
-    "@types/node": "^17.0.23",
-    "@typescript-eslint/parser": "^5.18.0",
+    "@types/node": "^24.0.14",
    "@zeit/ncc": "^0.22.3",
-    "eslint": "^8.12.0",
-    "eslint-plugin-github": "^4.3.6",
-    "prettier": "^2.6.2",
-    "typescript": "^4.6.3"
+    "eslint": "^9.31.0",
+    "eslint-plugin-github": "^6.0.0",
+    "prettier": "^3.6.2",
+    "typescript": "^5.8.3"
  },
  "dependencies": {
-    "@actions/core": "^1.9.1"
+    "@actions/core": "^2.0.2"
  }
 }
@@ -22,9 +22,6 @@ rules:
 - apiGroups: [""]
  resources: ["pods/log"]
  verbs: ["get", "list", "watch",]
- apiGroups: ["batch"]
-  resources: ["jobs"]
-  verbs: ["get", "list", "create", "delete"]
 - apiGroups: [""]
  resources: ["secrets"]
  verbs: ["get", "list", "create", "delete"]
@@ -33,6 +30,27 @@ rules:
 - The `ACTIONS_RUNNER_REQUIRE_JOB_CONTAINER` env should be set to true to prevent the runner from running any jobs outside of a container
 - The runner pod should map a persistent volume claim into the `_work` directory
    - The `ACTIONS_RUNNER_CLAIM_NAME` env should be set to the persistent volume claim that contains the runner's working directory, otherwise it defaults to `${ACTIONS_RUNNER_POD_NAME}-work`
+- By default, the hook uses the Kubernetes scheduler with `nodeAffinity` to ensure job pods are scheduled correctly (essential for `ReadWriteOnce` volumes). Setting `ACTIONS_RUNNER_DISABLE_KUBE_SCHEDULER=true` will fall back to legacy `nodeName` pinning (not recommended).
+
+## Storage Guidance
+The K8s hooks require a shared volume between the runner pod and the job pods to share the workspace and other internal directories.
+
+### RWX (Recommended)
+The preferred way to configure storage is using a `ReadWriteMany` (RWX) Persistent Volume Claim. RWX allows the Kubernetes scheduler to place job pods on any node in the cluster, maximizing resource availability and flexibility.
+
+To migrate from RWO to RWX:
+1. Provision a new `ReadWriteMany` StorageClass if one is not available.
+2. Update your PVC definition to use `accessModes: [ReadWriteMany]`.
+3. No additional environment variables are needed - affinity-based scheduling is the default.
+
+### RWO Fallback (Affinity-based)
+If `ReadWriteMany` storage is not available, you can use `ReadWriteOnce` (RWO) storage. In this mode, all job pods must be scheduled on the same node as the runner pod that owns the PVC.
+
+To enable this safely:
+1. The default affinity-based scheduling works automatically. Do not set `ACTIONS_RUNNER_DISABLE_KUBE_SCHEDULER`.
+2. The hooks will automatically add a `nodeAffinity` to the job pods, ensuring they are scheduled on the same node as the runner pod (`kubernetes.io/hostname` match).
+
+> **Note:** We do not recommend manually setting `nodeName` in the pod template, as the hooks handle node placement automatically via affinity when the scheduler is enabled.
 - Some actions runner env's are expected to be set. These are set automatically by the runner.
    - `RUNNER_WORKSPACE` is expected to be set to the workspace of the runner
    - `GITHUB_WORKSPACE` is expected to be set to the workspace of the job
@@ -43,3 +61,5 @@ rules:
 - Building container actions from a dockerfile is not supported at this time
 - Container actions will not have access to the services network or job container network
 - Docker [create options](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idcontaineroptions) are not supported
+- Container actions will have to specify the entrypoint, since the default entrypoint will be overridden to run the commands from the workflow.
+- Container actions need to have the following binaries in their container image: `sh`, `env`, `tail`.
@@ -1,13 +1,26 @@
-// eslint-disable-next-line import/no-commonjs
 module.exports = {
  clearMocks: true,
+  preset: 'ts-jest',
  moduleFileExtensions: ['js', 'ts'],
  testEnvironment: 'node',
  testMatch: ['**/*-test.ts'],
  testRunner: 'jest-circus/runner',
+  verbose: true,
  transform: {
-    '^.+\\.ts$': 'ts-jest'
+    '^.+\\.ts$': [
+      'ts-jest',
+      {
+        tsconfig: 'tsconfig.test.json'
+      }
+    ],
+    // Transform ESM modules to CommonJS
+    '^.+\\.(js|mjs)$': ['babel-jest', {
+      presets: [['@babel/preset-env', { targets: { node: 'current' } }]]
+    }]
  },
-  setupFilesAfterEnv: ['./jest.setup.js'],
-  verbose: true
+  transformIgnorePatterns: [
+    // Transform these ESM packages
+    'node_modules/(?!(shlex|@kubernetes/client-node|openid-client|oauth4webapi|jose|uuid)/)'
+  ],
+  setupFilesAfterEnv: ['./jest.setup.js']
 }
@@ -1 +1,2 @@
+// eslint-disable-next-line filenames/match-regex, no-undef
 jest.setTimeout(500000)
@@ -13,18 +13,25 @@
  "author": "",
  "license": "MIT",
  "dependencies": {
-    "@actions/core": "^1.9.1",
-    "@actions/exec": "^1.1.1",
-    "@actions/io": "^1.1.2",
-    "@kubernetes/client-node": "^0.18.1",
-    "hooklib": "file:../hooklib"
+    "@actions/core": "^2.0.2",
+    "@actions/exec": "^2.0.0",
+    "@actions/io": "^2.0.0",
+    "@kubernetes/client-node": "^1.3.0",
+    "hooklib": "file:../hooklib",
+    "js-yaml": "^4.1.0",
+    "shlex": "^3.0.0",
+    "tar-fs": "^3.1.0",
+    "uuid": "^11.1.0"
  },
  "devDependencies": {
-    "@types/jest": "^27.4.1",
-    "@types/node": "^17.0.23",
-    "@vercel/ncc": "^0.33.4",
-    "jest": "^27.5.1",
-    "ts-jest": "^27.1.4",
-    "typescript": "^4.6.3"
+    "@babel/core": "^7.28.3",
+    "@babel/preset-env": "^7.28.3",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.3.0",
+    "@vercel/ncc": "^0.38.3",
+    "babel-jest": "^30.1.1",
+    "jest": "^30.1.1",
+    "ts-jest": "^29.4.1",
+    "typescript": "^5.9.2"
  }
 }
@@ -41,7 +41,9 @@ export function getSecretName(): string {

 export const MAX_POD_NAME_LENGTH = 63
 export const STEP_POD_NAME_SUFFIX_LENGTH = 8
+export const CONTAINER_EXTENSION_PREFIX = '$'
 export const JOB_CONTAINER_NAME = 'job'
+export const JOB_CONTAINER_EXTENSION_NAME = '$job'

 export class RunnerInstanceLabel {
  private podName: string
@@ -1,26 +1,36 @@
 import * as core from '@actions/core'
 import * as io from '@actions/io'
 import * as k8s from '@kubernetes/client-node'
-import { ContextPorts, prepareJobArgs, writeToResponseFile } from 'hooklib'
+import {
+  JobContainerInfo,
+  ContextPorts,
+  PrepareJobArgs,
+  writeToResponseFile,
+  ServiceContainerInfo
+} from 'hooklib'
 import path from 'path'
 import {
  containerPorts,
  createPod,
  isPodContainerAlpine,
  prunePods,
-  waitForPodPhases
+  waitForPodPhases,
+  getPrepareJobTimeoutSeconds
 } from '../k8s'
 import {
  containerVolumes,
  DEFAULT_CONTAINER_ENTRY_POINT,
  DEFAULT_CONTAINER_ENTRY_POINT_ARGS,
  generateContainerName,
-  PodPhase
+  mergeContainerWithOptions,
+  readExtensionFromFile,
+  PodPhase,
+  fixArgs
 } from '../k8s/utils'
-import { JOB_CONTAINER_NAME } from './constants'
+import { CONTAINER_EXTENSION_PREFIX, JOB_CONTAINER_NAME } from './constants'

 export async function prepareJob(
-  args: prepareJobArgs,
+  args: PrepareJobArgs,
  responseFile
 ): Promise<void> {
  if (!args.container) {
@@ -28,29 +38,49 @@ export async function prepareJob(
  }

  await prunePods()
+
+  const extension = readExtensionFromFile()
  await copyExternalsToRoot()
+
  let container: k8s.V1Container | undefined = undefined
  if (args.container?.image) {
-    core.debug(`Using image '${args.container.image}' for job image`)
-    container = createContainerSpec(args.container, JOB_CONTAINER_NAME, true)
+    container = createContainerSpec(
+      args.container,
+      JOB_CONTAINER_NAME,
+      true,
+      extension
+    )
  }

  let services: k8s.V1Container[] = []
  if (args.services?.length) {
    services = args.services.map(service => {
-      core.debug(`Adding service '${service.image}' to pod definition`)
-      return createContainerSpec(service, generateContainerName(service.image))
+      return createContainerSpec(
+        service,
+        generateContainerName(service.image),
+        false,
+        extension
+      )
    })
  }
+
  if (!container && !services?.length) {
    throw new Error('No containers exist, skipping hook invocation')
  }
+
  let createdPod: k8s.V1Pod | undefined = undefined
  try {
-    createdPod = await createPod(container, services, args.container.registry)
+    createdPod = await createPod(
+      container,
+      services,
+      args.container.registry,
+      extension
+    )
  } catch (err) {
    await prunePods()
-    throw new Error(`failed to create job pod: ${err}`)
+    core.debug(`createPod failed: ${JSON.stringify(err)}`)
+    const message = (err as any)?.response?.body?.message || err
+    throw new Error(`failed to create job pod: ${message}`)
  }

  if (!createdPod?.metadata?.name) {
@@ -64,11 +94,12 @@ export async function prepareJob(
    await waitForPodPhases(
      createdPod.metadata.name,
      new Set([PodPhase.RUNNING]),
-      new Set([PodPhase.PENDING])
+      new Set([PodPhase.PENDING]),
+      getPrepareJobTimeoutSeconds()
    )
  } catch (err) {
    await prunePods()
-    throw new Error(`Pod failed to come online with error: ${err}`)
+    throw new Error(`pod failed to come online with error: ${err}`)
  }

  core.debug('Job pod is ready for traffic')
@@ -80,16 +111,21 @@ export async function prepareJob(
      JOB_CONTAINER_NAME
    )
  } catch (err) {
-    throw new Error(`Failed to determine if the pod is alpine: ${err}`)
+    core.debug(
+      `Failed to determine if the pod is alpine: ${JSON.stringify(err)}`
+    )
+    const message = (err as any)?.response?.body?.message || err
+    throw new Error(`failed to determine if the pod is alpine: ${message}`)
  }
  core.debug(`Setting isAlpine to ${isAlpine}`)
-  generateResponseFile(responseFile, createdPod, isAlpine)
+  generateResponseFile(responseFile, args, createdPod, isAlpine)
 }

 function generateResponseFile(
  responseFile: string,
+  args: PrepareJobArgs,
  appPod: k8s.V1Pod,
-  isAlpine
+  isAlpine: boolean
 ): void {
  if (!appPod.metadata?.name) {
    throw new Error('app pod must have metadata.name specified')
@@ -109,8 +145,10 @@ function generateResponseFile(
    const mainContainerContextPorts: ContextPorts = {}
    if (mainContainer?.ports) {
      for (const port of mainContainer.ports) {
-        mainContainerContextPorts[port.containerPort] =
-          mainContainerContextPorts.hostPort
+        if (port.containerPort && port.hostPort) {
+          mainContainerContextPorts[port.containerPort.toString()] =
+            port.hostPort.toString()
+        }
      }
    }

@@ -120,25 +158,29 @@ function generateResponseFile(
    }
  }

-  const serviceContainers = appPod.spec?.containers.filter(
-    c => c.name !== JOB_CONTAINER_NAME
-  )
-  if (serviceContainers?.length) {
-    response.context['services'] = serviceContainers.map(c => {
-      if (!c.ports?.length) {
-        return { image: c.image }
-      }
-      const ctxPorts: ContextPorts = {}
-      for (const port of c.ports) {
-        ctxPorts[port.containerPort] = port.hostPort
-      }
+  if (args.services?.length) {
+    const serviceContainerNames =
+      args.services?.map(s => generateContainerName(s.image)) || []

-      return {
-        image: c.image,
-        ports: ctxPorts
-      }
-    })
+    response.context['services'] = appPod?.spec?.containers
+      ?.filter(c => serviceContainerNames.includes(c.name))
+      .map(c => {
+        const ctxPorts: ContextPorts = {}
+        if (c.ports?.length) {
+          for (const port of c.ports) {
+            if (port.containerPort && port.hostPort) {
+              ctxPorts[port.containerPort.toString()] = port.hostPort.toString()
+            }
+          }
+        }
+
+        return {
+          image: c.image,
+          ports: ctxPorts
+        }
+      })
  }
+
  writeToResponseFile(responseFile, JSON.stringify(response))
 }

@@ -154,9 +196,10 @@ async function copyExternalsToRoot(): Promise<void> {
 }

 export function createContainerSpec(
-  container,
+  container: JobContainerInfo | ServiceContainerInfo,
  name: string,
-  jobContainer = false
+  jobContainer = false,
+  extension?: k8s.V1PodTemplateSpec
 ): k8s.V1Container {
  if (!container.entryPoint && jobContainer) {
    container.entryPoint = DEFAULT_CONTAINER_ENTRY_POINT
@@ -168,31 +211,55 @@ export function createContainerSpec(
    image: container.image,
    ports: containerPorts(container)
  } as k8s.V1Container
-  if (container.workingDirectory) {
-    podContainer.workingDir = container.workingDirectory
+  if (container['workingDirectory']) {
+    podContainer.workingDir = container['workingDirectory']
  }

  if (container.entryPoint) {
    podContainer.command = [container.entryPoint]
  }

-  if (container.entryPointArgs?.length > 0) {
-    podContainer.args = container.entryPointArgs
+  if (container.entryPointArgs && container.entryPointArgs.length > 0) {
+    podContainer.args = fixArgs(container.entryPointArgs)
  }

  podContainer.env = []
  for (const [key, value] of Object.entries(
-    container['environmentVariables']
+    container['environmentVariables'] || {}
  )) {
    if (value && key !== 'HOME') {
-      podContainer.env.push({ name: key, value: value as string })
+      podContainer.env.push({ name: key, value: value })
    }
  }

+  podContainer.env.push({
+    name: 'GITHUB_ACTIONS',
+    value: 'true'
+  })
+
+  if (!('CI' in (container['environmentVariables'] || {}))) {
+    podContainer.env.push({
+      name: 'CI',
+      value: 'true'
+    })
+  }
+
  podContainer.volumeMounts = containerVolumes(
-    container.userMountVolumes,
+    container['userMountVolumes'],
    jobContainer
  )

+  if (!extension) {
+    return podContainer
+  }
+
+  const from = extension.spec?.containers?.find(
+    c => c.name === CONTAINER_EXTENSION_PREFIX + name
+  )
+
+  if (from) {
+    mergeContainerWithOptions(podContainer, from)
+  }
+
  return podContainer
 }
@@ -12,12 +12,12 @@ import {
 } from '../k8s'
 import {
  containerVolumes,
-  DEFAULT_CONTAINER_ENTRY_POINT,
-  DEFAULT_CONTAINER_ENTRY_POINT_ARGS,
+  fixArgs,
+  mergeContainerWithOptions,
  PodPhase,
-  writeEntryPointScript
+  readExtensionFromFile
 } from '../k8s/utils'
-import { JOB_CONTAINER_NAME } from './constants'
+import { JOB_CONTAINER_EXTENSION_NAME, JOB_CONTAINER_NAME } from './constants'

 export async function runContainerStep(
  stepContainer: RunContainerStepArgs
@@ -28,13 +28,36 @@ export async function runContainerStep(

  let secretName: string | undefined = undefined
  if (stepContainer.environmentVariables) {
-    secretName = await createSecretForEnvs(stepContainer.environmentVariables)
+    try {
+      const envs = JSON.parse(
+        JSON.stringify(stepContainer.environmentVariables)
+      )
+      envs['GITHUB_ACTIONS'] = 'true'
+      if (!('CI' in envs)) {
+        envs.CI = 'true'
+      }
+      secretName = await createSecretForEnvs(envs)
+    } catch (err) {
+      core.debug(`createSecretForEnvs failed: ${JSON.stringify(err)}`)
+      const message = (err as any)?.response?.body?.message || err
+      throw new Error(`failed to create script environment: ${message}`)
+    }
  }

+  const extension = readExtensionFromFile()
+
  core.debug(`Created secret ${secretName} for container job envs`)
-  const container = createPodSpec(stepContainer, secretName)
+  const container = createContainerSpec(stepContainer, secretName, extension)
+
+  let job: k8s.V1Job
+  try {
+    job = await createJob(container, extension)
+  } catch (err) {
+    core.debug(`createJob failed: ${JSON.stringify(err)}`)
+    const message = (err as any)?.response?.body?.message || err
+    throw new Error(`failed to run script step: ${message}`)
+  }

-  const job = await createJob(container)
  if (!job.metadata?.name) {
    throw new Error(
      `Expected job ${JSON.stringify(
@@ -44,10 +67,23 @@ export async function runContainerStep(
  }
  core.debug(`Job created, waiting for pod to start: ${job.metadata?.name}`)

-  const podName = await getContainerJobPodName(job.metadata.name)
+  let podName: string
+  try {
+    podName = await getContainerJobPodName(job.metadata.name)
+  } catch (err) {
+    core.debug(`getContainerJobPodName failed: ${JSON.stringify(err)}`)
+    const message = (err as any)?.response?.body?.message || err
+    throw new Error(`failed to get container job pod name: ${message}`)
+  }
+
  await waitForPodPhases(
    podName,
-    new Set([PodPhase.COMPLETED, PodPhase.RUNNING, PodPhase.SUCCEEDED]),
+    new Set([
+      PodPhase.COMPLETED,
+      PodPhase.RUNNING,
+      PodPhase.SUCCEEDED,
+      PodPhase.FAILED
+    ]),
    new Set([PodPhase.PENDING, PodPhase.UNKNOWN])
  )
  core.debug('Container step is running or complete, pulling logs')
@@ -56,7 +92,7 @@ export async function runContainerStep(

  core.debug('Waiting for container job to complete')
  await waitForJobToComplete(job.metadata.name)
-  // pod has failed so pull the status code from the container
+
  const status = await getPodStatus(podName)
  if (status?.phase === 'Succeeded') {
    return 0
@@ -75,24 +111,21 @@ export async function runContainerStep(
  return Number(exitCode) || 1
 }

-function createPodSpec(
+function createContainerSpec(
  container: RunContainerStepArgs,
-  secretName?: string
+  secretName?: string,
+  extension?: k8s.V1PodTemplateSpec
 ): k8s.V1Container {
  const podContainer = new k8s.V1Container()
  podContainer.name = JOB_CONTAINER_NAME
  podContainer.image = container.image
-
-  const { entryPoint, entryPointArgs } = container
-  container.entryPoint = 'sh'
-
-  const { containerPath } = writeEntryPointScript(
-    container.workingDirectory,
-    entryPoint || DEFAULT_CONTAINER_ENTRY_POINT,
-    entryPoint ? entryPointArgs || [] : DEFAULT_CONTAINER_ENTRY_POINT_ARGS
-  )
-  container.entryPointArgs = ['-e', containerPath]
-  podContainer.command = [container.entryPoint, ...container.entryPointArgs]
+  podContainer.workingDir = container.workingDirectory
+  podContainer.command = container.entryPoint
+    ? [container.entryPoint]
+    : undefined
+  podContainer.args = container.entryPointArgs?.length
+    ? fixArgs(container.entryPointArgs)
+    : undefined

  if (secretName) {
    podContainer.envFrom = [
@@ -106,5 +139,16 @@ function createPodSpec(
  }
  podContainer.volumeMounts = containerVolumes(undefined, false, true)

+  if (!extension) {
+    return podContainer
+  }
+
+  const from = extension.spec?.containers?.find(
+    c => c.name === JOB_CONTAINER_EXTENSION_NAME
+  )
+  if (from) {
+    mergeContainerWithOptions(podContainer, from)
+  }
+
  return podContainer
 }
@@ -1,5 +1,6 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
 import * as fs from 'fs'
+import * as core from '@actions/core'
 import { RunScriptStepArgs } from 'hooklib'
 import { execPodStep } from '../k8s'
 import { writeEntryPointScript } from '../k8s/utils'
@@ -8,7 +9,7 @@ import { JOB_CONTAINER_NAME } from './constants'
 export async function runScriptStep(
  args: RunScriptStepArgs,
  state,
-  responseFile
+  responseFile?
 ): Promise<void> {
  const { entryPoint, entryPointArgs, environmentVariables } = args
  const { containerPath, runnerPath } = writeEntryPointScript(
@@ -28,7 +29,9 @@ export async function runScriptStep(
      JOB_CONTAINER_NAME
    )
  } catch (err) {
-    throw new Error(`failed to run script step: ${err}`)
+    core.debug(`execPodStep failed: ${JSON.stringify(err)}`)
+    const message = (err as any)?.response?.body?.message || err
+    throw new Error(`failed to run script step: ${message}`)
  } finally {
    fs.rmSync(runnerPath)
  }
@@ -1,5 +1,11 @@
 import * as core from '@actions/core'
-import { Command, getInputFromStdin, prepareJobArgs } from 'hooklib'
+import {
+  Command,
+  getInputFromStdin,
+  PrepareJobArgs,
+  RunContainerStepArgs,
+  RunScriptStepArgs
+} from 'hooklib'
 import {
  cleanupJob,
  prepareJob,
@@ -27,16 +33,16 @@ async function run(): Promise<void> {
    let exitCode = 0
    switch (command) {
      case Command.PrepareJob:
-        await prepareJob(args as prepareJobArgs, responseFile)
+        await prepareJob(args as PrepareJobArgs, responseFile)
        return process.exit(0)
      case Command.CleanupJob:
        await cleanupJob()
        return process.exit(0)
      case Command.RunScriptStep:
-        await runScriptStep(args, state, null)
+        await runScriptStep(args as RunScriptStepArgs, state)
        return process.exit(0)
      case Command.RunContainerStep:
-        exitCode = await runContainerStep(args)
+        exitCode = await runContainerStep(args as RunContainerStepArgs)
        return process.exit(exitCode)
      default:
        throw new Error(`Command not recognized: ${command}`)
@@ -1,7 +1,7 @@
 import * as core from '@actions/core'
 import * as k8s from '@kubernetes/client-node'
-import { ContainerInfo, Registry } from 'hooklib'
 import * as stream from 'stream'
+import type { ContainerInfo, Registry } from 'hooklib'
 import {
  getJobPodName,
  getRunnerPodName,
@@ -10,7 +10,13 @@ import {
  getVolumeClaimName,
  RunnerInstanceLabel
 } from '../hooks/constants'
-import { PodPhase } from './utils'
+import {
+  PodPhase,
+  mergePodSpecWithOptions,
+  mergeObjectMeta,
+  useKubeScheduler,
+  fixArgs
+} from './utils'

 const kc = new k8s.KubeConfig()

@@ -20,6 +26,8 @@ const k8sApi = kc.makeApiClient(k8s.CoreV1Api)
 const k8sBatchV1Api = kc.makeApiClient(k8s.BatchV1Api)
 const k8sAuthorizationV1Api = kc.makeApiClient(k8s.AuthorizationV1Api)

+const DEFAULT_WAIT_FOR_POD_TIME_SECONDS = 10 * 60 // 10 min
+
 export const POD_VOLUME_NAME = 'work'

 export const requiredPermissions = [
@@ -58,7 +66,8 @@ export const requiredPermissions = [
 export async function createPod(
  jobContainer?: k8s.V1Container,
  services?: k8s.V1Container[],
-  registry?: Registry
+  registry?: Registry,
+  extension?: k8s.V1PodTemplateSpec
 ): Promise<k8s.V1Pod> {
  const containers: k8s.V1Container[] = []
  if (jobContainer) {
@@ -80,15 +89,22 @@ export async function createPod(
  appPod.metadata.labels = {
    [instanceLabel.key]: instanceLabel.value
  }
+  appPod.metadata.annotations = {}

  appPod.spec = new k8s.V1PodSpec()
  appPod.spec.containers = containers
  appPod.spec.restartPolicy = 'Never'
-  appPod.spec.nodeName = await getCurrentNodeName()
+
+  const nodeName = await getCurrentNodeName()
+  if (useKubeScheduler()) {
+    appPod.spec.affinity = await getPodAffinity(nodeName)
+  } else {
+    appPod.spec.nodeName = nodeName
+  }
  const claimName = getVolumeClaimName()
  appPod.spec.volumes = [
    {
-      name: 'work',
+      name: POD_VOLUME_NAME,
      persistentVolumeClaim: { claimName }
    }
  ]
@@ -103,12 +119,23 @@ export async function createPod(
    appPod.spec.imagePullSecrets = [secretReference]
  }

-  const { body } = await k8sApi.createNamespacedPod(namespace(), appPod)
-  return body
+  if (extension?.metadata) {
+    mergeObjectMeta(appPod, extension.metadata)
+  }
+
+  if (extension?.spec) {
+    mergePodSpecWithOptions(appPod.spec, extension.spec)
+  }
+
+  return await k8sApi.createNamespacedPod({
+    namespace: namespace(),
+    body: appPod
+  })
 }

 export async function createJob(
-  container: k8s.V1Container
+  container: k8s.V1Container,
+  extension?: k8s.V1PodTemplateSpec
 ): Promise<k8s.V1Job> {
  const runnerInstanceLabel = new RunnerInstanceLabel()

@@ -118,6 +145,7 @@ export async function createJob(
  job.metadata = new k8s.V1ObjectMeta()
  job.metadata.name = getStepPodName()
  job.metadata.labels = { [runnerInstanceLabel.key]: runnerInstanceLabel.value }
+  job.metadata.annotations = {}

  job.spec = new k8s.V1JobSpec()
  job.spec.ttlSecondsAfterFinished = 300
@@ -125,58 +153,73 @@ export async function createJob(
  job.spec.template = new k8s.V1PodTemplateSpec()

  job.spec.template.spec = new k8s.V1PodSpec()
+  job.spec.template.metadata = new k8s.V1ObjectMeta()
+  job.spec.template.metadata.labels = {}
+  job.spec.template.metadata.annotations = {}
  job.spec.template.spec.containers = [container]
  job.spec.template.spec.restartPolicy = 'Never'
-  job.spec.template.spec.nodeName = await getCurrentNodeName()
+
+  const nodeName = await getCurrentNodeName()
+  if (useKubeScheduler()) {
+    job.spec.template.spec.affinity = await getPodAffinity(nodeName)
+  } else {
+    job.spec.template.spec.nodeName = nodeName
+  }

  const claimName = getVolumeClaimName()
  job.spec.template.spec.volumes = [
    {
-      name: 'work',
+      name: POD_VOLUME_NAME,
      persistentVolumeClaim: { claimName }
    }
  ]

-  const { body } = await k8sBatchV1Api.createNamespacedJob(namespace(), job)
-  return body
+  if (extension) {
+    if (extension.metadata) {
+      mergeObjectMeta(job, extension.metadata)
+      mergeObjectMeta(job.spec.template, extension.metadata)
+    }
+    if (extension.spec) {
+      mergePodSpecWithOptions(job.spec.template.spec, extension.spec)
+    }
+  }
+
+  return await k8sBatchV1Api.createNamespacedJob({
+    namespace: namespace(),
+    body: job
+  })
 }

 export async function getContainerJobPodName(jobName: string): Promise<string> {
  const selector = `job-name=${jobName}`
  const backOffManager = new BackOffManager(60)
  while (true) {
-    const podList = await k8sApi.listNamespacedPod(
-      namespace(),
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      selector,
-      1
-    )
+    const podList = await k8sApi.listNamespacedPod({
+      namespace: namespace(),
+      labelSelector: selector,
+      limit: 1
+    })

-    if (!podList.body.items?.length) {
+    if (!podList.items?.length) {
      await backOffManager.backOff()
      continue
    }

-    if (!podList.body.items[0].metadata?.name) {
+    if (!podList.items[0].metadata?.name) {
      throw new Error(
        `Failed to determine the name of the pod for job ${jobName}`
      )
    }
-    return podList.body.items[0].metadata.name
+    return podList.items[0].metadata.name
  }
 }

 export async function deletePod(podName: string): Promise<void> {
-  await k8sApi.deleteNamespacedPod(
-    podName,
-    namespace(),
-    undefined,
-    undefined,
-    0
-  )
+  await k8sApi.deleteNamespacedPod({
+    name: podName,
+    namespace: namespace(),
+    gracePeriodSeconds: 0
+  })
 }

 export async function execPodStep(
@@ -184,33 +227,36 @@ export async function execPodStep(
  podName: string,
  containerName: string,
  stdin?: stream.Readable
-): Promise<void> {
+): Promise<number> {
  const exec = new k8s.Exec(kc)
-  await new Promise(async function (resolve, reject) {
-    await exec.exec(
-      namespace(),
-      podName,
-      containerName,
-      command,
-      process.stdout,
-      process.stderr,
-      stdin ?? null,
-      false /* tty */,
-      resp => {
-        // kube.exec returns an error if exit code is not 0, but we can't actually get the exit code
-        if (resp.status === 'Success') {
-          resolve(resp.code)
-        } else {
-          core.debug(
-            JSON.stringify({
-              message: resp?.message,
-              details: resp?.details
-            })
-          )
-          reject(resp?.message)
+
+  command = fixArgs(command)
+  return await new Promise(function (resolve, reject) {
+    exec
+      .exec(
+        namespace(),
+        podName,
+        containerName,
+        command,
+        process.stdout,
+        process.stderr,
+        stdin ?? null,
+        false /* tty */,
+        resp => {
+          if (resp.status === 'Success') {
+            resolve(resp.code || 0)
+          } else {
+            core.debug(
+              JSON.stringify({
+                message: resp?.message,
+                details: resp?.details
+              })
+            )
+            reject(new Error(resp?.message || 'execPodStep failed'))
+          }
        }
-      }
-    )
+      )
+      .catch(e => reject(e))
  })
 }

@@ -222,7 +268,7 @@ export async function waitForJobToComplete(jobName: string): Promise<void> {
        return
      }
    } catch (error) {
-      throw new Error(`job ${jobName} has failed`)
+      throw new Error(`job ${jobName} has failed: ${JSON.stringify(error)}`)
    }
    await backOffManager.backOff()
  }
@@ -263,8 +309,10 @@ export async function createDockerSecret(
    )
  }

-  const { body } = await k8sApi.createNamespacedSecret(namespace(), secret)
-  return body
+  return await k8sApi.createNamespacedSecret({
+    namespace: namespace(),
+    body: secret
+  })
 }

 export async function createSecretForEnvs(envs: {
@@ -288,30 +336,33 @@ export async function createSecretForEnvs(envs: {
    secret.data[key] = Buffer.from(value).toString('base64')
  }

-  await k8sApi.createNamespacedSecret(namespace(), secret)
+  await k8sApi.createNamespacedSecret({
+    namespace: namespace(),
+    body: secret
+  })
  return secretName
 }

 export async function deleteSecret(secretName: string): Promise<void> {
-  await k8sApi.deleteNamespacedSecret(secretName, namespace())
+  await k8sApi.deleteNamespacedSecret({
+    name: secretName,
+    namespace: namespace()
+  })
 }

 export async function pruneSecrets(): Promise<void> {
-  const secretList = await k8sApi.listNamespacedSecret(
-    namespace(),
-    undefined,
-    undefined,
-    undefined,
-    undefined,
-    new RunnerInstanceLabel().toString()
-  )
-  if (!secretList.body.items.length) {
+  const secretList = await k8sApi.listNamespacedSecret({
+    namespace: namespace(),
+    labelSelector: new RunnerInstanceLabel().toString()
+  })
+  if (!secretList.items.length) {
    return
  }

  await Promise.all(
-    secretList.body.items.map(
-      secret => secret.metadata?.name && deleteSecret(secret.metadata.name)
+    secretList.items.map(
+      async secret =>
+        secret.metadata?.name && deleteSecret(secret.metadata.name)
    )
  )
 }
@@ -320,7 +371,7 @@ export async function waitForPodPhases(
  podName: string,
  awaitingPhases: Set<PodPhase>,
  backOffPhases: Set<PodPhase>,
-  maxTimeSeconds = 10 * 60 // 10 min
+  maxTimeSeconds = DEFAULT_WAIT_FOR_POD_TIME_SECONDS
 ): Promise<void> {
  const backOffManager = new BackOffManager(maxTimeSeconds)
  let phase: PodPhase = PodPhase.UNKNOWN
@@ -339,11 +390,32 @@ export async function waitForPodPhases(
      await backOffManager.backOff()
    }
  } catch (error) {
-    throw new Error(`Pod ${podName} is unhealthy with phase status ${phase}`)
+    throw new Error(
+      `Pod ${podName} is unhealthy with phase status ${phase}: ${JSON.stringify(error)}`
+    )
  }
 }

-async function getPodPhase(podName: string): Promise<PodPhase> {
+export function getPrepareJobTimeoutSeconds(): number {
+  const envTimeoutSeconds =
+    process.env['ACTIONS_RUNNER_PREPARE_JOB_TIMEOUT_SECONDS']
+
+  if (!envTimeoutSeconds) {
+    return DEFAULT_WAIT_FOR_POD_TIME_SECONDS
+  }
+
+  const timeoutSeconds = parseInt(envTimeoutSeconds, 10)
+  if (!timeoutSeconds || timeoutSeconds <= 0) {
+    core.warning(
+      `Prepare job timeout is invalid ("${timeoutSeconds}"): use an int > 0`
+    )
+    return DEFAULT_WAIT_FOR_POD_TIME_SECONDS
+  }
+
+  return timeoutSeconds
+}
+
+async function getPodPhase(name: string): Promise<PodPhase> {
  const podPhaseLookup = new Set<string>([
    PodPhase.PENDING,
    PodPhase.RUNNING,
@@ -351,8 +423,10 @@ async function getPodPhase(podName: string): Promise<PodPhase> {
    PodPhase.FAILED,
    PodPhase.UNKNOWN
  ])
-  const { body } = await k8sApi.readNamespacedPod(podName, namespace())
-  const pod = body
+  const pod = await k8sApi.readNamespacedPod({
+    name,
+    namespace: namespace()
+  })

  if (!pod.status?.phase || !podPhaseLookup.has(pod.status.phase)) {
    return PodPhase.UNKNOWN
@@ -360,11 +434,13 @@ async function getPodPhase(podName: string): Promise<PodPhase> {
  return pod.status?.phase as PodPhase
 }

-async function isJobSucceeded(jobName: string): Promise<boolean> {
-  const { body } = await k8sBatchV1Api.readNamespacedJob(jobName, namespace())
-  const job = body
+async function isJobSucceeded(name: string): Promise<boolean> {
+  const job = await k8sBatchV1Api.readNamespacedJob({
+    name,
+    namespace: namespace()
+  })
  if (job.status?.failed) {
-    throw new Error(`job ${jobName} has failed`)
+    throw new Error(`job ${name} has failed`)
  }
  return !!job.status?.succeeded
 }
@@ -384,31 +460,26 @@ export async function getPodLogs(
    process.stderr.write(err.message)
  })

-  const r = await log.log(namespace(), podName, containerName, logStream, {
+  await log.log(namespace(), podName, containerName, logStream, {
    follow: true,
-    tailLines: 50,
    pretty: false,
    timestamps: false
  })
-  await new Promise(resolve => r.on('close', () => resolve(null)))
+  await new Promise(resolve => logStream.on('end', () => resolve(null)))
 }

 export async function prunePods(): Promise<void> {
-  const podList = await k8sApi.listNamespacedPod(
-    namespace(),
-    undefined,
-    undefined,
-    undefined,
-    undefined,
-    new RunnerInstanceLabel().toString()
-  )
-  if (!podList.body.items.length) {
+  const podList = await k8sApi.listNamespacedPod({
+    namespace: namespace(),
+    labelSelector: new RunnerInstanceLabel().toString()
+  })
+  if (!podList.items.length) {
    return
  }

  await Promise.all(
-    podList.body.items.map(
-      pod => pod.metadata?.name && deletePod(pod.metadata.name)
+    podList.items.map(
+      async pod => pod.metadata?.name && deletePod(pod.metadata.name)
    )
  )
 }
@@ -416,16 +487,16 @@ export async function prunePods(): Promise<void> {
 export async function getPodStatus(
  name: string
 ): Promise<k8s.V1PodStatus | undefined> {
-  const { body } = await k8sApi.readNamespacedPod(name, namespace())
-  return body.status
+  const pod = await k8sApi.readNamespacedPod({
+    name,
+    namespace: namespace()
+  })
+  return pod.status
 }

 export async function isAuthPermissionsOK(): Promise<boolean> {
  const sar = new k8s.V1SelfSubjectAccessReview()
-  const asyncs: Promise<{
-    response: unknown
-    body: k8s.V1SelfSubjectAccessReview
-  }>[] = []
+  const asyncs: Promise<k8s.V1SelfSubjectAccessReview>[] = []
  for (const resource of requiredPermissions) {
    for (const verb of resource.verbs) {
      sar.spec = new k8s.V1SelfSubjectAccessReviewSpec()
@@ -435,11 +506,13 @@ export async function isAuthPermissionsOK(): Promise<boolean> {
      sar.spec.resourceAttributes.group = resource.group
      sar.spec.resourceAttributes.resource = resource.resource
      sar.spec.resourceAttributes.subresource = resource.subresource
-      asyncs.push(k8sAuthorizationV1Api.createSelfSubjectAccessReview(sar))
+      asyncs.push(
+        k8sAuthorizationV1Api.createSelfSubjectAccessReview({ body: sar })
+      )
    }
  }
  const responses = await Promise.all(asyncs)
-  return responses.every(resp => resp.body.status?.allowed)
+  return responses.every(resp => resp.status?.allowed)
 }

 export async function isPodContainerAlpine(
@@ -452,27 +525,18 @@ export async function isPodContainerAlpine(
      [
        'sh',
        '-c',
-        "[ $(cat /etc/*release* | grep -i -e '^ID=*alpine*' -c) != 0 ] || exit 1"
+        `'[ $(cat /etc/*release* | grep -i -e "^ID=*alpine*" -c) != 0 ] || exit 1'`
      ],
      podName,
      containerName
    )
-  } catch (err) {
+  } catch {
    isAlpine = false
  }

  return isAlpine
 }

-async function getCurrentNodeName(): Promise<string> {
-  const resp = await k8sApi.readNamespacedPod(getRunnerPodName(), namespace())
-
-  const nodeName = resp.body.spec?.nodeName
-  if (!nodeName) {
-    throw new Error('Failed to determine node name')
-  }
-  return nodeName
-}
 export function namespace(): string {
  if (process.env['ACTIONS_RUNNER_KUBERNETES_NAMESPACE']) {
    return process.env['ACTIONS_RUNNER_KUBERNETES_NAMESPACE']
@@ -487,6 +551,39 @@ export function namespace(): string {
  return context.namespace
 }

+async function getCurrentNodeName(): Promise<string> {
+  const resp = await k8sApi.readNamespacedPod({
+    name: getRunnerPodName(),
+    namespace: namespace()
+  })
+
+  const nodeName = resp.spec?.nodeName
+  if (!nodeName) {
+    throw new Error('Failed to determine node name')
+  }
+  return nodeName
+}
+
+async function getPodAffinity(nodeName: string): Promise<k8s.V1Affinity> {
+  const affinity = new k8s.V1Affinity()
+  affinity.nodeAffinity = new k8s.V1NodeAffinity()
+  affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution =
+    new k8s.V1NodeSelector()
+  affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms =
+    [
+      {
+        matchExpressions: [
+          {
+            key: 'kubernetes.io/hostname',
+            operator: 'In',
+            values: [nodeName]
+          }
+        ]
+      }
+    ]
+  return affinity
+}
+
 class BackOffManager {
  private backOffSeconds = 1
  totalTime = 0
@@ -554,3 +651,10 @@ export function containerPorts(
  }
  return ports
 }
+
+export async function getPodByName(name: string): Promise<k8s.V1Pod> {
+  return await k8sApi.readNamespacedPod({
+    name,
+    namespace: namespace()
+  })
+}
@@ -1,13 +1,21 @@
 import * as k8s from '@kubernetes/client-node'
 import * as fs from 'fs'
+import * as yaml from 'js-yaml'
+import * as core from '@actions/core'
+import { v1 as uuidv4 } from 'uuid'
+import { CONTAINER_EXTENSION_PREFIX } from '../hooks/constants'
+import * as shlex from 'shlex'
 import { Mount } from 'hooklib'
 import * as path from 'path'
-import { v1 as uuidv4 } from 'uuid'
 import { POD_VOLUME_NAME } from './index'

 export const DEFAULT_CONTAINER_ENTRY_POINT_ARGS = [`-f`, `/dev/null`]
 export const DEFAULT_CONTAINER_ENTRY_POINT = 'tail'

+export const ENV_HOOK_TEMPLATE_PATH = 'ACTIONS_RUNNER_CONTAINER_HOOK_TEMPLATE'
+export const ENV_DISABLE_KUBE_SCHEDULER =
+  'ACTIONS_RUNNER_DISABLE_KUBE_SCHEDULER'
+
 export function containerVolumes(
  userMountVolumes: Mount[] = [],
  jobContainer = true,
@@ -34,6 +42,16 @@ export function containerVolumes(
        name: POD_VOLUME_NAME,
        mountPath: '/github/file_commands',
        subPath: '_temp/_runner_file_commands'
+      },
+      {
+        name: POD_VOLUME_NAME,
+        mountPath: '/github/home',
+        subPath: '_temp/_github_home'
+      },
+      {
+        name: POD_VOLUME_NAME,
+        mountPath: '/github/workflow',
+        subPath: '_temp/_github_workflow'
      }
    )
    return mounts
@@ -73,7 +91,6 @@ export function containerVolumes(
          'Volume mounts outside of the work folder are not supported'
        )
      }
-      // source volume path should be relative path
      sourceVolumePath = userVolume.sourceVolumePath.slice(
        workspacePath.length + 1
      )
@@ -92,12 +109,66 @@ export function containerVolumes(
  return mounts
 }

+export function prepareJobScript(userVolumeMounts: Mount[]): {
+  containerPath: string
+  runnerPath: string
+} {
+  let mountDirs = userVolumeMounts.map(m => m.targetVolumePath).join(' ')
+
+  const content = `#!/bin/sh -l
+set -e
+cp -R /__w/_temp/_github_home /github/home
+cp -R /__w/_temp/_github_workflow /github/workflow
+mkdir -p ${mountDirs}
+`
+
+  const filename = `${uuidv4()}.sh`
+  const entryPointPath = `${process.env.RUNNER_TEMP}/${filename}`
+  fs.writeFileSync(entryPointPath, content)
+  return {
+    containerPath: `/__w/_temp/${filename}`,
+    runnerPath: entryPointPath
+  }
+}
+
 export function writeEntryPointScript(
  workingDirectory: string,
  entryPoint: string,
  entryPointArgs?: string[],
  prependPath?: string[],
  environmentVariables?: { [key: string]: string }
+): { containerPath: string; runnerPath: string } {
+  let exportPath = ''
+  if (prependPath?.length) {
+    const prepend =
+      typeof prependPath === 'string' ? prependPath : prependPath.join(':')
+    exportPath = `export PATH=${prepend}:$PATH`
+  }
+
+  const environmentPrefix = scriptEnv(environmentVariables)
+
+  const content = `#!/bin/sh -l
+${exportPath}
+cd ${workingDirectory} && \\
+exec ${environmentPrefix} ${entryPoint} ${
+    entryPointArgs?.length ? entryPointArgs.join(' ') : ''
+  }
+`
+  const filename = `${uuidv4()}.sh`
+  const entryPointPath = `${process.env.RUNNER_TEMP}/${filename}`
+  fs.writeFileSync(entryPointPath, content)
+  return {
+    containerPath: `/__w/_temp/${filename}`,
+    runnerPath: entryPointPath
+  }
+}
+
+export function writeRunScript(
+  workingDirectory: string,
+  entryPoint: string,
+  entryPointArgs?: string[],
+  prependPath?: string[],
+  environmentVariables?: { [key: string]: string }
 ): { containerPath: string; runnerPath: string } {
  let exportPath = ''
  if (prependPath?.length) {
@@ -106,24 +177,12 @@ export function writeEntryPointScript(
      typeof prependPath === 'string' ? prependPath : prependPath.join(':')
    exportPath = `export PATH=${prepend}:$PATH`
  }
-  let environmentPrefix = ''

-  if (environmentVariables && Object.entries(environmentVariables).length) {
-    const envBuffer: string[] = []
-    for (const [key, value] of Object.entries(environmentVariables)) {
-      if (key.includes(`=`) || key.includes(`'`) || key.includes(`"`)) {
-        throw new Error(
-          `environment key ${key} is invalid - the key must not contain =, ' or "`
-        )
-      }
-      envBuffer.push(
-        `"${key}=${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`
-      )
-    }
-    environmentPrefix = `env ${envBuffer.join(' ')} `
-  }
+  let environmentPrefix = scriptEnv(environmentVariables)

  const content = `#!/bin/sh -l
+set -e
+rm "$0" # remove script after running
 ${exportPath}
 cd ${workingDirectory} && \
 exec ${environmentPrefix} ${entryPoint} ${
@@ -139,9 +198,76 @@ exec ${environmentPrefix} ${entryPoint} ${
  }
 }

+export function writeContainerStepScript(
+  dst: string,
+  workingDirectory: string,
+  entryPoint: string,
+  entryPointArgs?: string[],
+  environmentVariables?: { [key: string]: string }
+): { containerPath: string; runnerPath: string } {
+  let environmentPrefix = scriptEnv(environmentVariables)
+
+  const parts = workingDirectory.split('/').slice(-2)
+  if (parts.length !== 2) {
+    throw new Error(`Invalid working directory: ${workingDirectory}`)
+  }
+
+  const content = `#!/bin/sh -l
+rm "$0" # remove script after running
+mv /__w/_temp/_github_home /github/home && \
+mv /__w/_temp/_github_workflow /github/workflow && \
+mv /__w/_temp/_runner_file_commands /github/file_commands || true && \
+mv /__w/${parts.join('/')}/ /github/workspace && \
+cd /github/workspace && \
+exec ${environmentPrefix} ${entryPoint} ${
+    entryPointArgs?.length ? entryPointArgs.join(' ') : ''
+  }
+`
+  const filename = `${uuidv4()}.sh`
+  const entryPointPath = `${dst}/${filename}`
+  core.debug(`Writing container step script to ${entryPointPath}`)
+  fs.writeFileSync(entryPointPath, content)
+  return {
+    containerPath: `/__w/_temp/${filename}`,
+    runnerPath: entryPointPath
+  }
+}
+
+function scriptEnv(envs?: { [key: string]: string }): string {
+  if (!envs || !Object.entries(envs).length) {
+    return ''
+  }
+  const envBuffer: string[] = []
+  for (const [key, value] of Object.entries(envs)) {
+    if (
+      key.includes(`=`) ||
+      key.includes(`'`) ||
+      key.includes(`"`) ||
+      key.includes(`$`)
+    ) {
+      throw new Error(
+        `environment key ${key} is invalid - the key must not contain =, $, ', or "`
+      )
+    }
+    envBuffer.push(
+      `"${key}=${value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\$/g, '\\$')
+        .replace(/`/g, '\\`')}"`
+    )
+  }
+
+  if (!envBuffer?.length) {
+    return ''
+  }
+
+  return `env ${envBuffer.join(' ')} `
+}
+
 export function generateContainerName(image: string): string {
  const nameWithTag = image.split('/').pop()
-  const name = nameWithTag?.split(':').at(0)
+  const name = nameWithTag?.split(':')[0]

  if (!name) {
    throw new Error(`Image definition '${image}' is invalid`)
@@ -150,6 +276,108 @@ export function generateContainerName(image: string): string {
  return name
 }

+// Overwrite or append based on container options
+//
+// Keep in mind, envs and volumes could be passed as fields in container definition
+// so default volume mounts and envs are appended first, and then create options are used
+// to append more values
+//
+// Rest of the fields are just applied
+// For example, container.createOptions.container.image is going to overwrite container.image field
+export function mergeContainerWithOptions(
+  base: k8s.V1Container,
+  from: k8s.V1Container
+): void {
+  for (const [key, value] of Object.entries(from)) {
+    if (key === 'name') {
+      if (value !== CONTAINER_EXTENSION_PREFIX + base.name) {
+        core.warning("Skipping name override: name can't be overwritten")
+      }
+      continue
+    } else if (key === 'image') {
+      core.warning("Skipping image override: image can't be overwritten")
+      continue
+    } else if (key === 'env') {
+      const envs = value as k8s.V1EnvVar[]
+      base.env = mergeLists(base.env, envs)
+    } else if (key === 'volumeMounts' && value) {
+      const volumeMounts = value as k8s.V1VolumeMount[]
+      base.volumeMounts = mergeLists(base.volumeMounts, volumeMounts)
+    } else if (key === 'ports' && value) {
+      const ports = value as k8s.V1ContainerPort[]
+      base.ports = mergeLists(base.ports, ports)
+    } else {
+      base[key] = value
+    }
+  }
+}
+
+export function mergePodSpecWithOptions(
+  base: k8s.V1PodSpec,
+  from: k8s.V1PodSpec
+): void {
+  for (const [key, value] of Object.entries(from)) {
+    if (key === 'containers') {
+      base.containers.push(
+        ...from.containers.filter(
+          e => !e.name?.startsWith(CONTAINER_EXTENSION_PREFIX)
+        )
+      )
+    } else if (key === 'volumes' && value) {
+      const volumes = value as k8s.V1Volume[]
+      base.volumes = mergeLists(base.volumes, volumes)
+    } else {
+      base[key] = value
+    }
+  }
+}
+
+export function mergeObjectMeta(
+  base: { metadata?: k8s.V1ObjectMeta },
+  from: k8s.V1ObjectMeta
+): void {
+  if (!base.metadata?.labels || !base.metadata?.annotations) {
+    throw new Error(
+      "Can't merge metadata: base.metadata or base.annotations field is undefined"
+    )
+  }
+  if (from?.labels) {
+    for (const [key, value] of Object.entries(from.labels)) {
+      if (base.metadata?.labels?.[key]) {
+        core.warning(`Label ${key} is already defined and will be overwritten`)
+      }
+      base.metadata.labels[key] = value
+    }
+  }
+
+  if (from?.annotations) {
+    for (const [key, value] of Object.entries(from.annotations)) {
+      if (base.metadata?.annotations?.[key]) {
+        core.warning(
+          `Annotation ${key} is already defined and will be overwritten`
+        )
+      }
+      base.metadata.annotations[key] = value
+    }
+  }
+}
+
+export function readExtensionFromFile(): k8s.V1PodTemplateSpec | undefined {
+  const filePath = process.env[ENV_HOOK_TEMPLATE_PATH]
+  if (!filePath) {
+    return undefined
+  }
+  const doc = yaml.load(fs.readFileSync(filePath, 'utf8'))
+  if (!doc || typeof doc !== 'object') {
+    throw new Error(`Failed to parse ${filePath}`)
+  }
+  return doc as k8s.V1PodTemplateSpec
+}
+
+export function useKubeScheduler(): boolean {
+  return process.env[ENV_DISABLE_KUBE_SCHEDULER] !== 'true'
+}
+
 export enum PodPhase {
  PENDING = 'Pending',
  RUNNING = 'Running',
@@ -158,3 +386,16 @@ export enum PodPhase {
  UNKNOWN = 'Unknown',
  COMPLETED = 'Completed'
 }
+
+function mergeLists<T>(base?: T[], from?: T[]): T[] {
+  const b: T[] = base || []
+  if (!from?.length) {
+    return b
+  }
+  b.push(...from)
+  return b
+}
+
+export function fixArgs(args: string[]): string[] {
+  return shlex.split(args.join(' '))
+}
@@ -3,6 +3,7 @@ import { cleanupJob, prepareJob } from '../src/hooks'
 import { RunnerInstanceLabel } from '../src/hooks/constants'
 import { namespace } from '../src/k8s'
 import { TestHelper } from './test-setup'
+import { PrepareJobArgs } from 'hooklib'

 let testHelper: TestHelper

@@ -14,7 +15,10 @@ describe('Cleanup Job', () => {
    const prepareJobOutputFilePath = testHelper.createFile(
      'prepare-job-output.json'
    )
-    await prepareJob(prepareJobData.args, prepareJobOutputFilePath)
+    await prepareJob(
+      prepareJobData.args as PrepareJobArgs,
+      prepareJobOutputFilePath
+    )
  })

  afterEach(async () => {
@@ -32,16 +36,12 @@ describe('Cleanup Job', () => {
    kc.loadFromDefault()
    const k8sApi = kc.makeApiClient(k8s.CoreV1Api)

-    const podList = await k8sApi.listNamespacedPod(
-      namespace(),
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      new RunnerInstanceLabel().toString()
-    )
+    const podList = await k8sApi.listNamespacedPod({
+      namespace: namespace(),
+      labelSelector: new RunnerInstanceLabel().toString()
+    })

-    expect(podList.body.items.length).toBe(0)
+    expect(podList.items.length).toBe(0)
  })

  it('should have no runner linked secrets', async () => {
@@ -51,15 +51,11 @@ describe('Cleanup Job', () => {
    kc.loadFromDefault()
    const k8sApi = kc.makeApiClient(k8s.CoreV1Api)

-    const secretList = await k8sApi.listNamespacedSecret(
-      namespace(),
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      new RunnerInstanceLabel().toString()
-    )
+    const secretList = await k8sApi.listNamespacedSecret({
+      namespace: namespace(),
+      labelSelector: new RunnerInstanceLabel().toString()
+    })

-    expect(secretList.body.items.length).toBe(0)
+    expect(secretList.items.length).toBe(0)
  })
 })
@@ -6,6 +6,7 @@ import {
  runScriptStep
 } from '../src/hooks'
 import { TestHelper } from './test-setup'
+import { RunContainerStepArgs, RunScriptStepArgs } from 'hooklib'

 jest.useRealTimers()

@@ -25,6 +26,7 @@ describe('e2e', () => {
  afterEach(async () => {
    await testHelper.cleanup()
  })
+
  it('should prepare job, run script step, run container step then cleanup without errors', async () => {
    await expect(
      prepareJob(prepareJobData.args, prepareJobOutputFilePath)
@@ -36,13 +38,16 @@ describe('e2e', () => {
    const prepareJobOutputData = JSON.parse(prepareJobOutputJson.toString())

    await expect(
-      runScriptStep(scriptStepData.args, prepareJobOutputData.state, null)
+      runScriptStep(
+        scriptStepData.args as RunScriptStepArgs,
+        prepareJobOutputData.state
+      )
    ).resolves.not.toThrow()

    const runContainerStepData = testHelper.getRunContainerStepDefinition()

    await expect(
-      runContainerStep(runContainerStepData.args)
+      runContainerStep(runContainerStepData.args as RunContainerStepArgs)
    ).resolves.not.toThrow()

    await expect(cleanupJob()).resolves.not.toThrow()
@@ -1,10 +1,14 @@
-import * as fs from 'fs'
-import { containerPorts, POD_VOLUME_NAME } from '../src/k8s'
+import * as fs from 'fs'
+import { containerPorts } from '../src/k8s'
 import {
-  containerVolumes,
  generateContainerName,
-  writeEntryPointScript
+  writeRunScript,
+  mergePodSpecWithOptions,
+  mergeContainerWithOptions,
+  readExtensionFromFile,
+  ENV_HOOK_TEMPLATE_PATH
 } from '../src/k8s/utils'
+import * as k8s from '@kubernetes/client-node'
 import { TestHelper } from './test-setup'

 let testHelper: TestHelper
@@ -22,35 +26,74 @@ describe('k8s utils', () => {

    it('should not throw', () => {
      expect(() =>
-        writeEntryPointScript(
-          '/test',
-          'sh',
-          ['-e', 'script.sh'],
-          ['/prepend/path'],
-          {
-            SOME_ENV: 'SOME_VALUE'
-          }
-        )
+        writeRunScript('/test', 'sh', ['-e', 'script.sh'], ['/prepend/path'], {
+          SOME_ENV: 'SOME_VALUE'
+        })
      ).not.toThrow()
    })

    it('should throw if RUNNER_TEMP is not set', () => {
      delete process.env.RUNNER_TEMP
      expect(() =>
-        writeEntryPointScript(
-          '/test',
-          'sh',
-          ['-e', 'script.sh'],
-          ['/prepend/path'],
-          {
-            SOME_ENV: 'SOME_VALUE'
-          }
-        )
+        writeRunScript('/test', 'sh', ['-e', 'script.sh'], ['/prepend/path'], {
+          SOME_ENV: 'SOME_VALUE'
+        })
      ).toThrow()
    })

+    it('should throw if environment variable name contains double quote', () => {
+      expect(() =>
+        writeRunScript('/test', 'sh', ['-e', 'script.sh'], ['/prepend/path'], {
+          'SOME"_ENV': 'SOME_VALUE'
+        })
+      ).toThrow()
+    })
+
+    it('should throw if environment variable name contains =', () => {
+      expect(() =>
+        writeRunScript('/test', 'sh', ['-e', 'script.sh'], ['/prepend/path'], {
+          'SOME=ENV': 'SOME_VALUE'
+        })
+      ).toThrow()
+    })
+
+    it('should throw if environment variable name contains single quote', () => {
+      expect(() =>
+        writeRunScript('/test', 'sh', ['-e', 'script.sh'], ['/prepend/path'], {
+          "SOME'_ENV": 'SOME_VALUE'
+        })
+      ).toThrow()
+    })
+
+    it('should throw if environment variable name contains dollar', () => {
+      expect(() =>
+        writeRunScript('/test', 'sh', ['-e', 'script.sh'], ['/prepend/path'], {
+          SOME_$_ENV: 'SOME_VALUE'
+        })
+      ).toThrow()
+    })
+
+    it('should escape double quote, dollar and backslash in environment variable values', () => {
+      const { runnerPath } = writeRunScript(
+        '/test',
+        'sh',
+        ['-e', 'script.sh'],
+        ['/prepend/path'],
+        {
+          DQUOTE: '"',
+          BACK_SLASH: '\\',
+          DOLLAR: '$'
+        }
+      )
+      expect(fs.existsSync(runnerPath)).toBe(true)
+      const script = fs.readFileSync(runnerPath, 'utf8')
+      expect(script).toContain('"DQUOTE=\\"')
+      expect(script).toContain('"BACK_SLASH=\\\\"')
+      expect(script).toContain('"DOLLAR=\\$"')
+    })
+
    it('should return object with containerPath and runnerPath', () => {
-      const { containerPath, runnerPath } = writeEntryPointScript(
+      const { containerPath, runnerPath } = writeRunScript(
        '/test',
        'sh',
        ['-e', 'script.sh'],
@@ -65,7 +108,7 @@ describe('k8s utils', () => {
    })

    it('should write entrypoint path and the file should exist', () => {
-      const { runnerPath } = writeEntryPointScript(
+      const { runnerPath } = writeRunScript(
        '/test',
        'sh',
        ['-e', 'script.sh'],
@@ -88,75 +131,6 @@ describe('k8s utils', () => {
      await testHelper.cleanup()
    })

-    it('should throw if container action and GITHUB_WORKSPACE env is not set', () => {
-      delete process.env.GITHUB_WORKSPACE
-      expect(() => containerVolumes([], true, true)).toThrow()
-      expect(() => containerVolumes([], false, true)).toThrow()
-    })
-
-    it('should always have work mount', () => {
-      let volumes = containerVolumes([], true, true)
-      expect(volumes.find(e => e.mountPath === '/__w')).toBeTruthy()
-      volumes = containerVolumes([], true, false)
-      expect(volumes.find(e => e.mountPath === '/__w')).toBeTruthy()
-      volumes = containerVolumes([], false, true)
-      expect(volumes.find(e => e.mountPath === '/__w')).toBeTruthy()
-      volumes = containerVolumes([], false, false)
-      expect(volumes.find(e => e.mountPath === '/__w')).toBeTruthy()
-    })
-
-    it('should have container action volumes', () => {
-      let volumes = containerVolumes([], true, true)
-      let workspace = volumes.find(e => e.mountPath === '/github/workspace')
-      let fileCommands = volumes.find(
-        e => e.mountPath === '/github/file_commands'
-      )
-      expect(workspace).toBeTruthy()
-      expect(workspace?.subPath).toBe('repo/repo')
-      expect(fileCommands).toBeTruthy()
-      expect(fileCommands?.subPath).toBe('_temp/_runner_file_commands')
-
-      volumes = containerVolumes([], false, true)
-      workspace = volumes.find(e => e.mountPath === '/github/workspace')
-      fileCommands = volumes.find(e => e.mountPath === '/github/file_commands')
-      expect(workspace).toBeTruthy()
-      expect(workspace?.subPath).toBe('repo/repo')
-      expect(fileCommands).toBeTruthy()
-      expect(fileCommands?.subPath).toBe('_temp/_runner_file_commands')
-    })
-
-    it('should have externals, github home and github workflow mounts if job container', () => {
-      const volumes = containerVolumes()
-      expect(volumes.find(e => e.mountPath === '/__e')).toBeTruthy()
-      expect(volumes.find(e => e.mountPath === '/github/home')).toBeTruthy()
-      expect(volumes.find(e => e.mountPath === '/github/workflow')).toBeTruthy()
-    })
-
-    it('should throw if user volume source volume path is not in workspace', () => {
-      expect(() =>
-        containerVolumes(
-          [
-            {
-              sourceVolumePath: '/outside/of/workdir'
-            }
-          ],
-          true,
-          false
-        )
-      ).toThrow()
-    })
-
-    it(`all volumes should have name ${POD_VOLUME_NAME}`, () => {
-      let volumes = containerVolumes([], true, true)
-      expect(volumes.every(e => e.name === POD_VOLUME_NAME)).toBeTruthy()
-      volumes = containerVolumes([], true, false)
-      expect(volumes.every(e => e.name === POD_VOLUME_NAME)).toBeTruthy()
-      volumes = containerVolumes([], false, true)
-      expect(volumes.every(e => e.name === POD_VOLUME_NAME)).toBeTruthy()
-      volumes = containerVolumes([], false, false)
-      expect(volumes.every(e => e.name === POD_VOLUME_NAME)).toBeTruthy()
-    })
-
    it('should parse container ports', () => {
      const tt = [
        {
@@ -253,4 +227,183 @@ describe('k8s utils', () => {
      expect(() => generateContainerName(':latest')).toThrow()
    })
  })
+
+  describe('read extension', () => {
+    beforeEach(async () => {
+      testHelper = new TestHelper()
+      await testHelper.initialize()
+    })
+
+    afterEach(async () => {
+      await testHelper.cleanup()
+    })
+
+    it('should throw if env variable is set but file does not exist', () => {
+      process.env[ENV_HOOK_TEMPLATE_PATH] =
+        '/path/that/does/not/exist/data.yaml'
+      expect(() => readExtensionFromFile()).toThrow()
+    })
+
+    it('should return undefined if env variable is not set', () => {
+      delete process.env[ENV_HOOK_TEMPLATE_PATH]
+      expect(readExtensionFromFile()).toBeUndefined()
+    })
+
+    it('should throw if file is empty', () => {
+      let filePath = testHelper.createFile('data.yaml')
+      process.env[ENV_HOOK_TEMPLATE_PATH] = filePath
+      expect(() => readExtensionFromFile()).toThrow()
+    })
+
+    it('should throw if file is not valid yaml', () => {
+      let filePath = testHelper.createFile('data.yaml')
+      fs.writeFileSync(filePath, 'invalid yaml')
+      process.env[ENV_HOOK_TEMPLATE_PATH] = filePath
+      expect(() => readExtensionFromFile()).toThrow()
+    })
+
+    it('should return object if file is valid', () => {
+      let filePath = testHelper.createFile('data.yaml')
+      fs.writeFileSync(
+        filePath,
+        `
+metadata:
+  labels:
+    label-name: label-value
+  annotations:
+    annotation-name: annotation-value
+spec:
+  containers:
+    - name: test
+      image: node:22
+    - name: job
+      image: ubuntu:latest`
+      )
+
+      process.env[ENV_HOOK_TEMPLATE_PATH] = filePath
+      const extension = readExtensionFromFile()
+      expect(extension).toBeDefined()
+    })
+  })
+
+  it('should merge container spec', () => {
+    const base = {
+      image: 'node:22',
+      name: 'test',
+      env: [
+        {
+          name: 'TEST',
+          value: 'TEST'
+        }
+      ],
+      ports: [
+        {
+          containerPort: 8080,
+          hostPort: 8080,
+          protocol: 'TCP'
+        }
+      ]
+    } as k8s.V1Container
+
+    const from = {
+      ports: [
+        {
+          containerPort: 9090,
+          hostPort: 9090,
+          protocol: 'TCP'
+        }
+      ],
+      env: [
+        {
+          name: 'TEST_TWO',
+          value: 'TEST_TWO'
+        }
+      ],
+      image: 'ubuntu:latest',
+      name: 'overwrite'
+    } as k8s.V1Container
+
+    const expectContainer = {
+      name: base.name,
+      image: base.image,
+      ports: [
+        ...(base.ports as k8s.V1ContainerPort[]),
+        ...(from.ports as k8s.V1ContainerPort[])
+      ],
+      env: [...(base.env as k8s.V1EnvVar[]), ...(from.env as k8s.V1EnvVar[])]
+    }
+
+    const expectJobContainer = JSON.parse(JSON.stringify(expectContainer))
+    expectJobContainer.name = base.name
+    mergeContainerWithOptions(base, from)
+    expect(base).toStrictEqual(expectContainer)
+  })
+
+  it('should merge pod spec', () => {
+    const base = {
+      containers: [
+        {
+          image: 'node:22',
+          name: 'test',
+          env: [
+            {
+              name: 'TEST',
+              value: 'TEST'
+            }
+          ],
+          ports: [
+            {
+              containerPort: 8080,
+              hostPort: 8080,
+              protocol: 'TCP'
+            }
+          ]
+        }
+      ],
+      restartPolicy: 'Never'
+    } as k8s.V1PodSpec
+
+    const from = {
+      securityContext: {
+        runAsUser: 1000,
+        fsGroup: 2000
+      },
+      restartPolicy: 'Always',
+      volumes: [
+        {
+          name: 'work',
+          emptyDir: {}
+        }
+      ],
+      containers: [
+        {
+          image: 'ubuntu:latest',
+          name: 'side-car',
+          env: [
+            {
+              name: 'TEST',
+              value: 'TEST'
+            }
+          ],
+          ports: [
+            {
+              containerPort: 8080,
+              hostPort: 8080,
+              protocol: 'TCP'
+            }
+          ]
+        }
+      ]
+    } as k8s.V1PodSpec
+
+    const expected = JSON.parse(JSON.stringify(base))
+    expected.securityContext = from.securityContext
+    expected.restartPolicy = from.restartPolicy
+    expected.volumes = from.volumes
+    expected.containers.push(from.containers[0])
+
+    mergePodSpecWithOptions(base, from)
+
+    expect(base).toStrictEqual(expected)
+  })
 })
@@ -3,8 +3,10 @@ import * as path from 'path'
 import { cleanupJob } from '../src/hooks'
 import { createContainerSpec, prepareJob } from '../src/hooks/prepare-job'
 import { TestHelper } from './test-setup'
-import { generateContainerName } from '../src/k8s/utils'
+import { ENV_HOOK_TEMPLATE_PATH, generateContainerName } from '../src/k8s/utils'
+import { execPodStep, getPodByName } from '../src/k8s'
 import { V1Container } from '@kubernetes/client-node'
+import { JOB_CONTAINER_NAME } from '../src/hooks/constants'

 jest.useRealTimers()

@@ -39,32 +41,82 @@ describe('Prepare job', () => {
  })

  it('should prepare job with absolute path for userVolumeMount', async () => {
+    const userVolumeMount = path.join(
+      process.env.GITHUB_WORKSPACE as string,
+      'myvolume'
+    )
+    fs.mkdirSync(userVolumeMount, { recursive: true })
+    fs.writeFileSync(path.join(userVolumeMount, 'file.txt'), 'hello')
    prepareJobData.args.container.userMountVolumes = [
      {
-        sourceVolumePath: path.join(
-          process.env.GITHUB_WORKSPACE as string,
-          '/myvolume'
-        ),
-        targetVolumePath: '/volume_mount',
+        sourceVolumePath: userVolumeMount,
+        targetVolumePath: '/__w/myvolume',
        readOnly: false
      }
    ]
    await expect(
      prepareJob(prepareJobData.args, prepareJobOutputFilePath)
    ).resolves.not.toThrow()
+
+    const content = JSON.parse(
+      fs.readFileSync(prepareJobOutputFilePath).toString()
+    )
+
+    await execPodStep(
+      ['sh', '-c', '[ "$(cat /__w/myvolume/file.txt)" = "hello" ] || exit 5'],
+      content!.state!.jobPod,
+      JOB_CONTAINER_NAME
+    ).then(output => {
+      expect(output).toBe(0)
+    })
  })

-  it('should throw an exception if the user volume mount is absolute path outside of GITHUB_WORKSPACE', async () => {
-    prepareJobData.args.container.userMountVolumes = [
-      {
-        sourceVolumePath: '/somewhere/not/in/gh-workspace',
-        targetVolumePath: '/containermount',
-        readOnly: false
-      }
-    ]
-    await expect(
-      prepareJob(prepareJobData.args, prepareJobOutputFilePath)
-    ).rejects.toThrow()
+  it('should prepare job with envs CI and GITHUB_ACTIONS', async () => {
+    await prepareJob(prepareJobData.args, prepareJobOutputFilePath)
+
+    const content = JSON.parse(
+      fs.readFileSync(prepareJobOutputFilePath).toString()
+    )
+
+    const got = await getPodByName(content.state.jobPod)
+    expect(got.spec?.containers[0].env).toEqual(
+      expect.arrayContaining([
+        { name: 'CI', value: 'true' },
+        { name: 'GITHUB_ACTIONS', value: 'true' }
+      ])
+    )
+    expect(got.spec?.containers[1].env).toEqual(
+      expect.arrayContaining([
+        { name: 'CI', value: 'true' },
+        { name: 'GITHUB_ACTIONS', value: 'true' }
+      ])
+    )
+  })
+
+  it('should not override CI env var if already set', async () => {
+    prepareJobData.args.container.environmentVariables = {
+      CI: 'false'
+    }
+
+    await prepareJob(prepareJobData.args, prepareJobOutputFilePath)
+
+    const content = JSON.parse(
+      fs.readFileSync(prepareJobOutputFilePath).toString()
+    )
+
+    const got = await getPodByName(content.state.jobPod)
+    expect(got.spec?.containers[0].env).toEqual(
+      expect.arrayContaining([
+        { name: 'CI', value: 'false' },
+        { name: 'GITHUB_ACTIONS', value: 'true' }
+      ])
+    )
+    expect(got.spec?.containers[1].env).toEqual(
+      expect.arrayContaining([
+        { name: 'CI', value: 'true' },
+        { name: 'GITHUB_ACTIONS', value: 'true' }
+      ])
+    )
  })

  it('should not run prepare job without the job container', async () => {
@@ -83,6 +135,85 @@ describe('Prepare job', () => {
    expect(services[0].args).toBe(undefined)
  })

+  it('should determine alpine correctly', async () => {
+    prepareJobData.args.container.image = 'alpine:latest'
+    await prepareJob(prepareJobData.args, prepareJobOutputFilePath)
+    const content = JSON.parse(
+      fs.readFileSync(prepareJobOutputFilePath).toString()
+    )
+    expect(content.isAlpine).toBe(true)
+  })
+
+  it('should run pod with extensions applied', async () => {
+    process.env[ENV_HOOK_TEMPLATE_PATH] = path.join(
+      __dirname,
+      '../../../examples/extension.yaml'
+    )
+
+    await expect(
+      prepareJob(prepareJobData.args, prepareJobOutputFilePath)
+    ).resolves.not.toThrow()
+
+    delete process.env[ENV_HOOK_TEMPLATE_PATH]
+
+    const content = JSON.parse(
+      fs.readFileSync(prepareJobOutputFilePath).toString()
+    )
+
+    const got = await getPodByName(content.state.jobPod)
+
+    expect(got.metadata?.annotations?.['annotated-by']).toBe('extension')
+    expect(got.metadata?.labels?.['labeled-by']).toBe('extension')
+    expect(got.spec?.restartPolicy).toBe('Never')
+
+    // job container
+    expect(got.spec?.containers[0].name).toBe(JOB_CONTAINER_NAME)
+    expect(got.spec?.containers[0].image).toBe('node:22')
+    expect(got.spec?.containers[0].command).toEqual(['sh'])
+    expect(got.spec?.containers[0].args).toEqual(['-c', 'sleep 50'])
+
+    // service container
+    expect(got.spec?.containers[1].image).toBe('redis')
+    expect(got.spec?.containers[1].command).toBeFalsy()
+    expect(got.spec?.containers[1].args).toBeFalsy()
+    expect(got.spec?.containers[1].env).toEqual(
+      expect.arrayContaining([
+        { name: 'CI', value: 'true' },
+        { name: 'GITHUB_ACTIONS', value: 'true' },
+        { name: 'ENV2', value: 'value2' }
+      ])
+    )
+    expect(got.spec?.containers[1].resources).toEqual({
+      requests: { memory: '1Mi', cpu: '1' },
+      limits: { memory: '1Gi', cpu: '2' }
+    })
+    // side-car
+    expect(got.spec?.containers[2].name).toBe('side-car')
+    expect(got.spec?.containers[2].image).toBe('ubuntu:latest')
+    expect(got.spec?.containers[2].command).toEqual(['sh'])
+    expect(got.spec?.containers[2].args).toEqual(['-c', 'sleep 60'])
+  })
+
+  it('should put only job and services in output context file', async () => {
+    process.env[ENV_HOOK_TEMPLATE_PATH] = path.join(
+      __dirname,
+      '../../../examples/extension.yaml'
+    )
+
+    await expect(
+      prepareJob(prepareJobData.args, prepareJobOutputFilePath)
+    ).resolves.not.toThrow()
+
+    const content = JSON.parse(
+      fs.readFileSync(prepareJobOutputFilePath).toString()
+    )
+
+    expect(content.state.jobPod).toBeTruthy()
+    expect(content.context.container).toBeTruthy()
+    expect(content.context.services).toBeTruthy()
+    expect(content.context.services.length).toBe(1)
+  })
+
  test.each([undefined, null, []])(
    'should not throw exception when portMapping=%p',
    async pm => {
@@ -96,4 +227,20 @@ describe('Prepare job', () => {
      expect(() => content.context.services[0].image).not.toThrow()
    }
  )
+
+  it('should prepare job with container with non-root user', async () => {
+    prepareJobData.args!.container!.image =
+      'ghcr.io/actions/actions-runner:latest' // known to use user 1001
+    await expect(
+      prepareJob(prepareJobData.args, prepareJobOutputFilePath)
+    ).resolves.not.toThrow()
+
+    const content = JSON.parse(
+      fs.readFileSync(prepareJobOutputFilePath).toString()
+    )
+    expect(content.state.jobPod).toBeTruthy()
+    expect(content.context.container.image).toBe(
+      'ghcr.io/actions/actions-runner:latest'
+    )
+  })
 })
@@ -1,16 +1,25 @@
-import { runContainerStep } from '../src/hooks'
+import { prepareJob, runContainerStep } from '../src/hooks'
 import { TestHelper } from './test-setup'
+import { ENV_HOOK_TEMPLATE_PATH } from '../src/k8s/utils'
+import * as fs from 'fs'
+import * as yaml from 'js-yaml'
+import { JOB_CONTAINER_EXTENSION_NAME } from '../src/hooks/constants'

 jest.useRealTimers()

 let testHelper: TestHelper

 let runContainerStepData: any
+let prepareJobData: any
+let prepareJobOutputFilePath: string

 describe('Run container step', () => {
  beforeEach(async () => {
    testHelper = new TestHelper()
    await testHelper.initialize()
+    prepareJobData = testHelper.getPrepareJobDefinition()
+    prepareJobOutputFilePath = testHelper.createFile('prepare-job-output.json')
+    await prepareJob(prepareJobData.args, prepareJobOutputFilePath)
    runContainerStepData = testHelper.getRunContainerStepDefinition()
  })

@@ -18,14 +27,41 @@ describe('Run container step', () => {
    await testHelper.cleanup()
  })

-  it('should not throw', async () => {
-    const exitCode = await runContainerStep(runContainerStepData.args)
-    expect(exitCode).toBe(0)
-  })
+  it('should run pod with extensions applied', async () => {
+    const extension = {
+      metadata: {
+        annotations: {
+          foo: 'bar'
+        },
+        labels: {
+          bar: 'baz'
+        }
+      },
+      spec: {
+        containers: [
+          {
+            name: JOB_CONTAINER_EXTENSION_NAME,
+            command: ['sh'],
+            args: ['-c', 'sleep 10000']
+          },
+          {
+            name: 'side-container',
+            image: 'ubuntu:latest',
+            command: ['sh'],
+            args: ['-c', 'echo test']
+          }
+        ],
+        restartPolicy: 'Never'
+      }
+    }

-  it('should fail if the working directory does not exist', async () => {
-    runContainerStepData.args.workingDirectory = '/foo/bar'
-    await expect(runContainerStep(runContainerStepData.args)).rejects.toThrow()
+    let filePath = testHelper.createFile()
+    fs.writeFileSync(filePath, yaml.dump(extension))
+    process.env[ENV_HOOK_TEMPLATE_PATH] = filePath
+    await expect(
+      runContainerStep(runContainerStepData.args)
+    ).resolves.not.toThrow()
+    delete process.env[ENV_HOOK_TEMPLATE_PATH]
  })

  it('should shold have env variables available', async () => {
@@ -38,4 +74,15 @@ describe('Run container step', () => {
      runContainerStep(runContainerStepData.args)
    ).resolves.not.toThrow()
  })
+
+  it('should run container step with envs CI and GITHUB_ACTIONS', async () => {
+    runContainerStepData.args.entryPoint = 'bash'
+    runContainerStepData.args.entryPointArgs = [
+      '-c',
+      "'if [[ -z $GITHUB_ACTIONS  ]] || [[ -z $CI ]]; then exit 1; fi'"
+    ]
+    await expect(
+      runContainerStep(runContainerStepData.args)
+    ).resolves.not.toThrow()
+  })
 })
@@ -1,6 +1,7 @@
 import * as fs from 'fs'
 import { cleanupJob, prepareJob, runScriptStep } from '../src/hooks'
 import { TestHelper } from './test-setup'
+import { PrepareJobArgs, RunScriptStepArgs } from 'hooklib'

 jest.useRealTimers()

@@ -8,7 +9,9 @@ let testHelper: TestHelper

 let prepareJobOutputData: any

-let runScriptStepDefinition
+let runScriptStepDefinition: {
+  args: RunScriptStepArgs
+}

 describe('Run script step', () => {
  beforeEach(async () => {
@@ -19,9 +22,14 @@ describe('Run script step', () => {
    )

    const prepareJobData = testHelper.getPrepareJobDefinition()
-    runScriptStepDefinition = testHelper.getRunScriptStepDefinition()
+    runScriptStepDefinition = testHelper.getRunScriptStepDefinition() as {
+      args: RunScriptStepArgs
+    }

-    await prepareJob(prepareJobData.args, prepareJobOutputFilePath)
+    await prepareJob(
+      prepareJobData.args as PrepareJobArgs,
+      prepareJobOutputFilePath
+    )
    const outputContent = fs.readFileSync(prepareJobOutputFilePath)
    prepareJobOutputData = JSON.parse(outputContent.toString())
  })
@@ -37,22 +45,14 @@ describe('Run script step', () => {

  it('should not throw an exception', async () => {
    await expect(
-      runScriptStep(
-        runScriptStepDefinition.args,
-        prepareJobOutputData.state,
-        null
-      )
+      runScriptStep(runScriptStepDefinition.args, prepareJobOutputData.state)
    ).resolves.not.toThrow()
  })

  it('should fail if the working directory does not exist', async () => {
    runScriptStepDefinition.args.workingDirectory = '/foo/bar'
    await expect(
-      runScriptStep(
-        runScriptStepDefinition.args,
-        prepareJobOutputData.state,
-        null
-      )
+      runScriptStep(runScriptStepDefinition.args, prepareJobOutputData.state)
    ).rejects.toThrow()
  })

@@ -64,16 +64,12 @@ describe('Run script step', () => {
      "'if [[ -z $NODE_ENV ]]; then exit 1; fi'"
    ]
    await expect(
-      runScriptStep(
-        runScriptStepDefinition.args,
-        prepareJobOutputData.state,
-        null
-      )
+      runScriptStep(runScriptStepDefinition.args, prepareJobOutputData.state)
    ).resolves.not.toThrow()
  })

  it('Should have path variable changed in container with prepend path string', async () => {
-    runScriptStepDefinition.args.prependPath = '/some/path'
+    runScriptStepDefinition.args.prependPath = ['/some/path']
    runScriptStepDefinition.args.entryPoint = '/bin/bash'
    runScriptStepDefinition.args.entryPointArgs = [
      '-c',
@@ -81,11 +77,25 @@ describe('Run script step', () => {
    ]

    await expect(
-      runScriptStep(
-        runScriptStepDefinition.args,
-        prepareJobOutputData.state,
-        null
-      )
+      runScriptStep(runScriptStepDefinition.args, prepareJobOutputData.state)
+    ).resolves.not.toThrow()
+  })
+
+  it('Dollar symbols in environment variables should not be expanded', async () => {
+    runScriptStepDefinition.args.environmentVariables = {
+      VARIABLE1: '$VAR',
+      VARIABLE2: '${VAR}',
+      VARIABLE3: '$(VAR)'
+    }
+    runScriptStepDefinition.args.entryPointArgs = [
+      '-c',
+      '\'if [[ -z "$VARIABLE1" ]]; then exit 1; fi\'',
+      '\'if [[ -z "$VARIABLE2" ]]; then exit 2; fi\'',
+      '\'if [[ -z "$VARIABLE3" ]]; then exit 3; fi\''
+    ]
+
+    await expect(
+      runScriptStep(runScriptStepDefinition.args, prepareJobOutputData.state)
    ).resolves.not.toThrow()
  })

@@ -100,11 +110,7 @@ describe('Run script step', () => {
    ]

    await expect(
-      runScriptStep(
-        runScriptStepDefinition.args,
-        prepareJobOutputData.state,
-        null
-      )
+      runScriptStep(runScriptStepDefinition.args, prepareJobOutputData.state)
    ).resolves.not.toThrow()
  })
 })
@@ -0,0 +1,137 @@
+import * as fs from 'fs'
+import { cleanupJob } from '../src/hooks'
+import { prepareJob } from '../src/hooks/prepare-job'
+import { TestHelper } from './test-setup'
+import { getPodByName } from '../src/k8s'
+import { ENV_DISABLE_KUBE_SCHEDULER } from '../src/k8s/utils'
+
+jest.useRealTimers()
+
+let testHelper: TestHelper
+let prepareJobData: any
+let prepareJobOutputFilePath: string
+
+describe('RWO Affinity Behavior (Scheduler Mode)', () => {
+  beforeEach(async () => {
+    testHelper = new TestHelper()
+    await testHelper.initialize()
+    prepareJobData = testHelper.getPrepareJobDefinition()
+    prepareJobOutputFilePath = testHelper.createFile('prepare-job-output.json')
+  })
+
+  afterEach(async () => {
+    await cleanupJob()
+    await testHelper.cleanup()
+    delete process.env[ENV_DISABLE_KUBE_SCHEDULER]
+  })
+
+  it('should add nodeAffinity with hostname selector by default', async () => {
+    await prepareJob(prepareJobData.args, prepareJobOutputFilePath)
+
+    const content = JSON.parse(
+      fs.readFileSync(prepareJobOutputFilePath).toString()
+    )
+
+    const pod = await getPodByName(content.state.jobPod)
+
+    expect(pod.spec?.affinity).toBeDefined()
+    expect(pod.spec?.affinity?.nodeAffinity).toBeDefined()
+
+    const nodeAffinity = pod.spec?.affinity?.nodeAffinity
+    expect(
+      nodeAffinity?.requiredDuringSchedulingIgnoredDuringExecution
+    ).toBeDefined()
+
+    const nodeSelectorTerms =
+      nodeAffinity?.requiredDuringSchedulingIgnoredDuringExecution
+        ?.nodeSelectorTerms
+
+    expect(nodeSelectorTerms).toBeDefined()
+    expect(nodeSelectorTerms?.length).toBeGreaterThan(0)
+
+    const matchExpressions = nodeSelectorTerms?.[0].matchExpressions
+    expect(matchExpressions).toBeDefined()
+    expect(matchExpressions?.length).toBeGreaterThan(0)
+
+    const hostnameExpression = matchExpressions?.[0]
+    expect(hostnameExpression?.key).toBe('kubernetes.io/hostname')
+    expect(hostnameExpression?.operator).toBe('In')
+
+    expect(hostnameExpression?.values).toBeDefined()
+    expect(hostnameExpression?.values?.length).toBeGreaterThan(0)
+    expect(hostnameExpression?.values?.[0]).toBeTruthy()
+  })
+
+  it('should NOT add nodeAffinity when scheduler mode is disabled', async () => {
+    process.env[ENV_DISABLE_KUBE_SCHEDULER] = 'true'
+
+    await prepareJob(prepareJobData.args, prepareJobOutputFilePath)
+
+    const content = JSON.parse(
+      fs.readFileSync(prepareJobOutputFilePath).toString()
+    )
+
+    const pod = await getPodByName(content.state.jobPod)
+
+    if (pod.spec?.affinity) {
+      expect(pod.spec.affinity.nodeAffinity).toBeUndefined()
+    }
+
+    expect(pod.spec?.nodeName).toBeDefined()
+  })
+
+  it('should fail assertion if affinity block is missing by default', async () => {
+    await prepareJob(prepareJobData.args, prepareJobOutputFilePath)
+
+    const content = JSON.parse(
+      fs.readFileSync(prepareJobOutputFilePath).toString()
+    )
+
+    const pod = await getPodByName(content.state.jobPod)
+
+    expect(pod.spec?.affinity).toBeDefined()
+    expect(pod.spec?.affinity?.nodeAffinity).toBeDefined()
+    expect(
+      pod.spec?.affinity?.nodeAffinity
+        ?.requiredDuringSchedulingIgnoredDuringExecution
+    ).toBeDefined()
+
+    const nodeSelectorTerms =
+      pod.spec?.affinity?.nodeAffinity
+        ?.requiredDuringSchedulingIgnoredDuringExecution?.nodeSelectorTerms
+
+    expect(nodeSelectorTerms?.[0]?.matchExpressions?.[0]?.key).toBe(
+      'kubernetes.io/hostname'
+    )
+    expect(nodeSelectorTerms?.[0]?.matchExpressions?.[0]?.operator).toBe('In')
+    expect(
+      nodeSelectorTerms?.[0]?.matchExpressions?.[0]?.values?.length
+    ).toBeGreaterThan(0)
+  })
+
+  it('should use correct node name from runner pod in affinity values by default', async () => {
+    const runnerPodName = process.env.ACTIONS_RUNNER_POD_NAME
+
+    await prepareJob(prepareJobData.args, prepareJobOutputFilePath)
+
+    const content = JSON.parse(
+      fs.readFileSync(prepareJobOutputFilePath).toString()
+    )
+
+    const jobPod = await getPodByName(content.state.jobPod)
+
+    const runnerPod = await getPodByName(runnerPodName!)
+
+    const affinityValues =
+      jobPod.spec?.affinity?.nodeAffinity
+        ?.requiredDuringSchedulingIgnoredDuringExecution?.nodeSelectorTerms?.[0]
+        ?.matchExpressions?.[0]?.values
+
+    expect(affinityValues).toBeDefined()
+    expect(affinityValues?.length).toBeGreaterThan(0)
+
+    if (runnerPod.spec?.nodeName) {
+      expect(affinityValues).toContain(runnerPod.spec.nodeName)
+    }
+  })
+})
@@ -0,0 +1,28 @@
+import {
+  isRWXTestEnabled,
+  getRWXStorageClass,
+  RWX_SKIP_MESSAGE
+} from './test-setup'
+
+describe('RWX Test Contract Demo', () => {
+  const describeOrSkip = isRWXTestEnabled() ? describe : describe.skip
+
+  describeOrSkip('RWX volume tests', () => {
+    it('should use RWX storage class when enabled', () => {
+      const storageClass = getRWXStorageClass()
+      expect(storageClass).toBeDefined()
+      expect(typeof storageClass).toBe('string')
+    })
+
+    it('should verify both env vars are required', () => {
+      expect(process.env.ACTIONS_RUNNER_K8S_TEST_ENABLE_RWX).toBe('true')
+      expect(
+        process.env.ACTIONS_RUNNER_K8S_TEST_RWX_STORAGE_CLASS
+      ).toBeDefined()
+    })
+  })
+
+  if (!isRWXTestEnabled()) {
+    it(RWX_SKIP_MESSAGE, () => {})
+  }
+})
@@ -0,0 +1,119 @@
+import * as k8s from '@kubernetes/client-node'
+import * as fs from 'fs'
+import { cleanupJob, prepareJob, runScriptStep } from '../src/hooks'
+import {
+  TestHelper,
+  isRWXTestEnabled,
+  getRWXStorageClass,
+  RWX_SKIP_MESSAGE
+} from './test-setup'
+import { RunScriptStepArgs } from 'hooklib'
+
+jest.useRealTimers()
+
+const kc = new k8s.KubeConfig()
+kc.loadFromDefault()
+const k8sApi = kc.makeApiClient(k8s.CoreV1Api)
+
+describe('RWX Volume Tests', () => {
+  const describeOrSkip = isRWXTestEnabled() ? describe : describe.skip
+
+  describeOrSkip('RWX volume integration', () => {
+    let testHelper: TestHelper
+    let rwxPvcName: string
+    let prepareJobData: any
+    let prepareJobOutputFilePath: string
+
+    beforeEach(async () => {
+      testHelper = new TestHelper()
+      await testHelper.initialize()
+
+      const podName = process.env.ACTIONS_RUNNER_POD_NAME
+      rwxPvcName = `${podName}-work-rwx`
+
+      const volumeClaim: k8s.V1PersistentVolumeClaim = {
+        metadata: {
+          name: rwxPvcName
+        },
+        spec: {
+          accessModes: ['ReadWriteMany'],
+          volumeMode: 'Filesystem',
+          storageClassName: getRWXStorageClass(),
+          resources: {
+            requests: {
+              storage: '1Gi'
+            }
+          }
+        }
+      }
+
+      await k8sApi.createNamespacedPersistentVolumeClaim({
+        namespace: 'default',
+        body: volumeClaim
+      })
+
+      process.env.ACTIONS_RUNNER_CLAIM_NAME = rwxPvcName
+
+      prepareJobData = testHelper.getPrepareJobDefinition()
+      prepareJobOutputFilePath = testHelper.createFile(
+        'prepare-job-output.json'
+      )
+    })
+
+    afterAll(async () => {
+      if (rwxPvcName) {
+        try {
+          await k8sApi.deleteNamespacedPersistentVolumeClaim({
+            name: rwxPvcName,
+            namespace: 'default'
+          })
+        } catch {
+          // Ignore cleanup errors - PVC may not exist
+        }
+      }
+    })
+
+    afterEach(async () => {
+      await testHelper.cleanup()
+    })
+
+    it('should successfully run hook flow with RWX volume', async () => {
+      await expect(
+        prepareJob(prepareJobData.args, prepareJobOutputFilePath)
+      ).resolves.not.toThrow()
+
+      const prepareJobOutputJson = fs.readFileSync(prepareJobOutputFilePath)
+      const prepareJobOutputData = JSON.parse(prepareJobOutputJson.toString())
+
+      const scriptStepData = testHelper.getRunScriptStepDefinition()
+
+      await expect(
+        runScriptStep(
+          scriptStepData.args as RunScriptStepArgs,
+          prepareJobOutputData.state
+        )
+      ).resolves.not.toThrow()
+
+      await expect(cleanupJob()).resolves.not.toThrow()
+    })
+
+    it('should verify RWX PVC was created with correct access mode', async () => {
+      const pvc = await k8sApi.readNamespacedPersistentVolumeClaim({
+        name: rwxPvcName,
+        namespace: 'default'
+      })
+
+      expect(pvc.spec?.accessModes).toContain('ReadWriteMany')
+      expect(pvc.spec?.storageClassName).toBe(getRWXStorageClass())
+      expect(pvc.spec?.volumeMode).toBe('Filesystem')
+    })
+
+    it('should verify RWX claim name is set correctly', () => {
+      expect(process.env.ACTIONS_RUNNER_CLAIM_NAME).toBe(rwxPvcName)
+    })
+  })
+
+  if (!isRWXTestEnabled()) {
+    it(RWX_SKIP_MESSAGE, () => {})
+  }
+})
@@ -14,25 +14,35 @@ const k8sStorageApi = kc.makeApiClient(k8s.StorageV1Api)
 export class TestHelper {
  private tempDirPath: string
  private podName: string
+  private runnerWorkdir: string
+  private runnerTemp: string
+
  constructor() {
    this.tempDirPath = `${__dirname}/_temp/runner`
+    this.runnerWorkdir = `${this.tempDirPath}/_work`
+    this.runnerTemp = `${this.tempDirPath}/_work/_temp`
    this.podName = uuidv4().replace(/-/g, '')
  }

-  public async initialize(): Promise<void> {
+  async initialize(): Promise<void> {
    process.env['ACTIONS_RUNNER_POD_NAME'] = `${this.podName}`
-    process.env['RUNNER_WORKSPACE'] = `${this.tempDirPath}/_work/repo`
-    process.env['RUNNER_TEMP'] = `${this.tempDirPath}/_work/_temp`
-    process.env['GITHUB_WORKSPACE'] = `${this.tempDirPath}/_work/repo/repo`
+    process.env['RUNNER_WORKSPACE'] = `${this.runnerWorkdir}/repo`
+    process.env['RUNNER_TEMP'] = `${this.runnerTemp}`
+    process.env['GITHUB_WORKSPACE'] = `${this.runnerWorkdir}/repo/repo`
    process.env['ACTIONS_RUNNER_KUBERNETES_NAMESPACE'] = 'default'

-    fs.mkdirSync(`${this.tempDirPath}/_work/repo/repo`, { recursive: true })
+    fs.mkdirSync(`${this.runnerWorkdir}/repo/repo`, { recursive: true })
    fs.mkdirSync(`${this.tempDirPath}/externals`, { recursive: true })
-    fs.mkdirSync(process.env.RUNNER_TEMP, { recursive: true })
+    fs.mkdirSync(this.runnerTemp, { recursive: true })
+    fs.mkdirSync(`${this.runnerTemp}/_github_workflow`, { recursive: true })
+    fs.mkdirSync(`${this.runnerTemp}/_github_home`, { recursive: true })
+    fs.mkdirSync(`${this.runnerTemp}/_runner_file_commands`, {
+      recursive: true
+    })

    fs.copyFileSync(
      path.resolve(`${__dirname}/../../../examples/example-script.sh`),
-      `${process.env.RUNNER_TEMP}/example-script.sh`
+      `${this.runnerTemp}/example-script.sh`
    )

    await this.cleanupK8sResources()
@@ -44,52 +54,80 @@ export class TestHelper {
    }
  }

-  public async cleanup(): Promise<void> {
+  async cleanup(): Promise<void> {
    try {
      await this.cleanupK8sResources()
      fs.rmSync(this.tempDirPath, { recursive: true })
-    } catch {}
+    } catch {
+      // Ignore errors during cleanup
+    }
  }
-  public async cleanupK8sResources() {
+
+  async cleanupK8sResources(): Promise<void> {
    await k8sApi
-      .deleteNamespacedPersistentVolumeClaim(
-        `${this.podName}-work`,
-        'default',
-        undefined,
-        undefined,
-        0
-      )
-      .catch(e => {})
-    await k8sApi.deletePersistentVolume(`${this.podName}-pv`).catch(e => {})
-    await k8sStorageApi.deleteStorageClass('local-storage').catch(e => {})
+      .deleteNamespacedPersistentVolumeClaim({
+        name: `${this.podName}-work`,
+        namespace: 'default',
+        gracePeriodSeconds: 0
+      })
+      .catch((e: k8s.ApiException<any>) => {
+        if (e.code !== 404) {
+          console.error(JSON.stringify(e))
+        }
+      })
    await k8sApi
-      .deleteNamespacedPod(this.podName, 'default', undefined, undefined, 0)
-      .catch(e => {})
+      .deletePersistentVolume({ name: `${this.podName}-pv` })
+      .catch((e: k8s.ApiException<any>) => {
+        if (e.code !== 404) {
+          console.error(JSON.stringify(e))
+        }
+      })
    await k8sApi
-      .deleteNamespacedPod(
-        `${this.podName}-workflow`,
-        'default',
-        undefined,
-        undefined,
-        0
-      )
-      .catch(e => {})
+      .deleteNamespacedPod({
+        name: this.podName,
+        namespace: 'default',
+        gracePeriodSeconds: 0
+      })
+      .catch((e: k8s.ApiException<any>) => {
+        if (e.code !== 404) {
+          console.error(JSON.stringify(e))
+        }
+      })
+    await k8sApi
+      .deleteNamespacedPod({
+        name: `${this.podName}-workflow`,
+        namespace: 'default',
+        gracePeriodSeconds: 0
+      })
+      .catch((e: k8s.ApiException<any>) => {
+        if (e.code !== 404) {
+          console.error(JSON.stringify(e))
+        }
+      })
+
+    await k8sStorageApi
+      .deleteStorageClass({ name: `${this.podName}-storage` })
+      .catch((e: k8s.ApiException<any>) => {
+        if (e.code !== 404) {
+          console.error(JSON.stringify(e))
+        }
+      })
  }
-  public createFile(fileName?: string): string {
+  createFile(fileName?: string): string {
    const filePath = `${this.tempDirPath}/${fileName || uuidv4()}`
    fs.writeFileSync(filePath, '')
    return filePath
  }

-  public removeFile(fileName: string): void {
+  removeFile(fileName: string): void {
    const filePath = `${this.tempDirPath}/${fileName}`
    fs.rmSync(filePath)
  }

-  public async createTestJobPod() {
+  async createTestJobPod(): Promise<void> {
    const container = {
-      name: 'nginx',
-      image: 'nginx:latest',
+      name: 'runner',
+      image: 'ghcr.io/actions/actions-runner:latest',
      imagePullPolicy: 'IfNotPresent'
    } as k8s.V1Container

@@ -99,28 +137,35 @@ export class TestHelper {
      },
      spec: {
        restartPolicy: 'Never',
-        containers: [container]
+        containers: [container],
+        securityContext: {
+          runAsUser: 1001,
+          runAsGroup: 1001,
+          fsGroup: 1001
+        }
      }
    } as k8s.V1Pod
-    await k8sApi.createNamespacedPod('default', pod)
+    await k8sApi.createNamespacedPod({ namespace: 'default', body: pod })
  }

-  public async createTestVolume() {
-    var sc: k8s.V1StorageClass = {
+  async createTestVolume(): Promise<void> {
+    const storageClassName = `${this.podName}-storage`
+
+    const sc: k8s.V1StorageClass = {
      metadata: {
-        name: 'local-storage'
+        name: storageClassName
      },
      provisioner: 'kubernetes.io/no-provisioner',
      volumeBindingMode: 'Immediate'
    }
-    await k8sStorageApi.createStorageClass(sc)
+    await k8sStorageApi.createStorageClass({ body: sc })

-    var volume: k8s.V1PersistentVolume = {
+    const volume: k8s.V1PersistentVolume = {
      metadata: {
        name: `${this.podName}-pv`
      },
      spec: {
-        storageClassName: 'local-storage',
+        storageClassName,
        capacity: {
          storage: '2Gi'
        },
@@ -131,15 +176,16 @@ export class TestHelper {
        }
      }
    }
-    await k8sApi.createPersistentVolume(volume)
-    var volumeClaim: k8s.V1PersistentVolumeClaim = {
+    await k8sApi.createPersistentVolume({ body: volume })
+
+    const volumeClaim: k8s.V1PersistentVolumeClaim = {
      metadata: {
        name: `${this.podName}-work`
      },
      spec: {
        accessModes: ['ReadWriteOnce'],
        volumeMode: 'Filesystem',
-        storageClassName: 'local-storage',
+        storageClassName,
        volumeName: `${this.podName}-pv`,
        resources: {
          requests: {
@@ -148,10 +194,13 @@ export class TestHelper {
        }
      }
    }
-    await k8sApi.createNamespacedPersistentVolumeClaim('default', volumeClaim)
+    await k8sApi.createNamespacedPersistentVolumeClaim({
+      namespace: 'default',
+      body: volumeClaim
+    })
  }

-  public getPrepareJobDefinition(): HookData {
+  getPrepareJobDefinition(): HookData {
    const prepareJob = JSON.parse(
      fs.readFileSync(
        path.resolve(__dirname + '/../../../examples/prepare-job.json'),
@@ -168,7 +217,7 @@ export class TestHelper {
    return prepareJob
  }

-  public getRunScriptStepDefinition(): HookData {
+  getRunScriptStepDefinition(): HookData {
    const runScriptStep = JSON.parse(
      fs.readFileSync(
        path.resolve(__dirname + '/../../../examples/run-script-step.json'),
@@ -180,7 +229,7 @@ export class TestHelper {
    return runScriptStep
  }

-  public getRunContainerStepDefinition(): HookData {
+  getRunContainerStepDefinition(): HookData {
    const runContainerStep = JSON.parse(
      fs.readFileSync(
        path.resolve(__dirname + '/../../../examples/run-container-step.json'),
@@ -194,3 +243,65 @@ export class TestHelper {
    return runContainerStep
  }
 }
+
+/**
+ * RWX Test Contract:
+ *
+ * Tests requiring ReadWriteMany (RWX) volumes MUST be gated by TWO environment variables:
+ * 1. ACTIONS_RUNNER_K8S_TEST_ENABLE_RWX=true (explicit opt-in)
+ * 2. ACTIONS_RUNNER_K8S_TEST_RWX_STORAGE_CLASS=<name> (storage class that supports RWX)
+ *
+ * If either variable is missing or ACTIONS_RUNNER_K8S_TEST_ENABLE_RWX is not "true",
+ * the test MUST be skipped with the exact message defined in this contract.
+ *
+ * This contract ensures:
+ * - RWX tests do not fail on clusters without RWX provisioners
+ * - Test requirements are explicit and documented
+ * - RWO affinity tests remain independent and always runnable
+ * - Skip behavior is deterministic (no dynamic cluster probing)
+ *
+ * Usage example:
+ * ```typescript
+ * import { isRWXTestEnabled, getRWXStorageClass, RWX_SKIP_MESSAGE } from './test-setup'
+ *
+ * describe('RWX Test Suite', () => {
+ *   const describeOrSkip = isRWXTestEnabled() ? describe : describe.skip
+ *
+ *   describeOrSkip('RWX volume tests', () => {
+ *     it('should test RWX functionality', async () => {
+ *       const storageClass = getRWXStorageClass()
+ *       // ... test code using storageClass
+ *     })
+ *   })
+ *
+ *   if (!isRWXTestEnabled()) {
+ *     it(RWX_SKIP_MESSAGE, () => {})
+ *   }
+ * })
+ * ```
+ */
+
+/**
+ * Checks if RWX tests should run based on environment variables.
+ * @returns true if both ACTIONS_RUNNER_K8S_TEST_ENABLE_RWX=true and ACTIONS_RUNNER_K8S_TEST_RWX_STORAGE_CLASS are set
+ */
+export function isRWXTestEnabled(): boolean {
+  const enabled = process.env.ACTIONS_RUNNER_K8S_TEST_ENABLE_RWX === 'true'
+  const storageClass = process.env.ACTIONS_RUNNER_K8S_TEST_RWX_STORAGE_CLASS
+  return enabled && !!storageClass
+}
+
+/**
+ * Gets the RWX storage class name from environment variable.
+ * @returns The storage class name, or undefined if not set
+ */
+export function getRWXStorageClass(): string | undefined {
+  return process.env.ACTIONS_RUNNER_K8S_TEST_RWX_STORAGE_CLASS
+}
+
+/**
+ * Skip message constant - DO NOT MODIFY
+ * This exact message must be used when skipping RWX tests
+ */
+export const RWX_SKIP_MESSAGE =
+  'RWX tests skipped: set ACTIONS_RUNNER_K8S_TEST_ENABLE_RWX=true and ACTIONS_RUNNER_K8S_TEST_RWX_STORAGE_CLASS'
@@ -5,7 +5,8 @@
      "outDir": "./lib",
      "rootDir": "./src"
    },
+    "esModuleInterop": true, /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
    "include": [
-      "./src"
+      "src/**/*",
    ]
-  }
+}
@@ -0,0 +1,6 @@
+{
+  "compilerOptions": {
+    "allowJs": true
+  },
+  "extends": "./tsconfig.json"
+}
@@ -1,12 +1,25 @@
-## Features
- Use service container entrypoint if no entrypoint is specified [#53]
+<!-- ## Features -->

 ## Bugs
- Fixed issue caused by promise rejection in kubernetes hook [#65]
- Fixed service container name issue when service image contains one or more `/`
-  in the name [#53]
- Fixed issue related to service container failures when no ports are specified
-  [#60]
- Allow equal signs in environment variable values [#62]

-<!-- ## Misc
+- Change command to remove sudo to fix fs-init initial container [#263]
+- Sort 'find' output before hashing for consistency [#267]
+- feat: check if required binaries are present [#272]
+- Allow non-root container [#264]
+- Improve validation checks after copying [#285]
+- Fix workingDir permissions issue by creating it within init container [#283]
+- Fix event.json not being copied to /github/workflow in kubernetes-novolume mode [#287]
+- Reduce the amount of data copied to the workflow pod [#293]
+- Overwrite runner file commands [#298]
+
+## Misc
+
+- Dependency updates [#276] [#277] [#278] [#279] [#304]
+- Group dependabot updates [#289]
+
+## SHA-256 Checksums
+
+The SHA-256 checksums for the packages included in this build are shown below:
+
+- actions-runner-hooks-docker-<HOOK_VERSION>.zip <DOCKER_SHA>
+- actions-runner-hooks-k8s-<HOOK_VERSION>.zip <K8S_SHA>