Skip to content
Crow CI

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.

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.

The organization acme wants a secret scan in every pipeline of its repositories.

  1. Write the template

    The template is in a policy repository, here acme/ci-policies, in the file .crow-templates/secret-scan.yaml:

    # .crow-templates/secret-scan.yaml in acme/ci-policies
    spec:
      description: Scan a change for credentials.
      inputs:
        fail_on:
          description: Lowest severity that fails the scan.
          options: [low, medium, high]
          default: high
      secrets:
        scanner_token:
          description: Token for the rule server of the scanner.
    
    workflow:
      when:
        - event: [pull_request, push]
      steps:
        - name: scan
          image: registry.example.com/security/secret-scanner:3
          environment:
            FAIL_ON: $[[ inputs.fail_on ]]
            SCANNER_TOKEN:
              from_secret: scanner_token
          commands:
            - secret-scanner --fail-on "$FAIL_ON" .

    Commit it and tag a release, here v1.4.0. The when of the template decides for which events the required workflow runs.

  2. Share the policy repository

    The policy repository has to be activated in Crow, and it has to share its templates with the organization:

    crow repo update acme/ci-policies --template-access org

    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.

  3. 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 the pull_request event, which a secret created on the command line does not by default:

    crow org secret add acme --name SCANNER_TOKEN --value @scanner-token.txt --event pull_request --event push
  4. 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:

    crow repo show acme/web --output table=ID,Full_Name

    Here the ID is 4711. Put in the ID of your own repository, or leave --exclude-id out. On the command line:

    crow org required-workflow add acme \
      --name secret-scan \
      --template-repo acme/ci-policies --template-name secret-scan --ref v1.4.0 \
      --input fail_on=medium \
      --secret scanner_token=SCANNER_TOKEN \
      --include '*' --exclude-id 4711

    The server resolves v1.4.0 to 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:

    Added required workflow secret-scan at revision 1.
    NAME         REVISION  ENABLED  TEMPLATE                      COMMIT        REF     STATUS CONTEXT
    secret-scan  1         yes      acme/ci-policies/secret-scan  3f2a9c1d0e5b  v1.4.0  ci/crow/pull_request/required/secret-scan
    
    Commit:                3f2a9c1d0e5b4a7f8c6d2e1b0a9f8e7d6c5b4a3f
    Inputs:                fail_on=medium
    Secrets:               scanner_token=SCANNER_TOKEN
    Include:               *
    Exclude IDs:           4711
    Status context:        ci/crow/pull_request/required/secret-scan
    For other events:      ci/crow/<event>/required/secret-scan
    Repositories in scope: 2

    Over the API the same assignment is this request body:

    {
      "name": "secret-scan",
      "template": {
        "repo": "acme/ci-policies",
        "name": "secret-scan",
        "ref": "v1.4.0"
      },
      "inputs": {
        "fail_on": "medium"
      },
      "secrets": {
        "scanner_token": {
          "from_secret": "SCANNER_TOKEN"
        }
      },
      "repos": {
        "include": ["*"],
        "exclude_ids": [4711]
      }
    }
    # The ID of the organization
    curl -H "Authorization: Bearer $CROW_TOKEN" https://crow.example.com/api/v1/orgs/lookup/acme
    
    # Create the required workflow from the body in secret-scan.json
    curl -X POST \
      -H "Authorization: Bearer $CROW_TOKEN" \
      -H "Content-Type: application/json" \
      -d @secret-scan.json \
      https://crow.example.com/api/v1/orgs/<org-id>/required-workflows

    <org-id> is the id of the first answer. The same file works on the command line, as crow org required-workflow add acme --file secret-scan.json. The answer:

    {
      "id": 1,
      "org_id": 1,
      "name": "secret-scan",
      "revision": 1,
      "template": {
        "repo": "acme/ci-policies",
        "name": "secret-scan",
        "sha": "3f2a9c1d0e5b4a7f8c6d2e1b0a9f8e7d6c5b4a3f",
        "ref_hint": "v1.4.0"
      },
      "inputs": {
        "fail_on": "medium"
      },
      "secrets": {
        "scanner_token": {
          "from_secret": "SCANNER_TOKEN"
        }
      },
      "repos": {
        "include": ["*"],
        "exclude_ids": [4711]
      },
      "enabled": true,
      "status_context": "ci/crow/pull_request/required/secret-scan",
      "status_context_pattern": "ci/crow/<event>/required/secret-scan",
      "created": 1794873600,
      "updated": 1794873600,
      "validation": {
        "warnings": [],
        "repos_in_scope": 2,
        "repos_hidden": 0,
        "repos": []
      },
      "new_revision": true,
      "dry_run": false
    }

    The two repositories in scope are acme/shop and the policy repository itself: * includes every activated repository of the organization. The repository with the ID 4711, acme/web, is left out.

  5. Require the status on the forge

    From now on every pull request pipeline of a repository in scope runs the workflow required/secret-scan and reports its result under the status context ci/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.

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 names the template the way a workflow file does, with repo, name and ref:

  • repo is 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_access is org for a repository of this organization, or instance.
  • name is the name of the template, which is the file .crow-templates/<name>.yaml.
  • ref is a tag, a branch or a commit, in the forms a workflow file uses: a bare name or refs/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 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 maps every secret alias the template declares to the name of a secret, written as in a workflow file:

{
  "secrets": {
    "scanner_token": {
      "from_secret": "SCANNER_TOKEN"
    }
  }
}

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.

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 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.

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.

A new release of the template takes effect when an admin moves the assignment to it:

# Move to another tag
crow org required-workflow update acme --name secret-scan --ref v1.5.0

# Resolve the ref the commit came from again, for a branch that advanced or a tag that moved
crow org required-workflow update acme --name secret-scan --latest

--latest sends the stored ref_hint as the ref. Over the API that is a PATCH with template.ref:

{
  "revision": 1,
  "template": {
    "ref": "v1.5.0"
  }
}

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.

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.

The revisions of an assignment are listed newest first, each with the user who saved it and the time:

crow org required-workflow revisions acme --name secret-scan

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.

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 name other than the one the assignment has and a revision below 1,
  • the form of template.repo, template.name and template.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:

{
  "repos": {
    "exclude_ids": []
  }
}

The policy repository acme/ci-policies is internal, so the answer names acme/web:

{
  "name": "secret-scan",
  "revision": 2,
  "repos": {
    "include": ["*"],
    "exclude_ids": []
  },
  "validation": {
    "warnings": [],
    "repos_in_scope": 3,
    "repos_hidden": 0,
    "repos": [
      {
        "id": 4711,
        "full_name": "acme/web",
        "reason": "acme/web is public and acme/ci-policies is internal: a repository cannot use the workflow templates of a repository that is less visible than itself"
      }
    ]
  },
  "new_revision": false,
  "dry_run": true
}

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_request event, 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 lint on 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.

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.

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 repository in place of the workflows of the repository. The entry is in the state error, has no steps and never runs. The pipeline ends with the status error, 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 status failure.

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.

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.

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.

A workflow of the repository may depend on a required workflow. The file .crow/deploy.yaml of acme/shop:

# .crow/deploy.yaml in acme/shop
when:
  - event: push
    branch: main

depends_on:
  - required/secret-scan

steps:
  - name: deploy
    image: registry.example.com/tools/deployer:2
    commands:
      - deployer release
  • 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 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:

template:
  repo: "acme/ci-policies"
  name: "secret-scan"
  ref: "3f2a9c1d0e5b4a7f8c6d2e1b0a9f8e7d6c5b4a3f"
  inputs:
    fail_on: "medium"
  secrets:
    scanner_token:
      from_secret: "SCANNER_TOKEN"

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.

A required workflow reports its result under a fixed status context:

<status-context>/<event>/required/<name>

<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.

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_request while no pipeline of that event carries the current revision for the commit,
  • for a pipeline that the when of 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

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.

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.

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 when of 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 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.

# List the outdated pipelines
curl -H "Authorization: Bearer $CROW_TOKEN" \
  https://crow.example.com/api/v1/orgs/<org-id>/required-workflows/secret-scan/outdated

# Start up to 50 of them again with a fresh restart
curl -X POST -H "Authorization: Bearer $CROW_TOKEN" \
  "https://crow.example.com/api/v1/orgs/<org-id>/required-workflows/secret-scan/outdated/restart?limit=50"

# Repeat the reset, for example after the server was stopped during one
curl -X POST -H "Authorization: Bearer $CROW_TOKEN" \
  https://crow.example.com/api/v1/orgs/<org-id>/required-workflows/secret-scan/outdated/reset

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.

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.

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.

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.

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.

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:

# .crow-templates/license-check.yaml in acme/ci-policies
spec:
  description: Check the licenses of the dependencies.

workflow:
  when:
    - event: pull_request
  steps:
    - name: licenses
      image: registry.example.com/security/license-check:2
      commands:
        - |
          if [ ! -f go.mod ] && [ ! -f package.json ]; then
            echo "no dependencies to check"
            exit 0
          fi
        - license-check --policy /policies/default.yaml .

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 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.

  • The template runs without the trust of the repository, see What a required workflow may use. A template that needs privileged or volumes cannot be assigned.
  • The template cannot set depends_on, runs_on or matrix, 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.

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_request event.
  • 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 includes Pipeline 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 than pull_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 the pull_request event 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 when of 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.

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.

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
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

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}}'.

# Prepare an assignment without enabling it, and look at the check
crow org required-workflow add acme --name license-check \
  --template-repo acme/ci-policies --template-name license-check --ref refs/heads/main \
  --include 'api-*' --include 'service-*' --disabled

# Switch it on
crow org required-workflow update acme --name license-check --enable

# See which repositories would fail it
crow org required-workflow show acme --name license-check

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>.

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.

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