Git Repository Scanning - Shieldome Docs

Overview

Git repository scanning connects Shieldome to your GitHub or GitLab repositories. When code is pushed, Shieldome fetches the changed files and runs the IaC, Dockerfile, and secrets scanners automatically. Findings appear in the app and, if configured, as PR/MR comments.

🔀

API-based, not git clone. Shieldome uses the GitHub or GitLab API to fetch individual files - it never clones your repository or stores your code. Only files relevant to security analysis are fetched (IaC, Dockerfiles, .env patterns, common secret-bearing extensions).

What gets scanned

File type	Scanner
Terraform (`.tf`, `.tfvars`)	IaC scanner - Terraform rules
Kubernetes (`.yaml`, `.yml`)	IaC scanner - Kubernetes rules
CloudFormation JSON/YAML	IaC scanner - CloudFormation rules
Docker Compose files	IaC scanner - Compose rules
Dockerfiles	IaC scanner - Dockerfile rules
`.env` files, `.py`, `.js`, etc.	Secrets scanner

Node modules, build artifacts, and other non-IaC paths are automatically skipped. Up to 80 files are scanned per push.

Setup: registering a repository

1. Create a Personal Access Token

GitHub: Go to Settings > Developer settings > Personal access tokens. Create a token with repo scope (or contents: read on fine-grained tokens). For PR comments, also add pull_requests: write.

GitLab: Go to User Settings > Access Tokens. Create a token with read_repository and (for MR comments) api scope.

2. Register the repository in Shieldome

In the app sidebar, click Git Repos
Click Add Repository
Select the provider (GitHub or GitLab)
Enter the repository path (owner/repo for GitHub, group/project for GitLab)
Paste the Personal Access Token
For self-hosted GitLab, enter your GitLab instance URL
Click Save

3. Set up the webhook (optional - for automatic scanning)

To scan on every push automatically, configure a webhook in your repository:

GitHub: Repository Settings > Webhooks > Add webhook

Payload URL: https://app.shieldome.com/api/webhooks/git/REPO_ID
Content type: application/json
Secret: copy the webhook secret shown in Shieldome after saving the repo
Trigger: Just the push event

GitLab: Repository Settings > Webhooks

URL: https://app.shieldome.com/api/webhooks/git/REPO_ID
Secret token: copy the webhook secret from Shieldome
Trigger: Push events

🔒

Webhook security. Every webhook request is verified using an HMAC-SHA256 signature (GitHub) or a shared secret header (GitLab). Requests that fail verification are rejected with HTTP 403.

On-demand scanning

You can trigger a scan at any time without a webhook push:

Go to Git Repos and find your repository
Click Scan Now
Optionally specify a branch or commit SHA
Results appear in the scan history for that repo

PR / MR comments

After a web scan completes, you can post a security summary comment to any pull request or merge request. See the PR / MR Comments documentation for setup details.

API

# List registered repos
curl https://app.shieldome.com/api/me/git-repos \
  -H "X-API-Key: YOUR_KEY"

# Trigger a scan of repo ID 3
curl -X POST https://app.shieldome.com/api/me/git-repos/3/scan \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ref":"main"}'

# Get scan history for repo ID 3
curl https://app.shieldome.com/api/me/git-repos/3/scans \
  -H "X-API-Key: YOUR_KEY"