Handling Errors and Debugging

1. Enabling Debug Logging

Setting	Description	Value
ACTIONS_STEP_DEBUG	Enables debug logging for each step	`true`
ACTIONS_RUNNER_DEBUG	Enables debug logging for the runner	`true`

Example: Setting debug environment variables

jobs:
  build:
    steps:
      - name: Setup debug logging
        env:
          ACTIONS_STEP_DEBUG: true
          ACTIONS_RUNNER_DEBUG: true
        run: |
          echo "Debug logging enabled"

Note: Debug logs contain sensitive information and should only be enabled in secure environments.

2. Enabling Runner Diagnostics

Example: Enabling debug logging in a workflow

name: Debug Workflow
on: [push]
jobs:
  debug-job:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Enable debug logging
        run: |
          echo "::debug::Debug message"
          echo "::notice::Notice message"
          echo "::warning::Warning message"
          echo "::error::Error message"

Log Level	Description	Usage
debug	Provides detailed information for debugging purposes	Use `::debug::message` to log debug information
notice	Provides general information about the workflow execution	Use `::notice::message` for notices
warning	Indicates a potential issue that does not stop the workflow	Use `::warning::message` to log warnings
error	Indicates an issue that stops the workflow or causes failure	Use `::error::message` to log errors

Note: Debug logs are only visible when the workflow is run with ACTIONS_STEP_DEBUG=true set in the environment variables.

Warning: Avoid logging sensitive information in debug messages as they can be exposed in logs.

Summary of Diagnostic Logging

Use ::debug::message for detailed debugging information.
Use ::notice::message for general workflow status updates.
Use ::warning::message to indicate potential issues.
Use ::error::message for errors that halt execution.

3. Using Continue on Error

By default, a GitHub Actions workflow stops executing if a job fails. However, you can configure jobs to continue running even when a step fails using the continue-on-error property.

Property	Values	Description
continue-on-error	`true` or `false`	If set to `true`, the job continues executing even if a step fails. Defaults to `false`.

Example: Using continue-on-error in a job step

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Run failing test
        id: failing-step
        continue-on-error: true
        run: |
          echo "This step will fail"
          exit 1
      - name: Continue with next step
        run: echo "Workflow continues despite previous failure"

Note: When continue-on-error is enabled, the step's result is still marked as failed in the UI, but the workflow proceeds to the next step.

4. Checking Step Outcome

Property	Description	Values
steps.<step-id>.outcome	Indicates the outcome of a step	`success`, `failure`, `cancelled`

Example: Using step outcome in conditional logic

name: Check Step Outcome
on: [push]
jobs:
  test-job:
    runs-on: ubuntu-latest
    steps:
      - name: Run a script
        id: script
        run: |
          echo "Running script"
          exit 1
      - name: Check outcome
        if: steps.script.outcome == 'failure'
        run: |
          echo "Script failed, handling accordingly"

5. Using Failure Conditions

Example: Using `if` with failure conditions

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run tests
        run: npm test

      - name: Upload coverage report
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: coverage-report
          path: coverage/

Condition	Description	Usage
success()	Runs if the job succeeded	`if: success()`
failure()	Runs if the job failed	`if: failure()`
cancelled()	Runs if the job was cancelled	`if: cancelled()`
always()	Runs regardless of job status	`if: always()`

Note: The if condition is evaluated before each step runs, and can be used to control whether a step should execute based on the outcome of previous steps or external conditions.

6. Logging Debug Messages

Level	Log Type	Description	Example
debug	`echo "::debug::Debug message"`	Logs a debug message to the console	`echo "::debug::Processing user data"`
info	`echo "::info::Info message"`	Logs an info message to the console	`echo "::info::User login successful"`
warning	`echo "::warning::Warning message"`	Logs a warning message to the console	`echo "::warning::User session timeout approaching"`
error	`echo "::error::Error message"`	Logs an error message to the console	`echo "::error::Failed to connect to database"`

Note: Debug messages are only visible in the workflow run logs when the ACTIONS_STEP_DEBUG environment variable is set to true.

Example: Using debug logging in a job

name: Debug Example
on: [push]
jobs:
  debug-job:
    runs-on: ubuntu-latest
    steps:
      - name: Setup debug
        run: |
          echo "::debug::Starting debug session"
          echo "::info::Processing data"
          echo "::warning::Potential issue detected"
          echo "::error::Critical error occurred"

7. Logging Warning Messages

Level	Message Type	Description	Example
warning	`notice`	Logs a warning message to the GitHub Actions UI and logs	`echo "::warning file=main.js,line=10::This is a warning message"`
warning	`notice`	Can include file and line information for better context	`echo "::warning file=app.js,line=25,col=10::Potential issue at line 25"`

Example: Using Warning Messages in a Workflow

name: Log Warnings
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Check for warnings
        run: |
          echo "::warning file=src/main.js,line=42::Variable not initialized"
          echo "::warning file=src/utils.js,line=15,col=5::Deprecated function used"

8. Logging Error Messages

Method	Description	Example
echo "Error: Something went wrong"	Logs a message to the console	`echo "Error: Something went wrong"`
echo "::error::Message"	Logs an error message with GitHub Actions formatting	`echo "::error::File not found"`
echo "::warning::Message"	Logs a warning message with GitHub Actions formatting	`echo "::warning::Deprecated action used"`
echo "::notice::Message"	Logs a notice message with GitHub Actions formatting	`echo "::notice::Build completed successfully"`

Note: Using ::error::, ::warning::, and ::notice:: formats messages in a way that GitHub Actions can parse and display them with appropriate severity levels.

9. Creating Annotations

Example: Creating a Warning Annotation

const core = require('@actions/core');

core.warning('This is a warning message');

Method	Description	Parameters	Notes
core.notice(message, options)	Creates a notice annotation	`message`, `options`	Displays a notice in the GitHub UI
core.warning(message, options)	Creates a warning annotation	`message`, `options`	Displays a warning in the GitHub UI
core.error(message, options)	Creates an error annotation	`message`, `options`	Displays an error in the GitHub UI

Note: Annotations are displayed in the GitHub UI under the "Checks" tab of a workflow run.

10. Using SSH Debugging

Example: SSH into a GitHub Actions Runner

ssh -i ~/.ssh/id_rsa -p 22 runner@github-runner.example.com

Option	Values	Notes
ssh-key	`~/.ssh/id_rsa`	Private key for SSH authentication
port	`22`	SSH port to connect on
user	`runner`	SSH user on the runner

Note: SSH access is only available for self-hosted runners.

Warning: Ensure SSH keys are securely stored and permissions are properly set.

SSH Debugging Workflow

Set up a self-hosted runner with SSH access enabled
Generate and store SSH keys securely in GitHub Secrets
Use the ssh command to connect to the runner
Debug workflows directly on the runner environment

11. Inspecting Workflow Files

Property	Description	Example
name	Name of the workflow	`deploy-app`
on	Triggers for the workflow	`push`, `pull_request`
jobs	Jobs to run in the workflow	`build`, `test`

Example: Basic Workflow File Structure

name: Deploy App
on:
  push:
    branches:
      - main
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

Note: Workflow files are stored in .github/workflows/ directory and must be valid YAML.

12. Validating Workflow Syntax

Validation Method	Description	Notes
GitHub Actions Validator	`act` command-line tool	Can be installed via `npm install -g act`
YAML Linting	Using `yamllint`	Ensures valid YAML structure and formatting
GitHub Web UI	Workflow editor in GitHub interface	Provides real-time syntax validation and error messages

Example: Using act to validate workflow syntax

act -W .github/workflows/my-workflow.yml

Note: The act tool simulates GitHub Actions locally and can catch syntax errors before pushing to GitHub.

Warning: YAML syntax errors in workflows can prevent jobs from running entirely.

13. Testing Workflows Locally

Example: Using act to test workflows locally

# Install act
brew install act

# Run workflow locally
act -W .github/workflows/deploy.yml

Option	Description	Notes
act	`act`	Command-line tool to run GitHub Actions workflows locally
-W	`-W <workflow>`	Specify the workflow file to run
-j	`-j <job>`	Run a specific job within the workflow
-s	`-s <secret>`	Set a secret variable (e.g., `-s GITHUB_TOKEN=abc123`)
-b	`-b`	Use a local branch instead of the default branch

Note: act emulates the GitHub Actions runner environment locally, including Docker containers and environment variables.

Warning: Not all GitHub Actions features are fully supported by act. Some steps or services may not behave exactly as in the cloud runner.