Commit a8fbf43b authored by Pierre Smeyers's avatar Pierre Smeyers
Browse files

Merge branch 'master' into 'master' 

Template generalization

Closes #19, #18, and #11

See merge request to-be-continuous/node!25
parents 2e2f8b6a 10509088

README.md

+75 −78
Original line number Diff line number Diff line 
# GitLab CI template for Node.js



This project implements a generic GitLab CI template for projects based on [Node.js](https://nodejs.org/)].

This project implements a generic GitLab CI template for projects based on [Node.js](https://nodejs.org/).



More precisely, it can be used by all projects based on [npm](https://www.npmjs.com/) or [yarn](https://yarnpkg.com/) package managers.



It provides several features, usable in different modes (by configuration).
@@ -20,9 +22,10 @@ include: 
The Node.js template uses some global configuration used throughout all jobs.



| Name                   | description                                                                                      | default value     |

| ------------------- | ------------------------------------ | ------------------------------------------------------ |

|------------------------|--------------------------------------------------------------------------------------------------|-------------------|

| `NODE_IMAGE`           | The Docker image used to run Node.js <br/>:warning: **set the version required by your project** | `node:lts-alpine` |

| `NPM_CONFIG_REGISTRY` | NPM [registry](https://docs.npmjs.com/configuring-your-registry-settings-as-an-npm-enterprise-user) | _none_ |

| `NODE_MANAGER`         | The package manager used by your project (npm or yarn)<br/>**If undefined, automatic detection** | _none_            |

| `NODE_CONFIG_REGISTRY` | npm [registry](https://docs.npmjs.com/cli/v8/using-npm/registry)                                 | _none_            |

| `NODE_PROJECT_DIR`     | Node project root directory                                                                      | `.`               |

| `NODE_SOURCE_DIR`      | Sources directory                                                                                | `src`             |
@@ -35,10 +38,11 @@ The Node template features a job `node-lint` that performs Node.js source code * 
It is bound to the `test` stage, and uses the following variable:



| Name                     | description                                                                                                                                                                                                                | default value                 |

| ---------------- | --------------------------------------------------------------------------- | ------------- |

|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------|

| `NODE_LINT_ENABLED`      | Set to `true` to enable lint analysis                                                                                                                                                                                      | _none_ (disabled)             |

| `NODE_LINT_ARGS` | NPM [run-script](https://docs.npmjs.com/cli/run-script.html) arguments to execute the lint analysis | `run lint`        |

| `NODE_LINT_REPORT_PATH` | Variable to define lint analysis report path                                        | `reports/eslint-report.json`|

| `NODE_LINT_ARGS`         | npm [run script](https://docs.npmjs.com/cli/v8/commands/npm-run-script) arguments to execute the lint analysis <br/> yarn [run script](https://classic.yarnpkg.com/en/docs/cli/run) arguments to execute the lint analysis | `run lint`                    |



The job generates a lint report that you will find here: `NODE_PROJECT_DIR/reports/eslint-report.json`.



### `node-build` job
@@ -50,27 +54,28 @@ for jobs dependency reasons (some jobs such as SONAR analysis have a dependency 
This job is bound to the `build` stage, and uses the following variables:



| Name                          | description                                                                                                                                                       | default value         |

| ----------------- | ------------------------------------------------------------ | -------------------- |

|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------|

| `NODE_BUILD_DISABLED`         | Set to `true` to disable build                                                                                                                                    | _none_ (enabled)      |

| `NODE_BUILD_DIR`              | Variable to define build directory                                                                                                                                | `dist`                |

| `NODE_BUILD_ARGS` | NPM [build](https://docs.npmjs.com/cli/build.html) arguments | `run build --prod`       |

| `NODE_TEST_ARGS`  | NPM [test](https://docs.npmjs.com/cli/test.html) arguments   | `test -- --coverage --bail` |

| `NODE_UNIT_TEST_REPORT_PATH` | The unit test report file path (JUnit format)     | `reports/unit_test_report.xml` |

| `NODE_BUILD_ARGS`             | npm [run script](https://docs.npmjs.com/cli/v8/commands/npm-run-script) arguments <br/> yarn [run script](https://classic.yarnpkg.com/en/docs/cli/run) arguments  | `run build --prod`    |

| `NODE_TEST_ARGS`              | npm [test](https://docs.npmjs.com/cli/v8/commands/npm-test) arguments <br/> yarn [test](https://classic.yarnpkg.com/en/docs/cli/test) arguments                   | `test -- --coverage`  |



Implementation rely on the official [NPM CLI](https://docs.npmjs.com/cli-documentation/cli) tool (`npm build` and `npm test` commands).

The job generates a unit test report that you will find here: `NODE_PROJECT_DIR/reports/unit_test_report.xml`.



#### Unit testing with Jest



If you're using [Jest](https://jestjs.io/) as unit testing framework, you'll have to make the following configuration in

order to [integrate your unit tests results to GitLab](https://docs.gitlab.com/ee/ci/junit_test_reports.html) (and optionally to SonarQube).

order to [integrate your unit tests results to GitLab](https://docs.gitlab.com/ee/ci/unit_test_reports.html) (and optionally to SonarQube).



##### Coverage



For coverage, Jest comes with in-built **Istanbul** package. So no need for extra dependency.

For coverage, Jest comes built-in with **Istanbul** package. So no need for extra dependency.



```js

"jest": {

...

    "coverageDirectory": './reports',

...

},

```
@@ -88,40 +93,61 @@ Then update your `jest.config.js` or `package.json` as follows: 


```js

"jest": {

  "reporters": [ "default", "jest-junit" ]

},

"jest-junit": {

...

    "reporters": [

        "default",

        [

            "jest-junit",

            {

                "outputDirectory": "reports",

                "outputName": "unit_test_report.xml"

            }

        ]

    ]

...

},

```



##### Sonar report



By default Jest doesn't generate any test report supported by Sonar. To do so you need to use the [jest-sonar-reporter](https://www.npmjs.com/package/jest-sonar-reporter) package.

By default Jest doesn't generate any test report supported by Sonar. To do so you need to use the [jest-sonar](https://www.npmjs.com/package/jest-sonar) package.



Add the package as a development dependency:



```bash

npm install --save-dev jest-sonar-reporter

npm install --save-dev jest-sonar

```



Then update your `jest.config.js` or `package.json` as follows:



```js

"jest": {

  "testResultsProcessor": "jest-sonar-reporter"

},

"jestSonar": {

  "reportPath": "reports",

  "reportFile": "sonar_test_report.xml"

...

    "reporters": [

        "default",

        [

            "jest-junit",

            {

                "outputDirectory": "reports",

                "outputName": "unit_test_report.xml"

            }

        ],

        [

            "jest-sonar",

            {

                "outputDirectory": "reports",

                "outputName": "sonar_test_report.xml"

            }

        ]

    ],

...

},

```



#### Unit testing with Mocha



If you're using [Mocha](https://mochajs.org/) as unit testing framework, you'll have to make the following configuration in

order to [integrate your unit tests results to GitLab](https://docs.gitlab.com/ee/ci/junit_test_reports.html) (and optionally to SonarQube).

order to [integrate your unit tests results to GitLab](https://docs.gitlab.com/ee/ci/unit_test_reports.html) (and optionally to SonarQube).



##### Coverage
@@ -232,58 +258,29 @@ More info: 
* [test coverage & execution parameters](https://docs.sonarqube.org/latest/analysis/coverage/)

* [third-party issues](https://docs.sonarqube.org/latest/analysis/external-issues/)



### `node-npm-audit` job

### `node-audit` job



The Node template features a job `node-npm-audit` that performs [npm audit](https://docs.npmjs.com/cli/audit) to find vulnerabilities (security).

The Node template features a job `node-audit` that performs an audit ([npm audit](https://docs.npmjs.com/cli/v8/commands/npm-audit) or [yarn audit](https://classic.yarnpkg.com/en/docs/cli/audit)) to find vulnerabilities (security).



It is bound to the `test` stage.



By default `npm audit` provide a long json report. For readability, `npm-audit-html` is used to generate an HTML report.



Add the package as a development dependency:



```shell

npm install --save-dev npm-audit-html

```



| Name                   | description                                                                                                                                           | default value                    |

| --------------------- | -----------------  | ----------------- |

|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------|

| `NODE_AUDIT_DISABLED`  | Set to `true` to disable npm audit                                                                                                                    | _none_ (enabled)                 |

| `NODE_AUDIT_ARGS`     | NPM [audit](https://docs.npmjs.com/cli/audit) arguments | `--audit-level=low` |

| `NODE_AUDIT_JSON_PATH`| NPM [audit](https://docs.npmjs.com/cli/audit) JSON report path | `reports/npm-audit-report.json` |

| `NODE_AUDIT_HTML_ARGS`| NPM [audit HTML](https://www.npmjs.com/package/npm-audit-html) report generation arguments | `--output reports/npm-audit-report.html` |

| `NODE_AUDIT_ARGS`      | npm [audit](https://docs.npmjs.com/cli/v8/commands/npm-audit) arguments <br/> yarn [audit](https://classic.yarnpkg.com/en/docs/cli/audit) arguments   | `--audit-level=low`              |



The job generates an audit report that you will find here: `NODE_PROJECT_DIR/reports/npm-audit-report.json`.



### `node-npm-outdated` job



The Node template features a job `node-npm-outdated` that performs [npm outdated](https://docs.npmjs.com/cli/outdated) to find dependencies that might be updated.

The Node template features a job `node-outdated` that performs outdated analysis ([npm outdated](https://docs.npmjs.com/cli/v8/commands/npm-outdated) or [yarn outdated](https://classic.yarnpkg.com/lang/en/docs/cli/outdated/)) to find dependencies that might be updated.



It is bound to the `test` stage.



By default `npm outdated` provide a long json report. For readability, `npm-outdated-html` is used to generate an HTML report.



Add the package as a development dependency:



```shell

npm install --save-dev npm-outdated-html

```



| Name                      | description                                                                                                                                                           | default value                      |

|---------------------------|--------------------------------------------------------------------------------------------------|---------------------------------------------|

|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------|

| `NODE_OUTDATED_DISABLED`  | Set to `true` to disable npm outdated                                                                                                                                 | _none_ (enabled)                   |

| `NODE_OUTDATED_ARGS`      | NPM [outdated](https://docs.npmjs.com/cli/outdated) arguments                                    | `--long`                                          |

| `NODE_OUTDATED_JSON_PATH` | NPM [outdated](https://docs.npmjs.com/cli/outdated) JSON report path                             | `reports/npm-outdated-report.json`          |

| `NODE_OUTDATED_HTML_ARGS` | NPM [outdated HTML](https://www.npmjs.com/package/npm-outdated-html) report generation arguments | `--output reports/npm-outdated-report.html` |



### `node-js-scan` job



This jobs is **disabled by default** and performs a [njsscan](https://github.com/ajinabraham/njsscan) (Static Security Code Scanner) analysis.

| `NODE_OUTDATED_ARGS`      | npm [outdated](https://docs.npmjs.com/cli/v8/commands/npm-outdated) arguments <br/> yarn [outdated](https://classic.yarnpkg.com/lang/en/docs/cli/outdated/) arguments | `--long`                           |



It is bound to the `test` stage, and uses the following variables:



To activate the NodeJsScan, you need to set some VARIABLES



| Name                  | description        | default value     |

| --------------------- | -----------------  | ----------------- |

| `NODEJSSCAN_ENABLED`  | Set to `true` to enable njsscan analysis | _none_ (disabled) |

| `NODEJSSCAN_IMAGE`    | njsscan image   | `opensecurity/njsscan:latest` |

| `NODEJSSCAN_ARGS`     | njsscan [arguments](https://github.com/ajinabraham/njsscan#command-line-options) | _none_ |
 
The job generates an outdated report that you will find here: `NODE_PROJECT_DIR/reports/npm-outdated-report.json`.

kicker.json

+23 −72
Original line number Diff line number Diff line
@@ -5,8 +5,8 @@ 
  "kind": "build",

  "variables": [

    {

      "name": "NPM_CONFIG_REGISTRY",

      "description": "NPM [registry](https://docs.npmjs.com/configuring-your-registry-settings-as-an-npm-enterprise-user)",

      "name": "NODE_CONFIG_REGISTRY",

      "description": "npm [registry](https://docs.npmjs.com/cli/v8/using-npm/registry)    ",

      "type": "url",

      "advanced": true

    },
@@ -15,6 +15,12 @@ 
      "description": "The Docker image used to run Node.js - **set the version required by your project**",

      "default": "node:lts-alpine"

    },

    {

      "name": "NODE_MANAGER",

      "description": "The package manager used by your project (npm or yarn) - **if undefined, automatic detection**",

      "default": "none",

      "advanced": true

    },

    {

      "name": "NODE_PROJECT_DIR",

      "description": "Node project root directory",
@@ -29,7 +35,7 @@ 
    },

    {

      "name": "NODE_BUILD_ARGS",

      "description": "NPM [build](https://docs.npmjs.com/cli/build.html) arguments",

      "description": "npm [run script](https://docs.npmjs.com/cli/v8/commands/npm-run-script) arguments - yarn [run script](https://classic.yarnpkg.com/en/docs/cli/run) arguments",

      "default": "run build --prod",

      "advanced": true

    },
@@ -41,104 +47,49 @@ 
    },

    {

      "name": "NODE_TEST_ARGS",

      "description": "NPM [test](https://docs.npmjs.com/cli/test.html) arguments",

      "default": "test -- --coverage --bail",

      "advanced": true

    },

    {

      "name": "NODE_UNIT_TEST_REPORT_PATH",

      "description": "The unit test report file path (JUnit format)",

      "default": "reports/unit_test_report.xml",

      "description": "npm [test](https://docs.npmjs.com/cli/v8/commands/npm-test) arguments - yarn [test](https://classic.yarnpkg.com/en/docs/cli/test) arguments",

      "default": "test -- --coverage",

      "advanced": true

    }

  ],

  "features": [

    {

      "id": "npm-lint",

      "name": "npm lint",

      "description": "npm lint analysis",

      "id": "node-lint",

      "name": "node lint",

      "description": "node lint analysis",

      "enable_with": "NODE_LINT_ENABLED",

      "variables": [

        {

          "name": "NODE_LINT_ARGS",

          "description": "NPM [run-script](https://docs.npmjs.com/cli/run-script.html) arguments to execute the lint analysis",

          "description": "npm [run script](https://docs.npmjs.com/cli/v8/commands/npm-run-script) arguments to execute the lint analysis - yarn [run script](https://classic.yarnpkg.com/en/docs/cli/run) arguments to execute the lint analysis",

          "default": "run lint",

          "advanced": true

        },

        {

          "name": "NODE_LINT_REPORT_PATH",

          "description": "Variable to define lint analysis report path",

          "default": "reports/eslint-report.json",

          "advanced": true

        }

      ]

    },

    {

      "id": "npm-audit",

      "name": "npm audit",

      "description": "npm audit analysis",

      "id": "node-audit",

      "name": "node audit",

      "description": "node audit analysis",

      "disable_with": "NODE_AUDIT_DISABLED",

      "variables": [

        {

          "name": "NODE_AUDIT_ARGS",

          "description": "NPM [audit](https://docs.npmjs.com/cli/audit) arguments",

          "description": "npm [audit](https://docs.npmjs.com/cli/v8/commands/npm-audit) arguments - yarn [audit](https://classic.yarnpkg.com/en/docs/cli/audit) arguments",

          "default": "--audit-level=low"

        },

        {

          "name": "NODE_AUDIT_JSON_PATH",

          "description": "NPM [audit](https://docs.npmjs.com/cli/audit) JSON report path",

          "default": "reports/npm-audit-report.json",

          "advanced": true

        },

        {

          "name": "NODE_AUDIT_HTML_ARGS",

          "description": "NPM [audit HTML](https://www.npmjs.com/package/npm-audit-html) report generation arguments",

          "default": "--output reports/npm-audit-report.html",

          "advanced": true

        }

      ]

    },

    {

      "id": "npm-outdated",

      "name": "npm outdated",

      "description": "npm outdated analysis",

      "id": "node-outdated",

      "name": "node outdated",

      "description": "node outdated analysis",

      "disable_with": "NODE_OUTDATED_DISABLED",

      "variables": [

        {

          "name": "NODE_OUTDATED_ARGS",

          "description": "NPM [outdated](https://docs.npmjs.com/cli/outdated) arguments",

          "description": "npm [outdated](https://docs.npmjs.com/cli/v8/commands/npm-outdated) arguments - yarn [outdated](https://classic.yarnpkg.com/lang/en/docs/cli/outdated/) arguments",

          "default": "--long"

        },

        {

          "name": "NODE_OUTDATED_JSON_PATH",

          "description": "NPM [outdated](https://docs.npmjs.com/cli/outdated) JSON report path",

          "default": "reports/npm-outdated-report.json",

          "advanced": true

        },

        {

          "name": "NODE_OUTDATED_HTML_ARGS",

          "description": "NPM [outdated HTML](https://www.npmjs.com/package/npm-outdated-html) report generation arguments",

          "default": "--output reports/npm-outdated-report.html",

          "advanced": true

        }

      ]

    },

    {

      "id": "njsscan",

      "name": "njsscan",

      "description": "[njsscan](https://github.com/ajinabraham/njsscan) (Static Security Code Scanner) analysis",

      "enable_with": "NODEJSSCAN_ENABLED",

      "variables": [

        {

          "name": "NODEJSSCAN_IMAGE",

          "description": "njsscan image",

          "default": "opensecurity/njsscan:latest",

          "advanced": true

        },

        {

          "name": "NODEJSSCAN_ARGS",

          "description": "njsscan [arguments](https://github.com/ajinabraham/njsscan#command-line-options)",

          "advanced": true

        }

      ]

    }

templates/gitlab-ci-node.yml

+73 −58

File changed.

Preview size limit exceeded, changes collapsed.