{"id":14314672,"url":"https://github.com/masterpointio/github-action-opa-rego-test","last_synced_at":"2025-04-11T05:41:04.827Z","repository":{"id":251835897,"uuid":"838584850","full_name":"masterpointio/github-action-opa-rego-test","owner":"masterpointio","description":"GitHub Action to automate testing for your OPA (Open Policy Agent) Rego policies, generates a report with coverage information, and posts the test results as a comment on your pull requests.","archived":false,"fork":false,"pushed_at":"2025-04-01T08:06:08.000Z","size":2114,"stargazers_count":21,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-01T09:23:19.104Z","etag":null,"topics":["github-action","github-actions","opa","opa-testing","open-policy-agent","rego","rego-test","rego-testing"],"latest_commit_sha":null,"homepage":"https://masterpoint.io","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/masterpointio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-06T00:31:39.000Z","updated_at":"2025-02-25T18:49:58.000Z","dependencies_parsed_at":"2024-08-11T22:34:15.198Z","dependency_job_id":"ed2e95fb-a8ab-4360-b7a4-3ab7a355a6d2","html_url":"https://github.com/masterpointio/github-action-opa-rego-test","commit_stats":null,"previous_names":["masterpointio/github-action-opa-tests-coverage","masterpointio/github-action-opa-rego-test"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masterpointio%2Fgithub-action-opa-rego-test","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masterpointio%2Fgithub-action-opa-rego-test/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masterpointio%2Fgithub-action-opa-rego-test/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masterpointio%2Fgithub-action-opa-rego-test/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/masterpointio","download_url":"https://codeload.github.com/masterpointio/github-action-opa-rego-test/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248350977,"owners_count":21089268,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github-action","github-actions","opa","opa-testing","open-policy-agent","rego","rego-test","rego-testing"],"created_at":"2024-08-24T15:00:57.950Z","updated_at":"2025-04-11T05:41:04.805Z","avatar_url":"https://github.com/masterpointio.png","language":"TypeScript","funding_links":[],"categories":["Testing"],"sub_categories":["Serverless Blogs and Articles"],"readme":"[![Masterpoint Logo](https://masterpoint-public.s3.us-west-2.amazonaws.com/v2/standard-long-fullcolor.png)](https://masterpoint.io)\n\n# GitHub Action for OPA Rego Policy Tests [![Latest Release](https://img.shields.io/github/release/masterpointio/github-action-opa-rego-test.svg)](https://github.com/masterpointio/github-action-opa-rego-test/releases/latest)\n\nGitHub Action to automate testing for your OPA (Open Policy Agent) Rego policies, generates a report with coverage information, and posts the test results as a comment on your pull requests, making it easy for your team to review and approve policies.\n\nUse this to test your OPA Rego files for [Spacelift policies](https://docs.spacelift.io/concepts/policy), Kubernetes Admission Controller policies, Docker authorization policies, or any other use case that uses [Open Policy Agent's policy language Rego](https://www.openpolicyagent.org/docs/latest/). This Action also updates PR comments with the test results in place to prevent duplication.\n\n\u003cimg src=\"./assets/opa-logo.png\" alt=\"OPA Logo\" width=\"300\"\u003e\n\n\u003cimg src=\"./assets/banner-pr-comment-example.png\" alt=\"OPA Rego Test GitHub Comment Example\" width=\"600\"\u003e\n\nSee examples of the pull request comments below at the [Example Pull Request Comments section](#-example-pull-request-comments).\n\n📚 Table of Contents\n\n- [🚀 Usage](#-usage)\n  - [Inputs](#inputs)\n- [⚙️ How It Works](#️-how-it-works)\n- [🧪 Running Tests](#-running-tests)\n- [🏗️ Setup \u0026 Run Locally](#️-setup--run-locally)\n- [📦 Releases / Packaging for Distribution](#-releases--packaging-for-distribution)\n- [🤝 Contributing](#-contributing)\n- [💬 Example Pull Request Comments](#-example-pull-request-comments)\n\n## 🚀 Usage\n\nIt's super easy to get started and use this GitHub Action to test your OPA Rego policies. In your repository/directory with the `.rego` files and the `_test.rego` files, simply checkout the repository and add the step with `uses: masterpointio/github-action-opa-rego-test@main`. It's as simple as adding the step with no required inputs! It will then generate a PR comment (that updates in place) with the test results!\n\n```yaml\n- name: Run OPA Rego Tests\n  uses: masterpointio/github-action-opa-rego-test@main\n  with:\n    report_untested_files: true # Flag to check \u0026 report Rego files that does NOT have corresponding test files. Optional, defaults to false.\n```\n\n\u003cdetails\u003e\n    \u003csummary\u003eExpand to see full usage example!\u003c/summary\u003e\n\n```yaml\nname: Spacelift Policy OPA Rego Tests\n\non:\n  pull_request:\n    # Optionally only trigger tests on affecting .rego files.\n    # paths:\n    #   - '**.rego'\n\npermissions:\n  id-token: write\n  contents: read\n  pull-requests: write # required to comment on PRs\n\njobs:\n  opa-tests:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Check out repository code\n        uses: actions/checkout@v4\n\n      - name: Run OPA Rego Tests\n        uses: masterpointio/github-action-opa-rego-test@main\n        with:\n          path: \"./config/spacelift-policies\" # Path of the directory where the OPA Rego policies are stored. Optional, defaults to `.` which is the root directory.\n          report_untested_files: true # Flag to check \u0026 report Rego files without corresponding test files. Optional, defaults to false.\n```\n\n\u003c/details\u003e\n\nBe sure to always append the postfix to your test files. The default input for the `test_file_postfix` is `_test`, per [OPA's best practices](https://www.openpolicyagent.org/docs/latest/policy-testing/#test-format). If you have a different postfix for your test files, you can specify it in the inputs. This is how GitHub Action know what test to run on files.\n\nFor example, if you have a file named `my-policy.rego`, you would need a file named `my-policy_test.rego`. It does not matter where the `_test.rego` file is located, just that it is in the root path, meaning that it can be in a subdirectory.\n\nIn the example below, all `_test.rego` files' location are valid and will be executed.\n\n\u003cimg src=\"./assets/test-file-structure-example.png\" alt=\"Masterpoint GitHub Action OPA Test File Structure\" width=\"450\"\u003e\n\n### Inputs\n\n| Input                     | Description                                                                                     | Required | Default                           |\n| ------------------------- | ----------------------------------------------------------------------------------------------- | -------- | --------------------------------- |\n| `path`                    | Path to the directory containing OPA Rego files to test                                         | No       | `.` (root directory)              |\n| `test_file_postfix`       | Postfix of the test files to run (e.g. notification.rego \u003c\u003e notification_test.rego)             | No       | `_test`                           |\n| `write_pr_comment`        | Flag to write a user-friendly PR comment with test results                                      | No       | `true`                            |\n| `pr_comment_title`        | Title of the PR comment for test results                                                        | No       | `🧪 OPA Rego Policy Test Results` |\n| `pr_comment_mode`         | Mode that will be used to update comment. Options of upsert (update in place) or recreate.      | No       | `upsert`                          |\n| `run_coverage_report`     | Flag to run OPA coverage tests and include in PR comment                                        | No       | `true`                            |\n| `report_untested_files`   | Check \u0026 report Rego files without corresponding test files                                      | No       | `false`                           |\n| `opa_version`             | Version of the OPA CLI to use.                                                                  | No       | `0.67.1`                          |\n| `indicate_source_message` | Flag to comment the origins watermark (this repository) of the GitHub Action in the PR comment. | No       | `true`                            |\n\n### Outputs\n\n| Output           | Description                                                            |\n| ---------------- | ---------------------------------------------------------------------- |\n| `parsed_results` | The parsed results after processing the tests and/or coverage report.  |\n| `tests_failed`   | A `true` or `false` flag indicating if any of the tests failed or not. |\n\n## ⚙️ How It Works\n\nThis GitHub Action automates the process of testing OPA (Open Policy Agent) Rego policies and generating coverage reports. Here's a breakdown of its operation:\n\n1. Setup: The action begins by setting up OPA using the open-policy-agent/setup-opa@v2 action, ensuring the necessary tools are available.\n2. Run OPA Tests: It executes `opa test` on all .rego files in the specified directory (default is the root directory). The test results are captured and stored as an output.\n3. Run OPA Coverage Tests: Enabled by default but optional, the action performs coverage tests on each .rego file that has a corresponding \\_test.rego file. This step identifies which parts of your policies are covered by tests.\n4. Find Untested Files: Optionally if enabled, it can identify Rego files that don't have corresponding test files, helping you maintain comprehensive test coverage.\n5. Parse and Format Results: A custom TypeScript script (index.ts) processes the raw test and coverage outputs. It parses the results into a structured format and generates a user-friendly summary.\n6. Generate PR Comment: The formatted results are used to create or update a comment on the pull request.\n7. Fail the Action if Tests Fail: If any tests fail, the action is marked as failed, which can be used to block PR merges or trigger other workflows.\n\n![Masterpoint OPA Rego Test Action Diagram](https://lucid.app/publicSegments/view/60bf898e-2640-475f-b130-2a70d317a65d/image.png)\n\n## 🧪 Running Tests\n\nOn each pull request, there is a GitHub Actions workflow that runs the tests automatically, along with it testing itself by running the Action on itself against the `/examples` directory and commenting the OPA results on the same PR. To test locally, see below:\n\n1. `npm install`\n2. `npm run test`\n\n\u003cimg src=\"./assets/readme-test-results.png\" alt=\"NPM Test Results\" width=\"450\"\u003e\n\n## 🏗️ Setup \u0026 Run Locally\n\nYou can use [nektos/act](https://github.com/nektos/act) to simulate and run a GitHub Actions workflow locally. To directly test the custom TypeScript action locally, you can:\n\n1. `npm run install`\n2. `node ./dist/index.js`\n   This is assuming you have `npm` and `node` installed already. Note: You will have to manually provide the required inputs since this is directly executing the TypeScript code.\n\n## 📦 Releases / Packaging for Distribution\n\nThis Action executes the source from the `/dist` directory. It is generated using [@vercel/ncc](https://github.com/vercel/ncc) to easily compile the TypeScript module into a single file together with all its dependencies, gcc-style, to package it up for use and distribute.\n\nTo package for distribution, simply run the command which will do the above and generate into the `/dist` directory (see the source in `package.json`):\n\n```bash\nnpm run build\n```\n\nTo create a new release, merge the pull request created by [Release Please](https://github.com/googleapis/release-please). This will automatically create a new release with the version number and the changes made.\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request or open any issues you may have.\n\n## 💬 Example Pull Request Comments\n\nOne of the testing steps is running the test workflow against this Action itself. You can see some live examples in the closed PR section, including this [example here](https://github.com/masterpointio/github-action-opa-rego-test/pull/9#issuecomment-2305253112).\n\n- ![Masterpoint GitHub Actions OPA Rego Test PR Example](./assets/readme-example-1.png)\n  - Using `report_untested_files` to indicate policies without corresponding tests.\n- ![Masterpoint GitHub Actions OPA Rego Test PR Example](./assets/readme-example-2.png)\n- ![Masterpoint GitHub Actions OPA Rego Test PR Example](./assets/readme-example-3.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmasterpointio%2Fgithub-action-opa-rego-test","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmasterpointio%2Fgithub-action-opa-rego-test","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmasterpointio%2Fgithub-action-opa-rego-test/lists"}