package-controller/README.md

Package Controller let's you manage SemVer and upgrade your package dependencies automatically

# Package Controller

Upgrade your NPM package dependencies automatically!

NOTE: Currently only compatible with gitlab

## Quick Start

Install

```shell
npm i package-controller --save-dev
```

Add to your package.json

```json
 "packageController": {
    "only": [
      "MY PACKAGE NAME"
    ],
    "exclude": [],
    "skipCi": false
  }
```

## Options

- Only

  Specify packages you want to upgrade

- Exclude

  Exclude packages you don't want to upgrade

- skipCi 

  Disabled as default, skips builds in Merge Requests

# GitLab Configuration

## Requirements

1. Create a Project Access Token
2. Create a CI/CD Variable
3. Configure a Repository
4. Schedule pipeline jobs

## 1. Create a Project Access Token

In your GitLab project go to **Settings -> Access Tokens**

Now create a Project Access Token with the following information.

**Name:**
Package-Controller-AccessToken

**Scopes:**

- API
- read_repository
- write_repository

**and don't forget to copy the token to a safe place (you will need it for the next step).**

## 2. Create a CI/CD Variable

In your GitLab project go to **Settings -> CI/CD**

Expand the **Variables** section and click **Add Variable**

Create the variable with the following information:

**Key**: Package_Controller_AccessToken

**Value**: { **_Use the Package-Controller-AccessToken VALUE_** }

**Flags**: check **Protect variable** and **Mask variable**

Click **Add Variable**

## 3. Configure a Repository

Add to your .gitlab-ci.yml file the following code:

```yaml
package-controller:
   stage: maintenance
   cache: []
   image:
      name: brunomartinspro/node-powershell:latest
      entrypoint: [""]
   script:
    - npx package-controller 
   only:
    - schedules
```

If you want to create also an image for your organization like brunomartinspro/node-powershell:latest

```yaml
FROM mcr.microsoft.com/powershell:7.1.5-debian-buster-slim

RUN apt-get update \
 && apt-get upgrade -y \
 && apt-get install nodejs -y \
 && apt-get install npm -y \
 && apt-get install curl -y

RUN apt install git-all -y
 
RUN npm install -g n
RUN n 14.18.1
```

run the commands:

```shell
docker build -t registry.gitlab.com/MY_ORGANIZATION/tools/package-controller-standalone .
docker push registry.gitlab.com/MY_ORGANIZATION/tools/package-controller-standalone
```

and update the image name variable with:

```yaml
name: registry.gitlab.com/MY_ORGANIZATION/tools/package-controller-standalone:latest
```

If you are using private repositories this is probably the best approach since you can add to your script the configurations for private repositories, for example:

```
# Set URL for your scoped packages.
# For example package with name `@foo/bar` will use this URL for download
npm config set @foo:registry https://gitlab.example.com/api/v4/packages/npm/

# Add the token for the scoped packages URL. This will allow you to download
# `@foo/` packages from private projects.
npm config set -- '//gitlab.example.com/api/v4/packages/npm/:_authToken' "<your_token>"
```

**NOTE:** generally you can replace "<your_token>" with "${CI_JOB_TOKEN}"

as described in [Authenticate with a personal access token or deploy token](https://docs.gitlab.com/ee/user/packages/npm_registry/#authenticate-with-a-personal-access-token-or-deploy-token)

To ignore other jobs from being executed add a rule for each job:

```yaml
except:
  - schedules
```

When you want to ignore other jobs on a specific branch as a manual trigger

```yaml
when: manual
only:
  - master
except:
  - schedules
```

You may have to include a maintenance stage

```yaml
stages:
  - maintenance
```

Also sometimes the pipeline may run in detached mode, this means it won't be building a branch but the merge request itself.

You may want to add validations for these cases like:

```yaml
myJob:
  only:
    - merge_requests
```

## 4. Schedule pipeline jobs

In your GitLab project go to **CI/CD -> Schedules**

Click **New schedule** and set up the schedule to your preferences.

If you don't have any add preferences:

**Description**: Package ControllerInterval

**Pattern**: Custom and set to 0 18 \* \* 4 (Every Thursday at 6 PM every week)

**Cron Timezone**: UTC

**Target Branch**: master

Click **_"Save pipeline schedule"_**.

That's it, everything should work now!