-
Clément Contet authoredClément Contet authored
GitLab CI template for Angular
This project implements a GitLab CI/CD template to build, test and analyse your Angular projects.
Usage
In order to include this template in your project, add the following to your gitlab-ci.yml
:
include:
- project: 'to-be-continuous/angular'
ref: '4.2.3'
file: '/templates/gitlab-ci-angular.yml'
Global configuration
The Angular template uses some global configuration used throughout all jobs.
Name | description | default value |
---|---|---|
NG_CLI_IMAGE |
The Docker image used to run Angular-CLI (ng) ![]() |
registry.hub.docker.com/trion/ng-cli-karma:latest |
NPM_CONFIG_REGISTRY |
NPM registry |
none (defaults to https://registry.npmjs.org ) |
NPM_CONFIG_SCOPED_REGISTRIES |
Space separated list of NPM scoped registries (formatted as @somescope:https://some.npm.registry/some/repo @anotherscope:https://another.npm.registry/another/repo ) |
none |
NG_WORKSPACE_DIR |
Angular workspace directory | . |
NG_INSTALL_EXTRA_OPTS |
Extra options to install project dependencies (with npm ci ) |
none |
Configuring scoped registries
You may configure scoped registries with the $NPM_CONFIG_SCOPED_REGISTRIES
variable.
The value is expected as a (whitespace-separated) list of @registry_scope:registry_url
.
The Angular template also supports authentication tokens for each, simply by defining NPM_REGISTRY_<SCOPE>_AUTH
(as project or group secret variables).
<SCOPE>
part is the registry_scope
transformed in SCREAMING_SNAKE_CASE (uppercase words separated by underscores).
Example: declare the GitLab chart repository from another GitLab project
variables:
NPM_CONFIG_SCOPED_REGISTRIES: "@public-repo:https://public.npm.registry/some/repo @priv-repo:https://private.npm.registry/another/repo"
# NPM_REGISTRY_PRIV_REPO_AUTH set as a project secret variables
Jobs
ng-lint
job
The Angular template features a job ng-lint
that performs Angular source code lint.
It is bound to the check
stage, and uses the following variable:
Name | description | default value |
---|---|---|
NG_LINT_ARGS |
Angular ng lint arguments | lint |
ng-build
job
The Angular template features a job ng-build
that performs build and tests all at once.
Those stages are performed in a single job for optimization purpose (it saves time) and also for jobs dependency reasons (some jobs such as SONAR analysis have a dependency on test results).
Those stage are bound to the build
stage, and uses the following variable:
Name | description | default value |
---|---|---|
NG_TEST_ARGS |
Angular ng test arguments | test --code-coverage --reporters progress,junit |
NG_BUILD_ARGS |
Angular ng build arguments | build |
The next chapters presents some requirements related to your unit tests (using Karma).
Use a headless browser
To be able to launch unit tests with Angular CLI, the Angular template requires a headless browser within the Docker
image NG_CLI_IMAGE
(it is the case with the default image, docker-ng-cli-karma).
Code Coverage reports
In order to be able to compute and enable GitLab code coverage integration,
the Angular template expects the following in your karma.conf.js
:
- Add the karma-coverage package:
require('karma-coverage'),
- Configure the 2 reporters withing this config section:
coverageReporter: {
dir: 'reports',
subdir: '.',
reporters: [
// 'text-summary' to let GitLab grab coverage from stdout
{type: "text-summary"},
// 'cobertura' to enable GitLab test coverage visualization
{type: 'cobertura', file: 'ng-coverage.cobertura.xml'}
],
},
reports/ng-coverage-<projectName>.cobertura.xml
(it can be in sub-folders but must follow the file name pattern).
- Additionally, if using SonarQube, you may also want to generate LCOV report:
coverageReporter: {
dir: 'reports',
subdir: '.',
reporters: [
// 'text-summary' to let GitLab grab coverage from stdout
{type: "text-summary"},
// 'cobertura' to enable GitLab test coverage visualization
{type: 'cobertura', file: 'ng-coverage.cobertura.xml'},
// 'lcovonly' to enable SonarQube test coverage reporting
{type: 'lcovonly', file: 'ng-coverage.lcov.info'}
],
},
Unit Tests reports
In order to be able to integrate your test reports to GitLab:
- Add the karma-junit-reporter package as dev dependency:
npm install --save-dev karma-junit-reporter
- In your
karma.conf.js
, add the plugin:
// 'karma-junit-reporter' to enable GitLab unit test report integration
require('karma-junit-reporter'),
- Add the config section:
// 'karma-junit-reporter' to enable GitLab unit test report integration
junitReporter: {
outputDir: 'reports',
outputFile: 'ng-test.xunit.xml',
useBrowserName: false,
...
}
reports/ng-test-<projectName>.xunit.xml
or reports/<projectName>/ng-test.xunit.xml
.
Additionally, if using SonarQube, you may also want to generate SonarQube generic test report:
- Add karma-sonarqube-execution-reporter to your project as a dev dependency:
npm install --save-dev karma-sonarqube-execution-reporter
- In your
karma.conf.js
, add the plugin:
// 'karma-sonarqube-execution-reporter' to enable SonarQube unit test report integration
require('karma-sonarqube-execution-reporter')
- Add the config section:
// 'karma-sonarqube-execution-reporter' to enable SonarQube unit test report integration
sonarQubeExecutionReporter: {
outputDir: 'reports',
outputFile: 'ng-test.sonar.xml',
...
}
- Finally add the
sonarqubeUnit
reporter in the reporters parameter of theNG_TEST_ARGS
variable :
NG_TEST_ARGS: test --reporters junit,sonarqubeUnit`
ng-e2e
job
The Angular template features a job ng-e2e
that performs protractor tests
This stage is bound to the test
stage and uses the following variables :
Name | description | default value |
---|---|---|
NG_E2E_ARGS |
Angular ng e2e arguments | e2e |
NG_E2E_ENABLED |
set to true to enable the e2e tests execution |
none (disabled by default) |
Implementation rely on the official Angular CLI tool (ng build
and ng test
commands).
To enable JUnit reporting on this job, you'll need to add jasmine-reporters dependency to your project and add the following snippet to your protractor config file :
const { JUnitXmlReporter } = require('jasmine-reporters');
exports.config = {
...
onPrepare() {
jasmine.getEnv().addReporter(new JUnitXmlReporter({
consolidateAll: true,
savePath: 'reports',
filePrefix: 'ng-e2e.xunit'
}));
}
...
}
ng-sbom
job
This job generates a SBOM file listing installed packages using @cyclonedx/cyclonedx-npm.
It is bound to the test
stage, and uses the following variables:
Name | description | default value |
---|---|---|
NG_SBOM_DISABLED |
Set to true to disable this job |
none |
NG_SBOM_VERSION |
The version of @cyclonedx/cyclonedx-npm used to emit SBOM | none (uses latest) |
NG_SBOM_OPTS |
Options for @cyclonedx/cyclonedx-npm used for SBOM analysis | --omit dev |
ng-publish
job
The Angular template features a ng-publish
job to publish the built project.
This job is bound to the publish
stage, and uses the following variable:
Name | description | default value |
---|---|---|
NG_PUBLISH_ENABLED |
Set variable to true to enable the publish job |
none (disabled) |
NG_PUBLISH_PROJECTS |
Space separated list of projects to publish | If no project is specified, all workspace projects are published |
NG_PUBLISH_ARGS |
NPM publish arguments | --verbose |
NPM_PUBLISH_REGISTRY |
NPM registry to publish to | uses GitLab project npm packages registry |
![]() NPM_PUBLISH_TOKEN
|
NPM publication registry authentication token | none |
@scope/package-name
:
- The
@scope
is the root namespace of the GitLab project. It must match exactly, including the case. - The
package-name
can be whatever you want.
For example, if your project is https://gitlab.example.com/my-org/engineering-group/team-amazing/analytics
, the root namespace is my-org
. When you publish a package, it must have my-org
as the scope.
For more details see Package naming convention.
package.json
file (not the workspace top-level one).
{
"name": "@my-org/hello-world",
"version": "0.0.6",
"peerDependencies": {
"@angular/common": "^10.1.6",
"@angular/core": "^10.1.6"
},
"dependencies": {
"tslib": "^2.0.0"
},
"publishConfig": {
"@my-org:registry": "https://<publication-registry-url>"
}
}
https://<gitlab-host>/api/v4/projects/<your_project_id>/packages/npm/
, with:
-
<gitlab-host>
is your GitLab host domain name. -
<your_project_id>
is your project ID, found on the project’s home page.
SonarQube analysis
If you're using the SonarQube template to analyse your Angular code, here is a sample sonar-project.properties
file:
# see: https://docs.sonarqube.org/latest/analyzing-source-code/test-coverage/javascript-typescript-test-coverage/
# set your source directory(ies) here (relative to the sonar-project.properties file)
sonar.sources=app
# exclude unwanted directories and files from being analysed
sonar.exclusions=node_modules/**,dist/**,**/*.spec.ts
# set your tests directory(ies) here (relative to the sonar-project.properties file)
sonar.tests=app
sonar.test.inclusions=**/*.spec.ts
# tests report: generic format
# set the path configured with karma-sonarqube-execution-reporter
sonar.testExecutionReportPaths=reports/ng-test.sonar.xml
# lint report: TSLint JSON
sonar.typescript.tslint.reportPaths=reports/ng-lint.tslint.json
# coverage report: LCOV format
# set the path configured with karma-coverage-istanbul-reporter
sonar.typescript.lcov.reportPaths=reports/ng-coverage.lcov.info
More info: