Skip to content
Crow CI

Workflow templates

A workflow template is a workflow that is written once and used by many workflow files. The template contains the steps. A workflow file that uses it holds no steps: it names the template and passes inputs and secrets.

A template is a file in a Git repository, in the directory .crow-templates/. It can be used by the workflow files of the same repository, and by other repositories on the same forge once its repository shares it.

You want to Use
Repeat a few keys inside one file YAML anchors
Generate workflows with loops and conditions in one repository Jsonnet
Package one task in a container image A plugin
Use the same workflow in several files or repositories A workflow template

Anchors and Jsonnet work inside one repository: a Jsonnet import only finds files next to the importing file. A plugin is one step, and the workflow around it is still written in every repository. A template is a whole workflow with a declared interface, and a version that every pipeline records.

A template is not merged with the file that uses it. Every key belongs to one side, as Who owns which key lists.

The repository acme/shop lints its Go code with a template of the repository acme/ci-templates.

The workflow file of acme/shop:

# .crow/lint.yaml in acme/shop
when:
  - event: [push, pull_request]

template:
  repo: acme/ci-templates
  name: go-lint
  ref: v1.4.0
  inputs:
    go_version: '1.24'
  secrets:
    sonar_token:
      from_secret: SONAR_TOKEN

The template in acme/ci-templates:

# .crow-templates/go-lint.yaml in acme/ci-templates
spec:
  description: Lint a Go module and upload the report.
  inputs:
    go_version:
      description: Go toolchain version.
      default: '1.24'
    upload:
      type: boolean
      default: true
  secrets:
    sonar_token:
      description: Token for the SonarQube upload.

workflow:
  when:
    - event: [push, pull_request, manual]
  steps:
    - name: lint
      image: golang:$[[ inputs.go_version ]]
      commands:
        - go vet ./...
    - name: upload
      image: sonarsource/sonar-scanner-cli:11
      environment:
        SONAR_TOKEN:
          from_secret: sonar_token
      commands:
        - sonar-scanner
      when:
        - evaluate: 'inputs.upload'

When a pipeline is created, Crow resolves v1.4.0 to a commit of acme/ci-templates, reads the template there and expands it with the values of the workflow file. This is the workflow that runs:

# lint.yaml → acme/ci-templates/go-lint@v1.4.0
when:
  - event:
      - push
      - pull_request
steps:
  - name: lint
    image: golang:1.24
    commands:
      - go vet ./...
  - name: upload
    image: sonarsource/sonar-scanner-cli:11
    environment:
      SONAR_TOKEN:
        from_secret: SONAR_TOKEN
    commands:
      - sonar-scanner
    when:
      - evaluate: inputs.upload

$[[ inputs.go_version ]] became the value the file passes, and the alias sonar_token became the name of the secret SONAR_TOKEN of acme/shop. The value of that secret is in neither file: from_secret names a secret, here as in every step. The when of the template is not part of the expanded workflow: Crow checks it next to the when of the workflow file, and the workflow runs only if both match.

Before any of this works, acme/ci-templates has to share its templates, see Sharing templates.

A workflow file uses a template if it has a template block and no steps. A file with steps is an ordinary workflow, whatever other keys it has, and a template key in it is ignored with a warning.

Key Required Meaning
name Yes Name of the template, which is the file .crow-templates/<name>.yaml
repo No Full name of the repository that contains the template, such as acme/ci-templates
ref With repo Tag, branch or commit of that repository, see Refs
inputs No Values for the inputs the template declares
secrets No A secret of this repository for every secret alias the template declares, named with from_secret

Without repo, the template is read from the repository of the workflow file, at the commit of the pipeline. ref is then not allowed.

repo, name and ref are literals. ${...} in them is an error, because Crow has to know the templates of a pipeline before it substitutes any variable.

Every other key in template is an error, and so is a single value instead of a mapping.

Next to template, a workflow file may set name, when, matrix, depends_on, runs_on, labels, approval, variables and $schema. They mean what they mean in every workflow file.

services, clone, skip_clone, workspace, cache and artifacts belong to the template and are errors in the workflow file. A top-level secrets key and every unknown key are errors as well. notify is ignored with a deprecation warning.

These files are stricter than ordinary workflow files, where an unknown key is only a warning. A misspelled key inside approval, inside when or inside an entry of depends_on is an error too.

A workflow file that uses a template can use ${VAR} in its values, with the names an ordinary workflow file can use: matrix axes, the variables block, CI_* values and the variables of a manual run. A name without a value becomes an empty text.

Crow replaces ${VAR} inside the values of the parsed file and not in its text. A value can therefore change a value and never the structure: a commit message that contains a colon followed by a space, or a #, stays one text. ${VAR} is not replaced in mapping keys.

A Jsonnet file can produce a workflow file that uses a template. The template itself is always YAML.

A template is the file .crow-templates/<name>.yaml at the root of a repository.

  • The directory is fixed. It does not follow the config path of the repository, and no other file of a repository can be used as a template.
  • The name matches [a-z0-9][a-z0-9_-]{0,62}. Subdirectories are not supported.
  • The extension is .yaml. A file that ends in .yml is not found.
  • Do not put templates into the workflow directory .crow/. Crow reads every file there as a workflow, and a template fails as one.

The root of a template file holds spec and workflow, optionally $schema, and nothing else.

spec is the interface. It is required, and a template without inputs and secrets writes spec: {}.

Key Meaning
description What the template does
inputs The inputs the template takes
secrets The secret aliases the template needs

workflow is the body.

Key Meaning
steps Required, with at least one step
services, clone, skip_clone, workspace, cache, artifacts As in a workflow file
when, labels, approval Combined with the workflow file, see Who owns which key
variables A place for YAML anchors only, with no other meaning

name, depends_on, runs_on, matrix, notify and template are errors in workflow. A template cannot use another template.

A step of a template can use the keys of an ordinary step: name, image, pull, commands, entrypoint, environment, settings, directory, depends_on, failure, detach, when, temp_volumes and ports. The keys privileged, volumes, devices, network_mode, dns, dns_search, extra_hosts, tmpfs and backend_options work only in a template of the same repository, see Templates from another repository. The step-level secrets list is not available. Every other key is an error, in a step and in every mapping with fixed keys such as approval, workspace or an entry of cache.

A template file is one YAML document. YAML anchors and merge keys work inside it, and YAML tags such as !!str are not supported.

An input is declared under spec.inputs. Its name matches [a-z][a-z0-9_]*.

Key Meaning
type string (the default), number, boolean or array
default Value used when the workflow file does not pass the input
description Shown in the error when the input is missing or wrong
options Allowed values, for string and number inputs

An input without default is required. A default has to be a value of the type and, if there are options, one of them. Every other key in a declaration is an error.

An input cannot be named after a keyword of evaluate expressions: and, contains, else, false, if, in, let, matches, nil, not, or or true.

This template declares one input of every type:

# .crow-templates/deploy.yaml
spec:
  description: Deploy a release.
  inputs:
    target:
      description: Environment to deploy to.
      options: [staging, production]
    image_tag:
      description: Tag of the image to deploy.
    replicas:
      type: number
      default: 2
    dry_run:
      type: boolean
      default: false
    regions:
      type: array
      default: [eu-central]

workflow:
  steps:
    - name: deploy
      image: acme/deployer:2
      environment:
        TARGET: $[[ inputs.target ]]
        IMAGE: registry.example.com/shop:$[[ inputs.image_tag ]]
        REPLICAS: $[[ inputs.replicas ]]
        DRY_RUN: $[[ inputs.dry_run ]]
        REGIONS: $[[ inputs.regions ]]
      commands:
        - deploy

A workflow file that uses it:

# .crow/deploy.yaml
when:
  - event: tag

template:
  name: deploy
  inputs:
    target: production
    image_tag: ${CI_COMMIT_TAG:-latest}
    replicas: 3
    regions: [eu-central, us-east]

The expanded workflow, as crow lint --show-expanded prints it outside of a pipeline, where CI_COMMIT_TAG is empty:

# deploy.yaml → .crow-templates/deploy.yaml
when:
  - event: tag
steps:
  - name: deploy
    image: acme/deployer:2
    environment:
      TARGET: production
      IMAGE: registry.example.com/shop:latest
      REPLICAS: 3
      DRY_RUN: false
      REGIONS:
        - eu-central
        - us-east
    commands:
      - deploy

A passed value is a text or a list of texts, and the declared type alone decides what it is. The typing and the quoting of YAML play no part, so race: true and race: 'true' are the same value.

Type Accepted values
string The text as written, so 1.20 stays 1.20, and the empty text is a value
boolean Exactly true or false
number A decimal integer or fraction with an optional sign, such as 3, -2 or 1.5
array A YAML list of texts
  • A number cannot have a leading zero, an exponent or a missing digit before the point: 010, 1e3 and .5 are errors.
  • A whole number has to fit into 64 bits.
  • A number with a fraction has at most 15 digits, is below 1000000, and is zero or at least 0.0001 in size.
  • An array holds texts. A list or a mapping inside the list is an error.
  • A null is not a value. That is the YAML null, written as null, ~ or an empty value. The quoted texts 'null' and '' are texts.
  • The empty text is not a value for a boolean or number input.
  • To use the default, leave the key out. To fall back inside the workflow file, write ${VAR:-fallback}.

An unknown input, a missing required input, a value of the wrong type and a value outside options are errors. They name the workflow file and the field template.inputs.<name>.

$[[ inputs.<name> ]] places an input into the body of a template. It is written with exactly one space on each side. $[[inputs.name]] is an error, and so is anything else inside $[[ ]].

  • A value that is exactly one reference takes the input in its declared type, quoted or not. A boolean stays a boolean, a number stays a number, and an array becomes a YAML list.
  • A reference inside a longer text inserts the text of the input. A number keeps its text there, so 1.20 stays 1.20.
  • An array input can only be the whole value of a key, such as commands: $[[ inputs.commands ]]. It cannot be embedded in a text or be one element of a list.
  • What is inserted is never scanned again. A value that happens to contain $[[ inputs.x ]] or ${VAR} stays as it is.
  • $$ writes a literal $, so $$[[ writes a literal $[[.

References work in the values of workflow. They do not work in mapping keys, in spec, in from_secret or in when.evaluate.

Differences from ${VAR} in a workflow file

Section titled “Differences from ${VAR} in a workflow file”

An ordinary workflow file replaces ${VAR} in its text before YAML is parsed. A template is stricter:

  • Only CI_* names. ${CI_COMMIT_SHA} and the other built-in variables work. Every other name is an error. The string operations work as well, such as ${CI_COMMIT_SHA:0:8}, ${CI_COMMIT_TAG##v} and ${CI_COMMIT_TAG:-none}. The operand of such an operation is plain text and cannot name another variable, not even a CI_* one: ${CI_COMMIT_TAG:-${CI_COMMIT_SHA}} is an error.
  • The values come from the pipeline alone. A matrix axis or a variable of the workflow file that is named CI_... does not change them. The matrix, the variables block and the variables of a manual run reach a template only through inputs.
  • Not in commands and entrypoint. Every ${...} is an error there. The same values are in the environment of the step, where the shell reads them as $CI_COMMIT_BRANCH. A branch name or a pull request title therefore never becomes part of the script.
  • Write $${NAME} for a shell variable. $NAME without braces needs no escape.
  • Quote a command that contains a colon followed by a space. YAML reads - echo key: value as a mapping, and a template rejects a mapping where a text belongs. Write - 'echo key: value'.
# .crow-templates/build.yaml
spec:
  inputs:
    go_version:
      default: '1.24'
    packages:
      default: ./...

workflow:
  steps:
    - name: build
      image: golang:$[[ inputs.go_version ]]
      environment:
        SHORT_SHA: ${CI_COMMIT_SHA:0:8}
        PACKAGES: $[[ inputs.packages ]]
      commands:
        - 'echo "commit: $SHORT_SHA on $CI_COMMIT_BRANCH"'
        - go build -ldflags "-X main.version=$${SHORT_SHA}" "$PACKAGES"

This template passes the input to the script through the environment. An input that is written into a command becomes part of the script, so whoever sets the input can run commands in the step. Prefer an environment variable that the shell expands.

A name that is not a CI_* value is an error:

# .crow-templates/build.yaml
spec: {}

workflow:
  steps:
    - name: build
      image: golang:${GO_VERSION}
      commands:
        - go build ./...

A when.evaluate expression of a template, at workflow level and at step level, reads its inputs as typed values and the CI_* values of the pipeline:

# .crow-templates/release.yaml
spec:
  inputs:
    mode:
      options: [short, full]
      default: short
    publish:
      type: boolean
      default: false

workflow:
  steps:
    - name: test
      image: golang:1.24
      commands:
        - go test ./...
    - name: integration
      image: golang:1.24
      commands:
        - go test -tags integration ./...
      when:
        - evaluate: 'inputs.mode == "full"'
    - name: publish
      image: golang:1.24
      commands:
        - make publish
      when:
        - evaluate: 'inputs.publish && CI_COMMIT_BRANCH == "main"'

inputs.publish is a boolean, so the text false is false. Every other identifier is an error: the variables of the workflow file and of a manual run are not visible. $[[ ... ]], ${...} and let are not available in the expression.

A template never names a secret of a repository, and a workflow file never contains the value of one. The template declares aliases under spec.secrets, and the workflow file maps every alias to one of its secrets under template.secrets. Both sides write from_secret, as every step that reads a secret does: the template to name an alias, the workflow file to name the secret behind it.

# .crow-templates/publish.yaml
spec:
  secrets:
    registry_user:
      description: User for the image registry.
    registry_password:
      description: Password for the image registry.

workflow:
  steps:
    - name: publish
      image: quay.io/skopeo/stable:v1.17
      environment:
        REGISTRY_USER:
          from_secret: registry_user
        REGISTRY_PASSWORD:
          from_secret: registry_password
      commands:
        - skopeo login --username "$REGISTRY_USER" --password "$REGISTRY_PASSWORD" registry.example.com
        - skopeo copy dir:image "docker://registry.example.com/shop:$CI_COMMIT_TAG"
# .crow/publish.yaml
when:
  - event: tag

template:
  name: publish
  secrets:
    registry_user:
      from_secret: REGISTRY_USER
    registry_password:
      from_secret:
        integration: prod-vault
        path: ci/registry
        key: password

The step above gets the secret REGISTRY_USER of the repository in its variable REGISTRY_USER, and the password from the external secret.

  • An alias matches [a-z][a-z0-9_]*, and its declaration may hold a description.
  • The workflow file has to map every declared alias, and cannot map one the template does not declare.
  • An alias holds from_secret and nothing else, written as in the environment of a step: with the name of a secret, or with an external secret of integration, path, key and optionally version. An integration that consists of digits is the ID of an integration, and every other text is its name.
  • A text directly below an alias, such as registry_user: REGISTRY_USER, is an error. It could be read as the name of a secret or as its value, and a value does not belong in a workflow file.
  • In the template, from_secret names a declared alias, in the values of environment and settings. The external-secret form of from_secret is not available in a template: only the workflow file decides which secret a template reads.
  1. When the template is expanded, the alias is replaced by what the workflow file maps it to: from_secret: registry_user becomes from_secret: REGISTRY_USER. The expanded workflow, which Crow stores and shows in the config tab, contains the names of secrets and never a value.
  2. From there the step is a step like every other that reads a secret. When the server builds the workflow for a run, it looks the name up in the secrets available to the repository that runs the pipeline, and hands the value to the step. These are the secrets every step of that repository reads: its own, those of its organization, global ones, and secrets shared with it. Using a template of another repository gives no access to the secrets of that repository.
  3. The event and plugin filters of the secret apply to the expanded step. A secret that is limited to a plugin image only reaches a template step that runs that plugin.
  4. The agent replaces the value with ******** where it appears in the log of a step, as for every step. It does so for every secret available to the pipeline, whether a step reads it or not. A value of three characters or fewer is not masked, and neither is a value that a step prints in another form, such as base64.

Inputs are not secrets. A value passed under template.inputs is written into the expanded workflow, stored with the pipeline and shown in the config tab, so a credential never belongs there.

Nothing is merged. Every key belongs to one side, and three keys have a fixed rule for both.

Key Workflow file Template workflow
template Required Error
steps Makes the file an ordinary workflow Required
services, clone, skip_clone, workspace, cache, artifacts Error Allowed
name, depends_on, runs_on, matrix Allowed Error
when Allowed Allowed
labels Allowed Allowed
approval Allowed Allowed
variables Variables and anchors, as in every workflow file Anchors only
notify Ignored with a warning Error
  • when: both have to match, and a side without when matches. A template can limit itself, for example to never run on pull_request, and a workflow file can narrow that but not widen it. The task selector of a manual run applies to the when of the workflow file only. The list of workflows offered for a manual run is built from the when of the workflow file alone as well, so a workflow whose template excludes manual is offered there and then skipped when the pipeline is created.
  • labels: the labels of both sides are united. The same label with different values on the two sides is an error. The values a and [a] are the same value.
  • approval: one side can set it. An approval on both sides is an error.
# .crow/release.yaml
when:
  - event: [push, tag]
    branch: main
labels:
  team: payments

template:
  name: release
# .crow-templates/release.yaml
spec: {}

workflow:
  when:
    - event: [tag, manual]
  labels:
    platform: linux/amd64
  approval:
    required: true
    timeout: 2h
  steps:
    - name: release
      image: golang:1.24
      commands:
        - make release

This workflow runs for a tag event only, the one event both sides name. It carries both labels and the approval gate of the template:

# release.yaml → .crow-templates/release.yaml
when:
  - event:
      - push
      - tag
    branch: main
labels:
  team: payments
  platform: linux/amd64
approval:
  required: true
  timeout: "2h"
steps:
  - name: release
    image: golang:1.24
    commands:
      - make release

The matrix belongs to the workflow file. Every axis expands the template on its own, and the axis values reach the template through inputs:

# .crow/test.yaml
name: test-${GO_VERSION}
matrix:
  GO_VERSION: ['1.23', '1.24']
when:
  - event: [push, pull_request]

template:
  name: go-test
  inputs:
    go_version: ${GO_VERSION}
# .crow-templates/go-test.yaml
spec:
  inputs:
    go_version:
      description: Go toolchain version.

workflow:
  steps:
    - name: test
      image: golang:$[[ inputs.go_version ]]
      commands:
        - go test ./...

The first of the two workflows:

# test.yaml → .crow-templates/go-test.yaml (GO_VERSION=1.23)
name: test-1.23
when:
  - event:
      - push
      - pull_request
steps:
  - name: test
    image: golang:1.23
    commands:
      - go test ./...

A template cannot define a matrix, and its steps cannot use when: matrix:.

A template has an explicit interface, in its text and when it runs. The environment of a step, a service or a clone step that comes from a template holds:

  • the CI_* values of the pipeline,
  • the global environment of the instance (CROW_ENVIRONMENT) and its proxy settings,
  • what the template sets itself, with environment, settings and its secrets.

It does not contain what the step of an ordinary workflow file gets in addition: the matrix axes, the defaults of the variables block, the variables of a manual run and the parameters of a restart. Such a value reaches a template step only if the workflow file passes it as an input.

The ordinary workflow files of the same pipeline are not affected.

A template of the same repository has no ref: it is read at the commit of the pipeline, like the workflow files. A template of another repository needs a ref, in one of three forms:

Form Example Meaning
A bare name, or refs/tags/<tag> v1.4.0 A tag
refs/heads/<branch> refs/heads/main A branch, followed by every new pipeline
A full commit SHA 3f2a9c1d0e5b4a7f8c6d2e1b0a9f8e7d6c5b4a3f That commit, written with all 40 or 64 lowercase hex characters
  • A bare name is a tag and nothing else. If no such tag exists, the error suggests refs/heads/<name>, and Crow never falls back to a branch of that name.
  • An abbreviated SHA is not a SHA. It is read as a bare name, which is a tag.
  • A full SHA with uppercase letters is an error.
  • There is no default ref and no version range. A ref that starts with ~ or ^ is an error.

Crow resolves the ref to a commit when the pipeline is created and records that commit, see Pinning. A commit SHA always names the same template, and a tag does until somebody moves it. A branch follows every change of the template repository.

A repository can also name itself with repo and a ref, to use its own templates at another commit than the one of the pipeline. That needs no template_access, and the template is then treated as one from another repository.

A forge also serves commits that only a pull request reaches. Crow therefore accepts a commit SHA only if a branch or a tag of the template repository reaches the commit.

  • GitLab answers this in one call.
  • On GitHub, Forgejo and Gitea, Crow compares the commit with the default branch, then with at most 25 other branches and at most 25 tags. If the repository has more refs and none of the checked ones reaches the commit, the SHA is refused. Use a tag or a branch in that case.
  • A positive answer is stored, so a pinned commit stays valid when its branch is deleted later.
Forge Tag Branch Commit SHA
GitHub Yes Yes Yes
GitLab Yes Yes Yes
Forgejo Yes Yes Yes
Gitea Yes Yes Yes, from Gitea 1.22
Bitbucket, Bitbucket Datacenter, forge addons No Yes No

A Gitea server older than 1.22 cannot compare commits. A SHA is accepted there only if one of the checked branches or tags points exactly at it.

A ref form that a forge does not support is an error that names the supported forms.

A repository shares its templates with the repository setting template_access:

Value Who may use the templates
none No other repository, which is the default
org The repositories of the same organization in Crow
instance Every repository of the same forge on this Crow instance

A repository always may use its own templates. See Repository settings for how to change the setting.

  • The template repository has to be activated in Crow.
  • It has to be on the forge of the repository that uses it. Two forges can each have an acme/ci-templates, and they never mix.
  • repo is the full name of the repository. Upper and lower case do not matter.
  • Crow reads the template with the forge token of the user who activated the template repository, never with a token of the repository that uses it.

A repository cannot use the templates of a repository that is less visible than itself, in the order private, internal, public. A public repository would otherwise publish a private template on its pipeline pages. A template repository that is private on its forge counts as private, whatever its visibility in Crow is.

Crow checks template_access and the visibility rule when a pipeline is created, and again whenever a stored template is used or shown: on approval, rerun and restart, and when the pipeline page shows the configuration. If the template repository revokes the access, is deactivated or removed from Crow, or the using repository becomes more visible, existing pipelines can no longer be approved, rerun or restarted with that template. The pipeline page then withholds the template and the expanded workflow, and shows the reason.

A template that is not read from the commit of the pipeline gets none of the trust of the repository that uses it. That is every template with a repo.

  • No trusted settings. privileged, volumes, devices, network_mode, dns, dns_search, extra_hosts and tmpfs are errors, whatever the trust settings of the repository are.
  • No backend_options.
  • No forge credentials in steps. The netrc credentials reach the clone section only: the default clone step, or a clone step whose image is on the server-wide list CROW_PLUGINS_TRUSTED_CLONE. The steps and services of the template never get them, and the custom trusted clone plugins of the repository do not count.

temp_volumes and ports are allowed. A plugin on the server-wide list of privileged plugins runs privileged in a template as well.

# .crow-templates/image.yaml in acme/ci-templates
spec: {}

workflow:
  steps:
    - name: image
      image: docker:27
      volumes:
        - /var/run/docker.sock:/var/run/docker.sock
      commands:
        - docker build .
# .crow/image.yaml in acme/shop
when:
  - event: push

template:
  repo: acme/ci-templates
  name: image
  ref: v1.4.0

crow lint --strict rejects both files: the template can only be used inside acme/ci-templates, and acme/shop cannot use it.

A template of the same repository is treated like the workflow files of that commit: it can use these keys under the trust settings of the repository.

An admin of an organization can assign a template to the repositories of the organization as a required workflow. Every pipeline of a repository in scope then runs the template, and no workflow file names it.

The template file needs nothing for that. For its author, an assignment changes this:

  • The template is treated as a template of another repository, also in the pipelines of its own repository: no trusted settings, no backend_options, and forge credentials for the clone section only.
  • The inputs come from the assignment and are literal values. The secrets are those of the organization and global ones, never those of the repository the pipeline runs in.
  • The assignment stores a commit. A new commit, a moved tag or an advanced branch reaches the repositories only when an admin updates the assignment.
  • The when of the template alone decides for which pipelines the workflow runs. A pull request it does not match gets no status, and a forge that requires the status then waits for it.

See Writing a template for a required workflow.

Crow resolves templates once, when a pipeline is created. It resolves the ref of every template block to a commit, reads the template at that commit and stores it with the pipeline. What is stored does not change when a tag moves, a branch advances or the template repository is deleted on the forge.

Operation Templates used
Approving a blocked pipeline or a workflow at an approval gate The stored ones
Rerunning a workflow or a step The stored ones
Restarting a pipeline The stored ones, in a new pipeline
Starting a deployment from a pipeline The stored ones, in a new pipeline
Fresh restart Resolved again on the forge

None of the operations that use the stored templates asks the forge for a template.

  • Restart runs the stored workflow files with the stored templates. A template that could not be fetched when the pipeline was created is resolved now, so a restart is the way to retry after a forge outage. A template block the pipeline never had is an error that asks for a fresh restart. That happens when an external config service returns another file on restart.
  • Fresh restart is a restart of the same commit and the same event that resolves every template again. Use it to get a moved tag or a new commit on a branch without a new push. It also takes the required workflows of the repository as they are assigned now, where a restart replays the ones the pipeline recorded. On the command line it is crow pipeline start --fresh <repo> <pipeline>. Over the API it is the query parameter fresh=true of the restart endpoint, POST /api/v1/repos/{repo_id}/pipelines/{number}?fresh=true. It cannot be combined with a change of the event.
  • A pipeline that was created before the server supported templates has no stored templates. It needs a fresh restart.

What is pinned is the template. The values the workflow file passes are evaluated for every run: ${VAR} in inputs, Jsonnet, and the current values of the mapped secrets.

A pull request from a fork runs the workflow files of its own commit, and that holds for templates of the same repository too: the fork can change them. The approval requirement of the repository blocks such a pipeline as a whole.

A fork can only name the templates the base repository may use. It cannot reach a template that is not shared with the base repository.

Templates are resolved before a pipeline waits for approval. The approver therefore reads the pinned template, and approving runs that template: it is not fetched again. The expanded workflow is built again at approval, from the same workflow file and the same template. It can differ from the one shown before where a value changed in the meantime, for example ${CI_PREV_PIPELINE_STATUS} in inputs once an earlier pipeline has finished, or a mapped secret that was changed.

The Config tab of a pipeline shows what Crow made of a workflow file that uses a template:

  • the workflow file, with the template it was resolved to: repository, name, the ref as written and the commit, with a link to that commit on the forge,
  • the template file, as it was read at that commit,
  • the expanded workflow, marked as generated from the workflow file.

The expanded workflow is named after the workflow file: lint.expanded.yaml for lint.yaml, and test.expanded-1.yaml, test.expanded-2.yaml and so on for the axes of a matrix. It contains the when of the workflow file alone, and the when of the template is checked separately. A workflow that was skipped has no expanded workflow.

An error or a warning about a template names both files and the commit, such as lint.yaml → acme/ci-templates/go-lint@3f2a9c1, and the field in the template, such as workflow.steps.lint.image.

crow lint and crow exec expand templates without a server, see the CLI page. For editors, the JSON schema of workflow files covers the template block, and a second schema describes template files.

# Lint a workflow file that uses a template of its own repository
crow lint .crow/test.yaml

# Read the templates of another repository from a local checkout
crow lint --template-source acme/ci-templates=../ci-templates .crow/

# Print the expanded workflow, once per matrix axis
crow lint --show-expanded .crow/test.yaml

# Lint a template file with values for its inputs
crow lint --input go_version=1.24 --input packages=./... .crow-templates/build.yaml

# Run a workflow that uses a template
crow exec --template-source acme/ci-templates=../ci-templates .crow/lint.yaml
  • Without --template-source, a template of another repository is not read. crow lint then checks the template block only and warns that the inputs are not checked, which --strict turns into an error. crow exec does not run such a workflow.
  • The checkout is used as it is. The CLI does not check that it is at the ref the workflow file names.
  • A template file is linted on its own with its defaults, the values of --input and placeholders for the inputs that have neither. Repeat --input with the same name for the items of an array input.
  • A template file cannot be run with crow exec. Run a workflow file that uses it.

A problem with a template ends the pipeline with an error before any step runs. Crow never falls back to running without the template. A message about a template file names the file, the field and the kind of problem, and never quotes the text of the template. A message about a value the workflow file passes does name what the template declares for that input: its name, its description and its options. Crow resolves the templates of all workflow files of a pipeline, so a template that cannot be resolved fails the pipeline even if its workflow would be skipped for the event.

Message Cause and fix
template … not found or not shared with this repository The repository is unknown to Crow, not activated, on another forge, or does not share its templates with this repository: check repo, and template_access of the template repository. The same message appears when the template repository was renamed, moved or recreated on the forge after it was activated, because Crow then no longer finds the repository it knows under that name: repair the template repository in its Crow settings so Crow learns the new name, and write the new name in repo
… is public and … is private: a repository cannot use the workflow templates of a repository that is less visible than itself The visibility rule: make the template repository at least as visible as the repository that uses it
no tag main in …; write refs/heads/main to follow the branch A bare name is a tag: write refs/heads/<branch> or create the tag
no tag … in …, no branch … in … The ref does not exist in the template repository
commit … is not on a branch or tag of … The history rule: use a commit that a branch or a tag reaches
commit … was not found on the default branch, 25 other branches and 25 tags of … The template repository has more refs than Crow checks: use a tag or a branch as the ref
the forge of this repository cannot resolve tags: the ref must be … The forge supports fewer ref forms, see Limits per forge
no file .crow-templates/… in … at … The template does not exist at that commit: check name and the .yaml extension
could not fetch template … from the forge; restart the pipeline to try again The forge did not answer: restart the pipeline
this template was not part of the pipeline; use a fresh restart The stored pipeline has no copy of this template: use a fresh restart
Cannot approve the pipeline: … A stored template is no longer shared with this repository, and the pipeline stays blocked until it is shared again
not a template: the root of a template file holds … The file in .crow-templates/ is not a template
the template has no input …, the template requires the input … Fix template.inputs in the workflow file
the template needs the secret … Map the alias under template.secrets, with from_secret
a secret alias is mapped with from_secret … Write from_secret: <name of a secret> below the alias, not the name or the value directly
`${NAME}` is available in a template for names that start with `CI_` only Write $${NAME} for a shell variable or $[[ inputs.name ]] for an input
must be a text, at a command of a template Quote the command: it contains a colon followed by a space, which YAML reads as a mapping
the workflow files use … distinct workflow templates, and this server allows … The limit CROW_MAX_TEMPLATES
the file … has … bytes, and this server allows … bytes for a workflow template The limit CROW_MAX_TEMPLATE_SIZE

A server without this feature, and Woodpecker, read a workflow file that uses a template as a workflow without steps. It fails there with the error about an invalid or missing steps section.

Limit Value
Distinct templates per pipeline 50, set by CROW_MAX_TEMPLATES
Size of a template file 512 KiB, set by CROW_MAX_TEMPLATE_SIZE
Length of a template name 63 characters
Values in a template file, in a workflow file that uses a template, and in an expanded workflow 100000, after YAML aliases are resolved
Nesting of a template file, and of a workflow file that uses a template 100 levels
Text that one expansion inserts from variables, inputs and CI_* values 1 MiB
Branches and tags checked by the history rule The default branch, 25 other branches and 25 tags

Two template blocks are the same template if they agree in repo, name and ref. The templates of all workflow files of a pipeline count, also of the files that do not run for the event. The calls to the forge use CROW_FORGE_TIMEOUT and CROW_FORGE_RETRY, like the fetch of the workflow files.

A tag or a commit SHA does not move on its own. A custom manager lets Renovate update the repo and ref pair of a template block.

{
  "customManagers": [
    {
      "description": "Workflow templates of Crow CI",
      "customType": "regex",
      "managerFilePatterns": ["/\\.crow/.+\\.ya?ml$/", "/(^|/)\\.crow\\.ya?ml$/"],
      "matchStrings": [
        "repo: ['\"]?(?<depName>[\\w.~-]+(?:/[\\w.~-]+)+)['\"]?\\s*\\n\\s*name: [^\\n]+\\n\\s*ref: ['\"]?(?:refs/tags/)?(?<currentValue>v?\\d+\\.\\d+[^'\"\\s]*)",
        "repo: ['\"]?(?<depName>[\\w.~-]+(?:/[\\w.~-]+)+)['\"]?\\s*\\n\\s*name: [^\\n]+\\n\\s*# renovate: tag=(?<currentValue>\\S+)\\n\\s*ref: ['\"]?(?<currentDigest>[a-f0-9]{40})"
      ],
      "datasourceTemplate": "forgejo-tags",
      "registryUrlTemplate": "https://codefloe.com"
    }
  ]
}
  • Use the data source of the forge: forgejo-tags, gitea-tags, github-tags or gitlab-tags. registryUrlTemplate is the address of a self-hosted forge.
  • The manager expects the keys in the order repo, name, ref.
  • The first pattern updates a release tag such as v1.4.0 or 1.4. It does not match a branch ref or a commit SHA.
  • The second pattern updates a commit SHA that is pinned together with its tag, in a comment on the line above ref:
# .crow/lint.yaml in acme/shop
when:
  - event: [push, pull_request]

template:
  repo: acme/ci-templates
  name: go-lint
  # renovate: tag=v1.4.0
  ref: 3f2a9c1d0e5b4a7f8c6d2e1b0a9f8e7d6c5b4a3f
# .crow-templates/go-lint.yaml in acme/ci-templates
spec: {}

workflow:
  steps:
    - name: lint
      image: golang:1.24
      commands:
        - go vet ./...

A branch ref such as refs/heads/main needs no update: every new pipeline follows the branch.

This workflow file of acme/shop is to become a template that other repositories can use:

# .crow/test.yaml
when:
  - event: [push, pull_request]

matrix:
  GO_VERSION: ['1.23', '1.24']

steps:
  - name: test
    image: golang:${GO_VERSION}
    commands:
      - go test -coverprofile=coverage.out ./...
      - echo "tested ${CI_COMMIT_SHA:0:8}"
  - name: coverage
    image: codecov/codecov-cli:11
    environment:
      CODECOV_TOKEN:
        from_secret: codecov_token
    commands:
      - codecovcli upload-process --file coverage.out
  1. Create the template file

    Create .crow-templates/go-test.yaml in the same repository. Move steps under workflow, together with services, clone, skip_clone, workspace, cache and artifacts if the file has them, and add spec. Leave when, matrix, name, depends_on and runs_on in the workflow file.

  2. Replace what differs per repository by inputs

    Declare an input for every ${VAR} that is not a CI_* value, and write $[[ inputs.<name> ]] in its place. Here that is the Go version.

  3. Fix the commands

    ${...} does not work in commands. Read a CI_* value from the environment of the step, with a shell expression where the file used a string operation. Quote a command that contains a colon followed by a space.

  4. Declare the secrets

    Declare an alias under spec.secrets for every secret the steps read, and let from_secret name the alias.

    # .crow-templates/go-test.yaml
    spec:
      description: Test a Go module and upload the coverage.
      inputs:
        go_version:
          description: Go toolchain version.
      secrets:
        codecov_token:
          description: Token for the coverage upload.
    
    workflow:
      steps:
        - name: test
          image: golang:$[[ inputs.go_version ]]
          commands:
            - go test -coverprofile=coverage.out ./...
            - echo "tested $(echo "$CI_COMMIT_SHA" | cut -c1-8)"
        - name: coverage
          image: codecov/codecov-cli:11
          environment:
            CODECOV_TOKEN:
              from_secret: codecov_token
          commands:
            - codecovcli upload-process --file coverage.out
  5. Lint the template

    crow lint .crow-templates/go-test.yaml
  6. Replace the steps of the workflow file by a template block

    # .crow/test.yaml
    when:
      - event: [push, pull_request]
    
    matrix:
      GO_VERSION: ['1.23', '1.24']
    
    template:
      name: go-test
      inputs:
        go_version: ${GO_VERSION}
      secrets:
        codecov_token:
          from_secret: codecov_token
  7. Compare the expanded workflow with the old one

    crow lint --show-expanded .crow/test.yaml

    Then run a pipeline and read its config tab. Remember that the steps no longer see the matrix axis and the variables of the file in their environment, see What a template step sees.

  8. Move the template to a shared repository

    Move the file to .crow-templates/ of the shared repository, tag a release, and set template_access there. Then add repo and ref to the template block of every workflow file that uses it. A template of another repository cannot use trusted settings, see Templates from another repository.