The architectural challenge of managing dependencies between separate GitHub Actions workflow files is a frequent point of friction for developers operating within monorepos or complex CI/CD pipelines. In a standard GitHub Actions environment, the needs keyword is designed exclusively for job-level dependencies within a single YAML file. When a developer attempts to use needs to reference a job located in a different workflow file, the pipeline fails because the GitHub Actions engine requires at least one job with no dependencies to act as the entry point for that specific workflow execution. This creates a technical gap for those who wish to maintain a clean separation of concerns—such as keeping testing logic in test.yml and deployment logic in deploy.yml—while still enforcing a strict sequential execution order where deployment only occurs upon the successful completion of tests.

Achieving a dependable chain of execution across multiple files requires moving beyond simple job dependencies and leveraging event-driven triggers, conditional logic, and specific GitHub Actions events. Whether the goal is to ensure a Terraform plan is uploaded to an Azure Storage Account before a secondary plan begins, or to ensure that a production deployment only triggers after a successful test suite on a tagged release, the solution involves strategically manipulating the on trigger and the if conditional at the job level.

The Structural Limitation of Cross-Workflow Dependencies

The primary failure point in many initial attempts to create dependent workflows is the misuse of the needs keyword across different files. In a scenario where a test.yml handles the testing suite and a deploy.yml handles the release, a developer might attempt the following configuration:

```yaml

deploy.yml

name: Deploy
on:
push:
tags: ['*']
jobs:
deploy-app:
runs-on: ubuntu-latest
needs: run-tests
steps:
- uses: actions/checkout@v2
- run: npm run deploy
```

This configuration is fundamentally invalid because the run-tests job does not exist within the scope of deploy.yml. GitHub Actions evaluates each workflow file as an independent unit of execution. The error message indicating that the pipeline is invalid because it needs at least one job with no dependencies is the system's way of stating that the dependency graph is broken; it cannot find the starting point (run-tests) within the current context.

The impact of this limitation is that developers are often forced into a "copy-paste" anti-pattern, where they duplicate test steps into every deployment workflow to ensure safety. This leads to maintenance overhead and a violation of the DRY (Don't Repeat Yourself) principle. To solve this, one must implement orchestration patterns that bridge the gap between separate workflow files.

Implementation Strategy: The workflow_run Event

One of the most robust methods for establishing a dependency between two separate workflows is the workflow_run event. Unlike the push or pull_request events, workflow_run allows a workflow to be triggered by the completion of another specified workflow.

Technical Configuration of workflow_run

To implement this, the downstream workflow (e.g., deploy.yml) must be configured to listen for the completion of the upstream workflow (e.g., test.yml).

```yaml
name: Deploy
on:
workflow_run:
workflows: ["Run Tests"]
types:
- completed
branches:
- main

jobs:
deploy-app:
runs-on: ubuntu-latest
if: ${{ github.event.workflow_run.conclusion == 'success' && startsWith(github.ref, 'refs/tags/') }}
steps:
- uses: actions/checkout@v2
- run: npm run deploy
```

Deep Drilling into the workflow_run Mechanism

1. Direct Fact: The workflow_run event triggers a workflow after another workflow has been completed or requested.
2. Impact Layer: This eliminates the need to duplicate test jobs across multiple files, as the deployment workflow remains dormant until the testing workflow signals a completion state.
3. Contextual Layer: By combining the conclusion == 'success' check with a startsWith(github.ref, 'refs/tags/') condition, the system creates a precise gate. The deployment is not just dependent on the tests passing, but also on the specific Git reference being a tag, preventing accidental deployments from standard branch pushes.

Implementation Strategy: Job Consolidation and Conditional Logic

When the workflow_run event is not ideal, an alternative approach involves modifying the deployment workflow to include the testing job but using conditional logic to control when the deployment actually occurs. This method essentially merges the logic of two workflows into one for the purpose of the deployment pipeline, while keeping the independent test workflow for standard PRs.

The Consolidated Workflow Approach

In this model, the deploy.yml is modified to run on both main branch pushes and tag creations. It explicitly defines the test job and the deploy job within the same file to utilize the needs keyword correctly.

```yaml
name: Deploy
on:
push:
branches: [main]
tags: ['*']

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

deploy-app:
needs: run-tests
if: startsWith(github.ref, 'refs/tags/')
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- run: npm run deploy
```

Analysis of the Consolidated Pattern

• Trigger Flexibility: The workflow triggers on both main and tags.
• Dependency Enforcement: The deploy-app job explicitly needs: run-tests, ensuring that if the tests fail, the deployment is skipped.
• Targeted Execution: The if: startsWith(github.ref, 'refs/tags/') condition ensures that while tests run on every push to main, the actual deployment only happens when a tag is pushed. This effectively mimics the behavior of two separate workflows while staying within the technical constraints of GitHub's single-file dependency model.

Implementation Strategy: Manual Triggers via workflow_dispatch

For environments where deployments require a human "sanity check" or a manual override, the workflow_dispatch event can be integrated into the dependency chain. This allows a developer to manually trigger the sequence.

Manual Trigger Configuration

```yaml
name: Deploy
on:
push:
tags: ['*']
workflow_dispatch:

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

deploy-app:
needs: run-tests
runs-on: ubuntu-latest
if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
steps:
- uses: actions/checkout@v2
- run: npm run deploy
```

Impact of workflow_dispatch Integration

The addition of workflow_dispatch provides a safety valve. If a tag push fails for some reason but the developer knows the build is safe, they can manually trigger the workflow. However, the conditional if: github.event_name == 'push' ensures that the automated deployment only happens on a real tag push, while the manual trigger can be used to run the tests specifically.

Managing Sequence with Concurrency Controls

In complex environments, such as those involving Terraform plans where one plan must be completed before another begins (e.g., uploading a plan to an Azure Storage Account before a subsequent "apply" or "secondary plan" workflow), the concurrency feature can be used to prevent race conditions.

Applying Concurrency Groups

Concurrency allows the developer to ensure that only one job or workflow in a specific group runs at a time. If a second workflow is triggered while the first is still running, GitHub can either queue it or cancel the one in progress.

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

Concurrency Logic and Deployment Safety

By assigning a group based on the workflow name and the Git reference, the developer ensures that deployment attempts are sequential. If a test workflow is still running and a deploy workflow starts, the concurrency group manages the execution. While this does not replace the needs keyword for strict dependency, it prevents the system from attempting to deploy a version of the code that has not yet passed the current test run.

Comparison of Workflow Dependency Methods

The following table provides a technical comparison of the different methods used to handle dependencies between GitHub Actions workflows.

Infrastructure and DevOps Application: Terraform and Azure

In the context of Infrastructure as Code (IaC), specifically using Terraform, the need for dependent workflows is critical. A common pattern involves a "Terraform PR Plan" workflow that executes a terraform plan and uploads the resulting plan file to an Azure Storage Account. A subsequent workflow, such as a "Code Scan" or a "Terraform Apply," must wait for this upload to complete to ensure it is analyzing or applying the correct artifact.

For the "Terraform PR Plans" workflow, the trigger is typically:

yaml on: pull_request: types: [opened, synchronize, reopened]

To ensure the "Code Scan - Non Prod" workflow runs after the plan is uploaded, the workflow_run event is the most appropriate choice. This ensures that the security scan occurs against the actual plan intended for deployment, rather than a generic version of the code, thereby reducing the risk of deploying insecure infrastructure.

Conclusion: Analysis of Dependency Patterns

The evolution of GitHub Actions from simple scripts to complex CI/CD orchestrators has revealed a fundamental design choice: dependencies are local to the workflow file. This architecture encourages modularity but complicates the creation of linear pipelines across multiple files.

The most effective way to resolve this is not by fighting the system—attempting to use needs across files—but by embracing the event-driven nature of the platform. The workflow_run event transforms the pipeline from a static graph into a dynamic chain of events, allowing the "Deploy" workflow to act as a listener for the "Test" workflow's success.

For those prioritizing absolute safety and simplicity, the consolidated approach (merging tests and deployment into one file with conditional gates) remains the most reliable pattern. It removes the latency associated with workflow_run and provides a clear, visible dependency graph in the GitHub UI. For high-scale DevOps operations, particularly those managing stateful infrastructure like Azure and Terraform, the combination of workflow_run and concurrency groups provides the necessary guardrails to prevent state corruption and ensure that no infrastructure is modified without first passing all requisite validation gates.

Sources

1. How to set up workflow dependencies in GitHub Actions
2. Workflow Depends
3. GitHub Community Discussions - Terraform Workflow Setup