Document expression evaluation logs for job conditions (#59100)

Co-authored-by: Anne-Marie <102995847+am-stead@users.noreply.github.com>

Author: ericsciple

content/actions/how-tos/monitor-workflows/index.md

@@ -11,6 +11,7 @@ children:
   - /view-job-execution-time
   - /add-a-status-badge
   - /use-workflow-run-logs
+  - /view-job-condition-logs
   - /enable-debug-logging
 redirect_from:
   - /actions/monitoring-and-troubleshooting-workflows/monitoring-workflows

content/actions/how-tos/monitor-workflows/view-job-condition-logs.md

@@ -0,0 +1,40 @@
+---
+title: Viewing job condition expression logs
+shortTitle: View job condition logs
+intro: 'Learn how to access and interpret expression evaluation logs for job-level `if` conditions in {% data variables.product.prodname_actions %}.'
+versions:
+  fpt: '*'
+  ghec: '*'
+contentType: how-tos
+---
+
+When a job's `if` condition is evaluated, {% data variables.product.prodname_actions %} logs the expression evaluation to help you understand the result. This is useful for debugging both why a job was skipped and why a job ran when you expected it to be skipped.
+
+## Accessing expression logs
+
+1. Navigate to the workflow run summary.
+1. Click on the job.
+1. Click **{% octicon "gear" aria-label="The Gear icon" %}**.
+1. Select **Download log archive**.
+1. Extract the ZIP file and open the `JOB-NAME/system.txt` file.
+
+## Understanding the log output
+
+The system log shows the expression evaluation:
+
+```text
+Evaluating: (success() && ((github.repository == 'octo-org/octo-repo-prod')))
+Expanded: (true && (('my-username/octo-repo-prod' == 'octo-org/octo-repo-prod')))
+Result: false
+```
+
+| Line | Description |
+|------|-------------|
+| **Evaluating** | The original `if` expression from your workflow file. |
+| **Expanded** | The expression with context values substituted. This shows you exactly what values were used at runtime. |
+| **Result** | The final evaluation result (`true` or `false`). |
+
+In this example, the expanded line reveals that `github.repository` was `'my-username/octo-repo-prod'` (not `'octo-org/octo-repo-prod'`), which caused the condition to evaluate to `false`.
+
+> [!NOTE]
+> Expression logs are only available for job-level `if` conditions. For step-level conditions, you can enable debug logging to see expression evaluation in the job logs. For more information, see [AUTOTITLE](/actions/how-tos/monitor-workflows/enable-debug-logging).

content/actions/how-tos/troubleshoot-workflows.md

@@ -98,6 +98,23 @@ For path filtering, evaluating diffs is limited to the first 300 files. If there
 
 Workflow execution involves any issues seen after the workflow was triggered and a workflow run has been created.
 
+{% ifversion fpt or ghec %}
+
+### Debugging job conditions
+
+If a job was skipped unexpectedly, or ran when you expected it to be skipped, you can view the expression evaluation to understand why:
+
+1. Click on the job in the workflow run.
+1. Download the log archive from the job's menu.
+1. Open the `JOB-NAME/system.txt` file.
+1. Look for the `Evaluating`, `Expanded`, and `Result` lines.
+
+The `Expanded` line shows the actual runtime values that were substituted into your `if` condition, making it clear why the expression evaluated to `true` or `false`.
+
+For more information, see [AUTOTITLE](/actions/how-tos/monitor-workflows/view-job-condition-logs).
+
+{% endif %}
+
 ### Canceling Workflows
 
 If standard cancellation through the [UI](/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/canceling-a-workflow) or [API](/rest/actions/workflow-runs?apiVersion=2022-11-28#cancel-a-workflow-run) does not process as expected, there may be a conditional statement configured for your running workflow job(s) that causes it to not cancel.

content/actions/how-tos/write-workflows/choose-when-workflows-run/control-jobs-with-conditions.md

@@ -37,3 +37,9 @@ Skipped jobs display the message "This check was skipped."
 
 > [!NOTE]
 > A job that is skipped will report its status as "Success". It will not prevent a pull request from merging, even if it is a required check.
+
+{% ifversion fpt or ghec %}
+
+To debug why a job was skipped or ran unexpectedly, you can view job condition expression logs. For more information, see [AUTOTITLE](/actions/how-tos/monitor-workflows/view-job-condition-logs).
+
+{% endif %}