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.
When to use a template
Section titled “When to use a template”| 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.
A first example
Section titled “A first example”The repository acme/shop lints its Go code with a template of the repository acme/ci-templates.
The workflow file of acme/shop:
The template in acme/ci-templates:
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:
$[[ 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.
Using a template
Section titled “Using a template”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.
The template block
Section titled “The template block”| 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.
Keys next to template
Section titled “Keys next to template”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.
Variables in the workflow file
Section titled “Variables in the workflow file”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.
Writing a template
Section titled “Writing a template”Where templates live
Section titled “Where templates live”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.ymlis 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 template file
Section titled “The template file”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.
Inputs
Section titled “Inputs”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:
A workflow file that uses it:
The expanded workflow, as crow lint --show-expanded prints it outside of a pipeline, where CI_COMMIT_TAG is empty:
Value rules
Section titled “Value rules”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
numbercannot have a leading zero, an exponent or a missing digit before the point:010,1e3and.5are 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
arrayholds 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
booleanornumberinput. - 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>.
Interpolation
Section titled “Interpolation”$[[ 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
arraybecomes a YAML list. - A reference inside a longer text inserts the text of the input.
A
numberkeeps its text there, so1.20stays1.20. - An
arrayinput can only be the whole value of a key, such ascommands: $[[ 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 aCI_*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, thevariablesblock and the variables of a manual run reach a template only throughinputs. - Not in
commandsandentrypoint. 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.$NAMEwithout braces needs no escape. - Quote a command that contains a colon followed by a space.
YAML reads
- echo key: valueas a mapping, and a template rejects a mapping where a text belongs. Write- 'echo key: value'.
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:
evaluate
Section titled “evaluate”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:
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.
Secrets
Section titled “Secrets”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.
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 adescription. - The workflow file has to map every declared alias, and cannot map one the template does not declare.
- An alias holds
from_secretand nothing else, written as in theenvironmentof a step: with the name of a secret, or with an external secret ofintegration,path,keyand optionallyversion. Anintegrationthat 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_secretnames a declared alias, in the values ofenvironmentandsettings. The external-secret form offrom_secretis not available in a template: only the workflow file decides which secret a template reads.
How a mapped secret reaches a step
Section titled “How a mapped secret reaches a step”- When the template is expanded, the alias is replaced by what the workflow file maps it to:
from_secret: registry_userbecomesfrom_secret: REGISTRY_USER. The expanded workflow, which Crow stores and shows in the config tab, contains the names of secrets and never a value. - 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.
- 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.
- 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.
Who owns which key
Section titled “Who owns which key”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 withoutwhenmatches. A template can limit itself, for example to never run onpull_request, and a workflow file can narrow that but not widen it. Thetaskselector of a manual run applies to thewhenof the workflow file only. The list of workflows offered for a manual run is built from thewhenof the workflow file alone as well, so a workflow whose template excludesmanualis 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 valuesaand[a]are the same value.approval: one side can set it. Anapprovalon both sides is an error.
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:
Matrix workflows
Section titled “Matrix workflows”The matrix belongs to the workflow file.
Every axis expands the template on its own, and the axis values reach the template through inputs:
The first of the two workflows:
A template cannot define a matrix, and its steps cannot use when: matrix:.
What a template step sees
Section titled “What a template step sees”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,settingsand 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.
The history rule
Section titled “The history rule”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.
Limits per forge
Section titled “Limits per forge”| 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.
Sharing templates
Section titled “Sharing templates”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. repois 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.
The visibility rule
Section titled “The visibility rule”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.
Checked on every use
Section titled “Checked on every use”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.
Templates from another repository
Section titled “Templates from another repository”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_hostsandtmpfsare errors, whatever the trust settings of the repository are. - No
backend_options. - No forge credentials in steps.
The
netrccredentials reach the clone section only: the default clone step, or a clone step whose image is on the server-wide listCROW_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 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.
Templates as required workflows
Section titled “Templates as required workflows”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
whenof 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.
Pinning
Section titled “Pinning”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
templateblock 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 parameterfresh=trueof 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.
Pull requests from forks
Section titled “Pull requests from forks”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.
Reading the pipeline’s config tab
Section titled “Reading the pipeline’s config tab”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.
Checking templates locally
Section titled “Checking templates locally”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.
- Without
--template-source, a template of another repository is not read.crow lintthen checks thetemplateblock only and warns that the inputs are not checked, which--strictturns into an error.crow execdoes 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
--inputand placeholders for the inputs that have neither. Repeat--inputwith the same name for the items of anarrayinput. - A template file cannot be run with
crow exec. Run a workflow file that uses it.
Errors
Section titled “Errors”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.
Limits
Section titled “Limits”| 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.
Updating refs with Renovate
Section titled “Updating refs with Renovate”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.
- Use the data source of the forge:
forgejo-tags,gitea-tags,github-tagsorgitlab-tags.registryUrlTemplateis 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.0or1.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:
A branch ref such as refs/heads/main needs no update: every new pipeline follows the branch.
Migrating a workflow to a template
Section titled “Migrating a workflow to a template”This workflow file of acme/shop is to become a template that other repositories can use:
-
Create the template file
Create
.crow-templates/go-test.yamlin the same repository. Movestepsunderworkflow, together withservices,clone,skip_clone,workspace,cacheandartifactsif the file has them, and addspec. Leavewhen,matrix,name,depends_onandruns_onin the workflow file. -
Replace what differs per repository by inputs
Declare an input for every
${VAR}that is not aCI_*value, and write$[[ inputs.<name> ]]in its place. Here that is the Go version. -
Fix the commands
${...}does not work incommands. Read aCI_*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. -
Declare the secrets
Declare an alias under
spec.secretsfor every secret the steps read, and letfrom_secretname the alias. -
Lint the template
-
Replace the steps of the workflow file by a
templateblock -
Compare the expanded workflow with the old one
Then run a pipeline and read its config tab. Remember that the steps no longer see the matrix axis and the
variablesof the file in their environment, see What a template step sees. -
Move the template to a shared repository
Move the file to
.crow-templates/of the shared repository, tag a release, and settemplate_accessthere. Then addrepoandrefto thetemplateblock of every workflow file that uses it. A template of another repository cannot use trusted settings, see Templates from another repository.