feat: gitlab templates

.cz.yaml

@@ -109,3 +109,5 @@ commitizen:
   version: 0.22.0
   version_files:
   - internal/cli/app.go:Version
+  - gitlab/templates/sheriff.gitlab-ci.yml:sheriff:v
+  - README.md:tags/v

README.md

@@ -38,6 +38,8 @@ Sheriff is a tool to scan repositories and generate security reports.
   - [Source code hosting services](#source-code-hosting-services)
   - [Messaging services](#messaging-services)
   - [Scanners](#scanners)
+- [Usage in CI](#usage-in-ci)
+  - [In Gitlab](#in-gitlab)
 - [Contributors ✨](#contributors-)
 
 ## Quick Usage
@@ -239,6 +241,60 @@ Sets the token to be used when reporting the security report on slack
 - [x] [OSV-Scanner](https://github.com/google/osv-scanner)
 - [ ] [Trivy](https://github.com/aquasecurity/trivy)
 
+## Usage in CI
+
+Sheriff was designed so it could be run as part of a CI.
+
+### In Gitlab
+
+To run sheriff on Gitlab, we suggest the following set-up:
+1. Create a repostory which will contain your CI runner, you can call it `sheriff-runner` for example
+2. Create a CI file in this repository which extends from our template
+    ```yaml
+    include:
+      # renovate: depName=sheriff
+      - remote: 'https://raw.githubusercontent.com/elementsinteractive/sheriff/refs/tags/v0.22.0/gitlab/templates/sheriff.gitlab-ci.yml'
+
+    sheriff:
+      extends: .sheriff
+    ```
+
+    > Note that the line `# renovate: depName=sheriff` is optional. [Renovate](https://docs.renovatebot.com/) is used to bump dependencies automatically and we highly recommend it! If you want this line to work, add the following to your renovate configuration:
+    ```json
+    {
+      ...
+      "customManagers": [
+        {
+          "customType": "regex",
+          "fileMatch": [".gitlab-ci.yml"],
+          "datasourceTemplate": "custom.sheriff",
+          "matchStrings": [
+            "#\\s*renovate:\\s*(datasource=(?<datasource>.*?) )?depName=(?<depName>.*?)( versioning=(?<versioning>.*?))?\\s*\\w*:\\s*(?<currentValue>.*)\\s"
+          ],
+          "versioningTemplate": "{{#if versioning}}{{{versioning}}}{{else}}semver{{/if}}"
+        }
+      ],
+      "customDatasources": {
+        "sheriff": {
+          "defaultRegistryUrlTemplate": "https://api.github.com/repos/elementsinteractive/sheriff/releases",
+          "transformTemplates": [
+            "{\"releases\": $.{\"version\": tag_name, \"source_url\": html_url, \"releaseTimestamp\": published_at}, \"sourceUrl\": \"https://github.com/elementsinteractive/sheriff\"}"
+          ]
+        }
+      }
+    ```
+3. Go to **Build** -> **Pipeline schedules** -> **New schedule**
+   a. Add a name & a preferred cron interval. We prefer a weekly scan such as `0 7 * * 1` (every Monday at 7am)
+   b. Add a **Variable** Variable named `SHERIFF_CLI_ARGS` which extra CLI arguments you wish to add (see CLI configuration section)
+   c. Add a **File** Variable named `SHERIFF_CONFIG` containing your sheriff configuration (see file configuration section)
+4. Go to **Settings** -> **CI/CD** -> **Variables**
+   a. If scanning gitlab projects, add your gitlab token in **GITLAB_TOKEN** with *Protected*, *Masked*, *Hidden*
+   b. If publishing reports to slack, add your slack token in **SLACK_TOKEN** with *Protected*, *Masked*
+5. Test your pipeline by going to **Build** -> **Pipeline schedules** & clicking the play button on your pipline
+5. Enjoy! Your pipeline should now run & scan your projects on a weekly basis 😀
+
+We have a gitlab template set up for convenience, which runs sheriff with a set of configurable options.
+
 ## Contributors ✨
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

gitlab/templates/sheriff.gitlab-ci.yml

@@ -0,0 +1,28 @@
+variables:
+  GITLAB_TOKEN:
+    description: "GitLab token for API access"
+  SLACK_TOKEN:
+    description: "Slack token for notifications"
+  SHERIFF_CONFIG:
+    description: "Sheriff TOML configuration file contents. Will be available to sheriff as a file `sheriff.toml`"
+    SHERIFF_CLI_ARGS:
+    description: "Add CLI arguments to pass to the sheriff patrol command"
+
+.sheriff:
+  stage: deploy
+  image:
+    name: elementsinteractive/sheriff:v0.22.0
+    entrypoint: [""]
+  resource_group: production
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "schedule"
+    - if: $CI_PIPELINE_SOURCE == "web"
+  script:
+    - sheriff patrol
+      --gitlab-token $GITLAB_TOKEN
+      --slack-token $SLACK_TOKEN
+      --config $SHERIFF_CONFIG
+      $SHERIFF_CLI_ARGS
+
+sheriff:
+  extends: .sheriff