Complete documentation and tests for action execution model

Co-authored-by: salmanmkc <32169182+salmanmkc@users.noreply.github.com>

docs/action-execution-model.md

@@ -0,0 +1,144 @@
+# GitHub Actions Execution Model
+
+## Question: Do Actions Need to be Compiled?
+
+**Short Answer**: No, GitHub Actions themselves do **NOT** need to be compiled from source code. They run directly as interpreted code, container images, or step definitions.
+
+## How Different Action Types Are Executed
+
+### 1. JavaScript Actions (`using: node12/16/20/24`)
+
+JavaScript actions execute source code directly without compilation:
+
+```yaml
+# action.yml
+runs:
+  using: 'node20'
+  main: 'index.js'
+```
+
+**Execution Process**:
+1. Runner downloads the action repository
+2. Locates the `main` JavaScript file (e.g., `index.js`)
+3. Executes it directly using Node.js runtime: `node index.js`
+4. No compilation or build step required
+
+**Code Reference**: `src/Runner.Worker/Handlers/NodeScriptActionHandler.cs`
+- Resolves the target script file
+- Executes using Node.js: `StepHost.ExecuteAsync()` with node executable
+
+### 2. Container Actions (`using: docker`)
+
+Container actions run pre-built images or build from Dockerfile:
+
+```yaml
+# action.yml - Pre-built image
+runs:
+  using: 'docker'
+  image: 'docker://alpine:3.10'
+```
+
+```yaml
+# action.yml - Build from Dockerfile
+runs:
+  using: 'docker'
+  image: 'Dockerfile'
+```
+
+**Execution Process**:
+1. If using pre-built image: Pull and run the container
+2. If using Dockerfile: Build the container image, then run it
+3. No compilation of action source code - Docker handles image building
+
+**Code Reference**: `src/Runner.Worker/Handlers/ContainerActionHandler.cs`
+- Handles both pre-built images and Dockerfile builds
+- Uses Docker commands to run containers
+
+### 3. Composite Actions (`using: composite`)
+
+Composite actions are collections of steps defined in YAML:
+
+```yaml
+# action.yml
+runs:
+  using: 'composite'
+  steps:
+    - run: echo "Hello"
+      shell: bash
+    - uses: actions/checkout@v3
+```
+
+**Execution Process**:
+1. Parse the YAML step definitions
+2. Execute each step in sequence
+3. No compilation - just step orchestration
+
+**Code Reference**: `src/Runner.Worker/Handlers/CompositeActionHandler.cs`
+- Iterates through defined steps
+- Executes each step using appropriate handlers
+
+## What Does Get Compiled?
+
+### The GitHub Actions Runner (This Repository)
+
+The runner itself is compiled from C# source code:
+
+```bash
+cd src
+./dev.sh build  # Compiles the runner binaries
+```
+
+**What gets compiled**:
+- `Runner.Listener` - Registers with GitHub and receives jobs
+- `Runner.Worker` - Executes individual jobs and steps
+- `Runner.PluginHost` - Handles plugin execution
+- Supporting libraries
+
+**Build Output**: Compiled binaries in `_layout/bin/`
+
+## Key Distinctions
+
+| Component | Compilation Required | Execution Method |
+|-----------|---------------------|------------------|
+| **Runner** (this repo) | ✅ Yes - C# → binaries | Compiled executable |
+| **JavaScript Actions** | ❌ No | Direct interpretation |
+| **Container Actions** | ❌ No* | Container runtime |
+| **Composite Actions** | ❌ No | YAML interpretation |
+
+*Container actions may involve building Docker images, but not compiling action source code.
+
+## Implementation Details
+
+### Action Loading Process
+
+1. **Action Discovery** (`ActionManager.LoadAction()`)
+   - Parses `action.yml` manifest
+   - Determines action type from `using` field
+   - Creates appropriate execution data object
+
+2. **Handler Selection** (`HandlerFactory.Create()`)
+   - Routes to appropriate handler based on action type
+   - `NodeScriptActionHandler` for JavaScript
+   - `ContainerActionHandler` for Docker
+   - `CompositeActionHandler` for composite
+
+3. **Execution** (Handler-specific `RunAsync()`)
+   - Each handler implements execution logic
+   - No compilation step - direct execution
+
+### Source Code References
+
+- **Action Type Detection**: `src/Runner.Worker/ActionManifestManager.cs:428-495`
+- **Handler Factory**: `src/Runner.Worker/Handlers/HandlerFactory.cs`
+- **JavaScript Execution**: `src/Runner.Worker/Handlers/NodeScriptActionHandler.cs:143-153`
+- **Container Execution**: `src/Runner.Worker/Handlers/ContainerActionHandler.cs:247-261`
+
+## Conclusion
+
+GitHub Actions are designed for **runtime interpretation**, not compilation:
+
+- **JavaScript actions** run source `.js` files directly
+- **Container actions** use existing images or build from Dockerfile
+- **Composite actions** are YAML step definitions
+
+The only compilation involved is building the **runner infrastructure** (this repository) that interprets and executes the actions.

docs/contribute.md

@@ -4,6 +4,14 @@ We welcome contributions in the form of issues and pull requests. We view the co
 
 > IMPORTANT: Building your own runner is critical for the dev inner loop process when contributing changes.  However, only runners built and distributed by GitHub (releases) are supported in production.  Be aware that workflows and orchestrations run service side with the runner being a remote process to run steps.  For that reason, the service can pull the runner forward so customizations can be lost.
 
+## Understanding Actions vs Runner
+
+**New to GitHub Actions development?** See [Action Execution Model](action-execution-model.md) to understand the difference between:
+- **Actions** (JavaScript, containers, composite) - Run without compilation
+- **Runner** (this repository) - Compiled C# application that executes actions
+
+For examples of how different action types work, see [Action Execution Examples](examples/action-execution-examples.md).
+
 ## Issues
 
 Log issues for both bugs and enhancement requests.  Logging issues are important for the open community.

docs/examples/action-execution-examples.md

@@ -0,0 +1,117 @@
+# Action Execution Examples
+
+This directory contains examples demonstrating how different types of GitHub Actions are executed without compilation.
+
+## JavaScript Action Example
+
+A simple JavaScript action that runs source code directly:
+
+### action.yml
+```yaml
+name: 'JavaScript Example'
+description: 'Demonstrates direct JavaScript execution'
+runs:
+  using: 'node20'
+  main: 'index.js'
+```
+
+### index.js
+```javascript
+// This file runs directly - no compilation needed
+console.log('Hello from JavaScript action!');
+console.log('Process args:', process.argv);
+console.log('Environment:', process.env.INPUT_MESSAGE || 'No input provided');
+```
+
+**Execution**: The runner directly executes `node index.js` - no build step.
+
+## Container Action Example
+
+### action.yml (Pre-built image)
+```yaml
+name: 'Container Example'
+description: 'Demonstrates container execution'
+runs:
+  using: 'docker'
+  image: 'docker://alpine:latest'
+  entrypoint: '/bin/sh'
+  args:
+    - '-c'
+    - 'echo "Hello from container!" && env | grep INPUT_'
+```
+
+### action.yml (Build from source)
+```yaml
+name: 'Container Build Example'
+description: 'Demonstrates building from Dockerfile'
+runs:
+  using: 'docker'
+  image: 'Dockerfile'
+  args:
+    - 'Hello from built container!'
+```
+
+### Dockerfile
+```dockerfile
+FROM alpine:latest
+COPY entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+ENTRYPOINT ["/entrypoint.sh"]
+```
+
+### entrypoint.sh
+```bash
+#!/bin/sh
+echo "Container built and running: $1"
+echo "Environment variables:"
+env | grep INPUT_ || echo "No INPUT_ variables found"
+```
+
+**Execution**: Docker builds the image (if needed) and runs the container - action source isn't compiled.
+
+## Composite Action Example
+
+### action.yml
+```yaml
+name: 'Composite Example'
+description: 'Demonstrates composite action execution'
+runs:
+  using: 'composite'
+  steps:
+    - name: Run shell command
+      run: echo "Step 1: Hello from composite action!"
+      shell: bash
+    
+    - name: Use another action
+      uses: actions/checkout@v4
+      with:
+        path: 'checked-out-code'
+    
+    - name: Run another shell command
+      run: |
+        echo "Step 3: Files in workspace:"
+        ls -la
+      shell: bash
+```
+
+**Execution**: The runner interprets the YAML and executes each step - no compilation.
+
+## Comparison with Runner Compilation
+
+The **runner itself** (this repository) must be compiled:
+
+```bash
+# This compiles the runner from C# source code
+cd src
+./dev.sh build
+
+# The compiled runner then executes actions WITHOUT compiling them
+./_layout/bin/Runner.Worker
+```
+
+## Key Takeaway
+
+- **Actions** = Interpreted at runtime (JavaScript, containers, YAML)
+- **Runner** = Compiled from source (C# → binaries)
+
+The runner compiles once and then executes many different actions without compiling them.