Running GitHub Actions from Non-Master Branches

When developing with GitHub Actions, you might encounter situations where your workflows only seem to run from the master (or now commonly main) branch, even when you've created them in feature or development branches. This comprehensive guide explains why this happens and provides effective solutions.

Why Actions Don't Run from Other Branches

GitHub Actions workflows are only discovered and executed when they exist in the specific branch where the triggering event occurs. The process works like this:

1. An event (like a push or pull request) occurs on your repository
2. GitHub searches the .github/workflows directory specifically at that branch's commit SHA
3. Only workflow files present in that branch at that moment are considered
4. Workflows with matching triggers are executed using that branch's code

This means if you create a workflow file in a feature branch but haven't merged it to master, it won't be visible to events happening on the master branch.

Solutions for Testing Workflows in Feature Branches

1. Push the Workflow File to Your Branch

The simplest solution is to ensure your workflow file exists in the branch where you want it to run:

# .github/workflows/your-workflow.yaml
name: Your Workflow

on:
  push:
    branches: [ "your-feature-branch" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:
    # Your job steps here

WARNING

Remember that you need to actually push the workflow file to your branch for GitHub to detect it. Creating it locally isn't enough.

2. Use Manual Triggers with workflow_dispatch

Add workflow_dispatch to allow manual triggering from the GitHub UI:

on:
  workflow_dispatch:
  push:
    branches: [ "your-branch" ]

jobs:
  your-job:
    runs-on: ubuntu-latest
    steps:
      # Your steps here

This enables you to run the workflow manually from the Actions tab, regardless of which branch events are triggering.

How to trigger manually

1. Navigate to your repository's "Actions" tab
2. Select the workflow you want to run
3. Click "Run workflow"
4. Choose the branch and provide any required inputs

3. Path-Specific Triggers

If you want to trigger workflows only when specific files change in your branch:

on:
  push:
    branches: [ "feature-branch" ]
    paths:
      - 'src/**'
      - 'package.json'

4. Multiple Branch Configuration

For complex scenarios, you can configure different behavior for different branches:

on:
  push:
    branches: 
      - main
      - develop
      - feature/**

jobs:
  test:
    # Runs on all branches
    # ...
  
  deploy:
    # Only runs on specific branches
    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/production'
    # ...

Best Practices for Branch-Based Workflows

Keep Workflow Files in Sync

To avoid issues where workflows behave differently across branches:

1. Merge workflow changes frequently from your main branch to feature branches
2. Use reusable workflows to centralize complex logic
3. Test workflows early in the development process

Use Environment-Specific Configuration

jobs:
  deploy:
    environment: 
      name: ${{ github.ref_name == 'main' && 'production' || 'staging' }}
    steps:
      # Different steps based on environment

Handle Merge Conflicts Gracefully

When workflow files might conflict between branches:

on:
  pull_request:
    branches: [ main ]
    paths:
      - '.github/workflows/**'
      
jobs:
  validate-workflow:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate workflow syntax
        run: |
          # Add validation logic for your workflows

Troubleshooting Common Issues

Workflow Not Showing in Actions Tab

If your workflow doesn't appear in the Actions tab, ensure:

• The YAML file is in the correct .github/workflows directory
• The file has a .yml or .yaml extension
• You've actually pushed the file to the branch

Workflow Not Triggering

Check that:

• Your trigger conditions match the actual events
• The workflow file exists in the branch where the event occurred
• There are no syntax errors in your YAML file

Pro Tip

Use the GitHub Actions visual editor in your repository to quickly verify that your workflow syntax is correct and will be detected.

Conclusion

GitHub Actions are branch-specific by design, requiring workflow files to be present in the branch where events occur. By understanding this behavior and implementing the strategies outlined above, you can effectively develop, test, and run workflows from any branch in your repository.

Remember to push your workflow files to the target branch, use manual triggers during development, and maintain consistency across branches to ensure smooth CI/CD operations.