Fix: GitHub Actions CI Fails On Dev Branch - Workflow Missing

by Alex Johnson 62 views

Having issues with your GitHub Actions CI not running on the dev branch? This is a critical problem that can lead to significant risks in your development workflow. Let's dive into the root cause, impact, and solutions to get your CI back on track.

The Problem: GitHub Actions Not Triggering on the dev Branch

The core issue is that the GitHub Actions workflow, specifically the ci.yml file, is missing from the dev branch. While the workflow is configured to trigger on pushes and pull requests to dev, the absence of the file on the branch itself prevents the actions from running.

Symptoms Observed:

  • ✅ Pushes to main: CI runs normally.
  • ❌ Pushes to dev: No action is triggered.
  • ❌ Pull Requests to dev: No validation occurs.
  • 🔍 GitHub Actions tab: No runs appear for commits on dev.

Root Cause: Workflow File Exists Only on main

This problem stems from a fundamental rule of GitHub Actions:

For a workflow to trigger on a branch, the workflow file MUST exist on that branch.

This critical rule, as highlighted in the official GitHub documentation, is the key to understanding why your CI is failing on the dev branch.

Currently, the .github/workflows/ci.yml file exists only on the main branch. This means that while the configuration specifies that the workflow should run on pushes to dev, the system cannot find the workflow definition on that branch, and therefore, no actions are triggered.

Verifying the Issue

You can quickly verify this by checking out both the main and dev branches and listing the contents of the .github/workflows/ directory:

# On main
git checkout main
ls .github/workflows/
# Expected output: ci.yml ✅ Present

# On dev
git checkout dev
ls .github/workflows/
# Expected output: ls: cannot access '.github/workflows/': No such file or directory ❌ Absent

This simple check will confirm whether the workflow file exists on the dev branch.

Current Workflow Configuration

The ci.yml file, located in the .github/workflows/ directory (when present), contains the workflow configuration. In this case, lines 3-6 likely define the triggering conditions:

on:
  push:
    branches: [ main , dev ]  # ⚠️ 'dev' triggering but file absent on dev
  pull_request:
    branches: [ main , dev ]  # ⚠️ Idem

The configuration specifies that the workflow should trigger on pushes and pull requests to both main and dev. However, the critical missing piece is the presence of this file on the dev branch itself. Because the workflow file doesn't exist on dev, it cannot trigger, despite the configuration.

Impact of the Missing Workflow: A Critical Situation

The absence of a CI workflow on the dev branch has a severe impact on your development process.

Severity: 🔴 CRITICAL

  1. Zero CI/CD Coverage on the Development Branch:

    • Without CI on dev, there are no automated tests being run on the branch. This means that bugs are not being detected early in the development cycle.
    • This lack of testing increases the risk of merging broken code into main, which can lead to production issues.

  2. False Sense of Security:

    • Developers may assume that the CI is protecting the dev branch, leading to a false sense of security.
    • In reality, there is no automatic validation of code pushed to dev.

  3. Broken Contribution Workflow:

    • Pull Requests to dev are not being automatically validated.
    • This makes it impossible to merge code with confidence, as there is no automated verification of the changes.

  4. Impact on Existing Branches:

    The issue extends beyond just the dev branch. Any branch that lacks the workflow file will not have CI enabled.

    ✅ main                    → CI works
❌ dev                     → CI silent (file absent)
❌ feature-architecture-fix → CI silent (file absent)
❌ fix----query-bug        → CI silent (file absent)

Solutions: Getting Your CI Back on Track

There are two main approaches to resolving this issue. We'll start with the immediate fix and then discuss a longer-term strategy.

Option A: Immediate Fix (Recommended)

The quickest and most effective solution is to copy the workflow file from main to dev.

# From main
git checkout main
git pull

# Merge .github/ into dev
git checkout dev
git checkout main -- .github/
git add .github/
git commit -m "fix(ci): add missing GitHub Actions workflow on dev branch"
git push origin dev

Explanation:

  1. git checkout main: Switches to the main branch.
  2. git pull: Ensures you have the latest version of the main branch.
  3. git checkout dev: Switches to the dev branch.
  4. git checkout main -- .github/: Copies the .github/ directory from the main branch to the dev branch.
  5. git add .github/: Stages the copied files for commit.
  6. git commit -m ...: Commits the changes with a descriptive message.
  7. git push origin dev: Pushes the changes to the dev branch on the remote repository.

Result: This will immediately trigger the CI on the next push to dev, restoring the much-needed automated checks.

Option B: Long-Term Strategy

For a more robust and maintainable solution, consider the following steps:

  1. Ensure Workflow Exists on All Active Branches:

    • Merge the .github/ directory into dev, feature-*, and fix-* branches.
    • Document the requirement for the workflow file in the README to prevent future occurrences.

  2. Implement Branch Protection:

    GitHub's branch protection rules provide an extra layer of security and control.

    # Settings → Branches → Branch protection rules

Branch name pattern: dev
☑ Require status checks to pass before merging
☑ Require branches to be up to date before merging
Status checks:
  - docker / Build & Test Docker Compose Project

    This configuration ensures that pull requests to dev cannot be merged until the required status checks (e.g., CI) have passed.

  3. Centralized Workflow with workflow_call (Advanced):

    • Create a reusable workflow on main.
    • Other branches can then call this workflow using the workflow_call feature.
    • This approach simplifies maintenance by having a single workflow file to manage.

Bonus Issues Detected in the Workflow

While addressing the missing workflow file, it's worth noting several other potential issues within the current workflow configuration.

1️⃣ Non-Existent Services Being Tested

The CI configuration includes tests for agents A/B/C (ports 5001-5003), which do not exist in the docker-compose.yml file.

- name: Test Agent A
  run: curl -s http://localhost:5001/health | grep -q "healthy"  # ❌ Service inexistant

- name: Test Agent B  
  run: curl -s http://localhost:5002/health | grep -q "healthy"  # ❌ Service inexistant

- name: Test Agent C
  run: curl -s http://localhost:5003/health | grep -q "healthy"  # ❌ Service inexistant

The actual services exposed are:

  • query-management: port 5000
  • open-webui: port 3000
  • orchestrator: port 8000 (internal)

2️⃣ mcp-postgres Crash Loop

The mcp-postgres service is experiencing a crash loop due to a configuration issue.

mcp-postgres | Please provide a database URL as a command-line argument
mcp-postgres exited with code 1 (restarting)

Fix:

mcp-postgres:
  image: mcp/postgres
  command: ["postgres://user:password@postgres:5432/dbname"]  # Pas env var

3️⃣ Missing Healthchecks

None of the services define Docker healthcheck configurations. The CI attempts to manually verify health using curl loops, which is less efficient and reliable.

4️⃣ No BuildKit Cache

The CI performs a full rebuild on every run, wasting 3-5 minutes per execution. Implementing BuildKit caching can significantly reduce build times.

Actions to Take: Prioritizing the Fixes

To address these issues effectively, prioritize the following actions:

High Priority (Unblock CI)

  • [ ] Copy .github/workflows/ from main to dev.
  • [ ] Verify that the CI triggers on a test push to dev.
  • [ ] Enable branch protection on dev (require status checks).

Medium Priority (Stabilize CI)

  • [ ] Remove the Agent A/B/C tests or create these services.
  • [ ] Fix the mcp-postgres configuration (command vs environment).
  • [ ] Add healthchecks to all Docker services.

Low Priority (Optimization)

  • [ ] Implement BuildKit caching.
  • [ ] Document the CI setup in the README.
  • [ ] Create .env.example with all required variables.

References and Further Reading

Conclusion: Resolving the CI Crisis

Addressing the missing workflow file on the dev branch is crucial for maintaining a healthy and reliable development pipeline. By implementing the immediate fix and considering the long-term strategy, you can ensure that your CI is protecting your code and enabling confident collaboration. Remember, a robust CI/CD system is the backbone of modern software development, and addressing these issues promptly will save you time and headaches in the long run.

Estimated Effort: ~15 minutes (Option A) | ~2 hours (Option B)

Impact if Not Resolved: Deployment of untested code to production, potentially leading to significant issues.

For more information on GitHub Actions and best practices, consider exploring the official GitHub Actions Documentation.