Metadata-Version: 2.5
Name: depdelta-cli
Version: 0.1.0
Summary: DepDelta for CI: review a change's dependency updates on Gerrit or GitLab.
Project-URL: Homepage, https://depdelta.com
Project-URL: Source, https://github.com/mbobiosio/depdelta-cli
Project-URL: Issues, https://github.com/mbobiosio/depdelta-cli/issues
Author: Mbuodile Obiosio
License-Expression: MIT
License-File: LICENSE
Keywords: breaking-changes,ci,dependencies,gerrit,gitlab,renovate
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# depdelta-cli

DepDelta for CI on Gerrit and GitLab: the GitHub App's dependency review,
posted on the change.

On every change that touches a manifest or lockfile, `depdelta`:

1. sends the changed manifests and lockfiles (both ends) to DepDelta. Source
   code is never sent;
2. gets back each update's verdict and, for npm and Maven, the declarations
   it removes or changes;
3. looks for those declarations in the checkout, and sends only the hits
   (path, line, symbol);
4. posts the review: a Gerrit change message (no vote), or one GitLab merge
   request note that later pipelines edit in place.

Nine ecosystems: npm, PyPI, Maven, Composer, Cargo, RubyGems, pub.dev,
NuGet and Go. Needs Python 3.11+ and git, nothing else.

```
docker pull ghcr.io/mbobiosio/depdelta-cli:latest
# or
pip install depdelta-cli
```

## API key

Make one in DepDelta → Settings → API keys for CI, and store it in your CI's
secrets as `DEPDELTA_API_KEY`. Each key gets 240 reviews an hour, waiting
on release notes included.

## Jenkins with Gerrit Trigger

The job runs on `patchset-created`. Gerrit Trigger sets `GERRIT_PROJECT`,
`GERRIT_CHANGE_NUMBER`, `GERRIT_PATCHSET_REVISION` and `GERRIT_CHANGE_URL`.
The review is posted with a Gerrit account's HTTP password: a service
account works best.

The checkout needs the patch set's parent: don't clone with depth 1 (or let
`depdelta` fetch it; it does when the parent is missing).

```groovy
pipeline {
  agent { docker { image 'ghcr.io/mbobiosio/depdelta-cli:latest' } }
  stages {
    stage('DepDelta') {
      steps {
        withCredentials([
          string(credentialsId: 'depdelta-api-key', variable: 'DEPDELTA_API_KEY'),
          usernamePassword(credentialsId: 'gerrit-http',
                           usernameVariable: 'GERRIT_HTTP_USER',
                           passwordVariable: 'GERRIT_HTTP_PASSWORD'),
        ]) {
          // A DepDelta outage shouldn't fail the build.
          catchError(buildResult: 'SUCCESS', stageResult: 'UNSTABLE') {
            sh 'depdelta'
          }
        }
      }
    }
  }
}
```

Without Docker: `pip install depdelta-cli` on the agent, then the same
`sh 'depdelta'`.

`DEPDELTA_GERRIT_URL` overrides Gerrit's address when `GERRIT_CHANGE_URL`
isn't the REST root (a proxy, a different host name for agents).

Messages carry the tag `autogenerated:depdelta`, so Gerrit folds older patch
sets' reviews away, and notify only the change owner.

## GitLab CI

Runs in merge request pipelines. `CI_JOB_TOKEN` can't write notes: give the
job a project access token with the `api` scope (Reporter role is enough) as
`GITLAB_TOKEN`.

```yaml
depdelta:
  image: ghcr.io/mbobiosio/depdelta-cli:latest
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - "**/package.json"
        - "**/package-lock.json"
        - "**/pom.xml"
        - "**/requirements*.txt"
        - "**/pyproject.toml"
        - "**/*.lock"
        - "**/go.mod"
  variables:
    GIT_DEPTH: 0
  script:
    - depdelta
  allow_failure: true
```

Uses link to the files at the merge request's head commit.

## Options

```
depdelta [--repo .] [--base REV --head REV] [--print]
         [--format markdown|text] [--wait 300]
         [--fail-on never|breaking|review|unknown|safe]
         [--api-url URL]
```

- `--print` prints the review instead of posting it. With `--base` and
  `--head` (outside CI) it always prints:
  `depdelta --base origin/main --head HEAD`.
- `--wait` is how long to wait for DepDelta to read release notes it hasn't
  seen yet. After that the review posts as it stands, saying what is still
  being read.
- `--fail-on breaking` exits 1 when an update is breaking, to fail the job.

Exit status: 0 posted (or nothing to review), 1 the `--fail-on` verdict was
met, 2 it couldn't review or post.

## Privacy

Only the changed manifests and lockfiles leave CI, plus, for updates with
removed or changed APIs, the path, line and symbol of each use found. The
source code stays in CI. Gerrit and GitLab credentials are sent only to your
Gerrit or GitLab.

## Development

```
uv sync
make check format test
```

`src/depdelta_cli/usage.py` is copied from depdelta-api
(`app/updates/utils/usage.py`), and `manifests.py` follows its manifest
names: change them there first, then here.

Releases: bump `version` in `pyproject.toml`, then tag `v<version>` and
push the tag. GitHub Actions publishes to PyPI and GHCR.

## License

MIT
