Required workflows
A required workflow is a workflow template that an organization assigns to its repositories. Every pipeline of a repository in scope runs it, whatever the files of the repository say.
The assignment is stored on the Crow server and in no repository. No push can remove it, skip it or change what it does.
An admin of the organization manages its required workflows: an admin of the organization on the forge, the owner of a personal namespace, or an admin of the Crow instance. These are the users who may manage the secrets of the organization.
What a required workflow is for
Section titled “What a required workflow is for”Use a required workflow for a check that an organization wants on every change, such as a secret scan or a license check, and that a repository must not be able to switch off.
A repository can use the same template with a template block in one of its workflow files.
The two differ in who decides:
| Workflow file that uses a template | Required workflow | |
|---|---|---|
| Where it is written | In a workflow file of the repository | On the Crow server, for the organization |
| Who can change or remove it | Everybody who can push to the repository | An admin of the organization |
| Version of the template | The ref of the file, resolved for every new pipeline |
A commit, resolved when the assignment is saved |
| Inputs | From the file, with its variables | From the assignment, as literal values |
| Secrets | Those available to the repository | Those of the organization and global ones |
[skip ci], workflow selection of a manual run |
Apply | Do not apply |
| Name in a pipeline | The name of the file | required/<name> |
| Status context | Follows CROW_STATUS_CONTEXT_FORMAT |
Fixed |
A template needs nothing special to be assigned. There is no syntax for it in the template file or in a workflow file.
A first example
Section titled “A first example”The organization acme wants a secret scan in every pipeline of its repositories.
-
Write the template
The template is in a policy repository, here
acme/ci-policies, in the file.crow-templates/secret-scan.yaml:Commit it and tag a release, here
v1.4.0. Thewhenof the template decides for which events the required workflow runs. -
Share the policy repository
The policy repository has to be activated in Crow, and it has to share its templates with the organization:
See Sharing templates. A repository cannot use the templates of a repository that is less visible than itself. Make the policy repository at least as visible as the most visible repository it is assigned to.
-
Create the secret
The template declares the secret alias
scanner_token. A required workflow reads secrets of the organization and global secrets, so create the secret there. The scan runs for pull requests, so the secret has to allow thepull_requestevent, which a secret created on the command line does not by default: -
Create the assignment
The example covers every repository of the organization except
acme/web. A repository is left out by its ID in Crow, which is the first column of this command:Here the ID is 4711. Put in the ID of your own repository, or leave
--exclude-idout. On the command line:The server resolves
v1.4.0to a commit and stores the commit. It checks the inputs and the secret mapping against the template, and answers with the assignment and what it found:Over the API the same assignment is this request body:
<org-id>is theidof the first answer. The same file works on the command line, ascrow org required-workflow add acme --file secret-scan.json. The answer:The two repositories in scope are
acme/shopand the policy repository itself:*includes every activated repository of the organization. The repository with the ID 4711,acme/web, is left out. -
Require the status on the forge
From now on every pull request pipeline of a repository in scope runs the workflow
required/secret-scanand reports its result under the status contextci/crow/pull_request/required/secret-scan.Add this context to the required status checks of the protected branches on the forge. Until you do, a failed scan is shown on the pull request and does not keep anybody from merging it. Require this context and not the one of another event, see The status context.
The assignment
Section titled “The assignment”An assignment has a name, a template at a commit, inputs, a secret mapping, a selection of repositories and a switch. The API and the CLI take the same parts. So does the page Required workflows in the settings of an organization, see Web UI.
The name matches [a-z0-9][a-z0-9_-]{0,62} and is unique within the organization.
The name instance is reserved.
The workflow of a pipeline is named required/<name>, and the status context ends in it.
The name cannot be changed later.
To rename a required workflow, create a new one, delete the old one, and change the status context that the branch protection of the forge requires.
Template and ref
Section titled “Template and ref”template names the template the way a workflow file does, with repo, name and ref:
repois the full name of the repository that contains the template, on the forge of the organization. The repository has to be activated in Crow and has to share its templates with the organization:template_accessisorgfor a repository of this organization, orinstance.nameis the name of the template, which is the file.crow-templates/<name>.yaml.refis a tag, a branch or a commit, in the forms a workflow file uses: a bare name orrefs/tags/<tag>for a tag,refs/heads/<branch>for a branch, or a full commit SHA.
The server resolves the ref when the assignment is saved, and stores the commit. Pipelines read the template at that commit. A tag that moves or a branch that advances afterwards changes nothing until an admin updates the assignment.
Crow keeps the template of a revision once a pipeline has read it, and later pipelines use that copy. A policy repository that is deleted on the forge therefore does not stop the required workflow, and the check of the assignment does not warn of it. The required workflow fails once the policy repository is deactivated or removed in Crow.
The ref as it was written is kept next to the commit, as ref_hint.
It shows where the commit came from and is the ref an update follows.
It decides nothing else.
The server reads the template with the forge token of the user who activated the policy repository. The admin who saves the assignment needs no access to that repository on the forge.
Required workflows need a forge that can tell whether a commit belongs to a repository: GitHub, GitLab, Forgejo and Gitea. On Bitbucket, Bitbucket Datacenter and forge addons every required workflow fails.
Inputs
Section titled “Inputs”inputs holds a value for the inputs the template declares.
A value is a string, a number, a boolean or a list of strings.
The type the template declares decides what a value is, as for a workflow file.
The values are literals.
${VAR} in an input is not replaced: an input ${CI_COMMIT_BRANCH} is that text, and not the name of a branch that somebody pushed.
An assignment has no variables, so the template receives exactly what the admin entered, and nothing that a repository or a pull request controls becomes part of a value.
A template that needs a value of the pipeline reads the CI_* variable itself.
An input with a NUL character is refused. Bytes of a request that are not valid UTF-8 are not refused: the server reads each of them as the replacement character U+FFFD, and stores the input with it.
Inputs are not secrets. They are stored with the assignment and shown to the users of the repositories in scope, see The config tab.
Secrets
Section titled “Secrets”secrets maps every secret alias the template declares to the name of a secret, written as in a workflow file:
A required workflow reads two kinds of secrets:
- the secrets of the organization that assigned it,
- global secrets.
Where both have a secret of the same name, the one of the organization is used. Names are compared without regard to case.
A required workflow never reads a secret of the repository it runs in, and no secret that another owner shares with the repository or with the organization. A repository can therefore not put a secret of its own under a name that a required workflow reads.
The event and plugin filters of a secret apply to the steps of a required workflow as to every step.
A secret that a required workflow reads in pull request pipelines has to allow the pull_request event.
crow org secret add allows push, tag, release and deployment unless --event says otherwise.
Saving an assignment warns of a mapped secret that does not allow pull_request.
A secret that is named and does not exist is a warning when the assignment is saved, because it can be created afterwards. A pipeline that runs before it exists fails the required workflow.
External secrets are not available to required workflows in this release. Every integration belongs to the user who created it, and that user decides which organizations may use it. No integration belongs to the organization, so a user could put an integration of their own under the name an assignment asks for. A mapping to an external secret is refused when the assignment is saved.
Repositories
Section titled “Repositories”repos selects the repositories of the organization that the required workflow covers.
repos.include is a list of patterns.
A repository is included if one of them matches its name, which is the part after the owner.
| Pattern | Matches |
|---|---|
* |
Every repository of the organization |
api-* |
Every name that starts with api- |
shop-v? |
shop-v1, shop-v2: ? is one character |
service-[0-9] |
service-1: a class is one character of a set |
[!0-9]* |
Every name that does not start with a digit |
docs |
The repository docs |
- A pattern matches the whole name, without regard to case.
- A pattern cannot contain
/: it is compared with the name and never with the full name. - Alternatives in braces, such as
{web,docs}, and escapes with\are refused. Write one pattern for each alternative. - A pattern has at most 100 bytes and at most 8 wildcards, where every
*, every?and every class counts as one. - An assignment has at most 100 patterns.
- An assignment without a pattern covers no repository.
repos.exclude_ids lists repositories that are left out, by their ID in Crow.
An exclusion wins over every pattern.
An assignment excludes at most 1000 repositories.
A new entry has to be the ID of a repository of the organization that you can read.
An entry that is stored stays, whoever changes the list, also when its repository is gone.
Exclusions use the ID because a name can change.
A repository that is excluded stays excluded when it is renamed, and a rename cannot move a repository out of an assignment that includes *.
An assignment that includes repositories by a pattern does not have that property, see What Crow cannot do.
The first example shows how to find the ID of a repository.
Only activated repositories of the organization of the assignment are covered. A repository that moves to another organization leaves every assignment of the first one.
Enabled
Section titled “Enabled”enabled says whether new pipelines carry the workflow.
A new assignment is enabled unless the request says otherwise.
A disabled assignment keeps its revisions and covers no repository. Use it to prepare an assignment and check it before it takes effect, or to switch a check off without losing its history.
Deleting an assignment removes its revisions with it. Pipelines that carried it keep their workflows and logs.
Revisions
Section titled “Revisions”What a required workflow does is kept in numbered revisions: the template with its commit, the inputs and the secret mapping. A revision never changes. A pipeline records the revision of every required workflow it carries.
| Change | New revision |
|---|---|
| Another template repository or template name | Yes |
| Another commit | Yes |
| Other inputs | Yes |
| Another secret mapping | Yes |
| The same ref again, which still points at the same commit | No |
| The repositories | No |
enabled |
No |
A new revision is the current one at once. Every pipeline that is created from then on carries it. For pipelines that exist, see A new revision and open pull requests.
In a change, inputs and secrets each replace the whole map.
What a request leaves out stays as it is, and a change without template.ref keeps the commit.
The flags --input, --secret, --unset-input and --unset-secret of the CLI change single entries: the command reads the assignment first and sends the complete map.
Updating to the latest commit of the ref
Section titled “Updating to the latest commit of the ref”A new release of the template takes effect when an admin moves the assignment to it:
--latest sends the stored ref_hint as the ref.
Over the API that is a PATCH with template.ref:
If the ref still points at the commit the assignment has, nothing changes and the answer says "new_revision": false.
That also holds for another ref that points at the same commit: the assignment keeps its ref_hint, and a warning says so.
The base revision of a change
Section titled “The base revision of a change”Two admins can change an assignment at the same time.
A change can name the revision it was made from, as revision in the body of the PATCH.
If that is not the current revision any more, the server refuses the change with the status 409 and stores nothing.
Read the assignment again and repeat the change.
The CLI always sends a base revision: --revision, else the revision of --file, else the revision it read when the command started.
A change without a base revision is applied to the assignment as it is when the server stores it.
If the assignment changes while such a change is checked, the server checks the change again, three times in all, and then refuses it with the status 409.
History
Section titled “History”The revisions of an assignment are listed newest first, each with the user who saved it and the time:
Crow has no separate audit log.
The record of who changed what a required workflow does is this list, and the server log, which has a line for every new revision, every change of the repositories or of enabled, and every deletion.
A change of the repositories or of enabled makes no revision and is found in the server log only.
Checking an assignment
Section titled “Checking an assignment”Every save checks the assignment, and a dry run does the same without storing anything.
A dry run is the query parameter dry_run=true of the POST and of the PATCH, and the flag --dry-run of add and update.
A save or a dry run of an assignment that cannot be stored is refused with the status 400. The reasons come in two groups.
The first group needs no template, and the answer names every reason of it, in this order:
- the name, and for a change a
nameother than the one the assignment has and arevisionbelow 1, - the form of
template.repo,template.nameandtemplate.ref, - an input that is no string, number, boolean or list of strings, that has no valid name, or that holds a NUL character,
- a secret alias that has no valid name, is mapped to nothing or to an external secret, or holds a member other than
from_secret, - a pattern or an excluded ID that is not valid.
Only a request that passes the first group is checked against the template, and each of these checks gives all of its reasons:
- first that the template is found and shared with the organization, and that the ref resolves,
- then that the file is a valid template and uses no key a required workflow may not use,
- then that the inputs and the secret mapping fit the template: every input that is unknown, missing, of the wrong type or outside its options is named, and so is every alias that is not mapped or that the template does not declare.
The reasons name the inputs, the secret aliases and the types the template declares. They do not repeat other content of the template file, because the admin who saves need not be allowed to read the policy repository.
A request that is not one of this API, such as a body with an unknown member, is answered with the status 422, and a taken name or a stale base revision with 409, see When an assignment is saved.
What does not refuse a save is part of the answer, as validation:
| Member | Meaning |
|---|---|
warnings |
Sentences for the admin, see below |
repos_in_scope |
Number of activated repositories in scope that you may read |
repos_hidden |
Number of the other repositories in scope, which you may not read |
repos |
The repositories among repos_in_scope whose pipelines would fail the required workflow, each with id, full_name and reason |
The scope is counted as if the assignment were enabled, so a disabled assignment can be checked before it is switched on.
A repository in scope fails a required workflow if it may not use the template. There are two reasons:
- The visibility rule. A repository cannot use the templates of a repository that is less visible than itself.
- Sharing. The policy repository does not share its templates with that repository, is deactivated, or is gone.
This dry run asks what happens if acme/web, a public repository, is no longer excluded:
The policy repository acme/ci-policies is internal, so the answer names acme/web:
Saving this change is possible.
Every pipeline of acme/web would then carry a failed required/secret-scan until the policy repository is public.
A repository that you may not read is not named, and nothing is said about it but its part in repos_hidden: whoever manages the required workflows of an organization need not be allowed to read every repository of it.
The warnings are:
- a secret that is named and exists neither in the organization nor globally,
- a mapped secret that does not allow the
pull_requestevent, with the events it allows: every pull request pipeline would fail the required workflow, - an empty
repos.include, or a scope that holds no activated repository, - a template that is not available to the organization any more,
- a mapping to an external secret or a pattern that was stored before it was refused,
- the number of findings for which the linter refuses the expanded workflow, which
crow linton the template file shows to whoever may read the template.
What the linter only warns of, such as a when without an event filter, is not part of the validation.
It is not shown on the pipelines of the repositories in scope either, whose users cannot change the template.
Run crow lint on the template file to see it.
An access token may list the global secrets only if it has the scope user:read and is not limited to an organization or a repository.
With any other token every mapped secret that is no secret of the organization gets a warning, which says that the global secrets were not looked at.
GET on one assignment returns the same validation, computed from the database without a call to the forge.
It is the way to see later that a repository in scope became more visible than the policy repository.
What a repository sees
Section titled “What a repository sees”Every pipeline of a repository in scope carries the workflow required/<name>, if the when of the template matches the pipeline.
It is a workflow like the others of the pipeline, with its steps and logs, and the pipeline page marks it with Required.
The settings of a repository list the required workflows that cover it, see Web UI.
The list is read-only: the admins of the organization manage it.
Over the API it is GET /api/v1/repos/{repo_id}/required-workflows, for repository admins.
What cannot switch it off
Section titled “What cannot switch it off”| Attempt | What happens |
|---|---|
[skip ci] or [ci skip] in the commit message, or in what Crow reads as the message of a pull request |
The workflows of the repository are skipped, and the pipeline is created with the required workflows alone |
| No workflow files in the repository | The pipeline is created with the required workflows alone |
| A workflow file that cannot be built | The required workflows run, and the pipeline ends with the status error, see below |
A manual run that selects other workflows, or a task variable |
The selection applies to the workflows of the repository only, and the dialog of a manual run offers no required workflow |
| Variables of a manual run, parameters of a restart, a matrix | None of them reaches a required workflow, neither in its text nor in the environment of its steps |
A when in a file of the repository |
A required workflow has no workflow file in the repository, and the when of the template alone decides |
The message of a pull request pipeline is the title of the pull request on Forgejo, Gitea and GitHub, and the message of its last commit on GitLab.
[skip ci] in a commit of a pull request on the first three therefore skips nothing.
Required workflows and the workflows of the repository are built apart, and neither side keeps the other from running.
- The side of the repository cannot be built.
Without required workflows, such a pipeline has an error and no workflows.
Next to required workflows it gets one entry named
repositoryin place of the workflows of the repository. The entry is in the stateerror, has no steps and never runs. The pipeline ends with the statuserror, whether the required workflows passed or failed, and the errors of the pipeline say what is wrong. The entry reports no commit status of its own and cannot be rerun. The same entry stands for workflow files that could not be fetched from the forge. - A required workflow cannot be built.
Its entry
required/<name>is recorded as failed, without steps, and reports a failure under its status context. The other required workflows and the workflows of the repository run. A pipeline in which nothing but a required workflow failed ends with the statusfailure.
A pipeline is not created if nothing would be part of it: no workflow of the repository matches, and the template of every required workflow in scope skips the event.
Names and status contexts that collide
Section titled “Names and status contexts that collide”No workflow name is reserved for all repositories. In a repository that a required workflow covers, a workflow of the repository is an error if:
- its name is
required/<name>, after the matrix and the variables are substituted, - its status context, as the instance renders it with
CROW_STATUS_CONTEXT_FORMAT, is a status context of the required workflow, for whatever event.
The error is on the workflow of the repository and names the required workflow. It makes the side of the repository fail, and the required workflows run.
The comparison is made again whenever a status is published. A workflow of the repository that was built before the assignment took effect publishes nothing under the context of a required workflow. If its status is on the way to the forge while the assignment takes effect, Crow publishes the status of the required workflow after it.
What a required workflow may use
Section titled “What a required workflow may use”A required workflow is treated as a template of another repository, also when the policy repository is the repository of the pipeline.
| What a required workflow gets | |
|---|---|
| Values | The inputs of the assignment and the CI_* values of the pipeline |
| Environment of a step | The CI_* values, the global environment of the instance and what the template sets |
| Trusted settings | None: privileged, volumes, devices, network_mode, dns, dns_search, extra_hosts, tmpfs and backend_options are errors, whatever the trust settings of the repository are |
| Forge credentials | For the clone section only, never for its steps and services |
| Secrets | Those of the organization and global ones, see Secrets |
| Registry credentials | Those of the organization and global ones, and for one address the one of the organization |
| Build cache | A cache of its own, per assignment |
The cache of a required workflow is kept apart from the caches of the repository and from those of other required workflows. No workflow of a repository can save an archive that a required workflow restores. The cache is stored with the repository the workflow runs in and counts against its limits.
The template of a required workflow does not count against the limit CROW_MAX_TEMPLATES, so the files of a repository cannot use the limit up.
CROW_MAX_TEMPLATE_SIZE applies.
Depending on a required workflow
Section titled “Depending on a required workflow”A workflow of the repository may depend on a required workflow.
The file .crow/deploy.yaml of acme/shop:
- If the required workflow fails, also because it could not be built, the workflow is skipped, unless it sets
runs_on: [success, failure]. - If the required workflow is not part of the pipeline, because its template skips the event, the workflow is left out of the pipeline like every workflow whose dependency does not run.
A required workflow cannot depend on a workflow of the repository.
A template cannot set depends_on, so nothing can make a required workflow wait.
The config tab
Section titled “The config tab”The Config tab of a pipeline lists a required workflow with three entries:
- the workflow file the assignment stands for, marked Required workflow with its revision, which the API returns with the kind
required, - the template file, as it was read at the commit of the revision,
- the expanded workflow, named
required/<name>.expanded.yaml.
No repository contains the workflow file. The server writes it from the revision the pipeline recorded. For the assignment of the first example it is:
The file contains the inputs and the names of the secrets the assignment passes, so everybody who can read the pipelines of a repository in scope can read them.
All three entries are shown only while the repository may use the template. Once it may not, the entry keeps the name and the revision and says why, and shows no content.
Statuses
Section titled “Statuses”The status context
Section titled “The status context”A required workflow reports its result under a fixed status context:
<status-context> is the prefix of the instance, CROW_STATUS_CONTEXT, which is ci/crow by default.
CROW_STATUS_CONTEXT_FORMAT does not change the form.
| Event of the pipeline | Status context of secret-scan |
|---|---|
pull_request |
ci/crow/pull_request/required/secret-scan |
push |
ci/crow/push/required/secret-scan |
pull_request_edited |
ci/crow/pull_request_edited/required/secret-scan |
pull_request_closed |
ci/crow/pull_request_closed/required/secret-scan |
pull_request_merged |
ci/crow/pull_request_merged/required/secret-scan |
tag, release, deployment, cron, manual |
ci/crow/tag/required/secret-scan and so on |
Every event has a context of its own.
The contexts of ordinary workflows share the segment pr for the four pull request events, and the contexts of required workflows do not.
A pipeline for an edited, closed or merged pull request can therefore not write the context of the pull_request event.
The context to require in the branch protection of the forge is the one of the pull_request event.
The API returns it as status_context, and the form for the other events as status_context_pattern.
Only this context follows the open pull requests of a commit: the reset after a new revision and the rule for several pull requests on one commit concern no other.
Under the context of another event a commit keeps the status it has until a pipeline of that event with the current revision reports.
The context changes if an admin of the instance changes CROW_STATUS_CONTEXT.
The branch protection of every repository then has to be changed with it.
What a context shows
Section titled “What a context shows”Crow does not publish the result of whichever workflow reported last. It decides what a context shows on a commit from what it has stored, and publishes that. It does so whenever something changes that the answer depends on: a required workflow changes its state, a pipeline is created or deleted, the forge reports that a pull request was opened, got commits, was closed, merged or opened again, or a save is followed by a reset.
Only a pipeline that carries the current revision of the assignment counts.
A pipeline with an earlier revision, or without the assignment, says nothing.
It can neither turn the context green nor replace the result of a pipeline with the current revision, also when it is the later pipeline.
Its required workflow still runs, and the pipeline shows the result.
The pipeline page marks the workflow with Outdated, and the API returns it with "required_outdated": true.
| Context | What decides it on a commit |
|---|---|
pull_request |
The open pull requests whose head the commit is, see What a pull request shows |
pull_request_edited, pull_request_closed, pull_request_merged |
The pull requests that have a pipeline of that event for the commit with the current revision, by the same rule: a pull request without such a pipeline is not waited for |
Every other event, and pull_request on a commit that is the head of no open pull request |
The latest pipeline of that event for the commit with the current revision |
Where nothing decides, Crow publishes nothing, and the commit keeps the status it has on the forge. That is the case:
- while the assignment does not exist, is disabled, or does not cover the repository,
- for an event other than
pull_requestwhile no pipeline of that event carries the current revision for the commit, - for a pipeline that the
whenof the template does not match, which has no required workflow, see Match every pull request, with one exception for a pull request that an earlier revision reported for.
Nothing is published either for the entry repository of a side of the repository that could not be built, and for a workflow in history that was imported from another instance.
What a restart publishes follows from that:
| Operation | Under the context |
|---|---|
| Restart, and the recorded revision is the current one | Pending when the pipeline is created, then its result |
| Restart, and the recorded revision is superseded | Nothing of its own: the context keeps what the pipelines with the current revision say |
| Fresh restart | Pending when the pipeline is created, then its result |
Any restart whose pipeline has no required workflow, because the when of the template does not match |
Required workflow does not run for this pull request, if the commit has had a status of the required workflow, and nothing otherwise |
What each state reports
Section titled “What each state reports”Where the required workflow of a pipeline decides, its state is reported like this:
| State of the required workflow | Reported | Description on the forge |
|---|---|---|
| Pending | pending | Pipeline is pending |
| Waits for the approval of the pipeline | pending | Pipeline is pending approval |
| Running | running | Pipeline is running |
| Success | success | Pipeline was successful |
| Failure or error | failure | Pipeline failed |
| Could not be built or resolved | failure | Required workflow could not be built |
| Canceled while it ran | failure | Pipeline was canceled |
| Canceled before it started, or while it waited for approval | failure | Required workflow did not run |
| Pipeline declined | failure | Pipeline was rejected |
Everything that is not a success, not running and not waiting is reported as a failure. A canceled required workflow never reads as passed or as still to come.
After a rerun, the status is the one of the last attempt.
What a pull request shows
Section titled “What a pull request shows”Under the context of the pull_request event, the head commit of an open pull request shows:
| The pull request | Reported | Description on the forge |
|---|---|---|
Has a pull_request pipeline for the commit that carries the current revision, of which the latest decides |
The state of the required workflow in it | As in the table above |
Has pull_request pipelines for the commit, and none of them carries the current revision |
pending, or no status if the required workflow never applied to it | Required workflow was updated: a fresh restart of the pipeline runs it |
Has no pull_request pipeline for the commit |
pending | Required workflow has not run for pull request 12 with this commit |
Is not matched by the when of the template, and the commit has had a status of the required workflow |
pending | Required workflow does not run for this pull request |
Is not matched by the when of the template, and the commit never had a status of the required workflow |
No status |
- The status of the second row links to the latest pipeline of the pull request, which is the one to start again with a fresh restart. A plain restart runs the revision the pipeline recorded and changes nothing.
- The required workflow never applied to a pull request if every pipeline it has for the commit was built under the assignment without the required workflow, and no pipeline of any pull request for the commit ever had it. Such a pull request is not asked to restart: there is no status that a new revision would have to take back. One with a pipeline from before the assignment covered the repository is asked.
- A pull request without a pipeline for its head commit gets the status of the third row from a reset, once another pull request shares the commit, or when it is opened on a commit that already has a status of the required workflow. In the last case Crow publishes it as soon as the forge reports the pull request, before a pipeline exists, so that the success of an earlier pull request does not stand for the new one. Until then the commit has no status under the context. The status links to the repository in Crow, because there is no pipeline to link to.
- The status of the fourth row takes the place of a success that must not stay: one of an earlier revision, one of a pull request that is closed by now, or one from before the pull request was given another target branch. A pipeline that is created without the required workflow publishes it at once.
- A description names a pull request by its number on the forge, or by its ref while Crow knows no number for it.
A forge that requires the context lets none of these through but the success.
One decision reads the latest 500 pipelines of the event for a commit.
A commit with that many pipelines shows a failure that is among them, and otherwise a result only if every open pull request with the commit has a pipeline with the current revision among them.
If not, the context is pending with Required workflow has no result in the latest 500 pipelines of this commit: run the pipeline again.
For the events that the latest pipeline decides, the same holds with the latest 20 pipelines that recorded the current revision.
Several pull requests on one head commit
Section titled “Several pull requests on one head commit”A commit status belongs to a commit and not to a pull request. Open pull requests with the same head commit share the context, and one of them could turn it green for the others. Crow therefore decides the context over all of them, and the first row of this table that applies is what the commit shows:
| The pull requests with the commit | Reported | Description on the forge |
|---|---|---|
| The required workflow failed for one of them | failure | Required workflow failed in pipeline #31 of a pull request with this commit |
| One of them has not run the current revision | pending | Required workflow was updated: pipeline #31 of pull request 12 with this commit has to run it, or Required workflow has not run for pull request 12 with this commit |
| The required workflow of one of them runs | running | Required workflow is running for pull request 12 with this commit |
| The required workflow of one of them waits | pending | Required workflow is pending for pull request 12 with this commit, or Required workflow waits for approval for pull request 12 with this commit |
| At least one of them passed | success | Pipeline was successful |
The when of the template matches none of them |
pending, or no status | Required workflow does not run for the pull requests with this commit, if an earlier revision reported for one of them |
- A pull request that the
whenof the template does not match withholds nothing: the others decide. - A pull request no longer counts for a commit once the forge reports it closed or merged, or once it got other commits. Crow then publishes the context of the commit again for the pull requests that are left, which is how a withheld success arrives.
- A pull request that is opened again counts again. Forgejo, Gitea, GitHub and GitLab report that.
- Deleting the pipelines of a pull request does not take it out of the rule. It then counts as one that has not run. Crow decides the contexts of a deleted pipeline again within about a minute, see When the forge does not take a status. Until then the forge shows what it had.
A new revision and open pull requests
Section titled “A new revision and open pull requests”A pull request that passed the previous revision must not stay green.
When a revision becomes current, Crow publishes the context of the pull_request event again on the head commit of every open pull request in scope.
A pull request that has not run the new revision then shows pending, as above, and one that has run it keeps its result.
A pull request the required workflow never applied to gets no status from it.
This reset does nothing else:
- It starts no pipeline. A pull request runs the new revision with its next commit, or when its pipeline is started again with a fresh restart.
- It leaves the contexts of the other events as they are.
- It does not reach commits that are the head of no open pull request, such as commits that were merged under the previous revision.
The same reset follows when an assignment is enabled and when its scope grows, for the repositories that come under it. It also follows for one repository when the repository is activated or repaired, and when a rename or a move puts it into the scope of an assignment.
- The reset goes over the pull requests Crow knows as open, and not over pipelines. A pull request whose pipelines were all deleted is reset as well.
- The reset runs after the save has been answered, for 30 minutes at most, and calls the forge for every commit.
- A repository that is not active is not reset. It is reset when it is activated again.
The outdated pipelines of an assignment are the pipelines to start again: of every open pull request in scope that has not run the current revision for its head commit, the latest pull_request pipeline it has for that commit.
A pull request without a pipeline for its head commit has nothing to start again, and needs a new commit.
The restart is a fresh restart of each pipeline, run as the user who activated its repository.
One request restarts at most 100 pipelines, 20 by default, and answers how many it left as remaining.
A pipeline that cannot be restarted, such as one that waits for approval, is named with the reason and stays outdated.
The pipelines of a repository that you may not read are neither listed nor restarted, and are counted as hidden.
The page of a required workflow in the web UI lists the same pipelines and restarts them.
When the forge does not take a status
Section titled “When the forge does not take a status”A status that did not reach the forge is sent again. Crow stores the context of a commit as work to do when the forge refuses a status or does not answer, when Crow cannot read its database while it decides, when the status keeps changing while it is published, and when the server is stopped while it publishes. It stores the contexts of a pipeline with required workflows that is deleted in the same way, because the answer for its commit can change with it. A task of the server then decides the status anew and sends it:
| Try | When |
|---|---|
| First | 1 minute after the context was stored, and within half a minute for a deleted pipeline |
| Each further one | Twice as long after the try before it: after 2, 4, 8 minutes and so on, and 6 hours at most |
| None any more | 3 days after the context was first stored: Crow gives up and writes an error to the server log |
Until a try succeeds, the forge shows the status it had, which can be the success of an earlier revision.
The work is stored in the database, so it outlives a restart of the server, and with several servers on one database one of them does it.
The commits a reset cannot send a status for, because the forge fails for their repository, are stored the same way.
A reset that is cut off, because its 30 minutes are over or the server is stopped, stores nothing for the commits it had not come to: repeat it with outdated/reset.
The pull requests Crow knows
Section titled “The pull requests Crow knows”Crow learns from the hooks of the forge which pull requests are open and which commit is the head of each. It stores that apart from the pipelines, so a pull request whose pipelines were deleted is still known.
A pull request that no hook has reported is stored when a pipeline of it is created or restarted with a required workflow.
A pull_request pipeline stores it as open on the commit of that pipeline, under the ref of the pipeline, until a hook of the forge says more about it.
A pull request with neither a hook nor such a pipeline is unknown to Crow, see What Crow cannot do.
Approval, rerun and restart
Section titled “Approval, rerun and restart”A pipeline records its required workflows and their revisions when it is created. Later operations differ in whether they use that record or the assignments as they are now.
| Operation | Required workflows it runs |
|---|---|
| Approving a blocked pipeline, or a workflow at an approval gate | The recorded ones, at the recorded revisions |
| Rerunning a workflow | The recorded revision |
| Restarting a pipeline | The recorded ones, in a new pipeline |
| Fresh restart | The assignments in scope now, at their current revisions |
| Starting a deployment from a pipeline of another event | The assignments in scope now, at their current revisions |
The operations in the first three rows read the template that was stored with the pipeline. Only a restart asks the forge, and only for a template that could not be fetched when the pipeline was created: it reads that one at the recorded commit. A workflow they run at a revision that is not current any more decides no status.
- A step of a required workflow cannot be rerun alone. A step rerun builds an attempt that holds this step and the steps after it, so a check that failed could be left out of the attempt that is reported. Rerun the workflow as a whole.
- A restart replays what was recorded, also an assignment that was disabled or no longer covers the repository.
The fresh restart is the way to get the required workflows as they are assigned now.
On the command line it is
crow pipeline start --fresh <repo> <pipeline>. - An assignment that was deleted is left out of an approval and of a restart.
The pipeline gets the warning
This pipeline carried the required workflow …, which was deleted since.The rerun of such a workflow is refused. - A pipeline that waits for approval cannot be restarted. Approve or decline it first.
- A pipeline that skipped the workflows of the repository for
[skip ci]keeps skipping them when it is restarted.
Pull requests from forks
Section titled “Pull requests from forks”A pull request from a fork that waits for approval waits as a whole, with its required workflows.
Their status is pending, with the description Pipeline is pending approval, so a forge that requires the context does not let the pull request through.
Declining the pipeline reports a failure. Approving it runs the required workflows at the revisions that were recorded when the pipeline was created. If a revision was superseded in the meantime, the workflow runs and decides no status: the pull request keeps the pending status of the reset, and a fresh restart of the pipeline runs the current revision.
A fork cannot change a required workflow: nothing of it is read from the commit of the pull request.
A template can set an approval gate of its own. Approving such a gate is refused, and the workflow is recorded as failed, if the repository no longer belongs to the organization of the assignment, if the assignment was deleted, or if the pipeline has no record of it.
Writing a template for a required workflow
Section titled “Writing a template for a required workflow”A template is assigned as it is. These rules make it hold as a check.
Match every pull request
Section titled “Match every pull request”A pull request that the when of the template does not match gets no status under the context.
A forge that requires the context then waits for it, and the pull request cannot be merged.
Let the template match every pull request, and decide inside the steps what there is to do.
Do not narrow when by branch or by path:
Bring your own tooling
Section titled “Bring your own tooling”A required workflow that runs a script of the repository, such as make lint, runs what the pull request changed.
The repository can then make the check pass.
Put the tool and its rules into the image of the step, or fetch them from a place the repository cannot write to.
Pin the images of the steps, because the commit of the template is pinned and a moving image tag is not.
Do not depend on the target branch
Section titled “Do not depend on the target branch”Do not make the result depend on the target branch of the pull request or on the files it changed. Two pull requests can share a head commit and differ in both, and they write the same status context. Crow withholds a success while another pull request with that commit fails, and a check that gives the same answer for the same commit does not need that rule.
Read values of the pipeline from the environment
Section titled “Read values of the pipeline from the environment”${CI_*} is not available in commands and entrypoint of a template.
Read $CI_COMMIT_BRANCH and the other values from the environment of the step, so a branch name or a pull request title never becomes part of the script.
An input that is written into a command becomes part of the script as well: pass it through environment, as the first example does with FAIL_ON.
What changes for the author of a template
Section titled “What changes for the author of a template”- The template runs without the trust of the repository, see What a required workflow may use.
A template that needs
privilegedorvolumescannot be assigned. - The template cannot set
depends_on,runs_onormatrix, as no template can, and an assignment cannot set them either. A required workflow is one workflow that waits for nothing. - A new commit of the template does not reach the repositories until an admin updates the assignment.
- Sharing the policy repository lets the users of the repositories in scope read the template on their pipeline pages.
What Crow cannot do
Section titled “What Crow cannot do”Crow guarantees that every pipeline created for an event in scope contains the current required workflow, unaltered, and that nothing Crow builds from the files of a repository reports under its status context. The following is outside of that guarantee.
- Crow does not block a merge.
The branch protection of the forge does, and it has to require the status context of the
pull_requestevent. - A forge accepts a commit status from everybody who holds a credential with write access to the repository. A maintainer can post a status under any context from a laptop, or from a pipeline step that holds such a credential. A repository whose Security trust setting is on hands the forge token of its owner to every step of its own workflows. Crow cannot prevent this. Do not switch that setting on for a repository where required workflows matter, and restrict on the forge who may set a required context where the forge can do that.
- A reset does not reach back, and a commit keeps a success it has. A new revision resets the context on the head commits of open pull requests. A commit that passed an earlier revision and is the head of no open pull request at that moment keeps its success: the commits of pull requests that are closed or merged, and the earlier commits of a pull request that got more since. A new pull request with such a commit as its head starts with that success. Crow replaces it with a pending status as soon as the forge reports the pull request, which takes a moment, and a merge that is asked for within that moment goes through. Content that passed an earlier revision can therefore still be merged after the required workflow was tightened. The same holds without a new revision for a check whose result depends on the pull request and not only on the commit, such as its title or its target branch.
- A repository admin can stop pipelines. Deactivating the repository in Crow or disabling pull request pipelines produces no new status. A forge that requires the context treats a commit without a status as not passed. With pull request pipelines disabled, Crow still hears of a new pull request and takes back a success its commit has. A deactivated repository hears of nothing, so a commit that already has a success keeps it there, see the limit above.
- A pattern does not hold against a rename.
A repository admin who renames a repository can move it out of an assignment that includes it by a name pattern.
Include
*and exclude by ID where that matters. - A plain restart replays the recorded revision. The guarantee is about pipelines created for a new event, a fresh restart, and a deployment started from a pipeline of another event.
- A script of the repository can defeat a check that runs it, see Bring your own tooling.
- Secrets of the organization are not private to the required workflow, see Secrets.
- A workflow that already waits keeps its secrets. The secrets of a workflow are read when the pipeline is built. A workflow that waits in the queue keeps them if the repository moves to another organization meanwhile. This holds for the organization secrets of ordinary workflows too.
- Where nothing decides a context, the status on the forge stays.
Under the context of an event other than
pull_request, a commit keeps what it has until a pipeline of that event with the current revision reports. That includes a status that a workflow of the repository sent under a context of the form…/required/<name>before an assignment of that name existed. It also includesPipeline is running: a commit whose pipeline was superseded by a new revision while it ran keeps that status under the context of an event other thanpull_request, and so does a commit whose assignment was disabled while its required workflow ran, until the assignment is enabled again. Require the context of thepull_requestevent on the forge, and not the one of another event. - A pull request that no hook reported is unknown until something reports it. Crow does not know a pull request that was opened before the server was upgraded to this release, or while its repository was not active in Crow, and that got no hook from the forge since. A reset does not reach it, and the outdated pipelines do not list it. It has no status under the context, so a forge that requires the context does not merge it. A new commit, or a fresh restart of one of its pipelines, makes it known.
- A pull request that a restart made known counts as open until a hook says otherwise, also if it was closed long before.
- A reset that is cut off is not repeated by itself, whether a server stop ends it or its 30 minutes.
The next save that asks for a reset repeats it, and so does
POST …/outdated/reset. - A pull request whose pipelines were all deleted has nothing to restart. After a reset it shows pending until it gets a new commit.
- A pull request without a pipeline holds back the others on its commit.
A pull request gets no pipeline when the
whenof the template does not match it and the repository has no workflow that runs for it. Crow cannot tell such a pull request from one that has not run, so the success of another pull request with the same head commit is withheld until the first is closed or one of them gets a new commit. A template that matches every pull request does not have this. - Anyone who can open a pull request can hold back a commit.
A pull request from a fork with the same head commit as another pull request counts like every other one.
While its pipeline waits for approval the commit shows
Required workflow waits for approval for pull request …. A maintainer ends that by closing the pull request, or by approving its pipeline, which then counts with its result. A declined pipeline counts as failed. - A repository that is not active keeps the statuses it has, until it is activated again.
- Crow gives up a status the forge did not take for three days. The forge then keeps showing what it had for that commit, and the server log has an error, see When the forge does not take a status.
- A forge addon builds its own status context. Crow cannot enforce the fixed form there.
- On GitHub, a required workflow in a deployment pipeline gets a commit status as well, next to the deployment status.
Errors and refusals
Section titled “Errors and refusals”When an assignment is saved
Section titled “When an assignment is saved”The status of a refused save says what kind of refusal it is:
| Status | Refused because |
|---|---|
| 400 | The checks of the assignment refuse it, or the body is not JSON |
| 404 | The PATCH names a required workflow the organization does not have |
| 409 | The name is taken, the base revision is not the current one, or a change without a base revision met another change each of the three times it was checked |
| 422 | The request is not one of this API: the body has a member the API does not have, a POST has no name or no template, or a query parameter has a value it cannot take |
A conflict is answered before any reason of the status 400.
For the status 400, detail names every reason of the group, one per line, and errors lists them one by one.
For the status 422, detail is validation failed, and errors names every unknown member with the message unexpected property and its place as location, such as body.bogus, body.template.path or body.repos.includes.
The CLI prints that as server returned 422: validation failed: body.bogus: unexpected property.
| Message | Cause and fix |
|---|---|
name: the name of a required workflow must match … |
See Name |
name: the name of a required workflow cannot be changed … |
Create a new one and delete this one |
revision: the revision a change was made from is a number from 1 … |
Send the revision the change was made from, or leave revision out |
this org already has a required workflow named … (409) |
Choose another name, or change the existing one with PATCH |
the required workflow … is at revision 3 and the change was made from revision 2 … (409) |
Somebody else changed it: read it again and repeat the change |
the required workflow … kept changing while this change was checked; try again (409) |
Other changes were saved while this one was checked: repeat it |
repos.include: … |
The pattern is not valid, see Repositories |
repos.exclude_ids: … is not the ID of a repository of this org that you can read |
Use the ID of a repository of this organization in Crow that you can read. A repository of another organization, one that does not exist and one you cannot read get the same message |
template … not found or not shared with this repository |
The policy repository is unknown to Crow, not activated, on another forge, or does not share its templates with the organization: check template.repo and its template_access |
no tag … in …, no branch … in …, commit … is not on a branch or tag of … |
The ref does not resolve, see the errors of templates |
could not fetch template … from the forge; try again |
The forge did not answer |
the input name … must match …, inputs: the input … is neither a string, a number, a boolean nor a list of strings, inputs: the input … is null … |
The input cannot be passed to any template: correct its name or its value, or leave it out |
inputs.<name>: … |
The input is unknown, missing, of the wrong type or outside its options. Every such input is named, in the order of the names |
inputs.<name>: the value of a boolean input cannot be empty; leave the input out to use the default of the template |
An empty value is no boolean and no number: leave the input out |
the input … holds a NUL character, which cannot be passed on to a template |
Remove the character |
inputs: more inputs are refused than the 100 that are named here, secrets: more secret aliases are refused than the 100 that are named here |
An answer names at most 100 inputs and 100 aliases: correct them and save again |
secrets.<alias>: the template needs the secret …; map it under secrets of the required workflow to a secret of the organization or to a global secret, with from_secret |
Map the alias in secrets of the assignment |
secrets.<alias>: the template declares no secret … |
Remove the alias from secrets |
secrets.<alias>: the alias is mapped to an external secret … |
Map the alias to the name of a secret of the organization or of a global secret |
secrets.<alias>: unknown key … below a secret alias; it holds from_secret and nothing else |
Remove the key: an alias holds from_secret alone |
secrets.<alias>: a secret alias is mapped with from_secret … |
Write {"from_secret": "<name of a secret>"}, not the name or the value directly |
template …: workflow.steps: … is not allowed in a required workflow … |
The template uses a trusted setting: it cannot be assigned |
template …: workflow.matrix: `matrix` is reserved in a template …, template …: workflow.depends_on: `depends_on` belongs to the consumer and cannot be set by a template |
The template sets a key no template can set: it cannot be assigned |
The lookup of a template words its message for a workflow file, so template … not found or not shared with this repository speaks of a repository also where an organization is meant.
In a pipeline
Section titled “In a pipeline”A required workflow that cannot be built is a failed workflow required/<name> without steps.
The reason is among the errors of the pipeline.
| Message | Cause and fix |
|---|---|
template … not found or not shared with this repository |
The policy repository no longer shares its templates with this repository, was deactivated or removed, or another repository has the name it had when the assignment was saved. A policy repository that was only renamed keeps working: Crow finds it by its identity and not by its name |
… 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 policy repository at least as visible, or exclude the repository |
Secret "…" is not allowed to be used with pipeline event "pull_request" |
Add the event to the secret of the organization |
secret "…" not found |
Create the secret in the organization or globally. The message prints the name in lower case, however the assignment writes it |
the required workflow … maps the secret alias … to an external secret … |
The mapping was stored before external secrets were refused: map the alias to the name of a secret |
the required workflow … belongs to another org than this repository |
The repository moved to another organization after the pipeline was created |
the forge of this repository cannot tell whether a commit belongs to a repository … |
The forge does not support required workflows, see Template and ref |
could not fetch template … from the forge; restart the pipeline to try again |
The forge did not answer: restart the pipeline |
the workflow is named required/…, which is the name of the required workflow … of this repository; give it another name |
A workflow of the repository collides with a required workflow: rename it |
the status of the workflow … would be published as …, which is the status of the required workflow … |
The same, for the status context |
When a workflow is run again
Section titled “When a workflow is run again”| Message | Cause and fix |
|---|---|
Cannot rerun a step of the required workflow …: a required workflow can only be run again as a whole. |
Rerun the workflow |
Cannot rerun the workflow: the required workflow … was deleted … |
The assignment is gone: nothing is left to run |
Cannot rerun the workflow: the pipeline has no record of the required workflow … |
The pipeline was imported from another instance: use a fresh restart |
Cannot rerun this entry: it stands for the workflows of the repository, which could not be built … |
Fix the workflow files and push again |
Cannot approve the workflow: the required workflow … belongs to another org than this repository … |
The repository left the organization of the assignment, and the workflow was recorded as failed |
Cannot approve the workflow: the required workflow … was deleted … |
The assignment is gone, and the workflow was recorded as failed |
cannot restart a pipeline with status blocked |
Approve or decline the pipeline first |
Reference
Section titled “Reference”The endpoints of an organization need an admin of the organization, and an access token needs the scope repo:admin.
Only an admin of the instance can limit a token to an organization, and everybody can limit one to their own namespace.
An admin of an organization on the forge therefore uses a token without a limit, which reaches everything that user may administer.
All paths are below /api/v1.
| Method and path | Purpose |
|---|---|
GET /orgs/{org_id}/required-workflows |
List the required workflows of the organization, with page and perPage, which is 50 at most |
POST /orgs/{org_id}/required-workflows |
Create one, or check one without saving it with dry_run=true |
GET /orgs/{org_id}/required-workflows/{name} |
Read one, with its validation |
PATCH /orgs/{org_id}/required-workflows/{name} |
Change one, or check a change without saving it with dry_run=true |
DELETE /orgs/{org_id}/required-workflows/{name} |
Delete one with its revisions, answered with the status 204 |
GET /orgs/{org_id}/required-workflows/{name}/revisions |
List its revisions, newest first, with page and perPage |
GET /orgs/{org_id}/required-workflows/{name}/outdated |
List its outdated pipelines |
POST /orgs/{org_id}/required-workflows/{name}/outdated/restart |
Fresh-restart outdated pipelines, at most limit (1 to 100, default 20) |
POST /orgs/{org_id}/required-workflows/{name}/outdated/reset |
Repeat the reset for every open pull request in scope, answered with the status 202 |
GET /repos/{repo_id}/required-workflows |
List the required workflows that cover a repository, for repository admins |
GET /repos/{repo_id}/workflows/names, which the dialog of a manual run and the workflow filter of the pipeline list read, returns the workflows of the repository only: no required workflow, and no entry repository.
The body of a POST:
| Member | Required | Meaning |
|---|---|---|
name |
Yes | Name of the required workflow |
template |
Yes | repo, name and ref, see Template and ref |
inputs |
No | Object of input names and values |
secrets |
No | Object of secret aliases, each as {"from_secret": "<name>"} |
repos |
No | include and exclude_ids, see Repositories. Without it the assignment covers no repository |
enabled |
No | true unless it is set to false |
The body of a PATCH takes the same members, all optional, and revision as the base revision.
What it leaves out stays as it is.
name can be sent only with the name the assignment has.
A member the body does not have is refused with the status 422, also below template and repos, and so is revision in a POST.
A member below a secret alias other than from_secret is refused with the status 400.
The name of a member is read without regard to case.
The answer to a POST, a PATCH and a GET of one assignment is the assignment, as in the first example.
validation is not part of the list.
new_revision and dry_run are part of the answer to a save.
An entry of the list of revisions holds revision, current, template, inputs, secrets, author_id, author and created.
The answer of outdated has the current revision, pipelines and hidden, the number of outdated pipelines of repositories you may not read.
An entry holds repo_id, repo, pull_request (the ref of the pull request), pull_request_url, title, event, which is always pull_request, pipeline (its number), commit and revision, which is the revision the pipeline carries, or 0.
The answer of outdated/restart adds new_pipeline or error to every entry, and restarted and remaining to the whole.
An entry of the list of a repository holds name, revision, template, status_context, status_context_pattern and, if pipelines of the repository would fail the required workflow, error.
It holds neither the inputs nor the secret mapping.
In the answers about a pipeline, a workflow carries required_workflow_id and required_revision if it is a required workflow, build_failed if it could not be built, and required_outdated if it decides no status.
The configuration of a pipeline has entries of the kind required, with required.name and required.revision.
crow org required-workflow, or crow org rw, manages the required workflows of an organization.
The organization is the first argument or --organization, as its ID or its name.
| Command | Purpose |
|---|---|
ls |
List the required workflows |
show --name <name> |
Show one, with both status contexts and its validation |
add --name <name> |
Create one |
update --name <name> |
Change one |
revisions --name <name> |
List its revisions, newest first |
rm --name <name> |
Delete one with its revisions |
Flags of add and update:
| Flag | Meaning |
|---|---|
--template-repo, --template-name, --ref |
The template and its ref |
--input <name>=<value> |
An input, repeated for every input |
--input-list <name>=<value> |
One element of a list input, repeated for every element |
--secret <alias>=<NAME> |
Map a secret alias to the name of a secret |
--include <pattern> |
A pattern for the repositories to include, with '*' quoted for the shell, repeated for every pattern |
--exclude-id <id> |
The ID of a repository to leave out, repeated for every repository |
--file <path>, -f |
A JSON or YAML file in the form of the request body, or - for the standard input, with the flags applied to it |
--dry-run |
Check and print what saving would return, without saving |
--include and --exclude-id each replace the whole list with what they name.
A file with revision is refused by add, which has no revision to change from.
Only for add:
| Flag | Meaning |
|---|---|
--disabled |
Save the required workflow without enabling it |
Only for update:
| Flag | Meaning |
|---|---|
--latest |
Move to the latest commit of the ref the commit came from, which cannot be combined with --ref |
--unset-input <name> |
Remove an input, so the default of the template applies |
--unset-secret <alias> |
Remove a secret alias from the mapping |
--unset-include |
Remove every include pattern, so the required workflow covers no repository. It cannot be combined with --include |
--unset-exclude-id |
Remove every excluded repository. It cannot be combined with --exclude-id |
--enable, --disable |
Switch the required workflow on or off |
--revision <n> |
The base revision of the change |
ls, show, add, update and revisions take --output with table, json, yaml or go-template=<template>.
ls and revisions print a list.
show, add and update print one object, so a template reads its fields without range, as in --output 'go-template={{.Name}} {{.Revision}}'.
There is no command for the outdated pipelines.
Use the API or the web UI.
To run the current revision in one pipeline, start it again with crow pipeline start --fresh <repo> <pipeline>.
Web UI
Section titled “Web UI”The settings of an organization have the tab Required workflows. The owner of a personal namespace reaches it from the user settings, where Personal namespace has the button Manage required workflows.
The tab lists the required workflows of the organization, each with Enabled or Disabled, its revision, its template with the commit, and the repositories it covers. Add required workflow opens the form of a new one. A name in the list opens the page of that required workflow, which is the same form with what was saved.
| Section | What it holds |
|---|---|
| Template | The name, the Template repository, the Template name and the Ref, and once it is saved the Pinned commit |
| Inputs | A row for every input: its name, its type (Text, Number, Yes or no or List of texts) and its value |
| Secrets | A row for every secret alias and the name of the secret it reads, with the secrets of the organization to choose from |
| Repositories | The Include patterns, the Exclude list with the repositories of the organization to choose from, and the switch Enabled |
| Status check | The Status context for pull requests, to copy into the branch protection of the forge, and the form of the contexts of other events |
| Outdated pull requests | The outdated pipelines of the required workflow |
| Revision history | Every revision with its template, who saved it and when, and the mark In force on the current one |
The last three sections are there once the required workflow is saved.
- Check sends the form as a dry run. The result shows the reasons of a refusal, or how many activated repositories in scope you can read and how many are hidden from you, the warnings, and every repository whose pipelines would fail the required workflow, with the reason.
- Create required workflow and Save required workflow run the same check first. A check without a warning and without a failing repository is followed by the save at once. Otherwise nothing is saved, the page shows what the check found, and a second click saves what was checked.
- Update to the latest of the ref resolves the ref again. If it points at another commit, a dialog shows both commits and what the check of the new one found, and saves on confirmation. The button is not there for a required workflow that was saved with a commit SHA, and it waits while the form has changes that are not saved.
- If somebody else changed the required workflow in between, nothing is saved, and Load the current state reads it again.
- Delete required workflow asks for a confirmation.
Outdated pull requests has a row for every outdated pipeline: the repository, the pull request with a link to the forge, a link to the pipeline, the commit, and the revision the pipeline ran. Restart with the number of pipelines starts up to 20 of them again with a fresh restart, after a confirmation, and then shows the new pipeline of each or the reason it was not restarted. Pipelines of repositories that are hidden from you are counted, not listed and not restarted. The page has no control that repeats the reset: use the API.
The settings of a repository have the tab Required workflows as well. It is a read-only list of the required workflows that cover the repository: the name, the revision, the template with the commit and the Status context for pull requests of each, and Pipelines of this repository fail this workflow with the reason where that is the case.
A pipeline marks its workflows:
| Mark | Meaning |
|---|---|
| Required | The workflow is a required workflow |
| Outdated | Its revision is not the current one, or its assignment no longer covers the repository, so it decides no status |
| Could not be built | The required workflow could not be built and counts as failed, with the errors below it |
| Repository workflows | The entry that stands for the workflows of the repository, none of which could be built |
A required workflow has a rerun for the whole workflow, and its steps have none. The Config tab is described in The config tab.
Limits
Section titled “Limits”| Limit | Value |
|---|---|
| Length of a name | 63 characters |
| Include patterns of an assignment | 100 |
| Length of a pattern | 100 bytes |
| Wildcards in a pattern | 8 |
| Excluded repositories of an assignment | 1000 |
| Pipelines one request restarts | 100, and 20 by default |
| Entries of one page of a list | 50 |
| Refused inputs and refused secret aliases one answer names | 100 each |
| Time of a reset | 30 minutes |
| Pipelines of a commit that one status decision reads | 500, and 20 for the events that the latest pipeline decides |
| Tries for a status the forge did not take | From 1 minute to 6 hours apart, for 3 days |
| Size of the template file | 512 KiB, set by CROW_MAX_TEMPLATE_SIZE |