Integrations


[GitHub Integration](/documentation/github-integration)

[GitLab Integration](/documentation/gitlab-integration)

[CLI](/documentation/cli-integration)

[VSCode Integration](/documentation/vscode-integration)

[Bitbucket Integration](/documentation/bitbucket-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:

```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
    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.


<img
    className={'rounded-2xl'}
    width={1880}
    height={1044}
    src={`/assets/images/docs/secrets.png`}
    alt={`Update Secrets`}
/>

## 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.

<img
    className={'rounded-2xl'}
    width={1880}
    height={1044}
    src={`/assets/images/docs/workflow.png`}
    alt={`Grant write permissions to workflows`}
/>

### Option 2: Through the workflow file

Add the following permissions block to your workflow file:

```yaml
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](/documentation/github-action-label)

This guide will walk you through using the EkLine GitHub Action for automated documentation review in your GitHub repositories.

EkLine GitHub Integration Guide


## Prerequisites

- A GitHub repository with EkLine set up.
- EkLine GitHub Action configured in your repository.

## Steps

1. Open the **`.github/workflows/ekline.yml`** file in your GitHub repository.
2. Change the **`on`** section of the GitHub action to trigger on **`pull_request`** with **`types: [labeled]`**:
```yaml
on:
  pull_request:
    types: [labeled]
```
3. Add a new **`if`** condition to the **`jobs`** section to check if the label "ekline" is present:
```
jobs:
  test-pr-review:
    if: contains(github.event.label.name, 'ekline')
```
4. Save the changes to **`ekline.yml`** file.
The updated **`ekline.yml`** appears like this:
```yaml
name: EkLine
on:
  pull_request:
    types: [labeled]

jobs:
  test-pr-review:
    if: contains(github.event.label.name, 'ekline')
    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
          filter_mode: added
          # ignore_rule: "EK00001,EK00004" # Optional
```

With these changes, EkLine GitHub Action triggers when someone adds a label named "ekline" to a pull request.

## Usage

Add the "ekline" label to a specific pull request to run the EkLine GitHub Action. Upon adding the label, the action triggers and executes the configured checks.

This guide helps configure the EkLine GitHub Action to run when a specific label, named 'ekline', gets added to a pull request.

EkLine GitHub Action on Label


## Prerequisites

1. You have an EkLine API token provided by the EkLine contact person.
2. You have a GitLab account and a GitLab API token.

## Create `.gitlab-ci.yml` file

Create a new file named **`.gitlab-ci.yml`** in your project's root directory and add the following content:

```yaml
stages:
  - ekline-pr-review

ekline-pr-review-job:
  stage: ekline-pr-review
  image: ghcr.io/ekline-io/ekline-ci-cd:v6
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  script:
    - echo "Running EkLine"
  variables:
    INPUT_EK_TOKEN: $EK_TOKEN
    INPUT_GITLAB_TOKEN: $GITLAB_API_TOKEN
    INPUT_CONTENT_DIR: '<path_to_content_directory>'
    INPUT_REPORTER: 'gitlab-mr-discussion'
    INPUT_FILTER_MODE: 'added'
    # INPUT_IGNORE_RULE: "EK00001,EK00004" # Optional
```

Replace **`<path_to_content_directory>`** with the actual path to your content directory.

## Configure GitLab API Token

1. In GitLab, go to Settings > Access tokens.
2. Create a token with API access.
3. Add the token to your project's CI/CD > Variables as **`GITLAB_API_TOKEN`**.

## Configure EkLine API Token

1. Obtain your **`EK_TOKEN`** from the EkLine contact person.
2. Add the token to your project's CI/CD > Variables as **`EK_TOKEN`**.

## Configure Input Reporter (Optional)

You can choose between two options for **`INPUT_REPORTER`**:

- **`gitlab-mr-discussion`** (default): Reports results as merge request discussions.
- **`gitlab-mr-commit`**: Reports results to each commit in GitLab MergeRequest.

## Configure Input Filter Mode (Optional)

The following options are available for **`INPUT_FILTER_MODE`**:

- **`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 will report results as long as they are in added or modified files 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 check other results in the console at the same time.

## Ignoring Specific Rules (Optional)

To ignore specific rules during the review process, you can use the `INPUT_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 `INPUT_IGNORE_RULE` flag in your configuration like this:

```
  INPUT_IGNORE_RULE: "EK00001,EK00004"
```

Once you have configured the options, save your changes and push the **`.gitlab-ci.yml`** file to your repository. Now, EkLine will run on your content directory and give feedback as merge request discussions.

This guide will walk you through setting up the EkLine integration with GitLab.

EkLine GitLab Integration Guide


## Installation

Download the suitable EkLine binary for your operating system from this [link](https://github.com/ekline-io/ekline-cli-binaries/releases/latest).

## Usage

To use the EkLine CLI, execute the following command:

```bash
ekline-cli [options]
```

### Options

The following options can be used with the EkLine CLI:

- **v, --version**

Displays the current version of the EkLine CLI.

- **d, --debug**

Enables verbose logging to provide detailed debug information.

- **o, --output `<output-file-name>`**

Specifies the output filename. If not provided, the output is displayed in the terminal. For JSON output, use the file extension **`.jsonl`**. For CSV output, use the file extension **`.csv`**.

- **ns, --no-suggestion**

Disables suggestions. Please note that suggestions are only generated for **`.jsonl`** or **`.csv`** output formats.

- **i, --ignore `<rules>`**

Ignore specified rules during the check. Pass the rules as comma-separated values. For example, **`EK1,EK4`**.

- **cd, --content-directory `<contentDirectory...>`**

Specifies the directory paths where the content files are located. Paths should be relative to the current directory.

- **et, --ek-token `<token>`**

Authorizes your Ekline.io API token. This field is mandatory.

- **h, --help**

Displays the command's help information.


## Examples

Below are a few examples of using the EkLine CLI:

1. **Running EkLine CLI and ignoring specific rules**

```bash
ekline-cli -i EK1,EK4 --ek-token YOUR_EKLINE_TOKEN
```

2. **Running EkLine CLI and specifying a content directory**

```bash
ekline-cli -cd ./content --ek-token YOUR_EKLINE_TOKEN
```

Make sure to replace **`YOUR_EKLINE_TOKEN`** with your actual Ekline.io API token in these examples.

The EkLine CLI streamlines document quality control. This guide explains the available options and provides examples for effectively using the EkLine CLI.

EkLine CLI Documentation


## Prerequisites

You have an EkLine API token provided by the EkLine contact person.

## Getting started

### Installation

To install the VSCode extension from the web, follow these steps:

1. Visit the [EkLine Extension Page](https://marketplace.visualstudio.com/items?itemName=EkLine.ekline-vscode) on VSCode Marketplace.
2. Click Install.
3. Open Visual Studio Code when prompted.

Or,

To install the VSCode extension from within VSCode,

1. Open Visual Studio Code.
2. Click on the Extensions icon in the Activity Bar on the side of the window to access the Extensions view.
3. Type "EkLine" in the Extensions view search box.
4. Click the "Install" button next to the extension with the same name.

### Configure EkLine linter

EkLine asks for an API Token at first activation.

If you cancel or input an invalid token, the extension displays a popup offering another chance to set up EkLine or turn off for avoiding future popups.
Once turned off, execute 'Configure EkLine Linter' from the Command Palette or clear the 'off' box in Extension Settings.

## Usage

The extension runs EkLine on supported files when opened or saved.

To analyze all supported files in the workspace, execute 'Run EkLine Linter' from the Command Palette.


EkLine flags any style guide violations in your company's documentation with Visual Studio Code diagnostics. It offers immediate feedback, facilitating consistency in your documentation.

EkLine VSCode Integration


## Prerequisites

1. You have an EkLine API token provided by the EkLine contact person.
2. You have a Bitbucket account and the necessary permissions to configure pipelines.

## Create `bitbucket-pipelines.yml` file

Create a new file named **`bitbucket-pipelines.yml`** in your project's root directory and add the following content:

```yaml
runEkLineStep: &runEkLineStep
  name: EkLine Documentation Review
  image:
    name: ghcr.io/ekline-io/ekline-ci-cd:v6.8
  script:
    - export EK_TOKEN=$EK_TOKEN
    - export INPUT_CONTENT_DIR='<path_to_content_directory>'
    - /entrypoint.sh

pipelines:
  branches:
    main:
      - step: *runEkLineStep

  pull-requests:
    '**':
      - step: *runEkLineStep
```

Replace **`<path_to_content_directory>`** with the actual path to your content directory.

## Configure Bitbucket environment variables

1. In Bitbucket, navigate to your repository settings.
2. Go to **Repository settings > Pipelines > Repository variables**.
3. Add the following variables:
    **`EK_TOKEN`**: Your EkLine API token.

## Configure input options

### Ignoring specific rules (Optional)

To ignore specific rules during the review process, you can use the `INPUT_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 `INPUT_IGNORE_RULE` flag in your configuration like this:

```yaml
  INPUT_IGNORE_RULE: "EK00001,EK00004"


This guide will walk you through setting up the EkLine integration with Bitbucket.

EkLine Bitbucket Integration Guide

/*@jsxRuntime automatic @jsxImportSource react*/
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = Object.assign({
    h2: "h2",
    a: "a",
    span: "span",
    ul: "ul",
    li: "li",
    ol: "ol",
    strong: "strong",
    code: "code",
    pre: "pre",
    p: "p"
  }, props.components);
  return _jsxs(_Fragment, {
    children: [_jsxs(_components.h2, {
      id: "prerequisites",
      children: [_jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#prerequisites",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      }), "Prerequisites"]
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsx(_components.li, {
        children: "A GitHub repository with EkLine set up."
      }), "\n", _jsx(_components.li, {
        children: "EkLine GitHub Action configured in your repository."
      }), "\n"]
    }), "\n", _jsxs(_components.h2, {
      id: "steps",
      children: [_jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#steps",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      }), "Steps"]
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsxs(_components.li, {
        children: ["Open the ", _jsx(_components.strong, {
          children: _jsx(_components.code, {
            children: ".github/workflows/ekline.yml"
          })
        }), " file in your GitHub repository."]
      }), "\n", _jsxs(_components.li, {
        children: ["Change the ", _jsx(_components.strong, {
          children: _jsx(_components.code, {
            children: "on"
          })
        }), " section of the GitHub action to trigger on ", _jsx(_components.strong, {
          children: _jsx(_components.code, {
            children: "pull_request"
          })
        }), " with ", _jsx(_components.strong, {
          children: _jsx(_components.code, {
            children: "types: [labeled]"
          })
        }), ":"]
      }), "\n"]
    }), "\n", _jsx(_components.pre, {
      children: _jsxs(_components.code, {
        className: "hljs language-yaml",
        children: [_jsx(_components.span, {
          className: "hljs-attr",
          children: "on:"
        }), "\n  ", _jsx(_components.span, {
          className: "hljs-attr",
          children: "pull_request:"
        }), "\n    ", _jsx(_components.span, {
          className: "hljs-attr",
          children: "types:"
        }), " [", _jsx(_components.span, {
          className: "hljs-string",
          children: "labeled"
        }), "]\n"]
      })
    }), "\n", _jsxs(_components.ol, {
      start: "3",
      children: ["\n", _jsxs(_components.li, {
        children: ["Add a new ", _jsx(_components.strong, {
          children: _jsx(_components.code, {
            children: "if"
          })
        }), " condition to the ", _jsx(_components.strong, {
          children: _jsx(_components.code, {
            children: "jobs"
          })
        }), " section to check if the label \"ekline\" is present:"]
      }), "\n"]
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        children: "jobs:\n  test-pr-review:\n    if: contains(github.event.label.name, 'ekline')\n"
      })
    }), "\n", _jsxs(_components.ol, {
      start: "4",
      children: ["\n", _jsxs(_components.li, {
        children: ["Save the changes to ", _jsx(_components.strong, {
          children: _jsx(_components.code, {
            children: "ekline.yml"
          })
        }), " file.\nThe updated ", _jsx(_components.strong, {
          children: _jsx(_components.code, {
            children: "ekline.yml"
          })
        }), " appears like this:"]
      }), "\n"]
    }), "\n", _jsx(_components.pre, {
      children: _jsxs(_components.code, {
        className: "hljs language-yaml",
        children: [_jsx(_components.span, {
          className: "hljs-attr",
          children: "name:"
        }), " ", _jsx(_components.span, {
          className: "hljs-string",
          children: "EkLine"
        }), "\n", _jsx(_components.span, {
          className: "hljs-attr",
          children: "on:"
        }), "\n  ", _jsx(_components.span, {
          className: "hljs-attr",
          children: "pull_request:"
        }), "\n    ", _jsx(_components.span, {
          className: "hljs-attr",
          children: "types:"
        }), " [", _jsx(_components.span, {
          className: "hljs-string",
          children: "labeled"
        }), "]\n\n", _jsx(_components.span, {
          className: "hljs-attr",
          children: "jobs:"
        }), "\n  ", _jsx(_components.span, {
          className: "hljs-attr",
          children: "test-pr-review:"
        }), "\n    ", _jsx(_components.span, {
          className: "hljs-attr",
          children: "if:"
        }), " ", _jsx(_components.span, {
          className: "hljs-string",
          children: "contains(github.event.label.name,"
        }), " ", _jsx(_components.span, {
          className: "hljs-string",
          children: "'ekline'"
        }), _jsx(_components.span, {
          className: "hljs-string",
          children: ")"
        }), "\n    ", _jsx(_components.span, {
          className: "hljs-attr",
          children: "name:"
        }), " ", _jsx(_components.span, {
          className: "hljs-string",
          children: "runner"
        }), " ", _jsx(_components.span, {
          className: "hljs-string",
          children: "/"
        }), " ", _jsx(_components.span, {
          className: "hljs-string",
          children: "EkLine"
        }), " ", _jsx(_components.span, {
          className: "hljs-string",
          children: "Reviewer"
        }), " ", _jsx(_components.span, {
          className: "hljs-string",
          children: "(github-pr-review)"
        }), "\n    ", _jsx(_components.span, {
          className: "hljs-attr",
          children: "runs-on:"
        }), " ", _jsx(_components.span, {
          className: "hljs-string",
          children: "ubuntu-latest"
        }), "\n    ", _jsx(_components.span, {
          className: "hljs-attr",
          children: "steps:"
        }), "\n      ", _jsx(_components.span, {
          className: "hljs-bullet",
          children: "-"
        }), " ", _jsx(_components.span, {
          className: "hljs-attr",
          children: "uses:"
        }), " ", _jsx(_components.span, {
          className: "hljs-string",
          children: "actions/checkout@v3"
        }), "\n      ", _jsx(_components.span, {
          className: "hljs-bullet",
          children: "-"
        }), " ", _jsx(_components.span, {
          className: "hljs-attr",
          children: "uses:"
        }), " ", _jsx(_components.span, {
          className: "hljs-string",
          children: "ekline-io/ekline-github-action@v6"
        }), "\n        ", _jsx(_components.span, {
          className: "hljs-attr",
          children: "with:"
        }), "\n          ", _jsx(_components.span, {
          className: "hljs-attr",
          children: "content_dir:"
        }), " ", _jsx(_components.span, {
          className: "hljs-string",
          children: "./src/docs"
        }), "\n          ", _jsx(_components.span, {
          className: "hljs-attr",
          children: "ek_token:"
        }), " ", _jsx(_components.span, {
          className: "hljs-string",
          children: "${{"
        }), " ", _jsx(_components.span, {
          className: "hljs-string",
          children: "secrets.ek_token"
        }), " ", _jsx(_components.span, {
          className: "hljs-string",
          children: "}}"
        }), "\n          ", _jsx(_components.span, {
          className: "hljs-attr",
          children: "github_token:"
        }), " ", _jsx(_components.span, {
          className: "hljs-string",
          children: "${{"
        }), " ", _jsx(_components.span, {
          className: "hljs-string",
          children: "secrets.github_token"
        }), " ", _jsx(_components.span, {
          className: "hljs-string",
          children: "}}"
        }), "\n          ", _jsx(_components.span, {
          className: "hljs-attr",
          children: "reporter:"
        }), " ", _jsx(_components.span, {
          className: "hljs-string",
          children: "github-pr-review"
        }), "\n          ", _jsx(_components.span, {
          className: "hljs-attr",
          children: "filter_mode:"
        }), " ", _jsx(_components.span, {
          className: "hljs-string",
          children: "added"
        }), "\n          ", _jsx(_components.span, {
          className: "hljs-comment",
          children: "# ignore_rule: \"EK00001,EK00004\" # Optional"
        }), "\n"]
      })
    }), "\n", _jsx(_components.p, {
      children: "With these changes, EkLine GitHub Action triggers when someone adds a label named \"ekline\" to a pull request."
    }), "\n", _jsxs(_components.h2, {
      id: "usage",
      children: [_jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#usage",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      }), "Usage"]
    }), "\n", _jsx(_components.p, {
      children: "Add the \"ekline\" label to a specific pull request to run the EkLine GitHub Action. Upon adding the label, the action triggers and executes the configured checks."
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, Object.assign({}, props, {
    children: _jsx(_createMdxContent, props)
  })) : _createMdxContent(props);
}
return {
  default: MDXContent
};


Integrations

GitHub Action on Label

This guide helps configure the EkLine GitHub Action to run when a specific label, named 'ekline', gets added to a pull request.

Prerequisites

Steps

Usage

Table of Contents