Common GitHub Actions Mistakes Beginners Make and How to Fix Them

Apr 13, 2026

My GitHub Actions workflow failed. Again. I stared at the red “X” in my Actions tab, frustrated that my perfectly logical automation wouldn’t run. After hours of debugging, I found the problem: a missing permission block that GitHub didn’t explicitly mention in the error message.

If you’re new to GitHub Actions, you’ll likely hit these same walls. Let me share the five most common mistakes I’ve seen beginners make, and show you exactly how to fix each one.

Mistake 1: YAML Indentation Errors

The most frustrating part about YAML is that a single space can break your entire workflow. I’ve spent countless minutes staring at a workflow file, only to realize my steps: was indented one space too far.

Here’s what a broken workflow looks like:

name: Broken Workflow
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
     steps:          # Wrong: 5 spaces instead of 4
      - uses: actions/checkout@v4

The fix is simple but requires discipline:

name: Correct Workflow
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:           # Correct: 4 spaces (2-space indentation x 2 levels)
      - uses: actions/checkout@v4

Rule: Use 2-space indentation consistently throughout your YAML file. Use a YAML linter like yamllint or VS Code’s YAML extension to catch these errors before committing.

Mistake 2: Missing Permissions for Repository Operations

When I first tried to add labels to issues via a workflow, I got a vague “Resource not accessible” error. The problem? My workflow didn’t have permission to modify issues.

Many beginners assume the GITHUB_TOKEN has full access to everything in the repository. It doesn’t. By default, it has limited permissions, and you need to explicitly grant access for certain operations.

name: Label Issues
on:
  issues:
    types: [opened]

jobs:
  label-issues:
    runs-on: ubuntu-latest
    permissions:
      issues: write    # Required to modify issues
      contents: read   # Required to checkout repository
    steps:
      - name: Add triage label
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh issue edit ${{ github.event.issue.number }} --add-label "triage"

Without the permissions: block, the workflow fails silently or with confusing error messages. Always check the permissions documentation when your workflow needs to modify repository content.

Mistake 3: Workflow Files in the Wrong Directory

I once spent an hour wondering why my workflow wasn’t showing up in the Actions tab. The file was correct, the YAML was valid, but nothing happened. Turns out, I placed it in .github/workflow/ instead of .github/workflows/ (singular vs plural).

GitHub Actions only recognizes workflow files in the .github/workflows/ directory at the repository root. Anywhere else, and your workflow simply won’t run.

your-repo/
├── .github/
│   ├── workflows/
│   │   ├── ci.yml           # This WILL run
│   │   └── deploy.yml       # This WILL run
│   └── workflow/
│       └── broken.yml       # This will NOT run
├── src/
└── README.md

Double-check your directory structure if your workflow doesn’t appear in the Actions tab.

Mistake 4: Using Undefined Labels or Secrets

Another common mistake: referencing labels or secrets that don’t exist in the repository. I tried to add a “bug” label to an issue, but my repository didn’t have that label created yet. The workflow failed with a 404 error.

Before using labels in your workflows, create them in your repository:

Go to your repository on GitHub
Navigate to Issues > Labels
Create the labels you need (or use the defaults)

For secrets, the process is similar:

Go to Settings > Secrets and variables > Actions
Add your secrets there

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        env:
          API_KEY: ${{ secrets.MY_API_KEY }}  # Fails if secret doesn't exist
        run: echo "Deploying with API key..."

You can make your workflows more resilient by checking if resources exist before using them:

steps:
  - name: Check and add label
    env:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    run: |
      # List existing labels to verify
      gh label list --json name -q '.[].name'

      # Add label (fails gracefully if label doesn't exist)
      gh issue edit ${{ github.event.issue.number }} --add-label "triage"

Mistake 5: Forgetting to Merge Workflows to Main Branch

This one caught me off guard. I pushed a workflow to a feature branch, tested it there, and then wondered why it wasn’t running on main. The workflow file existed in my branch but not in the default branch.

By default, GitHub Actions only reads workflow files from your repository’s default branch (usually main or master). If you create a workflow on a feature branch, it won’t run until you merge it to the default branch.

Steps to avoid this:

Create your workflow file on a feature branch
Test it there (you can trigger it manually with workflow_dispatch)
Create a pull request
Merge to main when ready
The workflow is now active

You can also use workflow_dispatch to manually test workflows on any branch:

name: Manual Trigger
on:
  workflow_dispatch:  # Allows manual triggering from Actions tab

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Manually triggered!"

Debugging Your Workflows

When things go wrong (and they will), here’s my debugging checklist:

Check the Actions tab: View workflow runs, see detailed logs, and identify which step failed
Add debug output: Print context variables to understand what’s happening

steps:
  - name: Debug context
    run: |
      echo "Event: ${{ github.event_name }}"
      echo "Issue number: ${{ github.event.issue.number }}"
      echo "Repository: ${{ github.repository }}"
      echo "Actor: ${{ github.actor }}"
      echo "Ref: ${{ github.ref }}"

Re-run failed workflows: Use the “Re-run jobs” button in the Actions tab to try again
Temporarily disable workflows: If a workflow is causing problems, you can disable it without deleting it

Go to your repository > Actions > select a workflow > click the three dots menu > Disable workflow.

Quick Reference

Problem	Cause	Solution
YAML syntax error	Incorrect indentation	Use 2-space indentation consistently
”Resource not accessible”	Missing permissions	Add `permissions:` block to job
Workflow not appearing	Wrong directory	Place in `.github/workflows/`
Label/secret not found	Resource doesn’t exist	Create label/secret in repository settings
Workflow not running	Not on default branch	Merge to `main` branch

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!