{"id":22128616,"url":"https://github.com/redhat-plumbers-in-action/advanced-commit-linter","last_synced_at":"2025-07-25T18:31:38.675Z","repository":{"id":103147720,"uuid":"558241147","full_name":"redhat-plumbers-in-action/advanced-commit-linter","owner":"redhat-plumbers-in-action","description":"🎫 🔍 Check if your commit messages are in correct format based on policy","archived":false,"fork":false,"pushed_at":"2024-11-01T12:03:04.000Z","size":16219,"stargazers_count":2,"open_issues_count":4,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-25T09:35:40.778Z","etag":null,"topics":["cherry-pick","commit-message","github-action","policy-based","tickets","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/redhat-plumbers-in-action.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2022-10-27T06:49:55.000Z","updated_at":"2024-11-01T12:03:07.000Z","dependencies_parsed_at":null,"dependency_job_id":"aed017d9-9cd1-4dc5-831d-97b4deba7d61","html_url":"https://github.com/redhat-plumbers-in-action/advanced-commit-linter","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":"actions/typescript-action","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-plumbers-in-action%2Fadvanced-commit-linter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-plumbers-in-action%2Fadvanced-commit-linter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-plumbers-in-action%2Fadvanced-commit-linter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-plumbers-in-action%2Fadvanced-commit-linter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/redhat-plumbers-in-action","download_url":"https://codeload.github.com/redhat-plumbers-in-action/advanced-commit-linter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227606220,"owners_count":17792786,"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":["cherry-pick","commit-message","github-action","policy-based","tickets","typescript"],"created_at":"2024-12-01T17:46:17.723Z","updated_at":"2024-12-01T17:46:18.354Z","avatar_url":"https://github.com/redhat-plumbers-in-action.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- markdownlint-disable MD033 MD041 --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/redhat-plumbers-in-action/team/blob/30bfefc6f64a5e4f84dc58397dffcf4b829176f4/members/white-plumber.png\" width=\"100\" /\u003e\n  \u003ch1 align=\"center\"\u003eAdvanced Commit Linter\u003c/h1\u003e\n\u003c/p\u003e\n\n[![GitHub Marketplace][market-status]][market] [![Tests][test-status]][test] [![Lint Code Base][linter-status]][linter] [![CodeQL][codeql-status]][codeql] [![Check dist/][check-dist-status]][check-dist] [![codecov][codecov-status]][codecov]\n\n\u003c!-- Status links --\u003e\n\n[market]: https://github.com/marketplace/actions/advanced-commit-linter\n[market-status]: https://img.shields.io/badge/Marketplace-Advanced%20Commit%20Linter-blue.svg?colorA=24292e\u0026colorB=0366d6\u0026style=flat\u0026longCache=true\u0026logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAM6wAADOsB5dZE0gAAABl0RVh0U29mdHdhcmUAd3d3Lmlua3NjYXBlLm9yZ5vuPBoAAAERSURBVCiRhZG/SsMxFEZPfsVJ61jbxaF0cRQRcRJ9hlYn30IHN/+9iquDCOIsblIrOjqKgy5aKoJQj4O3EEtbPwhJbr6Te28CmdSKeqzeqr0YbfVIrTBKakvtOl5dtTkK+v4HfA9PEyBFCY9AGVgCBLaBp1jPAyfAJ/AAdIEG0dNAiyP7+K1qIfMdonZic6+WJoBJvQlvuwDqcXadUuqPA1NKAlexbRTAIMvMOCjTbMwl1LtI/6KWJ5Q6rT6Ht1MA58AX8Apcqqt5r2qhrgAXQC3CZ6i1+KMd9TRu3MvA3aH/fFPnBodb6oe6HM8+lYHrGdRXW8M9bMZtPXUji69lmf5Cmamq7quNLFZXD9Rq7v0Bpc1o/tp0fisAAAAASUVORK5CYII=\n\n[linter]: https://github.com/redhat-plumbers-in-action/advanced-commit-linter/actions/workflows/lint.yml\n[linter-status]: https://github.com/redhat-plumbers-in-action/advanced-commit-linter/actions/workflows/lint.yml/badge.svg\n\n[test]: https://github.com/redhat-plumbers-in-action/advanced-commit-linter/actions/workflows/test.yml\n[test-status]: https://github.com/redhat-plumbers-in-action/advanced-commit-linter/actions/workflows/test.yml/badge.svg\n\n[codeql]: https://github.com/redhat-plumbers-in-action/advanced-commit-linter/actions/workflows/codeql-analysis.yml\n[codeql-status]: https://github.com/redhat-plumbers-in-action/advanced-commit-linter/actions/workflows/codeql-analysis.yml/badge.svg\n\n[check-dist]: https://github.com/redhat-plumbers-in-action/advanced-commit-linter/actions/workflows/check-dist.yml\n[check-dist-status]: https://github.com/redhat-plumbers-in-action/advanced-commit-linter/actions/workflows/check-dist.yml/badge.svg\n\n[codecov]: https://codecov.io/gh/redhat-plumbers-in-action/advanced-commit-linter\n[codecov-status]: https://codecov.io/gh/redhat-plumbers-in-action/advanced-commit-linter/branch/main/graph/badge.svg?token=YO0RD8EESQ\n\n\u003c!-- --\u003e\n\nAdvanced Commit Linter is a GitHub Action that lint commit messages of PR. It checks for issue trackers and upstream references. Results can be displayed as a status check or Pull Request comment when used together with [issue-commentator](https://github.com/redhat-plumbers-in-action/issue-commentator) GitHub Action.\n\n## How does it work\n\nTBA\n\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/images/linter-comment-dark.png\"\u003e\n  \u003cimg src=\"docs/images/linter-comment-light.png\" width=\"600\" /\u003e\n\u003c/picture\u003e\n\n## Features\n\n* Tracker references validator\n* Upstream references (cherry-pick) validator\n\n## Usage\n\nTo set up Advanced Commit Linter, we need three files:\n\n* Workflow that captures Pull Request metadata (number and commit metadata) and uploads this data as an artifact\n* Workflow that runs on `workflow-run` trigger, downloads artifact, and runs `advanced-commit-linter` GitHub Action\n* `advanced-commit-linter.yml` configuration\n\n\u003e [!NOTE]\n\u003e\n\u003e Setup is complicated due to GitHub [permissions on `GITHUB_TOKEN`](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token). When used in workflow executed from fork it has `read-only` permissions. By using the `workflow-run` trigger we are able to [safely overcome this limitation](https://securitylab.github.com/research/github-actions-preventing-pwn-requests/) and it allows us to comment on Pull Requests.\n\n```yml\npolicy:\n  cherry-pick:\n    upstream:\n      - github: systemd/systemd\n      - github: systemd/systemd-stable\n    exception:\n      note:\n        - rhel-only\n  tracker:\n    - keyword:\n        - 'Resolves: #'\n        - 'Related: #'\n      type: bugzilla\n      issue-format:\n        - '[0-9]+$'\n      url: 'https://bugzilla.redhat.com/show_bug.cgi?id='\n      exception:\n        note:\n          - github-only\n    - keyword:\n        - 'Resolves: '\n        - 'Related: '\n      type: jira\n      issue-format:\n        - 'JIRA-1234'\n      url: 'https://issues.redhat.com/browse/'\n      exception:\n        note:\n          - github-only\n```\n\n```yml\nname: Gather Pull Request Metadata\non:\n  pull_request:\n    types: [ opened, reopened, synchronize ]\n    branches: [ main ]\n\npermissions:\n  contents: read\n\njobs:\n  gather-metadata:\n    runs-on: ubuntu-latest\n\n    steps:\n      - name: Repository checkout\n        uses: actions/checkout@v3\n\n      - id: Metadata\n        name: Gather Pull Request Metadata\n        uses: redhat-plumbers-in-action/gather-pull-request-metadata@v1\n\n      - name: Upload artifact with gathered metadata\n        uses: actions/upload-artifact@v3\n        with:\n          name: pr-metadata\n          path: ${{ steps.Metadata.outputs.metadata-file }}\n```\n\n```yml\nname: Commit Linter\non:\n  workflow_run:\n    workflows: [ Gather Pull Request Metadata ]\n    types:\n      - completed\n\npermissions:\n  contents: read\n\njobs:\n  download-metadata:\n    if: \u003e\n      github.event.workflow_run.event == 'pull_request' \u0026\u0026\n      github.event.workflow_run.conclusion == 'success'\n    runs-on: ubuntu-latest\n\n    outputs:\n      pr-metadata: ${{ steps.Artifact.outputs.pr-metadata-json }}\n\n    steps:\n      - id: Artifact\n        name: Download Artifact\n        uses: redhat-plumbers-in-action/download-artifact@v1\n        with:\n          name: pr-metadata\n\n  commit-linter:\n    needs: [ download-metadata ]\n    runs-on: ubuntu-latest\n\n    outputs:\n      validated-pr-metadata: ${{ steps.commit-linter.outputs.validated-pr-metadata }}\n\n    permissions:\n      # required for creation of checks\n      checks: write\n\n    steps:\n      - id: commit-linter\n        name: Lint Commits\n        uses: redhat-plumbers-in-action/advanced-commit-linter@v1\n        with:\n          pr-metadata: ${{ needs.download-metadata.outputs.pr-metadata }}\n          token: ${{ secrets.GITHUB_TOKEN }}\n```\n\n## Configuration options\n\nAction currently accepts the following options:\n\n```yml\n# ...\n\n- uses: redhat-plumbers-in-action/advanced-commit-linter@v1\n  with:\n    pr-metadata:    \u003cpr-metadata.json\u003e\n    config-path:    \u003cpath to config file\u003e\n    set-status:     \u003ctrue or false\u003e\n    status-title:  \u003ch3 title of status message\u003e\n    token:          \u003cGitHub token or PAT\u003e\n\n# ...\n```\n\n### pr-metadata\n\nStringified JSON Pull Request metadata provided by GitHub Action [`redhat-plumbers-in-action/gather-pull-request-metadata`](https://github.com/redhat-plumbers-in-action/gather-pull-request-metadata).\n\nPull Request metadata has the following format: [metadata format](https://github.com/redhat-plumbers-in-action/gather-pull-request-metadata#metadata)\n\n* default value: `undefined`\n* requirements: `required`\n\n### config-path\n\nPath to configuration file. Configuration file format is described in: [Policy section](#policy).\n\n* default value: `.github/advanced-commit-linter.yml`\n* requirements: `optional`\n\n### set-status\n\nSet status on Pull Request. If enabled, Action will create check-run with validation results.\n\n* default value: `false`\n* requirements: `optional`\n\n### status-title\n\nOptional H3 title of status message.\n\n* default value: `Commit validation`\n* requirements: `optional`\n\n### token\n\nGitHub token or PAT is used for setting status checks on Pull Request.\n\n```yml\n# required permission\npermissions:\n  checks: write\n  pull-requests: write\n```\n\n* default value: `undefined`\n* requirements: `required`\n* recomended value: `secrets.GITHUB_TOKEN`\n\n## Policy\n\nAction is configured using special policy file: `.github/advanced-commit-linter.yml`. The structure needs to be as follows:\n\n```yml\npolicy:\n  cherry-pick:\n    upstream:\n      - github: systemd/systemd\n      - github: systemd/systemd-stable\n    exception:\n      note:\n        - rhel-only\n  tracker:\n    - keyword:\n        - 'Resolves: #'\n        - 'Related: #'\n      type: bugzilla\n      issue-format:\n        - '[0-9]+$'\n      url: 'https://bugzilla.redhat.com/show_bug.cgi?id='\n      exception:\n        note:\n          - github-only\n    - keyword:\n        - 'Resolves: '\n        - 'Related: '\n      type: jira\n      issue-format:\n        - 'RHELPLAN-\\d+$'\n      url: 'https://issues.redhat.com/browse/'\n      exception:\n        note:\n          - github-only\n```\n\n### `cherry-pick` keyword\n\nThe section that specifies upstreams for which you frequently cherry-pick.\n\n* requirements: `optional`\n\n### `cherry-pick.upstream` keyword\n\nAn array of upstreams. Currently, the only supported upstream location is GitHub.\n\nSupported keys:\n\n* `github` - GitHub repository in format `\u003corg\u003e/\u003crepo\u003e`\n* requirements: `required`\n\n### `cherry-pick.exception` keyword\n\nProperty that describes possible exceptions for referencing upstream commits in commit messages. Currently supported exceptions:\n\n* `note` - for example `downstream-only` or `rhel-only`\n\n### `tracker` keyword\n\nThe section specifies the form and type of required trackers.\n\n### `tracker[].keyword` keyword\n\nKeyword that prefixes tracker identificator.\n\n* requirements: `required`\n* example: `Fixes:`\n\n### `tracker[].type` keyword\n\nType of tracker. Data can be used by postprocessing scripts/GitHub Actions.\n\nCurrently supproted types of trackers are: `bugzilla`, `jira` and `unknown`.\n\n* requirements: `required`\n\n### `tracker[].issue-format` keyword\n\nRegex that describes identificator of given tracker.\n\n* requirements: `required`\n* example: `[0-9]+$`\n\n### `tracker[].url` keyword\n\nUrl to better display detected trackers in Pull Request comment as a link. Tracker ID will be appended at the end of `url`.\n\n* requirements: `optional`\n* example: `https://issues.redhat.com/browse/`\n\n### `tracker[].exception` keyword\n\nProperty that describes possible exceptions for referencing trackers in commit messages. Currently supported exceptions:\n\n* `note` - for example `github-only` or `tests-only`\n\n## Outputs\n\n### validated-pr-metadata\n\n\u003cdetails\u003e\n  \u003csummary\u003eExample of validated metadata object\u003c/summary\u003e\n\n  ```ts\n  const metadata = {\n    number: 15,\n    labels: [\n      {\n        id: 5610751380,\n        name: 'bug',\n        description: 'Bug label',\n      },\n    ],\n    milestone: {},\n    commits: [\n      {\n        sha: 'b145cbd729d33cc50d299079a9a5c643531ad053',\n        url: 'https://github.com/redhat-plumbers-in-action/advanced-commit-linter/commit/b145cbd729d33cc50d299079a9a5c643531ad053',\n        message: {\n          title: 'fix Typo in README.md',\n          body: 'fix: typo\\\n  \\\n  rhel-only\\\n  \\\n  Related: RHELPLAN-1234',\n          cherryPick: [],\n        },\n        validation: {\n          status: 'success',\n          message:\n            '| https://github.com/redhat-plumbers-in-action/advanced-commit-linter/commit/b145cbd729d33cc50d299079a9a5c643531ad053 - _fix: typo_ | `rhel-only` |',\n          tracker: {\n            status: 'success',\n            message:\n              '[RHELPLAN-1234](https://issues.redhat.com/browse/RHELPLAN-1234)',\n            data: [\n              {\n                data: {\n                  keyword: 'Related: ',\n                  id: 'RHELPLAN-1234',\n                  type: 'jira',\n                  url: 'https://issues.redhat.com/browse/RHELPLAN-1234',\n                },\n              },\n            ],\n          },\n          upstream: {\n            data: [],\n            status: 'success',\n            exception: 'rhel-only',\n          },\n        },\n      },\n    ],\n    validation: {\n      status: 'success',\n      tracker: {\n        message: 'Tracker found',\n        type: 'unknown',\n        id: 'RHELPLAN-1234',\n        url: 'https://issues.redhat.com/browse/RHELPLAN-1234',\n      },\n      message:\n        'Tracker - [RHELPLAN-1234](https://issues.redhat.com/browse/RHELPLAN-1234)\\\n  \\\n  #### The following commits meet all requirements\\\n  \\\n  | commit | upstream |\\\n  |---|---|\\\n  | https://github.com/redhat-plumbers-in-action/advanced-commit-linter/commit/b145cbd729d33cc50d299079a9a5c643531ad053 - _fix: typo_ | `rhel-only` |',\n    },\n  };\n  ```\n\n\u003c/details\u003e\n\n#### `commits[].validation.status` keyword\n\nStatus of commit validation. Can be one of the following values:\n\n* `success` - commit meets all requirements\n* `failure` - commit does not meet all requirements\n\n#### `commits[].validation.message` keyword\n\nMessage that describes commit validation status.\n\n#### `commits[].validation.tracker` keyword\n\nObject that describes all trackers detected in commit message and their validation status.\n\n```ts\ntracker: {\n  status: 'success',\n  message: '[RHELPLAN-1234](https://issues.redhat.com/browse/RHELPLAN-1234)',\n  data: [{\n    data: {\n      keyword: 'Related: ',\n      id: 'RHELPLAN-1234',\n      type: 'jira',\n      url: 'https://issues.redhat.com/browse/RHELPLAN-1234',\n    },\n  }],\n}\n```\n\n#### `commits[].validation.upstream` keyword\n\nObject that describes all upstreams detected in commit message and their validation status.\n\n```ts\nupstream: {\n  data: [{\n    sha: 'b145cbd729d33cc50d299079a9a5c643531ad053',\n    repo: 'systemd/systemd',\n    url: 'https://github.com/systemd/systemd/commit/b145cbd729d33cc50d299079a9a5c643531ad053',\n  }],\n  status: 'success',\n  exception: 'rhel-only',\n}\n```\n\n#### `validation` keyword\n\nObject that describes overall validation status of all commits in Pull Request.\n\n```ts\nvalidation: {\n  status: 'success',\n  tracker: {\n    message: 'Tracker found',\n    type: 'unknown',\n    id: 'RHELPLAN-1234',\n    url: 'https://issues.redhat.com/browse/RHELPLAN-1234',\n  },\n  message:\n    'Tracker - [RHELPLAN-1234](https://issues.redhat.com/browse/RHELPLAN-1234)\\\n\\\n#### The following commits meet all requirements\\\n\\\n| commit | upstream |\\\n|---|---|\\\n| https://github.com/redhat-plumbers-in-action/advanced-commit-linter/commit/b145cbd729d33cc50d299079a9a5c643531ad053 - _fix: typo_ | `rhel-only` |',\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredhat-plumbers-in-action%2Fadvanced-commit-linter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fredhat-plumbers-in-action%2Fadvanced-commit-linter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredhat-plumbers-in-action%2Fadvanced-commit-linter/lists"}