@d-cat/tag-cli/README.md

# [@d-cat/tag-cli](https://www.npmjs.com/package/@d-cat/tag-cli)

[![npm](https://img.shields.io/npm/v/@d-cat/tag-cli?color=brightgreen)](https://www.npmjs.com/package/@d-cat/tag-cli) [![node](https://img.shields.io/node/v/@d-cat/tag-cli?color=brightgreen)](<(https://www.npmjs.com/package/@d-cat/tag-cli)>) [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/) [![codecov](https://codecov.io/gl/d-cat:templates:ci-cd/tag-cli/branch/master/graph/badge.svg?token=l7O5FqoJsT)](https://codecov.io/gl/d-cat:templates:ci-cd/tag-cli)

> [@d-cat/tag-cli](https://www.npmjs.com/package/@d-cat/tag-cli) is a [VZ](https://vodafoneziggo.com) CLI package that should be used to configure containers and tags when using [@d-cat/tag-manager](https://www.npmjs.com/package/@d-cat/tag-manager).

- [Install](#install)
- [Usage](#usage)
  * [Tag Manager commands](#tag-manager-commands)
    + [`create-tag-manager`](#create-tag-manager)
      - [What's included](#what-s-included)
      - [Update depedencies](#update-depedencies)
      - [Examples](#examples)
      - [GitLab configuration](#gitlab-configuration)
        * [CI/CD variables to create in GitLab](#cicd-variables-to-create-in-gitlab)
    + [`bundle-tag-manager`](#bundle-tag-manager)
      - [Example](#example)
      - [Test the bundle](#test-the-bundle)
    + [`deploy-test-instance`](#deploy-test-instance)
      - [Examples](#examples-1)
    + [`deploy-tag-manager`](#deploy-tag-manager)
      - [Examples](#examples-2)
  * [Tag Template Commands](#tag-template-commands)
    + [`deploy-tag-template`](#deploy-tag-template)
      - [Examples](#examples-3)
    + [`update-dependents`](#update-dependents)
      - [Example](#example-1)
  * [Tag commands](#tag-commands)
    + [`create-new-tag`](#create-new-tag)
      - [What's included](#what-s-included-1)
      - [Dependencies](#dependencies)
      - [Examples](#examples-4)
      - [Configuring a tag](#configuring-a-tag)
        * [Pipeline settings](#pipeline-settings)
        * [Tag Manager settings](#tag-manager-settings)
          + [`ITrigger`](#itrigger)
      - [GitLab configuration](#gitlab-configuration-1)
        * [CI/CD variables to create in GitLab](#cicd-variables-to-create-in-gitlab-1)
        * [Troubleshooting](#troubleshooting)
    + [`test-tag`](#test-tag)
      - [Examples](#examples-5)
    + [`lint-tag`](#lint-tag)
      - [Examples](#examples-6)
    + [`type-tag`](#type-tag)
      - [Examples](#examples-7)
    + [`publish-tag`](#publish-tag)
      - [Examples](#examples-8)
  * [Troubleshooting](#troubleshooting-1)


## Install

```bash
npm i -D @d-cat/tag-cli
```

# Usage
@d-cat/tag-cli is a toolkit to deploy and develop a Tag Manager with Tags using GitLab and Google Cloud Platform.
___

## Tag Manager commands
---
A D-CAT Tag Manager is a collective name for all layers that work together to generate and deploy a working JavaScript bundle of multiple GitLab repositories of a single GitLab Group in a defined Google Cloud Storage Bucket. To effectuate this, we depend on the following:

* [@d-cat/tag-manager](https://www.npmjs.com/package/@d-cat/tag-manager);
* [@d-cat/tag-cli](https://www.npmjs.com/package/@d-cat/tag-cli);
* [@d-cat/ddm-core](https://www.npmjs.com/package/@d-cat/ddm-core)
* [GitLab Group](https://docs.gitlab.com/ee/user/group/);
* [GitLab Group API](https://docs.gitlab.com/ee/api/groups.html);
* GitLab Tag Manager Repository in a GitLab Group;
* More than 0 GitLab Tag Repositories (generated through @d-cat/tag-cli) in a GitLab Group;

![bundle-tag-manager](https://www.plantuml.com/plantuml/png/PP4nRuD038Nt-nLFx205MBf46IfbQQTaYpeud8Ee21Tn9b9LyTzxLYyj5zY-Ppy_czjveL6cQsykhhSy8ZkuAsFVoHkTiH_TTClmRH2QkWir0g6sJh5AiKnnOsRpDpkEVULRxxuUqyd7ECs9dKVsSkY4DokbN2dLIgdD38F_s2ErUAU1MXxrc5DW_w5xDRsRhCRY97Pu2LyXlnLBGcVoZCms93aFzzpoNTruf0M7uiBx6Rp0h7wz74MnHGmBN3vnzSJrakEIAgMxBG5vlatILzNuPysE1niU-GS0)

---

### `create-tag-manager`
The `create-tag-manager` creates a Tag Manager boilerplate designed to use with @d-cat/tag-cli within GitLab CI/CD. Please make sure you update the e2e and unit tests to suite your needs and match the TMS you want to deploy.

```bash
Options:
  --version               Show version number                          [boolean]
  --help                  Show help                                    [boolean]
```

#### What's included
The Tag Manager boilerplate contains everything to:
* unit test the build version of the tag manager
* e2e test the build version of the tag manager in chrome headless browser
* deploy test/prod containers in a GCP bucket
* deploy testable open websites with the TMS running on it for functional testing
* dockerized TMS to run the TMS locally in isolation
* dockerized TMS that registers images in GitLab private registery
* stable pipeline file with artifacts enabled both on success as failure
* babel/ts for browser compatibility

Some parts of the generated boilerplate can look weird as the pipeline will interpolate varialbes/files/libs and build the full version when running `npx tag-cli bundle-tag-manager`. 

> The roadmap is to replace interpolated files with a configuration (json/yml) file to make it more intuitive.

#### Update depedencies
By default dependencies are fixed in the package-lock.json and package.json files. Updating a package manually will break the pipeline as it runs `npm ci`, thus you have to update both package.json as package-lock.json:

```bash
npm i yourpackage@1.0.0
```

#### Examples
Make sure docker is installed and you've updated your [.env](https://docs.docker.com/compose/environment-variables/) file.

```bash
# create a new tag folder
mkdir myTag

cd myTag

# creating a tag manager boilerplate
npx tag-cli create-tag-manager

# running a tag manager locally in isolation on localhost:8080
docker build -t ${img_name} .
docker run --name ${container_name} --rm -p 8080:8080 -ti ${img_name}:latest

# running a tag manager locally in isolation with docker-compose
docker-compose build bundle
docker-compose up bundle

# running the full tms pipeline (except deployment in gcp/test sites) locally in isolation
docker-compose build deploy
docker-compose up deploy
```

#### GitLab configuration
Make sure you did all necessary steps to [start with GitLab](https://docs.gitlab.com/ee/gitlab-basics/).

- Create a new GitLab (sub)group with name as Container ID: (i.e. 9999);
- Create a new project, called Tag Manager;
- Create CI/CD variables.

##### CI/CD variables to create in GitLab

Before you run the pipeline, make sure you [create the necessary CI/CD variables](https://docs.gitlab.com/ee/ci/variables/#custom-environment-variables) in the GitLab TMS Group.

| CI/CD variable          |   Type   |                                                                                                Description |
| ----------------------- | :------: | :--------------------------------------------------------------------------------------------------------- |
| `PERSONAL_ACCESS_TOKEN` | variable |                                       Your personal access token, that has owner rights of the tags group. |
| `CONTAINER_ID`          | variable |                                                                  Group ID that should be queried for tags. |
| `GCLOUD_SERVICE_KEY`    |   file   | Your [authentication file](https://cloud.google.com/docs/authentication/getting-started) for Google Cloud. |
| `SSH_KEY`               |   file   |                                                           Your SSH key to clone and push repo's of GitLab. |
| `GIT_USER_EMAIL`        | variable |                                                                   Your git email: `git config user.email`. |
| `GIT_USER_NAME`         | variable |                                                                Your git user name: `git config user.name`. |

---

### `bundle-tag-manager`
The `bundle-tag-manager` command bundles all tag `artifacts` to eventually transpile and deploy a Tag Manager. 

```bash
Options:
  --version                Show version number                         [boolean]
  --help                   Show help                                   [boolean]
  --access-token, --token  The GitLab personal accesstoken with owner rights.
  --group-id, --id         The GitLab Group ID that should be analyzed.
  --dir-name, --dir        The unique dir name where to store the temporary artifacts.
  --branch-name, --branch  The current branch.
  --job-token, --j         Unique token linked to a pipeline built. Previously this was a job token but due to security issues we recommend using the $CI_PIPELINE_ID.
  --environment --e        TMS environment, should be either `development` or `production`.
```

#### Example
Note that all flags are either mandatory or are set as a node environment variable. 

```bash
# the environment variable should be used to trigger
# the tag managers pipeline from another pipeline or API
# more at: https://docs.gitlab.com/ee/ci/triggers/#making-use-of-trigger-variables

# gitlab variables to set as env variables
ACCESS_TOKEN=$MY_PERSONAL_ACCESS_TOKEN
GROUP_ID=$GITLAB_GROUP_ID

# build a dev bundle
# variables used are built-in gitlab env variables
# note that we use ci_pipeline_id as job_token
# this token is only used for e2e testing
npx tag-cli bundle-tag-manager --dir-name lib --branch-name $CI_COMMIT_REF_NAME --job-token $CI_PIPELINE_ID --environment $ENV_VAR_FROM_ANOTHER_PIPELINE
```

#### Test the bundle
Instead of running the pipeline from a shared runner in GitLab, you could also go for 2 other options to verify if the built is correct.

* [install a GitLab runner](https://docs.gitlab.com/runner/install/) locally and execute the `bundle` job from a Tag Manager project
* use Docker within a Tag Manager project:

```bash
docker build -t $MY_TMS_IMG .

# serve the container on localhost:8080
docker run --name $MY_CONTAINER_NAME --rm -p 8080:8080 -ti $MY_TMS_IMG:latest

# using docker-compose to only build the build job
docker-compose build build

# serve the container on localhost:8080
docker-compose up build
```
---

### `deploy-test-instance`
The `deploy-test-instance` command deploys a build version of the Tag Manager on a private or public website at `https://instances.gitlab.io/[tagmanager_id]/[branchName]`. It can take up to 10 minutes before your test instance is deployed, starting from your push. 

Note that his commands looks up the `tdn` folder in the root directory of the repo and searches for the build file of the Tag Manager, typically something like `tdn9999.js`. The corresponding deploy url would be `https://instances.gitlab.io/9999`. The command is meant to run it right after a bundle stage.

> Note that you need access to the instances.gitlab.io group before you can publish to it.

```bash
Options:
  --version                Show version number                          [boolean]
  --help                   Show help                                    [boolean]
  --access-token, --token  The GitLab personal accesstoken with owner rights.
  --group-id, --id         The GitLab Group ID that should be analyzed
  --branch-name, --n       The current branch name, equal to: $CI_COMMIT_REF_NAME.
  --job-token, --j         The GitLab's built-in job token: $CI_JOB_TOKEN. This token is generated for each job.
```

#### Examples
```bash
# Personal access token that's needed to authenticate
ACCESS_TOKEN=$PERSONAL_ACCESS_TOKEN

# Job Token generated by GitLab so we can see in the
# TMS interface that we triggered the pipeline of the instances group
JOB_TOKEN=$CI_JOB_TOKEN

# The Group ID in which the TMS project is placed
GROUP_ID=$TMS_GROUP_ID

npx tag-cli deploy-test-instance --branch-name $CI_COMMIT_REF_NAME
```
---

### `deploy-tag-manager`
The deploy tag manager commands deploys the build tag manager to a Google Cloud Bucket and optionally sends a success email to a list of receivers.

```bash
Options:
  --version            Show version number                               [boolean]
  --help               Show help                                         [boolean]
  --bucket-name, -b    Name of the Google Cloud Bucket.
  --key-file-name, -k  Google Cloud authentication JSON key.
  --group-name, -i     The namespace of the GitLab Group, equal to: $CI_PROJECT_NAMESPACE.
  --branch-name, -n    The current branch name, equal to: $CI_COMMIT_REF_NAME.
  --node-email, -gm    Gmail email address, that can function as transporter. More info at: https://nodemailer.com/usage/using-gmail/.
  --node-pass, -pass   Password of the gmail account that functions as transporter.
  --receivers, -list   String array of receivers.
  --is-empty -e        Boolean that indicates if an empty container should be deployed. Defaults to false.
```

#### Examples
Note that all flags are either mandatory or are set as an environment variable.

```bash
# The bucket name of the Google Cloud Bucket
BUCKET_NAME=$MY_GCP_BUCKET_NAME

# The Key file is your GCP IAM json.
# make sure it has write rights to the 
# correct bucket only
KEY_FILE=$MY_KEY_FILE

# The namespace of the gitlab group,
# we use this to determine wether the TMS id
# equals the namespace to prevent unexpected overrides
# of a production container
# so a GitLab Group called 9999
# must contain a TMS repo with tdn9999.ts entrypoint.
GROUP_NAME=$CI_PROJECT_NAMESPACE

# GitLab branch var
BRANCH_NAME=$CI_COMMIT_REF_NAME

# gmail where we send the mail from
NODE_EMAIL=$EMAIL_ADDRESS_OF_SENDER

# gmail pass
NODE_PASS=$EMAIL_PASS

# string with spaces of receiver mails
RECEIVERS=foo.bar@gmail.com

# You can deploy both an empty TMS (for initial release)
# or a non-empty.

# deploy empty TMS
npx tag-cli deploy-tag-manager --is-empty

# deploy non-empty (default)
npx tag-cli deploy-tag-manager --no-is-empty
```
___

## Tag Template Commands
---

A Tag Template functions as the backbone of a tag. It's a NPM package. It contains critical logic of handling tags logic and returns a class with a set of methods that we can use, inherit and override. Typically a Tag Template contains the following:

* it accepts an initializer object;
* it notifies the dataLayer that a Tag Template has been initialized;
* it's a class;
* it returns a render method;
* it's an NPM package, starting with: @d-cat/tag-template-;
* it publishes according NPM semver.

![tag-or-tag-template](https://unpkg.com/@d-cat/tag-cli/assets/tag-or-tag-template.png)

---

### `deploy-tag-template`
The `deploy-tag-template` command deploys a tag template on a NPM registery of choice. The package version is incremented based on the commits done through i.e. [commitizen](https://www.npmjs.com/package/commitizen). Standard-version is used to publish either a major, minor or patch according to [NPM's semver](https://docs.npmjs.com/misc/semver). A CHANGELOG.md is added or updatet within the repo. Please note that you should only use version 1.0.0 on a stable release. Using version 0.* will behave differently using NPM's semver.

```bash
Options:
  --version                  Show version number                         [boolean]
  --help                     Show help                                   [boolean]
  --access-token, --token    The GitLab personal accesstoken with owner rights.
  --branch-name, --branch    The current branch.
  --dist-dir, --d            The destination directoy, when publishing a flat package. Default to `lib`.
  --is-flat-package          Deploy package as flat-package (i.e. using lerna).
  --project-path, --p        The relative path to the project's repository in GitLab. This equals GitLab's built-in variable: $CI_PROJECT_PATH.
  --key, --k                 SSH Key linked to your personal GitLab account.
  --user, -u                 Git username linked to your personal GitLab account.
  --email, -e                Git email linked to your personal GitLab account.
  --o-auth-token, --oauth    NPM Registery authentication file.
```

#### Examples
Note that all flags are either mandatory or are set as an environment variable.

```bash
# Personal access token generated within gitlab
ACCESS_TOKEN=$MY_PERSONAL_ACCESS_TOKEN

# SSH key is used to increment the version of the npm package
# based on the commits done, according to commitizen.
# standard-version is used to update a major, minor or patch and use
# NPM's semver.
KEY=$SSH_KEY

# your git user + email for authentication
GIT_USER=$GIT_USER_VAR
GIT_EMAIL=$GIT_EMAIL_VAR

# deploy a flat package to a npm registery
# dist dir is set to dist, thus the build is placed in dist
# defined in your package.json
npx tag-cli deploy-tag-template --is-flat-package --dist-dir dist --branch-name $CI_COMMIT_REF_NAME --project-path $CI_PROJECT_PATH

# deploy a standard npm package
npx tag-cli deploy-tag-template --no-is-flat-package --branch-name $CI_COMMIT_REF_NAME --project-path $CI_PROJECT_PATH
```

---

### `update-dependents`
If not using [npm semver](https://docs.npmjs.com/misc/semver), you can use `update-dependents` to keep track of dependencies. The `update-dependents` command updates and triggers the first `1000` [default branches](https://docs.gitlab.com/ee/user/project/repository/branches/#default-branch) of all GitLab projects that either use the current package as dependency or as devDependency, using the [GitLab API](https://docs.gitlab.com/ce/api/projects.html#list-all-projects). Please note when using `npm ci` this will not impact the package-lock.json and thus you have to update that one manually.

```bash
# flags
Options:
  --version                Show version number                         [boolean]
  --help                   Show help                                   [boolean]
  --access-token, --token  The GitLab personal accesstoken with owner rights.
  --dir-name, --dir        The dir name.  
  --project-id, --d        The current project ID, equal to: $CI_PROJECT_ID.
  --key, --k               SSH Key linked to your personal GitLab account.
  --user, -u               Git username linked to your personal GitLab account.
  --email, -e              Git email linked to your personal GitLab account.
```

![update-dependents](https://www.plantuml.com/plantuml/png/dT4x3iCW40JGtgT0z3Wo7-WYxX5Hh6pa8X1PoVh-yG7C8hOU7iE8-4FuubdBTC3wXZqB6JUr0ZuGTeMv7WKmgqLEz04jwTnqSjihS9qBV2SFLy7hTbeIIZt5RQRJk34COnd6fSOWIwDXunacj1wdavZd1beQHOPXBCCusj1ev5izmmJQnFpPpbh-)

#### Example
Note that all flags are either mandatory or are set as an environment variable:

```bash
ACCESS_TOKEN=myAccesToken
DIR_NAME=foo
PROJECT_ID=1210
SSH_KEY=key
GIT_EMAIL=myEmail
```

```bash
npx tag-cli update-dependents --user myGitName
```
___

## Tag commands
-------------------
A Tag is used to initialize a [Tag Template](#tag-template-commands) or to handle a Google Tag Manager's data object. A tag should never contain complex logic. Use a tag template instead. A Tag is easy to read and easy to debug. There should be no complexity in a tag. The following is applicable for a Tag:

* it exports a default function without arguments;
* it initializes a tag template;
* it contains a `publish-tag` job;
* it contains no complexity.

### `create-new-tag`
The `create-new-tag` command creates a new Tag boilerplate designed to use with @d-cat/tag-cli within GitLab CI/CD.

```bash
Options:
  --version               Show version number                          [boolean]
  --help                  Show help                                    [boolean]
```

#### What's included
The Tag boilerplate contains all configurations to:
* Jest setup
* tslint setup
* prettier
* husky
* tag config file (`tag-cli.json`)
* dockerized tag environment to run the tag locally in isolation
* dockerized TMS that registers images in GitLab private registery
* stable pipeline file with artifacts enabled both on success and failure
* standard-version to created changelog + semver in the pipeline

#### Dependencies
By default dependencies are fixed in the package-lock.json and package.json files. Updating a package manually will break the pipeline as it runs `npm ci`, thus you have to update both package.json as package-lock.json:

```bash
npm i yourpackage@1.0.0
```

#### Examples
Make sure docker is installed and you've updated your [.env](https://docs.docker.com/compose/environment-variables/) file.

```bash
# creating a tag boilerplate
npx tag-cli create-new-tag

# running a tag locally in isolation on localhost:1234
docker build -t ${img_name} .
docker run --name ${tag_name} --rm -p 1234:1234 ${img_name}:latest

# running a tag locally in isolation with docker-compose
docker-compose build build
docker-compose up build

# running the full tag pipeline (except uploading artifacts) locally in isolation
docker-compose build pipeline
docker-compose up pipeline
```

#### Configuring a tag
The `create-new-tag` command will create a file called `tag-cli.json`. This file contains all configurations. The `tag-cli.json` file includes both `pipeline` as `tag manager` settings.

##### Pipeline settings
This are settings that indicates how a tag should behave inside a pipeline.

| Prop        | Type           | Desc  |
| ------------- |:-------------:| :-----|
| `isPipelineActive`      | Boolean | Boolean that indicates if the tags pipeline should run.|
| `pipelineBranches`      | String[]      | String array of branches that should trigger the Tag's pipeline. |
| `isImportInTagManager` | Boolean      |   Boolean to indicate if the tag should be imported in the tag manager. |
| `tagManagerBranches`      | String[]      | String array of tag branches that should be included in a tag manager bundle. |
| `isActive` | Boolean      | Boolean that indicates if the tag is active. |
| `isTrigger` | Boolean      | Boolean that indicates if the tag should trigger the Tag Managers pipeline after a publish. |

##### Tag Manager settings
This are settings that determine how the tag should behave inside the Tag Manager.

| Prop        | Type           | Desc  |
| ------------- |:-------------:| :-----|
| `firingAmount`      | Number | Amount a tag should be invoked when all business rules apply. |
| `priority`      | Number      | Priority of tag. 1 is highest priority. |
| `id` | String      |   UUID. |
| `urls`      | IUrl[]      | Object Array that contains 2 props: `url` (RegExp) and `reverse` (boolean).  |
| `triggers` | ITrigger[]      | Boolean that indicates if the tag is active. |

###### `ITrigger`

| Options   |  Type   | Required  Description |
| --------- | :-----: | :------ |:---- |
| `type`    | String  |     true | Type of the trigger, this must be one of the following: `instantly`, `datalayer`, `event`, `domEvent`, `persisted`. Note that when using `instantly`, this means the other triggers automatically are ignored, thus the tag will execute immediately. |
| `id`      | String  |     true |                                                                                                                                    Uniquely generated ID. Using the CLI this will generate an ID using [uuid/v1](https://www.npmjs.com/package/uuid). |
| `name`    | String  |    false |                                                                                                                                                                                         Depending on the type, the name key has a different function. |
| `value`   | String  |    false |                                                                                                                                                                                        Depending on the type, the value key has a different function. |
| `reverse` | Boolean |    false |                                                                                                                                                                                                            Reverse the match on either value or name. |
| `element` | String  |    false |                                                                                                                                                                                                 `window`, `document` both as string or an element ID. |

#### GitLab configuration
Make sure you did all necessary steps to [start with GitLab](https://docs.gitlab.com/ee/gitlab-basics/).


##### CI/CD variables to create in GitLab
Before you run the pipeline, make sure you [create the necessary CI/CD variables](https://docs.gitlab.com/ee/ci/variables/#custom-environment-variables) in your GitLab Tag project.

| CI/CD variable          |   Type   |                                                                                                Description |
| ----------------------- | :------: | :----- |
| `PERSONAL_ACCESS_TOKEN` | variable |                                       Your personal access token, that has owner rights of the tags group. |
| `TAG_MANAGER_ID`        | variable |                                                                      Gitlab Project ID of the Tag Manager. |
| `GCLOUD_SERVICE_KEY`    |   file   | Your [authentication file](https://cloud.google.com/docs/authentication/getting-started) for Google Cloud. |
| `SSH_KEY`               |   file   |                                                           Your SSH key to clone and push repo's of GitLab. |
| `GIT_USER_EMAIL`        | variable |                                                                   Your git email: `git config user.email`. |
| `GIT_USER_NAME`         | variable |                                                                Your git user name: `git config user.name`. |
| `CODECOV_TOKEN`         | variable |                                                       Your Codecov token to publish code coverage reports. |

##### Troubleshooting
> If the pipeline isn't running after the initial commit, trigger the pipeline manually.

---

### `test-tag`
The `test-tag` command runs the test script as defined in your package.json and uploads a codecoverage report to [Codecov](https://codecov.io/).

```bash
Options:
  --version                 Show version number                              [boolean]
  --help                    Show help                                        [boolean]
  --codecov, -c             Your Codecov token to publish code coverage report.
  --branch-name, --n        The current branch name, equal to: $CI_COMMIT_REF_NAME.
```

#### Examples
Note that all flags are either mandatory or are set as an environment variable.

```bash
# secret codecov token generated in the codecov interface
CODE_COV_TOKEN=$MY_CODE_COV_TOKEN

# run tests + upload report to codecov
npx tag-cli test-tag --branch-name $CI_COMMIT_REF_NAME
```

---

### `lint-tag`
The `lint-tag` command runs the [TypeScript linter](https://palantir.github.io/tslint/).

```bash
Options:
  --version                 Show version number                              [boolean]
  --help                    Show help                                        [boolean]
  --branch-name, --n        The current branch name, equal to: $CI_COMMIT_REF_NAME.
```

#### Examples

```bash
npx tag-cli lint-tag --branch-name $CI_COMMIT_REF_NAME
```

---

### `type-tag`
The `type-tag` command runs type checks the tag according TypeScript specs. 

```bash
Options:
  --version                 Show version number                              [boolean]
  --help                    Show help                                        [boolean]
  --branch-name, --n        The current branch name, equal to: $CI_COMMIT_REF_NAME.
```

#### Examples

```bash
npx tag-cli type-tag --branch-name $CI_COMMIT_REF_NAME
```

---

### `publish-tag`
The `publish-tag` command publishes tag artifacts in GitLab, increments the tag version and additionally triggers the Tag Managers pipeline to deploy a new version. The artifacts you publised can be fetched using [GitLab's API](https://docs.gitlab.com/ee/ci/pipelines/job_artifacts.html#downloading-the-latest-artifacts). Both incrementing the version as triggering the Tag Managers API are optional. However, triggering the Tag Managers pipeline is configured in the `tag-cli.json`.

```bash
Options:
  --version             Show version number                              [boolean]
  --help                Show help                                        [boolean]
  --job-token, -j       The GitLab's built-in job token: $CI_JOB_TOKEN. This token
                        is generated for each job.
  --access-token, -t           GitLab's personal access token with admin rights.
  --tag-manager-id, -i  GitLab's Tag Manager project ID.
  --key, -k             SSH Key linked to your personal GitLab account.
  --user, -u            Git username linked to your personal GitLab account.
  --email, -e           Git email linked to your personal GitLab account.
  --increment-version   Boolean that indicates if standard-version should invoke.
```

#### Examples
Note that all flags are either mandatory or are set as an environment variable.

```bash
# Personal access token generated within gitlab
ACCESS_TOKEN=$MY_PERSONAL_ACCESS_TOKEN

# SSH key is used to increment the version of the npm package
# based on the commits done, according to commitizen.
# standard-version is used to update a major, minor or patch and use
# NPM's semver.
KEY=$SSH_KEY

# your git user + email for authentication
GIT_USER=$GIT_USER_VAR
GIT_EMAIL=$GIT_EMAIL_VAR

# we need the job token to trigger the tag managers pipeline
# using the job token will show the tag managers pipeline
# to be triggered in GitLabs interface, and in the TMS
# project it shows our tag defined as the triggerer
JOB_TOKEN=$CI_JOB_TOKEN

# set a gitlab variable where the project id
# of the tag manager is saved
TAG_MANAGER_ID=$TAG_MANAGER_PROJECT_ID

# incrementing version
npx tag-cli publish-tag --increment-version

# do not increment version
npx tag-cli publish-tag --no-increment-version
```

---
## Troubleshooting
- `Publishing tag TypeError: Cannot read property 'map' of undefined`: make sure your `tag-cli.json` has an string array of both `branchesToImportInTagManager` and `branchesToRunInPipeline`.
- `Publishing tag This tag didn't triggered the pipeline.`: Make sure the branch that triggered the pipeline equals a branch that is whitelisted in your `tag-cli.json`.
- `GitLab API: Fetching projects. Unexpected response received from GitLab: [object Object], or the amount of received projects meets the maximum of 1000. Received: undefined` : Retry the pipeline, as the GitLab API didn't returned a correct response. It has probably something to do with a connection lost / timeout.