GitHub Integration

Prerequisites

Before you begin, ensure you have the following:

• An EkLine API token. You can obtain this by navigating to EkLine.io > Settings > Organization > Access Token.

Create a new GitHub Actions workflow

In your GitHub repository, navigate to the "Actions" tab. Click "New workflow" and choose the "set up a workflow yourself" option.

In the new workflow file, you can name it ekline.yml. GitHub stores this file in the .github/workflows/ directory in your repository.

Configure the EkLine GitHub action

Copy and paste the following template into your workflow file:

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
    permissions:
      contents: read
      pull-requests: write
    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
          filter_mode: added
          # ignore_rule: "EK00001,EK00004" # Optional

Adjust the configuration options as needed for your specific use case. The available options are:

• content_dir: The content directory relative to the root directory (default: .).
• ek_token: The token for the EkLine application (required).
• filter_mode: The filtering mode for the EkLine reviewer command [added, diff_context, file, nofilter] (default: added).
• github_token: The GITHUB_TOKEN (default: ${{ secrets.github_token }}).
• reporter: The reporter of the EkLine review command [github-pr-check, github-check, github-pr-review] (default: github-pr-check).

Filter modes

You can control how the EkLine reviewer filters results by specifying the filter_mode option. Available filter modes are as below:

• added (default): Filter results by added or modified lines.
• diff_context: Filter results by diff context. That's, changed lines +-N lines (N=3, for example).
• file: Filter results by added or modified file. EkLine reviewer reports results as long as they're in an added or modified file, even if the results aren't in the actual diff.
• nofilter: Don't filter any results. Useful for posting results as comments as much as possible and checking other results in the console simultaneously.

Reporter types

• github-pr-check: Reports results to GitHub Checks.
• github-check: Similar to github-pr-check, but works for both pull requests and commits.
• github-pr-review: Reports results to GitHub PullRequest review comments using a GitHub Personal API Access Token.

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:

			  ignore_rule: "EK00001,EK00004"

Save and commit the workflow file

After configuring the workflow file, click "Start commit" to save and commit the file to your repository. The EkLine GitHub Action runs automatically when you push changes to the master or main branches or create a pull request.

Add the EkLine API token to your repository secrets

Before the action can work, you need to provide the EkLine API token. Go to your repository settings, navigate to the "Secrets" tab, and add a new secret with the name ek_token. Paste your EkLine API token as the value.

Grant write permissions to workflows

To enable the EkLine GitHub Action to add comments to pull requests, you must grant write permissions to workflows. There are two ways to achieve this:

Option 1: Through repository settings

1. Navigate to Settings > Code and Automation > Actions > General > Workflow permissions.
2. Click the drop-down menu and select Read and write permissions.
3. Click on Save to apply the changes.

Option 2: Through the workflow file

Add the following permissions block to your workflow file:

permissions:
  contents: read
  pull-requests: write

Check the EkLine GitHub Action results

Once the EkLine GitHub Action runs, you can view the results in the "Actions" tab of your repository.

Now, you have integrated the EkLine GitHub Action into your repository for automated documentation review. Enjoy better quality and consistency in your documentation.

Other options

EkLine GitHub Action on Label