{"id":19604139,"url":"https://github.com/zedthree/clang-tidy-review","last_synced_at":"2025-04-12T21:22:44.744Z","repository":{"id":39887210,"uuid":"268098312","full_name":"ZedThree/clang-tidy-review","owner":"ZedThree","description":"Create a pull request review based on clang-tidy warnings","archived":false,"fork":false,"pushed_at":"2025-03-25T15:19:25.000Z","size":422,"stargazers_count":92,"open_issues_count":16,"forks_count":50,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-04T01:46:44.305Z","etag":null,"topics":["actions","clang-tidy","code-review"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ZedThree.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"2020-05-30T14:41:41.000Z","updated_at":"2025-03-31T07:21:49.000Z","dependencies_parsed_at":"2024-01-26T16:25:36.303Z","dependency_job_id":"d37c7cb6-12bd-4e8d-b4af-ca1cb5109987","html_url":"https://github.com/ZedThree/clang-tidy-review","commit_stats":{"total_commits":166,"total_committers":20,"mean_commits":8.3,"dds":0.4518072289156626,"last_synced_commit":"85799d63d217e8d0686b7735fb923acc986d8043"},"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZedThree%2Fclang-tidy-review","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZedThree%2Fclang-tidy-review/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZedThree%2Fclang-tidy-review/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZedThree%2Fclang-tidy-review/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ZedThree","download_url":"https://codeload.github.com/ZedThree/clang-tidy-review/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248632696,"owners_count":21136742,"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":["actions","clang-tidy","code-review"],"created_at":"2024-11-11T09:34:58.801Z","updated_at":"2025-04-12T21:22:44.719Z","avatar_url":"https://github.com/ZedThree.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Clang-Tidy Review\n\nCreate a pull-request review based on the warnings from clang-tidy.\n\nInspired by `clang-tidy-diff`, Clang-Tidy Review only runs on the\nchanges in the pull request. This makes it nice and speedy, as well as\nbeing useful for projects that aren't completely clang-tidy clean yet.\n\nWhere possible, makes the warnings into suggestions so you can apply\nthem immediately.\n\nReturns the number of comments, so you can decide whether the warnings\nact as suggestions, or check failure.\n\nDoesn't spam by repeating identical warnings for the same line.\n\nCan use `compile_commands.json`, so you can optionally configure the\nbuild how you like first.\n\n![Example review](example_review.png)\n\nExample usage:\n\n```yaml\nname: clang-tidy-review\n\n# You can be more specific, but it currently only works on pull requests\non: [pull_request]\n\njobs:\n  build:\n    runs-on: ubuntu-latest\n\n    steps:\n    - uses: actions/checkout@v4\n\n    # Optionally generate compile_commands.json\n\n    - uses: ZedThree/clang-tidy-review@v0.14.0\n      id: review\n\n    # Uploads an artefact containing clang_fixes.json\n    - uses: ZedThree/clang-tidy-review/upload@v0.14.0\n      id: upload-review\n\n    # If there are any comments, fail the check\n    - if: steps.review.outputs.total_comments \u003e 0\n      run: exit 1\n```\n\nThe `ZedThree/clang-tidy-review/upload` Action is optional (unless using the\nsplit workflow, see below), and will upload some of the output files as workflow\nartefacts. These are useful when there are more comments than can be posted, as\nwell as for applying fixes locally.\n\n## Limitations\n\nThis is a Docker container-based Action because it needs to install\nsome system packages (the different `clang-tidy` versions) as well as\nsome Python packages. This that means that there's a two-three minutes\nstart-up in order to build the Docker container. If you need to\ninstall some additional packages you can pass them via the\n`apt_packages` argument or run some install commands with `install_commands`.\n\nExcept for very simple projects, a `compile_commands.json` file is necessary for\nclang-tidy to find headers, set preprocessor macros, and so on. You can generate\none as part of this Action by setting `cmake_command` to something like `cmake\n. -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=on`.\n\nGitHub only mounts the `GITHUB_WORKSPACE` directory (that is, the\ndefault place where it clones your repository) on the container. If\nyou install additional libraries/packages yourself, you'll need to\nmake sure they are in this directory, otherwise they won't be\naccessible from inside this container.\n\nIt seems the GitHub API might only accept a limited number of comments\nat once, so `clang-tidy-review` will only attempt to post the first\n`max_comments` of them (default 25, as this has worked for me).\n\n## Inputs\n\n- `token`: Authentication token\n  - default: `${{ github.token }}`\n- `build_dir`: Directory containing the `compile_commands.json` file. This\n  should be relative to `GITHUB_WORKSPACE` (the default place where your\n  repository is cloned)\n  - default: `'.'`\n- `base_dir`: Absolute path to initial working directory\n  `GITHUB_WORKSPACE`.\n  - default: `GITHUB_WORKSPACE`\n- `clang_tidy_version`: Version of clang-tidy to use; one of 14, 15, 16, 17, 18, 19\n  - default: '19'\n- `clang_tidy_checks`: List of checks\n  - default: `'-*,performance-*,readability-*,bugprone-*,clang-analyzer-*,cppcoreguidelines-*,mpi-*,misc-*'`\n- `config_file`: Path to clang-tidy config file, replaces `clang_tidy_checks`\n  - default: '' which will use `clang_tidy_checks` if there are any, else closest `.clang-tidy` to each file\n- `include`: Comma-separated list of files or patterns to include\n  - default: `\"*.[ch],*.[ch]xx,*.[ch]pp,*.[ch]++,*.cc,*.hh\"`\n- `exclude`: Comma-separated list of files or patterns to exclude\n  - default: ''\n- `apt_packages`: Comma-separated list of apt packages to install\n  - default: ''\n- `install_commands`: Commands to execute after `apt_packages` before `cmake_command`\n  - default: ''\n- `cmake_command`: A CMake command to configure your project and generate\n  `compile_commands.json` in `build_dir`. You _almost certainly_ want\n  to include `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON`!\n  - default: ''\n- `max_comments`: Maximum number of comments to post at once\n  - default: '25'\n- `lgtm_comment_body`: Message to post on PR if no issues are\n  found. An empty string will post no LGTM comment.\n  - default: 'clang-tidy review says \"All clean, LGTM! :+1:\"'\n- `split_workflow`: Only generate but don't post the review, leaving\n  it for the second workflow. Relevant when receiving PRs from forks\n  that don't have the required permissions to post reviews.\n  - default: false\n- `annotations`: Use Annotations instead of comments. A maximum of 10\n  annotations can be written fully, the rest will be summarised. This is a\n  limitation of the GitHub API.\n- `num_comments_as_exitcode`: Set the exit code to be the amount of comments (enabled by default).\n\n## Outputs\n\n- `total_comments`: Total number of warnings from clang-tidy\n\n## Generating `compile_commands.json`\n\nVery simple projects can get away without a `compile_commands.json`\nfile, but for most projects `clang-tidy` needs this file in order to\nfind include paths and macro definitions.\n\nIf you use the GitHub `ubuntu-latest` image as your normal `runs-on`\ncontainer, you only install packages from the system package manager,\nand don't need to build or install other tools yourself, then you can\ngenerate `compile_commands.json` as part of the `clang-tidy-review`\naction:\n\n```yaml\nname: clang-tidy-review\non: [pull_request]\n\njobs:\n  build:\n    runs-on: ubuntu-latest\n\n    steps:\n    - uses: actions/checkout@v4\n\n    - uses: ZedThree/clang-tidy-review@v0.14.0\n      id: review\n      with:\n        # List of packages to install\n        apt_packages: liblapack-dev,devscripts,equivs\n        install_commands: 'ln -s foo bar; mk-build-deps -i'\n        # CMake command to run in order to generate compile_commands.json\n        cmake_command: cmake . -DCMAKE_EXPORT_COMPILE_COMMANDS=on\n```\n\nIf you don't use CMake, this may still work for you if you can use a\ntool like [bear](https://github.com/rizsotto/Bear) for example.\n\nYou can also generate this file outside the container, e.g. by adding\n`-DCMAKE_EXPORT_COMPILE_COMMANDS=ON` to a cmake command in an earlier\naction and omitting the `cmake_command` paramter.\n\n## Use in a non-default location\n\nIf you're using the `container` argument in your GitHub workflow,\ndownloading/building other tools manually, or not using CMake, you\nwill need to generate `compile_commands.json` before the\n`clang-tidy-review` action. However, the Action is run inside another\ncontainer, and due to the way GitHub Actions work, `clang-tidy-review`\nends up running with a different absolute path.\n\nWhat this means is that if `compile_commands.json` contains absolute\npaths, `clang-tidy-review` needs to adjust them to where it is being\nrun instead. By default, it replaces absolute paths that start with\nthe value of [`${GITHUB_WORKSPACE}`][env_vars] with the new working\ndirectory.\n\nIf you're running in a container other than a default GitHub\ncontainer, then you may need to pass the working directory to\n`base_dir`. Unfortunately there's not an easy way for\n`clang-tidy-review` to auto-detect this, so in order to pass the\ncurrent directory you will need to do something like the following:\n\n```yaml\nname: clang-tidy-review\non: [pull_request]\n\njobs:\n  build:\n    runs-on: ubuntu-latest\n    # Using another container changes the\n    # working directory from GITHUB_WORKSPACE\n    container:\n      image: my-container\n\n    steps:\n    - uses: actions/checkout@v4\n\n    # Get the current working directory and set it\n    # as an environment variable\n    - name: Set base_dir\n      run: echo \"base_dir=$(pwd)\" \u003e\u003e $GITHUB_ENV\n\n    - uses: ZedThree/clang-tidy-review@v0.14.0\n      id: review\n      with:\n        # Tell clang-tidy-review the base directory.\n        # This will get replaced by the new working\n        # directory inside the action\n        base_dir: ${{ env.base_dir }}\n```\n\n## Usage in fork environments (Split workflow)\n\nActions from forks are limited in their permissions for your security. To\nsupport this use case, you can use the split workflow described below.\n\nExample review workflow:\n\n```yaml\nname: clang-tidy-review\n\n# You can be more specific, but it currently only works on pull requests\non: [pull_request]\n\njobs:\n  build:\n    runs-on: ubuntu-latest\n\n    steps:\n    - uses: actions/checkout@v4\n\n    # Optionally generate compile_commands.json\n\n    - uses: ZedThree/clang-tidy-review@v0.14.0\n      with:\n        split_workflow: true\n\n    - uses: ZedThree/clang-tidy-review/upload@v0.14.0\n```\nThe `clang-tidy-review/upload` Action will automatically upload the following\nfiles as workflow artefacts:\n\n- `clang-tidy-review-output.json`\n- `clang-tidy-review-metadata.json`\n- `clang_fixes.json`\n\nExample post comments workflow:\n\n```yaml\nname: Post clang-tidy review comments\n\non:\n  workflow_run:\n    # The name field of the lint action\n    workflows: [\"clang-tidy-review\"]\n    types:\n      - completed\n\njobs:\n  build:\n    runs-on: ubuntu-latest\n\n    steps:\n      - uses: ZedThree/clang-tidy-review/post@v0.14.0\n        # lgtm_comment_body, max_comments, and annotations need to be set on the posting workflow in a split setup\n        with:\n          # adjust options as necessary\n          lgtm_comment_body: ''\n          annotations: false\n          max_comments: 10\n```\n\nThis Action will try to automatically download\n`clang-tidy-review-{output,metadata}.json` from the workflow that triggered it.\n\nThe review workflow runs with limited permissions and no access to\nrepo/organisation secrets, while the post comments workflow has the required\npermissions because it's triggered by the `workflow_run` event and always uses\nthe version of the workflow in the original repo.\n\nRead more about workflow security limitations\n[here](https://securitylab.github.com/research/github-actions-preventing-pwn-requests/).\n\nEnsure that your workflow name doesn't contain any [special characters](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet) as Github [does not treat](https://github.com/orgs/community/discussions/50835#discussioncomment-5428789) `on.workflow_run.workflows` literally.\n\n## Project layout\n\nThis project is laid out as follows:\n\n```\n.\n├── action.yml       # The `review` Action\n├── Dockerfile\n└── post\n    ├── action.yml   # The `post` Action\n    ├── Dockerfile\n    └── clang_tidy_review      # Common python package\n        └── clang_tidy_review\n            ├── __init__.py\n            ├── post.py        # Entry point for `post`\n            └── review.py      # Entry point for `review`\n```\n\nIn order to accommodate the split workflow, the `review` and `post`\nactions must have their own Action metadata files. GitHub requires\nthis file to be named exactly `action.yml`, so they have to be in\nseparate directories. The associated `Dockerfile`s must also be named\nexactly `Dockerfile`, so they also have to be separate directories.\n\nLastly, we want to be able to reuse the python package between the two\nActions, which means it must be in a subdirectory of _both_\n`Dockerfile`s because they can't see parent directories.\n\nWhich is why we've ended up with this slightly strange structure! This\nway, we can `COPY` the python package into both Docker images.\n\n\n## Real world project samples\n|Project|Workflow|\n|----------|-------|\n|[BOUT++](https://github.com/boutproject/BOUT-dev) |[CMake](https://github.com/boutproject/BOUT-dev/blob/master/.github/workflows/clang-tidy-review.yml) |\n|[Mudlet](https://github.com/Mudlet/Mudlet) |[CMake + Qt](https://github.com/Mudlet/Mudlet/blob/development/.github/workflows/clangtidy-diff-analysis.yml) |\n\n\n\n[env_vars]: https://docs.github.com/en/actions/learn-github-actions/environment-variables#default-environment-variables\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzedthree%2Fclang-tidy-review","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzedthree%2Fclang-tidy-review","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzedthree%2Fclang-tidy-review/lists"}