Can You have multiple GitHub actions yml files?

The direct answer to the question is: Yes, you can have multiple GitHub Actions YAML files, but they aren’t used in the same way as you might expect. While you can’t define multiple workflows within a single file, you accomplish complex CI/CD pipelines by utilizing different files for different workflows or breaking down complex jobs within a single workflow into modular components.

Table of Contents

Understanding GitHub Actions Workflows

Workflow Definitions

A GitHub Actions workflow defines a series of actions that are executed in response to specific events, such as a push to a repository, a tag creation, or a scheduled event. This definition resides within a .yml file (often named action.yml for a reusable action) usually located in the root of your repo, or within special actions directories.

Workflow vs. Action Granularity

A workflow sets the overall flow and structure of your CI/CD pipeline, which encompasses multiple jobs. A job represents a collection of tasks executing serially or in parallel. Finally, actions are individual units of work like building a project or packaging an artifact.

The Need for Multiple Files

Using multiple files offers advantages in managing and organizing intricate build processes.

Managing Complexity with Multiple YAML Files

Modular Design

Complex workflows can become difficult to manage when crammed into a single YAML file. Breaking down these processes into dedicated files enhances readability and maintainability.

Maintainability: Smaller files are easier to debug and modify.

Readability: The project structure mirrors the logical decomposition of the workflow.

Reusability: Define reusable actions in separate files, promoting code reuse across multiple workflows.

Scenario Examples

Independent Workflows: Imagine different branches requiring different build configurations. Having separate workflows.yml files for features branches (e.g., feature/myfeature-config.yml), development branches (develop-config.yml), and main (main-config.yml), allows for targeted configurations.

Reusable Actions: Create a dedicated directory for actions and define each action in its own action.yml. This promotes organization and reusability. Avoid code duplication by using reusable actions.

Multi-stage Builds: A single workflow for a large project might involve numerous stages: code analysis, testing, building, and deployment. Defining each stage as a separate .yml file within a common workflows directory facilitates managing complicated CI/CD pipelines.

How to Structure Multiple Files

Using Directories

workflows/: Keep all your workflows inside this directory for a clear structure.

actions/: Create a directory to store reusable actions.

jobs/: (Optional) Create a directory for structured jobs within a single workflow file. Useful for a very complex single workflow with lots of jobs that require organization.

Example Directory Structure (Workflows)

myrepo/

├── workflows/

│   ├── main-config.yml

│   ├── feature/myfeature-config.yml

│   └── develop-config.yml

└── actions/

    ├── build-action.yml

    └── test-action.yml

Example Workflow File (main-config.yml)

name: Main Workflow

on:

  push:

    branches:

      - main

jobs:

  build:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v3

      - uses: ./actions/build-action.yml

      - uses: actions/setup-python@v4  # Example of a required action

Utilizing Reusable Actions

Defining `action.yml`

A reusable action, defined in a file like build-action.yml, encapsulates a specific task like building your project. These actions are referenced by workflows via uses.

# build-action.yml

name: My Build Action

inputs:

  python_version:

    description: Python version

    required: true

    default: '3.9' # Example default, often use inputs for configurations

runs:

  using: 'composite'

  steps:

    - name: Use Python ${{ inputs.python_version }}

      uses: actions/setup-python@v4

      with:

        python-version: ${{ inputs.python_version }}

    - name: Install Dependencies

      run: pip install -r requirements.txt

    - name: Build Project

      run: python setup.py build

Using Reusable Actions (in main-config.yml example)

# ... (main-config.yml) ...

jobs:

  build:

    runs-on: ubuntu-latest

    steps:

      - uses: ./actions/build-action.yml

        with:

          python_version: '3.10' # Using the input

Key Considerations

uses is critical for referencing actions/workflows from separate files.

Versioning: For reusability, add versioning to reusable actions to avoid conflicts over different codebases.

Inputs and Outputs: Use inputs and outputs to parameterize reusable actions for flexibility without code duplication.

Permissions and Secrets: Protect sensitive secrets used by actions appropriately.

Error Handling: Implement robust error handling in your workflows to ensure smooth execution of multiple actions & jobs.

Conclusion

Multiple GitHub Actions YAML files are essential for managing complex CI/CD pipelines. By leveraging modularity, reusability, and good file structure, they help to overcome the limitations that would arise from using a single, monolithic workflow file. Proper organization improves maintainability, readability, and facilitates collaborative development in any repository with intricate automated workflows.