From 96e2a5fb99610ae4c2d1d76a14ac918bede15786 Mon Sep 17 00:00:00 2001 From: Arun Bhalla Date: Mon, 24 Mar 2025 11:52:32 -0700 Subject: [PATCH 1/2] Update docs for this repository https://github.com/ekline-io/ekline-github-action based on the git diff --- README.md | 152 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..cc4af64 --- /dev/null +++ b/README.md @@ -0,0 +1,152 @@ +# EkLine GitHub Action + +[![Test](https://github.com/ekline-io/ekline-github-action/workflows/Test/badge.svg)](https://github.com/ekline-io/ekline-github-action/actions?query=workflow%3ATest) +[![release](https://github.com/ekline-io/ekline-github-action/workflows/release/badge.svg)](https://github.com/ekline-io/ekline-github-action/actions?query=workflow%3Arelease) +[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/ekline-io/ekline-github-action?logo=github&sort=semver)](https://github.com/ekline-io/ekline-github-action/releases) +[![release](https://ghcr-badge.egpl.dev/ekline-io/ekline-ci-cd/latest_tag?label=Docker%20version%20ekline_ci_cd)](https://github.com/ekline-io/ekline-cli/pkgs/container/ekline-cli) + +Improve the quality and consistency of your documentation with EkLine, an automated review tool for your GitHub repositories. This action integrates seamlessly with your existing GitHub workflow, allowing you to maintain high-quality documentation. + + +* [EkLine GitHub Action](#ekline-github-action) + * [Input](#input) + * [Usage](#usage) + * [Reporters](#reporters) + * [Reporter: GitHub Checks (reporter: github-pr-check)](#reporter-github-checks-reporter-github-pr-check) + * [Reporter: GitHub Checks (reporter: github-check)](#reporter-github-checks-reporter-github-check) + * [Reporter: GitHub PullRequest review comment (reporter: github-pr-review)](#reporter-github-pullrequest-review-comment-reporter-github-pr-review) + * [Filter mode](#filter-mode) + * [`added` (default)](#added-default) + * [`diff_context`](#diff_context) + * [`file`](#file) + * [`nofilter`](#nofilter) + * [Filter Mode Support Table](#filter-mode-support-table) + * [Ignoring Specific Rules](#ignoring-specific-rules) + +* [EkLine Documentation](https://ekline.notion.site/EkLine-Documentation-820e545d76214d9d9cb2cbf627c19613) + +## Input + +```yaml +inputs: + content_dir: + description: 'Content directories relative to the root. Specify a single path or multiple paths (one per line). Example: + content_dir: ./testData + content_dir: | + ./testData + ./testData2' + default: '.' + ek_token: + description: 'Token for EkLine application' + required: true + filter_mode: + description: | + Filtering mode for the EkLine reviewer command [added,diff_context,file,nofilter]. + Default is added. + default: 'added' + github_token: + description: 'GITHUB_TOKEN' + default: '${{ secrets.github_token }}' + reporter: + description: 'Reporter of EkLine review command [github-pr-check,github-check,github-pr-review].' + default: 'github-pr-check' + ignore_rule: + description: 'Ignore the rules that are passed in as comma-separated values (eg: EK00001,EK00004). Use this flag to skip specific rules during the review process.' + default: '' + debug: + description: 'Enable debug mode to print all environment variables starting with INPUT_ when set to true.' + default: 'false' + openapi_spec: + description: 'Path to the OpenAPI specification file to be reviewed.' + default: '' +``` + +## Usage + +```yaml +name: EkLine +on: + push: + branches: + - master + - main + pull_request: +jobs: + test-pr-review: + if: github.event_name == 'pull_request' + name: runner / EkLine Reviewer (github-pr-review) + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: ekline-io/ekline-github-action@v6 + with: + content_dir: ./src/docs + ek_token: ${{ secrets.ek_token }} + github_token: ${{ secrets.github_token }} + reporter: github-pr-review + ignore_rule: "EK00010,EK00003" # Optional + openapi_spec: './path/to/openapi.yaml' # Optional +``` + +## Reporters + +EkLine reviewer can report results in review services as +continuous integration. + +### Reporter: GitHub Checks (reporter: github-pr-check) + +github-pr-check reporter reports results to [GitHub Checks](https://help.github.com/articles/about-status-checks/). + +### Reporter: GitHub Checks (reporter: github-check) + +It's essentially the same as `reporter: github-pr-check` except it works not only for +Pull Request but also for commit. + +### Reporter: GitHub PullRequest review comment (reporter: github-pr-review) + +![sample-github-pr-review.png](./image/sample-github-pr-review.png) + +github-pr-review reporter reports results to GitHub PullRequest review comments +using GitHub Personal API Access Token. +[GitHub Enterprise](https://enterprise.github.com/home) supports this too. + +- Go to https://github.com/settings/tokens and generate new API token. +- Check `repo` for private repositories or `public_repo` for public repositories. + +## Filter mode +You can control how EkLine reviewer filter results by `-filter-mode` flag. +Available filter modes are as below. + +### `added` (default) +Filter results by added/modified lines. +### `diff_context` +Filter results by diff context. that is, changed lines +-N lines (N=3 for example). +### `file` +Filter results by added/modified file. That is, EkLine reviewer reports results as long as they're in added/modified file even if the results aren't in actual diff. +### `nofilter` +Don't filter any results. Useful for posting results as comments as much as possible and check other results in console at the same time. + +### Filter Mode Support Table +Note that not all reporters provide full support of filter mode due to API limitation. +for example `github-pr-review` reporter uses [GitHub Review +API](https://developer.github.com/v3/pulls/reviews/) but it doesn't support posting comment outside diff (`diff_context`), +so EkLine reviewer uses [Check annotation](https://developer.github.com/v3/checks/runs/) as fallback to post those comments [1]. + +| `reporter` \ `filter-mode` | `added` | `diff_context` | `file` | `nofilter` | +| -------------------------- | ------- | -------------- | ----------------------- | ---------- | +| **`github-check`** | OK | OK | OK | OK | +| **`github-pr-check`** | OK | OK | OK | OK | +| **`github-pr-review`** | OK | OK | Supported [1] | Supported [1] | + +- [1] Report results which are outside diff context with Check annotation as fallback if it's running in GitHub actions instead of Review API (comments). The console also shows all results. + +### Ignoring Specific Rules + +To ignore specific rules during the review process, you can use the `ignore_rule` flag. This flag accepts a comma-separated list of rule identifiers that you wish to skip. + +For example, if you want to ignore rules `EK00001` and `EK00004`, you can set the `ignore_rule` flag in your configuration like this: +```yaml + ignore_rule: "EK00001,EK00004" +``` + +By following this updated documentation, users learn about the new `openapi_spec` input parameter, how to utilize it, and how it integrates into the existing EkLine GitHub Action workflow. \ No newline at end of file From 24b916f050999f9bbd272602b6cd40620588c84d Mon Sep 17 00:00:00 2001 From: Arun Bhalla Date: Mon, 24 Mar 2025 11:52:33 -0700 Subject: [PATCH 2/2] Update docs for this repository https://github.com/ekline-io/ekline-github-action based on the git diff --- action.yml | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 action.yml diff --git a/action.yml b/action.yml new file mode 100644 index 0000000..1ee2e3b --- /dev/null +++ b/action.yml @@ -0,0 +1,74 @@ +````yaml +name: 'EkLine (GitHub Action)' +description: '📝 Optimize and improve your documentation website.' +author: 'EkLine' +inputs: + github_token: + description: 'GITHUB_TOKEN' + default: '${{ github.token }}' + workdir: + description: 'Working directory relative to the root directory.' + default: '.' + ### Flags for reviewdog ### + level: + description: 'Report level for reviewdog [info,warning,error]' + default: 'info' + reporter: + description: 'Reporter of reviewdog command [github-pr-check,github-pr-review].' + default: 'github-pr-check' + filter_mode: + description: | + Filtering mode for the reviewdog command [added,diff_context,file,nofilter]. + Default is added. + default: 'added' + fail_on_error: + description: | + Exit code for reviewdog when errors are found [true,false] + Default is `false`. + default: 'false' + reviewdog_flags: + description: 'Additional reviewdog flags' + default: '' + ### Flags for EkLine Reviewer ### + ek_token: + description: 'Token for EkLine application' + required: true + content_dir: + description: 'Content directories relative to the root. Specify a single path or multiple paths (one per line). Example: + content_dir: ./testData + content_dir: | + ./testData + ./testData2' + default: '.' + ignore_rule: + description: 'Ignore the rules that are passed in as comma separated values (eg: EK1,EK4)' + default: '' + enable_ai_suggestions: + description: 'Enable AI suggestions' + default: false + openapi_spec: + description: 'Path to the OpenAPI specification file to be reviewed.' + default: '' +runs: + using: 'docker' + image: 'Dockerfile' + +# Ref: https://haya14busa.github.io/github-action-brandings/ +branding: + icon: 'book-open' + color: 'blue' +``` + +### Explanation of updates + +1. **New Input Parameter:** + - A new input parameter `openapi_spec` allows users to specify a path to an OpenAPI specification file for review. + - The description states that this parameter is for specifying the OpenAPI specification file path. + +2. **Optional Parameter:** + - Since the `openapi_spec` parameter is optional, there is no `required` field, and its default value defaults to an empty string, indicating that it does not need a specification unless necessary. + +3. **Documentation Consistency:** + - The addition of the `openapi_spec` parameter is consistent with the existing documentation format, ensuring clarity and ease of understanding for users. This update integrates seamlessly with the existing workflow, providing enhanced capabilities for documentation checks. + +These updates ensure that users learn about the new feature and how to use it without altering the existing functionality.` \ No newline at end of file