Skip to content
Snippets Groups Projects
Commit 8517d813 authored by Pierre Smeyers's avatar Pierre Smeyers
Browse files

style: Markdown formatting

parent 7e7b0383
No related branches found
No related tags found
No related merge requests found
Show whitespace changes
Inline Side-by-side
Showing
with 194 additions and 181 deletions
README.md
+ 194
− 181
View file @ 8517d813
...@@ -30,9 +30,9 @@ Add the following to your `.gitlab-ci.yml`: ...@@ -30,9 +30,9 @@ Add the following to your `.gitlab-ci.yml`:
```yaml ```yaml
include: include:
# 1: include the template # 1: include the template
- project: 'to-be-continuous/node' - project: "to-be-continuous/node"
ref: '4.0.0' ref: "4.0.0"
file: '/templates/gitlab-ci-node.yml' file: "/templates/gitlab-ci-node.yml"
variables: variables:
# 2: set/override template variables # 2: set/override template variables
...@@ -45,7 +45,7 @@ variables: ...@@ -45,7 +45,7 @@ variables:
The Node.js template uses some global configuration used throughout all jobs. The Node.js template uses some global configuration used throughout all jobs.
| Input / Variable | Description | Default value | | Input / Variable | Description | Default value |
|------------------------|--------------------------------------------------------------------------------------------------|-------------------| | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `image` / `NODE_IMAGE` | The Docker image used to run Node.js <br/>:warning: **set the version required by your project** | `registry.hub.docker.com/library/node:lts-alpine` | | `image` / `NODE_IMAGE` | The Docker image used to run Node.js <br/>:warning: **set the version required by your project** | `registry.hub.docker.com/library/node:lts-alpine` |
| `manager` / `NODE_MANAGER` | The package manager used by your project (one of `npm`, `yarn` or `pnpm`)<br/>**If undefined, automatic detection** | _none_ (auto) | | `manager` / `NODE_MANAGER` | The package manager used by your project (one of `npm`, `yarn` or `pnpm`)<br/>**If undefined, automatic detection** | _none_ (auto) |
| `config-registry` / `NODE_CONFIG_REGISTRY` | Main npm [registry](https://docs.npmjs.com/cli/v8/using-npm/registry) to use | _none_ | | `config-registry` / `NODE_CONFIG_REGISTRY` | Main npm [registry](https://docs.npmjs.com/cli/v8/using-npm/registry) to use | _none_ |
...@@ -60,9 +60,9 @@ Scoped registries allow to pull and publish packages using multiple registries. ...@@ -60,9 +60,9 @@ Scoped registries allow to pull and publish packages using multiple registries.
Examples: Examples:
* `npm install foo` installs `foo` package from https://www.npmjs.com/ by default, - `npm install foo` installs `foo` package from https://www.npmjs.com/ by default,
* `npm install @angular/core` installs `@angular/core` package from https://www.npmjs.com/ if no npm registry associated to scope `@angular` is declared, - `npm install @angular/core` installs `@angular/core` package from https://www.npmjs.com/ if no npm registry associated to scope `@angular` is declared,
* `npm install @acme-corp/bar` installs `@acme-corp/bar` package from https://registry.acme.corp/npm if this registry url is associated to scope `@acme-corp`. - `npm install @acme-corp/bar` installs `@acme-corp/bar` package from https://registry.acme.corp/npm if this registry url is associated to scope `@acme-corp`.
First of all, be aware that the Node.js template automatically configures the [GitLab's project-level npm packages registry](https://docs.gitlab.com/ee/user/packages/npm_registry/) associated to a scope corresponding to the root of the project (ex: project `https://gitlab.example.com/my-org/engineering-group/team-amazing/analytics` will have GitLab's project-level npm packages registry scope `@my-org`). First of all, be aware that the Node.js template automatically configures the [GitLab's project-level npm packages registry](https://docs.gitlab.com/ee/user/packages/npm_registry/) associated to a scope corresponding to the root of the project (ex: project `https://gitlab.example.com/my-org/engineering-group/team-amazing/analytics` will have GitLab's project-level npm packages registry scope `@my-org`).
Therefore, GitLab's project-level npm packages registry can freely be used both to install packages (with the right scope) or even to [publish](#node-publish-job) your own packages. Therefore, GitLab's project-level npm packages registry can freely be used both to install packages (with the right scope) or even to [publish](#node-publish-job) your own packages.
...@@ -73,9 +73,8 @@ The value is expected as a (whitespace-separated) list of `@registry-scope:regis ...@@ -73,9 +73,8 @@ The value is expected as a (whitespace-separated) list of `@registry-scope:regis
The Node.js template also supports authentication for each, simply by defining the appropriate variable (as project or group secret variables) The Node.js template also supports authentication for each, simply by defining the appropriate variable (as project or group secret variables)
depending on the desired authentication method: depending on the desired authentication method:
* `NODE_REGISTRY_<SCOPE>_AUTH_TOKEN`: authentication token - `NODE_REGISTRY_<SCOPE>_AUTH_TOKEN`: authentication token
* `NODE_REGISTRY_<SCOPE>_AUTH_BASIC`: base64 authentication string (`base64(username + ':' + password)`) - `NODE_REGISTRY_<SCOPE>_AUTH_BASIC`: base64 authentication string (`base64(username + ':' + password)`)
:warning: The `<SCOPE>` part is the `registry-scope` transformed in [SCREAMING_SNAKE_CASE](https://en.wikipedia.org/wiki/Snake_case) (uppercase words separated by underscores). :warning: The `<SCOPE>` part is the `registry-scope` transformed in [SCREAMING_SNAKE_CASE](https://en.wikipedia.org/wiki/Snake_case) (uppercase words separated by underscores).
...@@ -96,7 +95,7 @@ The Node template features a job `node-lint` that performs Node.js source code * ...@@ -96,7 +95,7 @@ The Node template features a job `node-lint` that performs Node.js source code *
It is bound to the `build` stage, and uses the following variable: It is bound to the `build` stage, and uses the following variable:
| Input / Variable | Description | Default value | | Input / Variable | Description | Default value |
|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------| | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- |
| `lint-enabled` / `NODE_LINT_ENABLED` | Set to `true` to enable lint analysis | _none_ (disabled) | | `lint-enabled` / `NODE_LINT_ENABLED` | Set to `true` to enable lint analysis | _none_ (disabled) |
| `lint-args` / `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 <br/> pnpm [run script](https://pnpm.io/cli/run) arguments to execute the lint analysis | `run lint` | | `lint-args` / `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 <br/> pnpm [run script](https://pnpm.io/cli/run) arguments to execute the lint analysis | `run lint` |
...@@ -112,13 +111,12 @@ for jobs dependency reasons (some jobs such as SONAR analysis have a dependency ...@@ -112,13 +111,12 @@ 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: This job is bound to the `build` stage, and uses the following variables:
| Input / Variable | Description | Default value | | Input / Variable | Description | Default value |
|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `build-disabled` / `NODE_BUILD_DISABLED` | Set to `true` to disable build | _none_ (enabled) | | `build-disabled` / `NODE_BUILD_DISABLED` | Set to `true` to disable build | _none_ (enabled) |
| `build-dir` / `NODE_BUILD_DIR` | Variable to define build directory | `dist` | | `build-dir` / `NODE_BUILD_DIR` | Variable to define build directory | `dist` |
| `build-args` / `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 <br/> pnpm [run script](https://pnpm.io/cli/run) arguments <br/>⚠ default value should be overridden for `pnpm` as `--prod` is not a valid option. | `run build --prod` | | `build-args` / `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 <br/> pnpm [run script](https://pnpm.io/cli/run) arguments <br/>⚠ default value should be overridden for `pnpm` as `--prod` is not a valid option. | `run build --prod` |
| `test-args` / `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 <br/> pnpm [test](https://pnpm.io/cli/test) arguments | `test -- --coverage` | | `test-args` / `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 <br/> pnpm [test](https://pnpm.io/cli/test) arguments | `test -- --coverage` |
#### Unit Tests and Code Coverage reports #### Unit Tests and Code Coverage reports
This chapter details the required configuration (depending on the unit testing framework you're using) in This chapter details the required configuration (depending on the unit testing framework you're using) in
...@@ -131,7 +129,7 @@ Additionally, if also using SonarQube, you'll have to enable some extra reporter ...@@ -131,7 +129,7 @@ Additionally, if also using SonarQube, you'll have to enable some extra reporter
Here is the required configuration if you're using [Jest](https://jestjs.io/) as unit testing framework. Here is the required configuration if you're using [Jest](https://jestjs.io/) as unit testing framework.
| Reporter | Needs `npm install` | Expected report file | Usage | | Reporter | Needs `npm install` | Expected report file | Usage |
| ---------------- | --------------------- | ----------------- | ----------------- | | -------------------------------------------------------------------------------------------- | ------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [jest-junit](https://github.com/jest-community/jest-junit) | Yes | `reports/node-test.xunit.xml` | [GitLab unit tests integration](https://docs.gitlab.com/ee/ci/testing/unit_test_reports.html) _(JUnit format)_ | | [jest-junit](https://github.com/jest-community/jest-junit) | Yes | `reports/node-test.xunit.xml` | [GitLab unit tests integration](https://docs.gitlab.com/ee/ci/testing/unit_test_reports.html) _(JUnit format)_ |
| istanbul [text](https://istanbul.js.org/docs/advanced/alternative-reporters/#text) | No | N/A _(stdout)_ | [GitLab MR test coverage results](https://docs.gitlab.com/ee/ci/pipelines/settings.html#merge-request-test-coverage-results) _(GitLab grabs coverage from stdout)_ | | istanbul [text](https://istanbul.js.org/docs/advanced/alternative-reporters/#text) | No | N/A _(stdout)_ | [GitLab MR test coverage results](https://docs.gitlab.com/ee/ci/pipelines/settings.html#merge-request-test-coverage-results) _(GitLab grabs coverage from stdout)_ |
| istanbul [cobertura](https://istanbul.js.org/docs/advanced/alternative-reporters/#cobertura) | No | `reports/cobertura-coverage.xml` | [GitLab code coverage integration](https://docs.gitlab.com/ee/ci/testing/test_coverage_visualization.html) _(Cobertura format)_ | | istanbul [cobertura](https://istanbul.js.org/docs/advanced/alternative-reporters/#cobertura) | No | `reports/cobertura-coverage.xml` | [GitLab code coverage integration](https://docs.gitlab.com/ee/ci/testing/test_coverage_visualization.html) _(Cobertura format)_ |
...@@ -178,7 +176,7 @@ Here is an example of a `jest.config.js` configuration file with all the above r ...@@ -178,7 +176,7 @@ Here is an example of a `jest.config.js` configuration file with all the above r
Here is the required configuration if you're using [Mocha](https://mochajs.org/) as unit testing framework. Here is the required configuration if you're using [Mocha](https://mochajs.org/) as unit testing framework.
| Reporter | Needs `npm install` | Expected report file | Usage | | Reporter | Needs `npm install` | Expected report file | Usage |
| ---------------- | --------------------- | ----------------- | ----------------- | | -------------------------------------------------------------------------------------------- | ---------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [mocha-junit-reporter](https://github.com/michaelleeallen/mocha-junit-reporter) | Yes | `reports/node-test.xunit.xml` | [GitLab unit tests integration](https://docs.gitlab.com/ee/ci/testing/unit_test_reports.html) _(JUnit format)_ | | [mocha-junit-reporter](https://github.com/michaelleeallen/mocha-junit-reporter) | Yes | `reports/node-test.xunit.xml` | [GitLab unit tests integration](https://docs.gitlab.com/ee/ci/testing/unit_test_reports.html) _(JUnit format)_ |
| istanbul [text](https://istanbul.js.org/docs/advanced/alternative-reporters/#text) | Yes (in `nyc` package) | N/A _(stdout)_ | [GitLab MR test coverage results](https://docs.gitlab.com/ee/ci/pipelines/settings.html#merge-request-test-coverage-results) _(GitLab grabs coverage from stdout)_ | | istanbul [text](https://istanbul.js.org/docs/advanced/alternative-reporters/#text) | Yes (in `nyc` package) | N/A _(stdout)_ | [GitLab MR test coverage results](https://docs.gitlab.com/ee/ci/pipelines/settings.html#merge-request-test-coverage-results) _(GitLab grabs coverage from stdout)_ |
| istanbul [cobertura](https://istanbul.js.org/docs/advanced/alternative-reporters/#cobertura) | Yes (in `nyc` package) | `reports/cobertura-coverage.xml` | [GitLab code coverage integration](https://docs.gitlab.com/ee/ci/testing/test_coverage_visualization.html) _(Cobertura format)_ | | istanbul [cobertura](https://istanbul.js.org/docs/advanced/alternative-reporters/#cobertura) | Yes (in `nyc` package) | `reports/cobertura-coverage.xml` | [GitLab code coverage integration](https://docs.gitlab.com/ee/ci/testing/test_coverage_visualization.html) _(Cobertura format)_ |
...@@ -188,9 +186,11 @@ Here is the required configuration if you're using [Mocha](https://mochajs.org/) ...@@ -188,9 +186,11 @@ Here is the required configuration if you're using [Mocha](https://mochajs.org/)
:warning: Remarks: :warning: Remarks:
1. By default - unlike Jest - Mocha doesn't provide code coverage. To do so you need to install [Istanbul](https://www.npmjs.com/package/nyc) package (`nyc`): 1. By default - unlike Jest - Mocha doesn't provide code coverage. To do so you need to install [Istanbul](https://www.npmjs.com/package/nyc) package (`nyc`):
```shell ```shell
npm install --save-dev nyc npm install --save-dev nyc
``` ```
2. the default `xunit` Mocha reporter doesn't produce a JUnit format supported by GitLab, that's why we recommend you to use `mocha-junit-reporter` instead. 2. the default `xunit` Mocha reporter doesn't produce a JUnit format supported by GitLab, that's why we recommend you to use `mocha-junit-reporter` instead.
3. Mocha doesn't support multiple unit tests reporters. 3. Mocha doesn't support multiple unit tests reporters.
So unfortunaltely, if you're using SonarQube, you'll have to choose which report you want to generate. So unfortunaltely, if you're using SonarQube, you'll have to choose which report you want to generate.
...@@ -211,7 +211,8 @@ Here is the required configuration with CLI options directly in the `package.jso ...@@ -211,7 +211,8 @@ Here is the required configuration with CLI options directly in the `package.jso
Here is the equivalent using separate config files: Here is the equivalent using separate config files:
* `package.json`: - `package.json`:
```json ```json
"scripts": { "scripts": {
"test": "npm run mocha", "test": "npm run mocha",
...@@ -220,29 +221,38 @@ Here is the equivalent using separate config files: ...@@ -220,29 +221,38 @@ Here is the equivalent using separate config files:
}, },
... ...
``` ```
* `.mocharc.json`:
- `.mocharc.json`:
1. with `mocha-junit-reporter` (for GitLab): 1. with `mocha-junit-reporter` (for GitLab):
```json ```json
{ {
"reporter": "mocha-junit-reporter", "reporter": "mocha-junit-reporter",
"reporter-option": ["mochaFile=reports/node-test.xunit.xml"] "reporter-option": ["mochaFile=reports/node-test.xunit.xml"]
} }
``` ```
2. with `mocha-sonarqube-reporter` (for SonarQube): 2. with `mocha-sonarqube-reporter` (for SonarQube):
```json ```json
{ {
"reporter": "mocha-sonarqube-reporter", "reporter": "mocha-sonarqube-reporter",
"reporter-option": ["output=reports/node-test.sonar.xml"] "reporter-option": ["output=reports/node-test.sonar.xml"]
} }
``` ```
3. with both (using `mocha-multi-reporters`): 3. with both (using `mocha-multi-reporters`):
```json ```json
{ {
"reporter": "mocha-multi-reporters", "reporter": "mocha-multi-reporters",
"reporter-option": ["configFile=.mmr.json"] "reporter-option": ["configFile=.mmr.json"]
} }
``` ```
With `.mmr.json`: With `.mmr.json`:
```json ```json
{ {
"reporterEnabled": "spec, mocha-junit-reporter, mocha-sonarqube-reporter", "reporterEnabled": "spec, mocha-junit-reporter, mocha-sonarqube-reporter",
...@@ -254,7 +264,9 @@ Here is the equivalent using separate config files: ...@@ -254,7 +264,9 @@ Here is the equivalent using separate config files:
} }
} }
``` ```
* `.nycrc.json`:
- `.nycrc.json`:
```json ```json
{ {
"reporter": ["text", "cobertura", "lcovonly"], "reporter": ["text", "cobertura", "lcovonly"],
...@@ -315,10 +327,10 @@ sonar.typescript.lcov.reportPaths=reports/lcov.info ...@@ -315,10 +327,10 @@ sonar.typescript.lcov.reportPaths=reports/lcov.info
More info: More info:
* [JavaScript language support](https://docs.sonarqube.org/latest/analyzing-source-code/test-coverage/javascript-typescript-test-coverage/) - [JavaScript language support](https://docs.sonarqube.org/latest/analyzing-source-code/test-coverage/javascript-typescript-test-coverage/)
* [TypeScript language support](https://docs.sonarqube.org/latest/analyzing-source-code/test-coverage/javascript-typescript-test-coverage/) - [TypeScript language support](https://docs.sonarqube.org/latest/analyzing-source-code/test-coverage/javascript-typescript-test-coverage/)
* [test coverage & execution parameters](https://docs.sonarqube.org/latest/analysis/coverage/) - [test coverage & execution parameters](https://docs.sonarqube.org/latest/analysis/coverage/)
* [third-party issues](https://docs.sonarqube.org/latest/analysis/external-issues/) - [third-party issues](https://docs.sonarqube.org/latest/analysis/external-issues/)
### `node-audit` job ### `node-audit` job
...@@ -327,17 +339,16 @@ The Node template features a job `node-audit` that performs an audit ([npm audit ...@@ -327,17 +339,16 @@ The Node template features a job `node-audit` that performs an audit ([npm audit
It is bound to the `test` stage. It is bound to the `test` stage.
| Input / Variable | Description | Default value | | Input / Variable | Description | Default value |
|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------| | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `audit-disabled` / `NODE_AUDIT_DISABLED` | Set to `true` to disable npm audit | _none_ (enabled) | | `audit-disabled` / `NODE_AUDIT_DISABLED` | Set to `true` to disable npm audit | _none_ (enabled) |
| `audit-args` / `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 <br/> pnpm [audit](https://pnpm.io/cli/audit) arguments | `--audit-level=low` | | `audit-args` / `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 <br/> pnpm [audit](https://pnpm.io/cli/audit) arguments | `--audit-level=low` |
In addition to a textual report in the console, this job produces the following report, kept for one day: In addition to a textual report in the console, this job produces the following report, kept for one day:
| Report | Format | Usage | | Report | Format | Usage |
| -------------- | ---------------------------------------------------------------------------- | ----------------- | | ------------------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$NODE_PROJECT_DIR/reports/npm-audit.native.json` | [JSON](https://docs.npmjs.com/cli/v9/commands/npm-audit#json) | [DefectDojo integration](https://documentation.defectdojo.com/integrations/parsers/#npm-audit)<br/>_This report is generated only if DefectDojo template is detected, if needed, you can force it with `$DEFECTDOJO_NPMAUDIT_REPORTS`_ | | `$NODE_PROJECT_DIR/reports/npm-audit.native.json` | [JSON](https://docs.npmjs.com/cli/v9/commands/npm-audit#json) | [DefectDojo integration](https://documentation.defectdojo.com/integrations/parsers/#npm-audit)<br/>_This report is generated only if DefectDojo template is detected, if needed, you can force it with `$DEFECTDOJO_NPMAUDIT_REPORTS`_ |
### `node-outdated` job ### `node-outdated` job
The Node template features a job `node-outdated` that performs outdated analysis ([npm outdated](https://docs.npmjs.com/cli/v8/commands/npm-outdated), [yarn outdated](https://classic.yarnpkg.com/lang/en/docs/cli/outdated/) or [pnpm outdated](https://pnpm.io/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), [yarn outdated](https://classic.yarnpkg.com/lang/en/docs/cli/outdated/) or [pnpm outdated](https://pnpm.io/cli/outdated) to find dependencies that might be updated.
...@@ -345,7 +356,7 @@ The Node template features a job `node-outdated` that performs outdated analysis ...@@ -345,7 +356,7 @@ The Node template features a job `node-outdated` that performs outdated analysis
It is bound to the `test` stage. It is bound to the `test` stage.
| Input / Variable | Description | Default value | | Input / Variable | Description | Default value |
|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------| | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| `outdated-disabled` / `NODE_OUTDATED_DISABLED` | Set to `true` to disable npm outdated | _none_ (enabled) | | `outdated-disabled` / `NODE_OUTDATED_DISABLED` | Set to `true` to disable npm outdated | _none_ (enabled) |
| `outdated-args` / `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 <br/> pnpm [outdated](https://pnpm.io/cli/outdated) arguments | `--long` | | `outdated-args` / `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 <br/> pnpm [outdated](https://pnpm.io/cli/outdated) arguments | `--long` |
...@@ -358,7 +369,7 @@ The Node template features a job `node-semgrep` that performs a [Semgrep](https: ...@@ -358,7 +369,7 @@ The Node template features a job `node-semgrep` that performs a [Semgrep](https:
It is bound to the `test` stage, and uses the following variables: It is bound to the `test` stage, and uses the following variables:
| Input / Variable | Description | Default value | | Input / Variable | Description | Default value |
| ----------------------- | -------------------------------------- | ----------------- | | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ |
| `semgrep-disabled` / `NODE_SEMGREP_DISABLED` | Set to `true` to disable this job | _none_ | | `semgrep-disabled` / `NODE_SEMGREP_DISABLED` | Set to `true` to disable this job | _none_ |
| `semgrep-image` / `NODE_SEMGREP_IMAGE` | The Docker image used to run [Semgrep](https://semgrep.dev/docs/) | `registry.hub.docker.com/semgrep/semgrep:latest` | | `semgrep-image` / `NODE_SEMGREP_IMAGE` | The Docker image used to run [Semgrep](https://semgrep.dev/docs/) | `registry.hub.docker.com/semgrep/semgrep:latest` |
| `semgrep-args` / `NODE_SEMGREP_ARGS` | Semgrep [scan options](https://semgrep.dev/docs/cli-reference#semgrep-scan-command-options) | `--metrics off --disable-version-check --no-suppress-errors` | | `semgrep-args` / `NODE_SEMGREP_ARGS` | Semgrep [scan options](https://semgrep.dev/docs/cli-reference#semgrep-scan-command-options) | `--metrics off --disable-version-check --no-suppress-errors` |
...@@ -369,14 +380,14 @@ It is bound to the `test` stage, and uses the following variables: ...@@ -369,14 +380,14 @@ It is bound to the `test` stage, and uses the following variables:
> :information_source: Semgrep may [collect some metrics](https://semgrep.dev/docs/metrics), especially when using rules from the Semgrep Registry. > :information_source: Semgrep may [collect some metrics](https://semgrep.dev/docs/metrics), especially when using rules from the Semgrep Registry.
> To protect your privacy and let you run Semgrep in air-gap environments, this template disables all Semgrep metrics by default: > To protect your privacy and let you run Semgrep in air-gap environments, this template disables all Semgrep metrics by default:
> >
> * rules from the Semgrep registry are pre-downloaded and passed to Semgrep as local rule files (can be disabled by setting `semgrep-download-rules-enabled` / `NODE_SEMGREP_DOWNLOAD_RULES_ENABLED` to `false`), > - rules from the Semgrep registry are pre-downloaded and passed to Semgrep as local rule files (can be disabled by setting `semgrep-download-rules-enabled` / `NODE_SEMGREP_DOWNLOAD_RULES_ENABLED` to `false`),
> * the `--metrics` option is set to `off`, > - the `--metrics` option is set to `off`,
> * the `--disable-version-check` option is set. > - the `--disable-version-check` option is set.
In addition to a textual report in the console, this job produces the following reports, kept for one day: In addition to a textual report in the console, this job produces the following reports, kept for one day:
| Report | Format | Usage | | Report | Format | Usage |
| -------------- | ---------------------------------------------------------------------------- | ----------------- | | ---------------------------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$NODE_PROJECT_DIR/reports/node-semgrep.gitlab.json` | [GitLab's SAST format](https://semgrep.dev/docs/cli-reference#semgrep-scan-command-options) | [GitLab integration](https://docs.gitlab.com/ee/ci/yaml/artifacts_reports.html#artifactsreportssast) | | `$NODE_PROJECT_DIR/reports/node-semgrep.gitlab.json` | [GitLab's SAST format](https://semgrep.dev/docs/cli-reference#semgrep-scan-command-options) | [GitLab integration](https://docs.gitlab.com/ee/ci/yaml/artifacts_reports.html#artifactsreportssast) |
| `$NODE_PROJECT_DIR/reports/node-semgrep.native.json` | [Semgrep's JSON format](https://semgrep.dev/docs/cli-reference#semgrep-scan-command-options) | [DefectDojo integration](https://documentation.defectdojo.com/integrations/parsers/file/semgrep)<br/>_This report is generated only if DefectDojo template is detected_ | | `$NODE_PROJECT_DIR/reports/node-semgrep.native.json` | [Semgrep's JSON format](https://semgrep.dev/docs/cli-reference#semgrep-scan-command-options) | [DefectDojo integration](https://documentation.defectdojo.com/integrations/parsers/file/semgrep)<br/>_This report is generated only if DefectDojo template is detected_ |
...@@ -387,7 +398,7 @@ This job generates a [SBOM](https://cyclonedx.org/) file listing installed packa ...@@ -387,7 +398,7 @@ This job generates a [SBOM](https://cyclonedx.org/) file listing installed packa
It is bound to the `test` stage, and uses the following variables: It is bound to the `test` stage, and uses the following variables:
| Input / Variable | Description | Default value | | Input / Variable | Description | Default value |
| --------------------- | -------------------------------------- | ----------------- | | -------------------------------------- | ----------------------------------------------------------- | -------------------- |
| `sbom-disabled` / `NODE_SBOM_DISABLED` | Set to `true` to disable this job | _none_ | | `sbom-disabled` / `NODE_SBOM_DISABLED` | Set to `true` to disable this job | _none_ |
| `sbom-version` / `NODE_SBOM_VERSION` | The version of @cyclonedx/cyclonedx-npm used to emit SBOM | _none_ (uses latest) | | `sbom-version` / `NODE_SBOM_VERSION` | The version of @cyclonedx/cyclonedx-npm used to emit SBOM | _none_ (uses latest) |
| `sbom-opts` / `NODE_SBOM_OPTS` | Options for @cyclonedx/cyclonedx-npm used for SBOM analysis | `--omit dev` | | `sbom-opts` / `NODE_SBOM_OPTS` | Options for @cyclonedx/cyclonedx-npm used for SBOM analysis | `--omit dev` |
...@@ -402,7 +413,7 @@ When enabled, it is executed on a Git tag with a semantic versioning pattern (`v ...@@ -402,7 +413,7 @@ When enabled, it is executed on a Git tag with a semantic versioning pattern (`v
It uses the following variables: It uses the following variables:
| Input / Variable | Description | Default value | | Input / Variable | Description | Default value |
|----------------------------|-----------------------------------------------------------------------------|-------------------| | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| `publish-enabled` / `NODE_PUBLISH_ENABLED` | Set to `true` to enable the publish job | _none_ (disabled) | | `publish-enabled` / `NODE_PUBLISH_ENABLED` | Set to `true` to enable the publish job | _none_ (disabled) |
| `publish-args` / `NODE_PUBLISH_ARGS` | npm [publish](https://docs.npmjs.com/cli/v8/commands/npm-publish) extra arguments<br/>yarn [publish](https://classic.yarnpkg.com/lang/en/docs/cli/publish/) extra arguments <br/>pnpm [publish](https://pnpm.io/cli/publish) extra arguments | _none_ | | `publish-args` / `NODE_PUBLISH_ARGS` | npm [publish](https://docs.npmjs.com/cli/v8/commands/npm-publish) extra arguments<br/>yarn [publish](https://classic.yarnpkg.com/lang/en/docs/cli/publish/) extra arguments <br/>pnpm [publish](https://pnpm.io/cli/publish) extra arguments | _none_ |
| :lock: `NODE_PUBLISH_TOKEN` | npm publication registry authentication token | _none_ | | :lock: `NODE_PUBLISH_TOKEN` | npm publication registry authentication token | _none_ |
...@@ -411,7 +422,8 @@ It uses the following variables: ...@@ -411,7 +422,8 @@ It uses the following variables:
The target registry url for publication shall be configured in the `publishConfig` of your `package.json` file. Examples: The target registry url for publication shall be configured in the `publishConfig` of your `package.json` file. Examples:
* for an unscoped package: - for an unscoped package:
```json ```json
{ {
"name": "my-package", "name": "my-package",
...@@ -422,7 +434,9 @@ The target registry url for publication shall be configured in the `publishConfi ...@@ -422,7 +434,9 @@ The target registry url for publication shall be configured in the `publishConfi
// ... // ...
} }
``` ```
* for a scoped package:
- for a scoped package:
```json ```json
{ {
"name": "@acme/my-package", "name": "@acme/my-package",
...@@ -445,11 +459,10 @@ For example, if your project is `https://gitlab.example.com/my-org/engineering-g ...@@ -445,11 +459,10 @@ For example, if your project is `https://gitlab.example.com/my-org/engineering-g
Don't forget to exclude undesired folders and files from the package resources (simply add them to your `.gitignore` or `.npmignore` file): Don't forget to exclude undesired folders and files from the package resources (simply add them to your `.gitignore` or `.npmignore` file):
* the `.npm/`, `.yarn/` or `.pnpm-store` folder, that is used internally by the Node template to store `npm`, `yarn` or `pnpm` cache (depending on the package manager you're actually using), - the `.npm/`, `.yarn/` or `.pnpm-store` folder, that is used internally by the Node template to store `npm`, `yarn` or `pnpm` cache (depending on the package manager you're actually using),
* the `reports/` folder, that is used by most _to be continuous_ to output all kind of reports, - the `reports/` folder, that is used by most _to be continuous_ to output all kind of reports,
* the Node.js build output dir (if any), - the Node.js build output dir (if any),
* any other undesired file & folder that you don't want to appear in your published package(s). - any other undesired file & folder that you don't want to appear in your published package(s).
## Variants ## Variants
...@@ -464,7 +477,7 @@ This variant allows delegating your secrets management to a [Vault](https://www. ...@@ -464,7 +477,7 @@ This variant allows delegating your secrets management to a [Vault](https://www.
In order to be able to communicate with the Vault server, the variant requires the additional configuration parameters: In order to be able to communicate with the Vault server, the variant requires the additional configuration parameters:
| Input / Variable | Description | Default value | | Input / Variable | Description | Default value |
| ----------------- | -------------------------------------- | ----------------- | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `TBC_VAULT_IMAGE` | The [Vault Secrets Provider](https://gitlab.com/to-be-continuous/tools/vault-secrets-provider) image to use (can be overridden) | `registry.gitlab.com/to-be-continuous/tools/vault-secrets-provider:latest` | | `TBC_VAULT_IMAGE` | The [Vault Secrets Provider](https://gitlab.com/to-be-continuous/tools/vault-secrets-provider) image to use (can be overridden) | `registry.gitlab.com/to-be-continuous/tools/vault-secrets-provider:latest` |
| `vault-base-url` / `VAULT_BASE_URL` | The Vault server base API url | _none_ | | `vault-base-url` / `VAULT_BASE_URL` | The Vault server base API url | _none_ |
| `vault-oidc-aud` / `VAULT_OIDC_AUD` | The `aud` claim for the JWT | `$CI_SERVER_URL` | | `vault-oidc-aud` / `VAULT_OIDC_AUD` | The `aud` claim for the JWT | `$CI_SERVER_URL` |
...@@ -482,7 +495,7 @@ Then you may retrieve any of your secret(s) from Vault using the following synta ...@@ -482,7 +495,7 @@ Then you may retrieve any of your secret(s) from Vault using the following synta
With: With:
| Parameter | Description | | Parameter | Description |
| -------------------------------- | -------------------------------------- | | -------------------------------- | --------------------------------------------------------------------- |
| `secret_path` (_path parameter_) | this is your secret location in the Vault server | | `secret_path` (_path parameter_) | this is your secret location in the Vault server |
| `field` (_query parameter_) | parameter to access a single basic field from the secret JSON payload | | `field` (_query parameter_) | parameter to access a single basic field from the secret JSON payload |
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment