From 8e31a0f1e70c54d3eae01ba0cb118c8282db32be Mon Sep 17 00:00:00 2001 From: Charlie Egan Date: Tue, 21 Apr 2026 15:32:37 +0100 Subject: [PATCH] Update Regal docs to v0.40.0 (#8538) Add new rule docs, update adopters, and remove automated docs workflow (broken due to hardening). Signed-off-by: Charlie Egan --- .github/workflows/docs-update.yaml | 128 ------------------ docs/imported.json | 2 +- docs/projects/regal/adopters.md | 4 +- docs/projects/regal/cicd.md | 4 +- .../regal/configuration/capabilities.md | 30 ++-- .../regal/rules/bugs/import-shadows-rule.md | 8 +- .../regal/rules/bugs/invalid-regexp.md | 46 +++++++ .../regal/rules/bugs/redundant-loop-count.md | 6 + .../regal/rules/custom/naming-convention.md | 17 ++- .../rules/idiomatic/superfluous-object-get.md | 47 +++++++ .../regal/rules/imports/confusing-alias.md | 6 + .../regal/rules/imports/pointless-import.md | 6 + 12 files changed, 151 insertions(+), 153 deletions(-) delete mode 100644 .github/workflows/docs-update.yaml create mode 100644 docs/projects/regal/rules/bugs/invalid-regexp.md create mode 100644 docs/projects/regal/rules/idiomatic/superfluous-object-get.md diff --git a/.github/workflows/docs-update.yaml b/.github/workflows/docs-update.yaml deleted file mode 100644 index d8d27d4a97..0000000000 --- a/.github/workflows/docs-update.yaml +++ /dev/null @@ -1,128 +0,0 @@ -name: Update Regal Docs -on: - workflow_dispatch: {} # Allow for manual triggers - schedule: - - cron: '0 6 * * *' # Daily at 6:00 UTC - -permissions: - contents: read - -jobs: - update-regal-docs: - name: Update Regal Documentation - runs-on: ubuntu-latest - steps: - - name: Check out code - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - with: - token: ${{ secrets.GH_PUSH_TOKEN }} # zizmor: ignore[secrets-outside-env] - persist-credentials: false - - - name: Get latest Regal release - id: latest - env: - GH_TOKEN: ${{ secrets.GH_PUSH_TOKEN }} # zizmor: ignore[secrets-outside-env] - run: | - LATEST_VERSION=$(gh api repos/open-policy-agent/regal/releases/latest --jq '.tag_name') - echo "version=$LATEST_VERSION" >> $GITHUB_OUTPUT - echo "Latest Regal version: $LATEST_VERSION" - - - name: Get current version - id: current - run: | - CURRENT_VERSION=$(jq -r '.regal' docs/imported.json) - echo "version=$CURRENT_VERSION" >> $GITHUB_OUTPUT - echo "Current Regal version: $CURRENT_VERSION" - - - name: Check if update needed - id: check - run: | - if [ "${STEPS_LATEST_OUTPUTS_VERSION}" = "${STEPS_CURRENT_OUTPUTS_VERSION}" ]; then - echo "Already at latest version, no update needed" - echo "needed=false" >> $GITHUB_OUTPUT - else - echo "Update needed: ${STEPS_CURRENT_OUTPUTS_VERSION} -> ${STEPS_LATEST_OUTPUTS_VERSION}" - echo "needed=true" >> $GITHUB_OUTPUT - fi - env: - STEPS_LATEST_OUTPUTS_VERSION: ${{ steps.latest.outputs.version }} - STEPS_CURRENT_OUTPUTS_VERSION: ${{ steps.current.outputs.version }} - - - name: Check if branch already exists - if: steps.check.outputs.needed == 'true' - run: | - BRANCH_NAME="update-regal-${STEPS_LATEST_OUTPUTS_VERSION}" - if git ls-remote --exit-code --heads origin "$BRANCH_NAME" >/dev/null 2>&1; then - echo "::error::Branch '$BRANCH_NAME' already exists. A PR for this version may already be open." - exit 1 - fi - echo "Branch '$BRANCH_NAME' does not exist, proceeding with update" - env: - STEPS_LATEST_OUTPUTS_VERSION: ${{ steps.latest.outputs.version }} - - - name: Update imported.json - if: steps.check.outputs.needed == 'true' - run: | - jq --arg version "${STEPS_LATEST_OUTPUTS_VERSION}" '.regal = $version' docs/imported.json > docs/imported.json.tmp - mv docs/imported.json.tmp docs/imported.json - env: - STEPS_LATEST_OUTPUTS_VERSION: ${{ steps.latest.outputs.version }} - - - name: Run import script - if: steps.check.outputs.needed == 'true' - run: | - cd docs - VERSION=${STEPS_LATEST_OUTPUTS_VERSION} ./bin/import-regal-docs.sh - env: - STEPS_LATEST_OUTPUTS_VERSION: ${{ steps.latest.outputs.version }} - - - name: Check for changes - if: steps.check.outputs.needed == 'true' - id: changes - run: | - if git diff --quiet; then - echo "No changes detected after import" - echo "has_changes=false" >> $GITHUB_OUTPUT - else - echo "Changes detected" - echo "has_changes=true" >> $GITHUB_OUTPUT - fi - - - name: Configure git - if: steps.check.outputs.needed == 'true' && steps.changes.outputs.has_changes == 'true' - run: | - git config user.name "opa-docs-bot" - git config user.email "opa-docs-bot@openpolicyagent.org" - - - name: Create branch and commit - if: steps.check.outputs.needed == 'true' && steps.changes.outputs.has_changes == 'true' - run: | - BRANCH_NAME="update-regal-${STEPS_LATEST_OUTPUTS_VERSION}" - git checkout -b "$BRANCH_NAME" - git add -A - git commit -s -m "docs: Update Regal docs to ${STEPS_LATEST_OUTPUTS_VERSION}" - env: - STEPS_LATEST_OUTPUTS_VERSION: ${{ steps.latest.outputs.version }} - - - name: Push branch - if: steps.check.outputs.needed == 'true' && steps.changes.outputs.has_changes == 'true' - run: | - BRANCH_NAME="update-regal-${STEPS_LATEST_OUTPUTS_VERSION}" - git push origin "$BRANCH_NAME" - env: - STEPS_LATEST_OUTPUTS_VERSION: ${{ steps.latest.outputs.version }} - - - name: Create pull request - if: steps.check.outputs.needed == 'true' && steps.changes.outputs.has_changes == 'true' - env: - GH_TOKEN: ${{ secrets.GH_PUSH_TOKEN }} # zizmor: ignore[secrets-outside-env] - STEPS_LATEST_OUTPUTS_VERSION: ${{ steps.latest.outputs.version }} - run: | - VERSION="${STEPS_LATEST_OUTPUTS_VERSION}" - gh pr create \ - --title "docs: Update Regal docs to $VERSION" \ - --body "$(cat < +- [Code Rabbit](https://docs.coderabbit.ai/tools/regal) - [Dependency Management Data](https://gitlab.com/tanna.dev/dependency-management-data) -- [Enterprise OPA](https://github.com/styrainc/enterprise-opa) +- [EOPA](https://github.com/open-policy-agent/eopa) - [The Rego Playground](https://play.openpolicyagent.org) - [Trunk Check](https://trunk.io/) - [reviewdog/action-regal](https://github.com/reviewdog/action-regal) @@ -83,7 +84,6 @@ Some companies and organizations using Regal. - [Red Hat](https://www.redhat.com) - [Spacelift](https://www.spacelift.io) - [Stacklok](https://stacklok.com) -- [Styra](https://www.styra.com) - [UNIwise](https://uniwise.eu/) - [VodafoneZiggo](https://www.vodafoneziggo.nl) diff --git a/docs/projects/regal/cicd.md b/docs/projects/regal/cicd.md index 5ceffdb298..43a334921c 100644 --- a/docs/projects/regal/cicd.md +++ b/docs/projects/regal/cicd.md @@ -28,8 +28,8 @@ jobs: lint-rego: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 - - uses: open-policy-agent/setup-regal@v1 + - uses: actions/checkout@v6 + - uses: open-policy-agent/setup-regal@v2 with: # For production workflows, use a specific version, like v0.22.0 version: latest diff --git a/docs/projects/regal/configuration/capabilities.md b/docs/projects/regal/configuration/capabilities.md index 779cbd8a93..b1a3193aaf 100644 --- a/docs/projects/regal/configuration/capabilities.md +++ b/docs/projects/regal/configuration/capabilities.md @@ -52,18 +52,18 @@ capabilities: version: v0.58.0 minus: builtins: - # exclude rules that depend on the http.send built-in function - - name: http.send + # exclude rules that depend on the http.send built-in function + - name: http.send plus: builtins: - # make Regal aware of a custom "ldap.query" function - - name: ldap.query - type: function - decl: - args: - - type: string - result: - type: object + # make Regal aware of a custom "ldap.query" function + - name: ldap.query + type: function + decl: + args: + - type: string + result: + type: object ``` ## Loading Capabilities from URLs @@ -82,10 +82,10 @@ capabilities: Regal includes capabilities files for the following engines: -| Engine | Website | Description | -| ------ | --------------------------------------------------------------- | -------------------- | -| `opa` | [OPA website](https://www.openpolicyagent.org/) | Open Policy Agent | -| `eopa` | [Enterprise OPA website](https://www.styra.com/enterprise-opa/) | Styra Enterprise OPA | -| `rq` | [rq website](https://git.sr.ht/~charles/rq) | Rego Query (`rq`) | +| Engine | Website | Description | +| ------ | ------------------------------------------------------------ | ----------------- | +| `opa` | [OPA website](https://www.openpolicyagent.org/) | Open Policy Agent | +| `eopa` | [EOPA repository](https://github.com/open-policy-agent/eopa) | EOPA | +| `rq` | [rq website](https://git.sr.ht/~charles/rq) | Rego Query (`rq`) | **`rq` support note**: `rq` scripts must include `package` statements to be compatible with Regal. diff --git a/docs/projects/regal/rules/bugs/import-shadows-rule.md b/docs/projects/regal/rules/bugs/import-shadows-rule.md index 74ab29bcbe..0d9dea13b3 100644 --- a/docs/projects/regal/rules/bugs/import-shadows-rule.md +++ b/docs/projects/regal/rules/bugs/import-shadows-rule.md @@ -5,18 +5,20 @@ **Category**: Bugs **Avoid** + ```rego package policy import data.resources -# 'resources' shadowed by import +# 'resources' shadowed by import resources contains resource if { # ... } ``` **Prefer** + ```rego package policy @@ -56,3 +58,7 @@ rules: # one of "error", "warning", "ignore" level: error ``` + +## Related Resources + +- GitHub: [Source Code](https://github.com/open-policy-agent/regal/blob/main/bundle/regal/rules/bugs/import-shadows-rule/import_shadows_rule.rego) diff --git a/docs/projects/regal/rules/bugs/invalid-regexp.md b/docs/projects/regal/rules/bugs/invalid-regexp.md new file mode 100644 index 0000000000..9b4f81ed31 --- /dev/null +++ b/docs/projects/regal/rules/bugs/invalid-regexp.md @@ -0,0 +1,46 @@ +# invalid-regexp + +**Summary**: Invalid regular expression + +**Category**: Bugs + +**Avoid** + +```rego +package policy + +invalid if regex.match(`[abc`, input.text) +``` + +**Prefer** + +```rego +package policy + +valid if regex.match(`[abc]`, input.text) +``` + +## Rationale + +An invalid regular expression typically fails silently (i.e. the result is undefined) at runtime when OPA evaluates the +function call, or with a runtime error if the `show-builtin-errors` option is enabled. While hopefully caught by unit +tests, tracking down a typo in a regular expression is still time consuming. This rule instead analyzes any regular +expressions found in a policy as you author it (using OPA's own `regex.is_valid` function) and reports invalid patterns +directly. + +## Configuration Options + +This linter rule provides the following configuration options: + +```yaml +rules: + bugs: + invalid-regexp: + # one of "error", "warning", "ignore" + level: error +``` + +## Related Resources + +- OPA Docs: [Regex Functions](https://www.openpolicyagent.org/docs/latest/policy-reference/#regex-functions) +- GitHub: [Source Code](https://github.com/open-policy-agent/regal/blob/main/bundle/regal/rules/bugs/invalid-regexp/invalid_regexp.rego) diff --git a/docs/projects/regal/rules/bugs/redundant-loop-count.md b/docs/projects/regal/rules/bugs/redundant-loop-count.md index c45181ae4b..2094f28596 100644 --- a/docs/projects/regal/rules/bugs/redundant-loop-count.md +++ b/docs/projects/regal/rules/bugs/redundant-loop-count.md @@ -5,6 +5,7 @@ **Category**: Bugs **Avoid** + ```rego package policy @@ -17,6 +18,7 @@ allow if { ``` **Prefer** + ```rego package policy @@ -80,3 +82,7 @@ rules: # one of "error", "warning", "ignore" level: error ``` + +## Related Resources + +- GitHub: [Source Code](https://github.com/open-policy-agent/regal/blob/main/bundle/regal/rules/bugs/redundant-loop-count/redundant_loop_count.rego) diff --git a/docs/projects/regal/rules/custom/naming-convention.md b/docs/projects/regal/rules/custom/naming-convention.md index d6586b873c..f4d8f962d7 100644 --- a/docs/projects/regal/rules/custom/naming-convention.md +++ b/docs/projects/regal/rules/custom/naming-convention.md @@ -32,18 +32,27 @@ rules: # one of "error", "warning", "ignore" level: error conventions: - # allow only "private" rules and functions, i.e. those starting with - # underscore, or rules named "deny" or "allow" - - pattern: '^_[a-z]+$|^deny$|^allow$' + # allow only "private" rules and functions, i.e. those starting with + # underscore, or rules named "deny" or "allow" + - pattern: "^_[a-z]+$|^deny$|^allow$" # one of "package", "rule", "function", "variable" targets: - rule - function # any number of naming rules may be added # package names must start with "acmecorp" or "system" - - pattern: '^acmecorp|^system' + - pattern: "^acmecorp|^system" targets: - package + # a list of names may be provided in addition to a pattern + # if both a pattern and a list of names are provided, identifiers + # must match either the pattern or one of the names in the list + - names: + - i + - j + - k + targets: + - var ``` **Note:** In order to avoid characters accidentally getting escaped, always use single quotes to encode your regex diff --git a/docs/projects/regal/rules/idiomatic/superfluous-object-get.md b/docs/projects/regal/rules/idiomatic/superfluous-object-get.md new file mode 100644 index 0000000000..08b95266e6 --- /dev/null +++ b/docs/projects/regal/rules/idiomatic/superfluous-object-get.md @@ -0,0 +1,47 @@ +# superfluous-object-get + +**Summary**: Superfluous `object.get` call + +**Category**: Idiomatic + +**Avoid** + +```rego +package policy + +allow if { + object.get(input, ["path", "to", "value"], "default") == "expected" +} +``` + +**Prefer** + +```rego +package policy + +allow if { + input.path.to.value == "expected" +} +``` + +## Rationale + +The `object.get` function is sometimes used to guard against undefined references halting evaluation. Immediately +comparing the result of the call to a constant value that isn't the same as the default is however superfluous, as +the expression will evaluate the same without using `object.get`. In such cases the call can simply be removed. + +## Configuration Options + +This linter rule provides the following configuration options: + +```yaml +rules: + idiomatic: + superfluous-object-get: + # one of "error", "warning", "ignore" + level: error +``` + +## Related Resources + +- GitHub: [Source Code](https://github.com/open-policy-agent/regal/blob/main/bundle/regal/rules/idiomatic/superfluous-object-get/superfluous_object_get.rego) diff --git a/docs/projects/regal/rules/imports/confusing-alias.md b/docs/projects/regal/rules/imports/confusing-alias.md index 4b6ad35fc5..545e6017e4 100644 --- a/docs/projects/regal/rules/imports/confusing-alias.md +++ b/docs/projects/regal/rules/imports/confusing-alias.md @@ -5,6 +5,7 @@ **Category**: Imports **Avoid** + ```rego package policy @@ -14,6 +15,7 @@ import data.resources.users as employees ``` **Prefer** + ```rego package policy @@ -50,3 +52,7 @@ rules: # one of "error", "warning", "ignore" level: error ``` + +## Related Resources + +- GitHub: [Source Code](https://github.com/open-policy-agent/regal/blob/main/bundle/regal/rules/imports/confusing-alias/confusing_alias.rego) diff --git a/docs/projects/regal/rules/imports/pointless-import.md b/docs/projects/regal/rules/imports/pointless-import.md index d8f9b8f8de..bbdfbc0920 100644 --- a/docs/projects/regal/rules/imports/pointless-import.md +++ b/docs/projects/regal/rules/imports/pointless-import.md @@ -5,6 +5,7 @@ **Category**: Imports **Avoid** + ```rego package policy @@ -20,6 +21,7 @@ rule if { ``` **Prefer** + ```rego package policy ``` @@ -40,3 +42,7 @@ rules: # one of "error", "warning", "ignore" level: error ``` + +## Related Resources + +- GitHub: [Source Code](https://github.com/open-policy-agent/regal/blob/main/bundle/regal/rules/imports/pointless-import/pointless_import.rego)