Conditional Logic in GitHub Actions Workflow Execution

The orchestration of Continuous Integration and Continuous Deployment (CI/CD) pipelines often demands a high degree of flexibility to accommodate varying deployment targets, dependency management strategies, and build configurations. Within the ecosystem of GitHub Actions, the implementation of conditional logic allows developers to move away from the cumbersome practice of maintaining multiple, nearly identical workflow files for different environments. By leveraging the if statement, a single YAML configuration can dynamically determine which steps to execute based on the current state of environment variables or project parameters. This capability transforms a static sequence of commands into a programmable pipeline capable of adapting to the specific needs of a project, such as switching between different Static Site Generators (SSG) configurations or alternating between multiple cloud hosting providers.

The Architecture of GitHub Actions Conditionals

At the core of dynamic workflow execution is the if conditional, which acts as a gatekeeper for jobs and steps. When a GitHub Action encounters an if statement, it evaluates the expression provided. If the expression resolves to true, the step or job proceeds; if it resolves to false, the step is skipped entirely.

The syntax for these expressions requires a specific format to be recognized by the GitHub Actions runner. Specifically, a GitHub Action expression must be encased in double curly brackets following a dollar sign.

Example syntax:
${{ env.NODE == 'true' }}

This syntax tells the runner to evaluate the content within the brackets as an expression rather than a literal string. By utilizing this mechanism, developers can inject logic into the workflow that queries the environment (env) to decide the path of execution.

Environment Variables as Control Parameters

The env section of a GitHub Actions workflow file serves as the centralized control panel for the entire pipeline. Instead of hard-coding logic into individual steps, an expert implementation defines parameters at the top level of the workflow. This allows the operator to change the behavior of the entire deployment process by modifying a single value in the environment section.

Consider the following configuration parameters used to manage a Hugo-based project:

The use of these parameters eliminates the need to "juggle" multiple workflow files. In a traditional setup, a developer might have one file for deploy-vercel.yml and another for deploy-cloudflare.yml. With conditionals, these are merged into a single file where the HOST variable dictates which deployment step is activated.

Deep Drilling into Conditional Step Execution

The practical application of the if statement is most evident when managing dependencies and deployment targets. By mapping environment variables to specific steps, the workflow becomes a modular system.

Node.js Environment Setup

In many modern web projects, Node.js is required for package management and build tools. However, not every project configuration requires Node.js. By using the NODE environment variable, the workflow can conditionally install the Node.js runtime.

The implementation looks as follows:

yaml - name: Set up Node.js if: ${{ env.NODE == 'true' }} uses: actions/setup-node@v3 with: node-version: '18'

The impact of this logic is significant: it reduces the execution time of the workflow by skipping the installation of the Node.js environment when it is not required. In a "hybrid" project where some versions use npm and others use direct binary downloads from GitHub repositories, this conditional allows the developer to pivot their strategy without rewriting the YAML structure.

Deployment Target Switching

One of the most powerful use cases for GitHub Action conditionals is the ability to target different hosting providers within the same pipeline. This is achieved by checking the HOST variable against the desired provider.

For Cloudflare Pages, the workflow uses the following logic:

yaml - name: Deploy to Cloudflare Pages if: ${{ env.HOST == 'CFP' }} uses: cloudflare/pages-action@v1 with: # site-specific parameters

Conversely, for Vercel deployments, the workflow utilizes a different action:

yaml - name: Publish to Vercel if: ${{ env.HOST == 'Vercel' }} uses: BetaHuhn/deploy-to-vercel-action@v1 with: # site-specific parameters

This approach provides an architectural advantage: the developer only needs to change HOST: CFP to HOST: Vercel in the env section to switch the entire deployment destination. This eliminates the risk of maintaining outdated parameters across multiple files and ensures that the deployment logic remains centralized.

Integrating SSG Logic with Workflow Conditionals

The concept of using conditionals in GitHub Actions mirrors the logic often found within Static Site Generators like Hugo. In Hugo, conditionals are used to determine how assets are processed. For instance, a project might use a conditional to choose between Sass (SCSS) and vanilla CSS enhanced by PostCSS.

The internal Hugo logic might look like this:

go {{- if eq .Site.Params.Styling "SCSS" -}} {{- $css = resources.Get "scss/index.scss" | toCSS $scssOptions -}} {{- else -}} {{- $css = resources.Get "css/index.css" | postCSS | minify -}} {{- end -}}

When this logic is ported to the GitHub Actions workflow level, the STYLING environment variable (SCSS or VCSS) can be used to trigger different build steps. If STYLING is set to SCSS, the workflow can be configured to ensure the Dart Sass compiler is present in the system path. If it is set to VCSS (Vanilla CSS), the workflow can instead trigger a PostCSS build chain. This alignment between the SSG configuration and the CI/CD pipeline ensures that the environment provided by the GitHub runner perfectly matches the requirements of the build process.

Comprehensive Workflow Example

To illustrate the convergence of these concepts, the following example demonstrates a complete workflow structure incorporating environment-based conditionals.

```yaml
name: Deploy to web
on:
push:
branches:
- main

env:
HUGOVERSION: 0.111.3
DARTSASSVERSION: 1.62.1
PAGEFINDVERSION: 0.12.0
NODE: true
STYLING: VCSS
HOST: CFP

jobs:
deploy:
runs-on: ubuntu-latest
permissions:
contents: read
deployments: write
steps:
- name: Checkout default branch
uses: actions/checkout@v3
with:
fetch-depth: 0

  - name: Set up Node.js
    if: ${{ env.NODE == 'true' }}
    uses: actions/setup-node@v3
    with:
      node-version: '18'

  - name: Install Hugo, Pagefind, etc
    # This step would be configured based on the versions defined in env

  - name: Deploy to Cloudflare Pages
    if: ${{ env.HOST == 'CFP' }}
    uses: cloudflare/pages-action@v1
    with:
      # site-specific parameters

  - name: Publish to Vercel
    if: ${{ env.HOST == 'Vercel' }}
    uses: BetaHuhn/deploy-to-vercel-action@v1
    with:
      # site-specific parameters

```

Advanced Considerations for Hybrid Setups

As workflow requirements grow in complexity, developers may encounter "hybrid" scenarios. A hybrid setup is one where some tools are installed via a package manager like npm, while others are downloaded as standalone binaries from a GitHub repository and added to the system PATH.

In such cases, the all-or-nothing approach to Node.js installation may be too restrictive. If a project uses a package.json to install Hugo but also requires a specific version of a tool downloaded manually, the conditionals must be adjusted. Instead of a single NODE flag, a developer might implement more granular flags such as USE_NPM_FOR_HUGO or USE_BINARIES_FOR_SASS.

This level of granularity prevents the workflow from becoming a bottleneck and ensures that only the necessary tools are installed, maintaining a lean and efficient CI/CD pipeline.

Analysis of Conditional Efficiency

The shift from multiple workflow files to a single, conditional-driven workflow provides several technical advantages:

1. Reduced Maintenance: Changes to the checkout process or permissions only need to be made in one file rather than across five or six different versions of the workflow.
2. Deterministic Builds: By defining versions (HUGO_VERSION, DART_SASS_VERSION) in the env block, the build process becomes deterministic, reducing the "it works on my machine" phenomenon.
3. Flexibility: The ability to toggle between CFP and Vercel or SCSS and VCSS via a simple string change allows for rapid testing of different deployment targets without altering the core logic of the pipeline.
4. Resource Optimization: The if statement ensures that expensive setup steps (like installing a specific Node.js version) are only executed when they are actually needed for the current configuration.

Conclusion

The implementation of conditional logic via the if statement in GitHub Actions represents a significant evolution in how developers manage deployment pipelines. By moving control parameters into the env section and utilizing expressions like ${{ env.VARIABLE == 'value' }}, it is possible to collapse a multitude of specialized workflow files into a single, authoritative configuration. This method not only simplifies the management of Static Site Generator deployments—such as those using Hugo, Dart Sass, and Pagefind—but also provides a scalable blueprint for any project that requires dynamic environment switching. Whether alternating between Cloudflare Pages and Vercel or toggling between different CSS processing pipelines, conditionals eliminate the redundant overhead of file management and ensure that the CI/CD process is as agile as the code it deploys.

Sources

1. Using Conditionals in GitHub Actions