Pipelines - Reusable Workflows

When managing multiple projects, writing identical pipeline configurations for every repository can lead to duplication and maintenance challenges. STACKIT Git allows you to build modular CI/CD pipelines by reusing existing workflow files.

By utilizing the jobs.<job_id>.uses, you can reference a centralized workflow template from the same repository or an external one, keeping your automation dry.

jobs.<job_id>.uses - Specifies the reusable workflow to call with a workflow_call event. uses can be specified in one of three supported formats:

• ./.forgejo/workflows/reusable.yml — refers to a workflow file within the same repository as the current workflow is defined.
• some-org/some-repo/.forgejo/workflows/reusable.yml@main — refers to a workflow file within a different repository (some-org/some-repo), at a specified path and Git reference (main). The target repository must be a public repository.
• https://example.com/some-org/some-repo/.forgejo/workflows/reusable.yml@main — refers to a workflow file hosted on a different Forgejo or GitHub instance. The target repository must be a public repository.

It is recommended that jobs.<job_id>.runs-on is omitted when using uses, as this will allow Forgejo to perform workflow expansion. Workflow expansion results in the target workflow’s jobs appearing in the UI as separate jobs. This provides an easier to understand experience for accessing the logs of each job, and permits the jobs to run on separate runners with their own runs-on fields. A workflow file hosted on a different Forgejo or GitHub instance is not supported by workflow expansion, and will automatically disable it.

uses is typically accompanied by jobs.<job_id>.with and jobs.<job_id>.secrets to provide information into the reusable workflow.

Understanding the with property

A dictionary mapping the inputs of the workflow_call event to concrete values. See on.workflow_call.inputs for more information on how the inputs are declared in reusable workflow.

Understanding the secrets property

Controls the secrets provided to the reusable workflow being called. It can either be secrets: inherit in which case the reusable workflow will have access to the same secrets as the caller. Or it can be a dictionary mapping a selection of secrets. For instance in the following, the reusable workflow will get keep_it_private as the result of evaluating the expression ${{ secrets.secret }}:

on:
push:

jobs:
caller:
    runs-on: docker
    uses: ./.forgejo/workflows/reusable.yml
    secrets:
    secret: keep_it_private