Filters and patterns in SourceCraft

Filter patterns in SourceCraft enable you to define rules and restrictions for specific files, directories, branches, and tags to apply in different scenarios. Filter use cases include:

• CI/CD trigger events: To run workflows when updating specific files, branches, or tags.
• Approval rules: To assign reviewers based on the modified files.
• Branch policies: To restrict the creation of branches and tags with specific names.

Basic patterns

Filters use patterns to match file paths or branch and tag names:

• *: Any sequence of characters excluding /.
• **: Any sequence of characters including /. Recommended for group filtering.
• ?: Any single character.

For example:

• "**": Matches every file in the repository.
• "pkg/**": Matches all files in the pkg directory.
• "*.py": Matches all .py files in the root directory.
• "**/*.py": Matches all .py files in all directories.

You use ! in filters. The rule will ignore any path that matches the negated pattern. For example:

• "!docs/**": Excludes the docs directory.
• "!*.md": Excludes all Markdown files.

Order of filters

The order of filters affects the result as follows:

• Filters are processed from top to bottom in the order of increasing priority.
• Each next filter can override the previous one. An inclusive filter can override a filter with negation, and vice versa.

Examples with ordered filters

Let's look at the examples of filtering modified files by their paths on trigger events.

Example of including all files except the specified ones

paths:
  - "**"
  - "!pkg/**"

The filter applies to all repository files except those located in the pkg directory.

Example of exclusion followed by inclusion

paths:
  - "internal/**"
  - "!internal/generated/**"
  - "internal/generated/models/auth/**"

The filter will not apply to internal/generated/models/data/data.go (excluded by the second rule) but does apply to internal/generated/models/auth/auth.go (the third rule overrides the second one).

Applying rules in different scenarios

CI/CD trigger events

In trigger events, filters define which changes initiate a workflow.

Here is an example of a trigger event that runs ci-workflow when the ci/** directory contents in the main branch is modified:

on:
  push:
    - workflows: ci-workflow
      filter:
        branches: "main"
        paths: "ci/**"

For more information, see Trigger events (on).

Approval rules

In approval rules, filters determine which files require approval from specific reviewers.

Here is an example of an approval rule which requires approval from senior-developer for all changes except those in the docs directory:

codereview:
  rules:
    - patterns:
        - "**"
        - "!docs/**"
      reviewers:
        usernames:
          - "senior-developer"

For more information, see Approval rules in SourceCraft.

Branch policies

In branch policies, the matches parameter uses the same filtering rules to restrict the creation of branches and tags with specific names.

Here is an example of a rule that blocks the creation of branches with the OO-, hotfix, chore, or release prefixes:

branch_protection:
  policies:
    - target: branch
      matches: ["**", "!OO-**/**", "!hotfix/**", "!chore/**", "!release/**"]
      message: "Please use proper branch naming"
      rules:
        - prevent_creation

For more information, see Branch policies in SourceCraft.

See also

• Trigger events (on)
• Setting up approval rules in a SourceCraft repository
• Setting up a branch policy in a SourceCraft repository