# CI Functions: Composability in GitLab CI/CD ## Introduction Composability is the primary goal for CI steps. Based on user research and customer feedback, we aim to define composability in the GitLab CI/CD context and how it can be improved. ## Requirement Users should be able to compose jobs from one (or multiple) CI Functions, allowing for greater flexibility and reusability in pipeline configurations. ## Problem to Solve CI Functions should address the following challenges in CI/CD pipelines: 1. **Reusability**: Enable the reuse of CI/CD configurations across multiple projects or within a single project. 2. **Modularity**: Allow complex pipelines to be broken down into smaller, more manageable units. 3. **Centralized Configuration**: Facilitate the maintenance of common CI/CD configurations in a central location, accessible by multiple projects. ## Limitations of the `include` Keyword While the `include` keyword aims to solve these problems, it has several limitations: * Users cannot use it in the context of a specific job. * It requires combining `include` with `extend` for job-level reuse, which only partially solves the reusability problem. * Although it breaks down pipelines into smaller files, these files are not easily manageable. * The `include` keyword affects the entire pipeline configuration, not just specific jobs. ## How CI Functions Address These Issues CI Functions aim to solve these problems by allowing users to call and run a step in the context of a job. This approach provides more granular control and better composability. ### Example Job Using Steps ```yaml my-job: run: - name: greet_user step: gitlab.com/gitlab-org/ci-cd/runner-tools/echo-step@v1 - name: print_system_information step: ./my-local-steps/uname ``` CI Functions aim to solve these problems by allowing users to call and run a step in the context of a job. This approach provides more granular control and better composability. ### Example Job Using Steps ```yaml my-job: run: - name: greet_user step: gitlab.com/gitlab-org/ci-cd/runner-tools/echo-step@v1 - name: print_system_information step: ./my-local-steps/uname ``` ## Requirements for Composability 1. **Job-level Composability**: * Users should be able to compose jobs from one or multiple CI Functions. * Steps should be usable within the context of specific jobs without affecting the entire pipeline. 2. **Enhanced Reusability**: * Steps should be reusable across multiple projects or within a single project. * A central repository of common steps should be available for easy sharing and using. 3. **Improved Modularity**: * Complex pipelines should be breakable into smaller, self-contained steps. * Each step should be independently maintainable and versioned. 4. **Flexible Step Sources**: * Support both remote and local step sources. * Allow referencing steps from a central repository or local directory. 5. **Version Control**: * Users should be able to pin and use a specific version. 6. **Existing CI features**: * The new steps feature should be compatible with existing CI/CD configurations, and if not we should document what is not supported 7. **Documentation and Discoverability**: * Provide clear documentation on how to create, use, and share steps. * Implement a system for discovering and browsing available steps (e.g., an official project and later on in the CI catalog). 8. **Intuitive Syntax**: * The syntax for using steps should be straightforward and easy to understand. * Try to maintain consistency with existing GitLab CI/CD configuration patterns, and if not we should consider porting those changes to the existing CI syntax (e.g `env.` ) 9. **Conditional Step Execution**: * Support conditional execution of steps based on the outputs of previous steps. * Allow users to define conditions that determine whether a step should run ## Final note By meeting these requirements, CI Functions will provide a more flexible, modular, and reusable approach to building CI/CD pipelines and answer the question that keeps popping up: "How do CI Functions make the life of a developer who has to create a CI pipeline easier? ### Program plan for implementing usage of GitLab Steps with .gitlab-ci.yml | [Architecture Blueprint Phase](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_steps/gitlab-ci/#phase-3-the-addition-of-setup-and-teardown-to-gitlab-ciyml) | Phase Description | Related Epic | Development Status | Notes | Customer impact | |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------|--------------|--------------------|-------|-----------------| | Phase 1 | Initial Support (Step Runner)- in this phase the scope is that the Step Runner will be used externally, without any dependencies to GitLab | ... | Complete | | | | Phase 2: | Add `run` keyword to `.gitlab-ci.yml` | .. | Complete | A key goal of this phase as defined is that `run` is designed to replace usage of `before_script`, `script` and `after_script`. | | | Phase 2b | Transition from `before_script`, `script` and `after_script` | .. | In Progress | | TBD | | Phase 3 | Add `setup` and `teardown` to `.gitlab-ci.yml` | ... | Not started | The addition of setup: and teardown: will replace the implicit functions provided by GitLab Runner: Git clone, artifacts and cache handling. This represents a significant milestone in the evolution of CI Functions. | TBD | ## Timeline (revised 2025-11-23) [Feature development stage](https://docs.gitlab.com/policy/development_stages_support/) <table> <tr> <th> \-- </th> <th>FY26 Q3</th> <th>FY26 Q4</th> <th>FY27 Q1</th> <th>FY27 Q2</th> <th>FY27 Q3</th> </tr> <tr> <td>Description of functionality available</td> <td> [Steps supports multiple operating systems](https://gitlab.com/groups/gitlab-org/-/epics/15074) </td> <td> [Script to Functions - Core Foundation](https://gitlab.com/groups/gitlab-org/-/epics/19182) </td> <td> [Path to Production](https://gitlab.com/groups/gitlab-org/-/epics/19959+s.) </td> <td> Additional build stages :star: [Customer requirement Allow reference/access files](https://gitlab.com/gitlab-org/gitlab/-/issues/579092) </td> <td>Support additional executors</td> </tr> <tr> <td>Primary Goal</td> <td>Run the same step efficiently across Linux, Windows, and macOS runners</td> <td>Transparently migrate all existing script-based jobs (before_script, script, after_script) to run through step-runner architecture without requiring any user changes which will help us mature CI step</td> <td>Customer will use step under the cover</td> <td> More parts of the runner uses CI steps Access local files such as binaries when running CI pipelines </td> <td>Use steps with Docker, Kubernetes, and shell executors based on their infrastructure</td> </tr> <tr> <td> `Experiment` </td> <td> `Experiment` </td> <td> `Experiment` </td> <td> `Experiment` </td> <td> `Experiment` </td> <td> `Beta` </td> </tr> </table> :star: Customer requirement is in the scope of Beta, timeline for implementation is not final