GitHub Actions Workflow Failed?

Exit code 1, missing secrets, permission denied, or Docker login errors? Here's how to diagnose and fix the most common GitHub Actions failures fast.

Current GitHub Actions Status

If GitHub's infrastructure is degraded, workflows will queue or fail regardless of your config. Check first:

GitHub Actions → prismix.dev/service/github

Identify Your Error Fast

Fix 1: "Error: Process completed with exit code 1"

The summary only tells you which step failed, not why. The real error is inside the step log. Click the failed step name to expand it, then scroll down past the runner setup lines.

What to look for in the log:

## Actual error will look like one of these:
Error: ENOENT: no such file or directory, open 'dist/index.js'
FAIL src/auth.test.ts (3.2s)
  ✕ should return 401 for expired tokens
npm ERR! code ELIFECYCLE
make: *** [build] Error 2

Fix the underlying command locally first: run the exact same command from your workflow in your local terminal before pushing again. Use act (the local Actions runner) to reproduce the full workflow environment without pushing.

Fix 2: Secrets Not Found or Empty

GITHUB_TOKEN is injected automatically — you do not create it. All other secrets must be added under Settings > Secrets and variables > Actions and referenced with the exact name you set there.

# In your workflow YAML — reference like this:
env:
  MY_API_KEY: {{ secrets.MY_API_KEY }}

# WRONG — these will be empty strings:
env:
  MY_API_KEY: {{ env.MY_API_KEY }}   # env context, not secrets
  MY_API_KEY: MY_API_KEY              # literal string

Fix 3: "Resource not accessible by integration"

This error means the automatic GITHUB_TOKEN does not have the permission your step needs. Add a permissions block — at workflow level (applies to all jobs) or per-job (more precise).

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write      # create releases, push tags
      packages: write      # push to GitHub Container Registry
      id-token: write      # OIDC for AWS/GCP/Azure auth
      pull-requests: write # comment on PRs
    steps:
      - uses: actions/checkout@v4
      # ... your steps

Only grant the scopes you actually need. Never use permissions: write-all in production workflows — it grants every permission the token can have.

Fix 4: Docker Login Failing in Actions

Running docker login directly in a run: step is unreliable in Actions runners. Use the official docker/login-action instead — it handles credential storage correctly across runner OS types.

- name: Log in to GitHub Container Registry
  uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: {{ github.actor }}
    password: {{ secrets.GITHUB_TOKEN }}

# For Docker Hub:
- name: Log in to Docker Hub
  uses: docker/login-action@v3
  with:
    username: {{ secrets.DOCKERHUB_USERNAME }}
    password: {{ secrets.DOCKERHUB_TOKEN }}

For GHCR, also add packages: write to the job's permissions block (see Fix 3 above).

Fix 5: Cache Hit/Miss Logic Problems

Cache keys must be unique per OS + lockfile hash. A common mistake is using only the lockfile hash, which causes cache collisions between Linux and macOS matrix builds.

- uses: actions/cache@v4
  with:
    path: ~/.npm
    # Include runner OS so Linux and macOS never share a cache:
    key: {{ runner.os }}-node-{{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      {{ runner.os }}-node-

The restore-keys list is a fallback: Actions tries each prefix in order and returns the most recent partial match. Always put the most specific key first.

Fix 6: Cancel Stale Runs on PR Push

Without concurrency settings, every push to a PR branch queues a new workflow run while the old one keeps running. This wastes minutes and can deploy outdated code. Add a concurrency block at the top of your workflow:

name: CI

on: [push, pull_request]

concurrency:
  group: {{ github.workflow }}-{{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test

Fix 7: Cross-Platform Matrix Testing

Use strategy.matrix to run the same steps on multiple OS versions in parallel. Pair it with fail-fast: false so one failing platform doesn't immediately cancel the others — you want to see all failures at once.

jobs:
  test:
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node: [18, 20, 22]
    runs-on: {{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: {{ matrix.node }}
      - run: npm ci
      - run: npm test

Frequently Asked Questions