GitHub Actions Workflow Failed

# GitHub Actions Workflow Failed

Common Error Patterns

GitHub Actions failures typically show:

Error: Process completed with exit code 1

The action 'xxx' has encountered an error

Error: No runner is available to run this job

Error: Unhandled error: HttpError: Not Found

Error: The requested workflow run was not found

Root Causes and Solutions

1. YAML Syntax Errors

Workflow file has invalid YAML syntax.

Solution:

Validate YAML syntax:

```bash # Use yamllint yamllint .github/workflows/workflow.yml

# Or online validator # https://www.yamllint.com/ ```

Common syntax errors:

```yaml # WRONG - Missing indentation steps: - name: Build run: make build

# CORRECT - Proper indentation steps: - name: Build run: make build

# WRONG - Invalid quotes run: echo "Hello ${GITHUB_REF}"

# CORRECT - Proper escaping run: echo "Hello ${{ github.ref }}" ```

Use GitHub's workflow validator:

1. 1.Navigate to Actions tab
2. 2.Click "New workflow"
3. 3.Paste your YAML - errors show inline

2. Missing or Invalid Secrets

Secrets not configured or referenced incorrectly.

Solution:

Add secrets to repository:

1. 1.Navigate to Settings > Secrets and variables > Actions
2. 2.Click "New repository secret"
3. 3.Add name and value

Reference secrets correctly:

steps:
  - name: Deploy
    env:
      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    run: |
      aws s3 sync ./dist s3://my-bucket/

Important: Secrets are masked in logs, but can still be exposed through certain patterns:

```yaml # WRONG - Exposing secret in command run: echo "Password is ${{ secrets.PASSWORD }}" # Shows secret!

# CORRECT - Use environment variable env: PASSWORD: ${{ secrets.PASSWORD }} run: ./deploy.sh # Script reads $PASSWORD from env ```

3. Permission Issues

Workflow lacks required permissions.

Solution:

Add permissions to workflow:

```yaml permissions: contents: read packages: write id-token: write # For OIDC

jobs: deploy: runs-on: ubuntu-latest permissions: contents: read id-token: write steps: - name: Configure AWS credentials uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: arn:aws:iam::123456789012:role/my-role aws-region: us-east-1 ```

For GITHUB_TOKEN usage:

```yaml permissions: contents: write # Allow pushing changes

jobs: update: runs-on: ubuntu-latest steps: - name: Push changes run: | git config user.name "github-actions[bot]" git config user.email "github-actions[bot]@users.noreply.github.com" git push ```

4. Runner Not Available

No runner available for the job.

Solution:

Check runner status:

1. 1.Navigate to Settings > Actions > Runners
2. 2.View runner status and labels

Use correct runner labels:

jobs:
  build:
    runs-on: ubuntu-latest  # GitHub-hosted runner
    # OR
    runs-on: [self-hosted, linux, x64]  # Self-hosted runner

For self-hosted runners:

```bash # Check runner service sudo systemctl status actions.runner.*

# Restart runner sudo systemctl restart actions.runner.* ```

5. Action Version Issues

Using outdated or broken action versions.

Solution:

Update to latest stable version:

```yaml # WRONG - Using deprecated version uses: actions/checkout@v1

# CORRECT - Use latest version uses: actions/checkout@v4

# CORRECT - Pin to specific SHA for security uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 ```

Check action releases:

gh api repos/actions/checkout/releases --jq '.[0].tag_name'

6. Timeout Issues

Workflow or step exceeds time limits.

Solution:

Set appropriate timeouts:

```yaml jobs: build: runs-on: ubuntu-latest timeout-minutes: 30 # Job timeout

steps: - name: Long running step timeout-minutes: 10 # Step timeout run: ./long-process.sh ```

For long-running jobs, consider: - Breaking into smaller jobs - Using caching to speed up steps - Running on self-hosted runners (longer timeout)

7. Container Issues

Docker container fails to start or run.

Solution:

Validate container configuration:

jobs:
  container-job:
    runs-on: ubuntu-latest
    container:
      image: node:18
      options: --cpus 1
      env:
        NODE_ENV: development
      volumes:
        - my_docker_volume:/volume_mount
    steps:
      - name: Check container
        run: node --version

For service containers:

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_PASSWORD: postgres
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - name: Run tests
        run: npm test
        env:
          DATABASE_URL: postgres://postgres:postgres@postgres:5432/test

8. Conditional Step Issues

Conditions not evaluating correctly.

Solution:

Use proper conditional syntax:

```yaml steps: - name: Deploy to production if: github.ref == 'refs/heads/main' && github.event_name == 'push' run: ./deploy.sh production

• name: Deploy to staging
• if: github.ref == 'refs/heads/develop'
• run: ./deploy.sh staging

• name: Skip on draft PR
• if: ${{ !github.event.pull_request.draft }}
• run: ./test.sh
• `

9. Cache Issues

Caching not working or causing conflicts.

Solution:

Configure proper cache keys:

steps:
  - name: Cache npm dependencies
    uses: actions/cache@v4
    with:
      path: ~/.npm
      key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
      restore-keys: |
        ${{ runner.os }}-npm-

For multiple caches:

- name: Cache node modules
  uses: actions/cache@v4
  with:
    path: |
      ~/.npm
      node_modules
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

Debugging Techniques

Enable Debug Logging

Add secrets to enable debug: - ACTIONS_STEP_DEBUG = true - ACTIONS_RUNNER_DEBUG = true

Or in workflow:

env:
  ACTIONS_STEP_DEBUG: true

Use Debug Steps

steps:
  - name: Debug context
    run: |
      echo "GitHub context:"
      echo "${{ toJson(github) }}"
      echo "Runner context:"
      echo "${{ toJson(runner) }}"
      echo "Environment:"
      env | sort

Download Logs

```bash # Via GitHub CLI gh run download <run-id> --repo owner/repo

# Via API gh api repos/owner/repo/actions/runs/<run-id>/logs > logs.zip ```

Re-run with verbose

steps:
  - name: Verbose shell
    shell: bash {0}  # Don't fail on error
    run: |
      set -x  # Print commands
      ./build.sh || echo "Build failed"

Common Issues Quick Fix

Health Check Commands

```bash # List recent runs gh run list --repo owner/repo --limit 10

# View specific run gh run view <run-id> --repo owner/repo

# Download logs gh run download <run-id> --repo owner/repo

# Cancel run gh run cancel <run-id> --repo owner/repo

# Re-run failed jobs gh run rerun <run-id> --repo owner/repo --failed ```

Prevention Tips

1. 1.Use pinned action versions for stability
2. 2.Set up branch protection rules requiring workflow success
3. 3.Use caching to speed up builds
4. 4.Set appropriate timeouts
5. 5.Store secrets securely, rotate regularly
6. 6.Use reusable workflows for common patterns

Related Articles

• [Jenkins Build Failed](#)
• [GitLab CI Pipeline Stuck](#)
• [Docker Build Failed in CI](#)