How to Deal with Lots of Workflows GitHub Actions

What are GitHub Action workflows?

GitHub Action workflows are automation pipelines defined within a repository to automate development processes, such as building, testing, and deploying code. Each workflow is triggered by specified GitHub events, such as pushes, pull requests, or even on a schedule. Actions are executed by GitHub-hosted runners in a defined sequence.

Developers define workflows using YAML files placed in the .github/workflows directory at the root of their repositories. These files specify jobs, steps, and actions that allow for customizable and repeatable automation solutions suited for various software projects.

Workflows can integrate with other tools, run on Linux, macOS, and Windows environments, and support both official and community-maintained actions from the GitHub Marketplace. They are useful for tasks ranging from linting code and running tests to deploying to cloud infrastructure or publishing packages. The modular structure also encourages consistent CI/CD practices across teams.

How to deal with lots of workflows in GitHub Actions? Two approaches

When managing many GitHub Action workflows across a repository or organization, two key strategies can help maintain performance and reduce duplication: controlling concurrency and using reusable workflows.

Control concurrency to avoid conflicts

By default, GitHub allows multiple instances of workflows and jobs to run at the same time. While this supports parallel processing, it can also lead to resource contention or overlapping deployments. To avoid this, use the concurrency keyword in the workflow or job definitions. This restricts execution so that only one job or workflow in a concurrency group runs at a time.

Concurrency groups are defined by a string or expression. When a job or workflow in a group is running, any newly triggered runs in that same group are either queued or canceled, depending on the configuration. Setting cancel-in-progress: true ensures that a running job is stopped in favor of the newer one. This is useful for avoiding unnecessary use of GitHub Actions minutes or ensuring only the latest deployment job is executed.

Use reusable workflows to eliminate duplication

If similar workflows exist across multiple repositories or projects, reusable workflows can reduce maintenance overhead. Instead of copying workflow logic, define a reusable workflow once and reference it from other workflows. This is effective for common tasks such as deployment pipelines or standardized test suites.

Caller workflows trigger these reusable workflows, which behave as if their steps were defined directly in the calling workflow. This allows teams to build and maintain a centralized library of workflows that can be updated in one place and used everywhere. Access controls and visibility settings ensure workflows are shared securely and appropriately within or across repositories.

Tutorial: Creating a reusable workflow

Creating a reusable workflow is an excellent way to deal with a large number of workflows. The instructions below are adapted from the GitHub Actions documentation.

To create a reusable workflow:

1. Begin by placing a YAML-formatted workflow file in the .github/workflows directory of the repository. The file must include the workflow_call trigger under the on key, which enables it to be invoked by other workflows.

   on:
       workflow_call:

2. Next, define any inputs and secrets that you want the reusable workflow to accept. These are specified under on.workflow_call.inputs and on.workflow_call.secrets. Each input must declare whether it’s required and its data type (string, number, or boolean).

3. Secrets must also be marked as required.

   on:  
       workflow_call:
           inputs:
               config-path:
                   required: true
                   type: string
           secrets:  
               token:
                   required: true

4. Inside the workflow, reference these inputs and secrets using inputs.<input_id> and secrets.<secret_id>. For example:

   jobs:
       triage:
           runs-on: ubuntu-latest
           steps:
               - uses: actions/labeler@v4
                   with:
                       repo-token: ${{ secrets.token }}
                       configuration-path: ${{ inputs.config-path }}

5. To call this workflow from another workflow, use the uses keyword within a job. Provide the full path to the reusable workflow file, along with a reference such as a branch name, tag, or commit SHA. Pass inputs using with and secrets using the secrets key.

   jobs:
       call-labeler:
           uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
       with:
           config-path: .github/labeler.yml
       secrets:
           token: ${{ secrets.GITHUB_TOKEN }}

6. Developers can also use secrets: inherit to pass all secrets from the caller workflow, which simplifies setup when all secrets should be made available.

7. Reusable workflows support matrix strategies as well. This makes it possible to run the same reusable workflow with different input values. For example:

   jobs:
       deploy:
           strategy:
               matrix:
                   environment: [dev, staging, prod]
           uses: org/repo/.github/workflows/deploy.yml@main
           with:
               target: ${{ matrix.environment }}

8. To expose outputs from a reusable workflow, map job-level outputs to workflow outputs using the outputs key under workflow_call. This allows the caller workflow to reference the results.

   on:
       workflow_call:
           outputs:
               result:
                   value: ${{ jobs.build.outputs.result }}

With this setup, developers can invoke reusable workflows from multiple jobs and projects, improving consistency and reducing duplication across the CI/CD pipeline.

Related content: Read our guide to GitHub Actions secrets

Best practices for handling numerous workflows in GitHub

Developers should be familiar with the following practices when working with multiple GitHub workflows.

1. Documenting each workflow

Every workflow should be accompanied by clear, up-to-date documentation, ideally within the workflow file as comments and in a centralized WORKFLOWS.md in the repository. Documentation should explain the workflow’s purpose, triggers, expected inputs, outputs, and links to any dependent resources or reusable templates.

Clear docstrings at the top of YAML files help developers quickly understand why a workflow exists and how it interacts with the rest of the codebase, reducing onboarding friction for new team members. Central documentation enables easier tracking and discovery, especially when workflow numbers increase. It can include diagrams, execution order, environment requirements, and contacts for workflow support.

2. Reviewing security and permissions

Security must be a primary concern when handling numerous workflows, especially since GitHub Actions can deploy code and access secrets. Teams should routinely review workflow permissions—such as GITHUB_TOKEN scopes and repository secrets—ensuring they align with the principle of least privilege.

Clearly defining which workflows can access deployments, secrets, and organization resources minimizes potential attack surfaces. Security reviews should also cover the usage of third-party or community actions. Actions from untrusted sources can introduce vulnerabilities or even malicious code.

Locking action versions with a commit SHA rather than a moving tag helps prevent supply chain attacks. Integrating code scanning and secret scanning in the workflow definitions themselves helps surface risky practices early and enables automatic alerts or pull request gating policies.

3. Cleaning outdated or redundant pipelines

Workflows can accumulate as projects evolve, leading to obsolete automation that wastes resources and complicates maintainability. Teams should perform scheduled reviews of their workflows to identify and remove those no longer serving an active purpose. This includes workflows attached to deprecated features, old branches, or superseded by newer templates.

Removing unused workflows reduces clutter, improves execution reliability, and mitigates confusion for developers encountering legacy files. Before deletion, ensure that dependent processes are migrated or redirected and announce removals to avoid workflow disruptions. Maintaining a changelog of deletions and rationale can be helpful for auditing and rollback.

4. Assigning ownership and maintenance responsibilities

Owners should be documented within workflow files—either in comments or structured with YAML keys—or within a centralized repository tracking all workflows and their maintainers. A defined owner is responsible for updating workflows in response to changes in dependencies, build tooling, or project requirements, ensuring no workflow is neglected or left incompatible after updates elsewhere.

Rotating ownership or regularly reviewing owner assignments helps prevent knowledge silos. Teams can implement automated reminders—using bots or code owners integration—to prompt maintainers to review workflows after major project milestones or during scheduled audits. Shared responsibility models, with backup maintainers, improve workflow reliability.

5. Automating notifications and reports

Automated notifications help teams stay informed about workflow executions, failures, or pending approvals. Integrating workflow notifications with Slack, Microsoft Teams, or email ensures stakeholders get timely alerts when issues arise. Setting up summary reports, either in dashboards or via scheduled digests, can provide a holistic view of workflow health.

Workflow automation can also be used to generate regular compliance and audit logs, ensuring adherence to internal standards and external regulations. Using GitHub APIs or custom reporting actions, teams can export and aggregate workflow data to identify trends, track remediation, and support operational reviews.

Octopus: Alternative to GitHub actions for complex deployments

Octopus provides GitHub Actions integrations that let you manage your Continuous Integration workflows in GitHub while smoothly transitioning to Octopus for enterprise-scale Continuous Deployment. This approach gives you access to specialized capabilities designed for managing sophisticated deployment scenarios at scale.

Through the Octopus interface, you can visualize your deployment workflows and track their progress. While deployment processes can be maintained as code within version control systems, the graphical interface allows you to review and modify them visually, enhancing comprehension and accessibility.

Multi-tenant deployment capabilities enable you to use a unified deployment workflow across different environments, geographical regions, physical sites (such as retail outlets or medical facilities), or customer-specific software instances.

Octopus accommodates both contemporary and legacy deployment approaches, providing a centralized view of all your deployments whether they target container orchestration platforms, cloud services, or traditional infrastructure across public cloud, private data centers, or hybrid environments.

The platform supports centralized variable and secret management with dynamic value injection during deployment execution, ensuring configuration accuracy and consistency across environments.

Beyond deployment orchestration, Octopus enables the creation of automated operational playbooks. These can streamline repetitive administrative tasks, facilitate incident response procedures, and deliver self-service automation capabilities to development and operations teams.

Learn more about Octopus Deploy

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback