Forgejo Trivy Action 🔒

A reusable Forgejo/Gitea Actions workflow for running Trivy security scans and automatically creating/updating issues when vulnerabilities are found.

Features

✅ Trivy Security Scanning - Supports filesystem, image, config, and repo scans
✅ Automatic Issue Management - Creates or updates Forgejo issues
✅ No Duplicate Issues - Intelligently updates existing issues
✅ Customizable - Configurable severity levels, labels, and scan types
✅ Artifact Upload - Saves scan reports for download
✅ Multiple Formats - Generates both table (human-readable) and JSON reports

Usage

Basic Example

name: Security Scan

on:
  push:
    branches: [main]
  schedule:
    - cron: '0 9 * * 1'  # Weekly on Monday

jobs:
  security-scan:
    runs-on: security
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run Trivy scan
        uses: ftmahringer/forgejo-trivy-action@v1
        with:
          forgejo-url: https://forgejo.ftmahringer.com
          forgejo-token: ${{ secrets.FORGEJO_TOKEN }}
          repository: ${{ github.repository }}
          branch: ${{ github.ref_name }}
          commit: ${{ github.sha }}

Advanced Example

- name: Run Trivy scan with custom settings
  uses: ftmahringer/forgejo-trivy-action@v1
  with:
    # Scan configuration
    scan-type: fs
    scan-ref: .
    severity: CRITICAL,HIGH,MEDIUM
    ignore-unfixed: false
    
    # Forgejo integration
    forgejo-url: https://forgejo.ftmahringer.com
    forgejo-token: ${{ secrets.FORGEJO_TOKEN }}
    repository: ${{ github.repository }}
    branch: ${{ github.ref_name }}
    commit: ${{ github.sha }}
    
    # Issue configuration
    issue-title: '[Security] Vulnerabilities in ${{ github.ref_name }}'
    issue-labels: security,vulnerability,automated
    create-issue: true
    
    # Artifact configuration
    upload-artifacts: true
    artifact-retention-days: 60
    
    # Trivy configuration
    trivy-version: latest
    exit-code: 1

Scan Docker Images

- name: Build Docker image
  run: docker build -t myapp:latest .

- name: Scan Docker image
  uses: ftmahringer/forgejo-trivy-action@v1
  with:
    scan-type: image
    scan-ref: myapp:latest
    forgejo-url: https://forgejo.ftmahringer.com
    forgejo-token: ${{ secrets.FORGEJO_TOKEN }}
    repository: ${{ github.repository }}
    branch: ${{ github.ref_name }}
    commit: ${{ github.sha }}

Scan Only (No Issues)

- name: Run Trivy scan without creating issues
  uses: ftmahringer/forgejo-trivy-action@v1
  with:
    scan-type: fs
    scan-ref: .
    create-issue: false
    forgejo-url: https://forgejo.ftmahringer.com
    forgejo-token: ${{ secrets.FORGEJO_TOKEN }}
    repository: ${{ github.repository }}
    branch: ${{ github.ref_name }}
    commit: ${{ github.sha }}

Inputs

Input	Description	Required	Default
scan-type	Type of scan (fs, image, config, repo)	No	fs
scan-ref	Path or image to scan	No	.
severity	Severities to scan for	No	HIGH,CRITICAL
exit-code	Exit code when vulnerabilities found	No	1
forgejo-url	Forgejo instance URL	Yes	-
forgejo-token	Forgejo access token	Yes	-
repository	Repository (owner/repo)	Yes	-
branch	Current branch name	Yes	-
commit	Current commit SHA	Yes	-
issue-title	Title for security issues	No	[Security] Trivy vulnerabilities detected
issue-labels	Labels for issues (comma-separated)	No	security,vulnerability
create-issue	Whether to create/update issues	No	true
trivy-version	Trivy Docker image version	No	latest
ignore-unfixed	Ignore unfixed vulnerabilities	No	false
upload-artifacts	Upload scan reports as artifacts	No	true
artifact-retention-days	Days to retain artifacts	No	30

Outputs

Output	Description
exit-code	Exit code from Trivy scan (0 = clean, 1 = vulnerabilities)
vulnerabilities-found	Whether vulnerabilities were found (true/false)
issue-number	Forgejo issue number (if created/updated)
issue-url	URL to the Forgejo issue

Using Outputs

- name: Run Trivy scan
  id: trivy
  uses: ftmahringer/forgejo-trivy-action@v1
  with:
    forgejo-url: https://forgejo.ftmahringer.com
    forgejo-token: ${{ secrets.FORGEJO_TOKEN }}
    repository: ${{ github.repository }}
    branch: ${{ github.ref_name }}
    commit: ${{ github.sha }}

- name: Check scan results
  run: |
    echo "Vulnerabilities found: ${{ steps.trivy.outputs.vulnerabilities-found }}"
    echo "Exit code: ${{ steps.trivy.outputs.exit-code }}"
    echo "Issue URL: ${{ steps.trivy.outputs.issue-url }}"

Requirements

Forgejo Token

Create a Personal Access Token with the following permissions:

• read:repo - Read repository information
• write:issue - Create and update issues

Steps:

1. Go to https://your-forgejo.com/user/settings/applications
2. Click "Generate New Token"
3. Name: Trivy Security Scanner
4. Select permissions: read:repo, write:issue
5. Generate and copy the token
6. Add to repository secrets as FORGEJO_TOKEN

Runner Requirements

• Docker installed and accessible
• jq will be auto-installed if not present
• Internet access to pull Trivy Docker image

How It Works

1. Install jq - Ensures jq is available for JSON processing
2. Run Trivy Scan - Scans using Docker with table format
3. Create JSON Report - Generates machine-readable report
4. Display Results - Shows scan output in workflow logs
5. Manage Issues - Creates new issue or comments on existing
6. Upload Artifacts - Saves reports for download
7. Fail on Vulnerabilities - Exits with error code if vulnerabilities found

Issue Management

First Scan with Vulnerabilities

• Creates a new issue with title: [Security] Trivy vulnerabilities detected
• Tags with labels: security, vulnerability
• Includes full scan results in code block

Subsequent Scans

• Searches for existing open issue with same title
• Adds comment with new scan results
• No duplicate issues created

Manual Resolution

Close the issue manually when vulnerabilities are fixed. On the next scan:

• If vulnerabilities still exist → New issue is created
• If clean → No issue created

Examples

Replace Existing Security Workflow

Before (inline script):

steps:
  - name: Checkout
    uses: actions/checkout@v4
  
  - name: Run Trivy
    run: |
      docker run --rm -v "$PWD:/project" aquasec/trivy:latest fs \
        --severity HIGH,CRITICAL \
        --format table \
        /project

After (using action):

steps:
  - name: Checkout
    uses: actions/checkout@v4
  
  - name: Security Scan
    uses: ftmahringer/forgejo-trivy-action@v1
    with:
      forgejo-url: https://forgejo.ftmahringer.com
      forgejo-token: ${{ secrets.FORGEJO_TOKEN }}
      repository: ${{ github.repository }}
      branch: ${{ github.ref_name }}
      commit: ${{ github.sha }}

Benefits:

• ✅ Automatic issue creation
• ✅ No duplicate issues
• ✅ Artifact upload
• ✅ Cleaner workflow file
• ✅ Reusable across repos

Troubleshooting

Issue Not Created

Problem: Scan finds vulnerabilities but no issue is created

Solutions:

• Verify FORGEJO_TOKEN secret is set
• Check token has read:repo and write:issue permissions
• Verify forgejo-url is correct
• Check workflow logs for API error messages

Permission Denied

Problem: ERROR: Failed to create issue (HTTP 403)

Solution: Regenerate token with correct permissions

jq Not Found

Problem: jq: command not found

Solution: The action auto-installs jq, but if it fails:

• Check runner has internet access
• Manually install jq on runner

Docker Not Available

Problem: docker: command not found

Solution: Ensure Docker is installed on the runner

License

MIT License - See LICENSE file

Contributing

Issues and pull requests welcome!

Author

FTMahringer - https://forgejo.ftmahringer.com

---

Made with ❤️ for the Forgejo community