Setup Frogbot Using GitHub Actions

Install Frogbot on GitHub using GitHub Actions

Prepare GitHub to work with Frogbot

Perform the following steps to allow GitHub and Frogbot to work together:

Step 1: Provide connection details

Set Frogbot's connection details as GitHub secrets

Go to your repository's settings tab and save the JFrog connection details as repository secrets with the following names:

1. JF_URL (JFrog Platform URL) Example: https://acme.jfrog.io You can also use JF_XRAY_URL and JF_ARTIFACTORY_URL instead of JF_URL.

2. JF_ACCESS_TOKEN (JFrog access token) You can also use JF_USER + JF_PASSWORD instead of JF_ACCESS_TOKEN. Instead of using JF_ACCESS_TOKEN and providing an access token as a GitHub secret, you can utilize the GitHub OpenID Connect (OIDC) authentication protocol.

3. JF_GIT_TOKEN (GitHub token) You can utilize ${{secrets.GITHUB_TOKEN}} for JF_GIT_TOKEN, which is an automatically generated token by GitHub. However, this option comes with a limitation: a workflow, such as Frogbot itself, cannot trigger another workflow. Consequently, if you have additional workflows intended to activate upon the creation of a new pull request, they might not be initiated. To resolve this issue, you can generate a personal access token and use it as JF_GIT_TOKEN.

Step 2: Allow Frogbot to open Pull Requests

Allow Pull Requests

Under Actions > General, check the Allow GitHub Actions to create and approve pull requests check box.

Step 3: Create execution Environment (open source projects only)

Create a dedicated execution environment for Frogbot

Create a new GitHub environment called frogbot and add people or public teams as reviewers. The chosen reviewers can trigger Frogbot scans on pull requests.

Create the required GitHub Actions templates

Step 1: Navigate to the project you wish to scan

Clone the GitHub repository you wish to scan to your local environment:

> git clone <my-project.git>
> cd <my-project>

Switch to the branch you'd like to scan with Frogbot:

> git checkout <branch-to-scan>

Step 2: Set up Repository Scan

In the branch you'd like to scan, create a file named frogbot-scan-repository.yml. Fill it with the provided template and push it into the .github/workflows directory at the root of your GitHub repository. You can see more advanced options in the full scan repository template.

frogbot-scan-repository.yml template

name: "Frogbot Scan Repository"
on:
  workflow_dispatch:
  schedule:
    # The repository will be scanned once a day at 00:00 GMT.
    - cron: "0 0 * * *"
permissions:
  contents: write
  pull-requests: write
  security-events: write
  # [Mandatory If using OIDC authentication protocol instead of JF_ACCESS_TOKEN]
  # id-token: write
jobs:
  scan-repository:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        # The repository scanning will be triggered periodically on the following branches.
        branch: ["dev"]
    steps:
      - uses: jfrog/frogbot@v2
        env:
          # [Mandatory]
          # JFrog platform URL
          JF_URL: ${{ secrets.JF_URL }}

          # [Mandatory if JF_USER and JF_PASSWORD are not provided]
          # JFrog access token with 'read' permissions on Xray service
          JF_ACCESS_TOKEN: ${{ secrets.JF_ACCESS_TOKEN }}

          # [Mandatory if JF_ACCESS_TOKEN is not provided]
          # JFrog username with 'read' permissions for Xray. Must be provided with JF_PASSWORD
          # JF_USER: ${{ secrets.JF_USER }}

          # [Mandatory if JF_ACCESS_TOKEN is not provided]
          # JFrog password. Must be provided with JF_USER
          # JF_PASSWORD: ${{ secrets.JF_PASSWORD }}

          # [Mandatory]
          # The GitHub token is automatically generated for the job
          JF_GIT_TOKEN: ${{ secrets.GITHUB_TOKEN }}

          # [Mandatory]
          # The name of the branch on which Frogbot will perform the scan
          JF_GIT_BASE_BRANCH: ${{ matrix.branch }}

        # [Mandatory if using OIDC authentication protocol instead of JF_ACCESS_TOKEN]
        # Insert to oidc-provider-name the 'Provider Name' defined in the OIDC integration configured in the JPD
        # with:
        #   oidc-provider-name: ""

Step 3: Set up Pull Request Scan

Create a file named frogbot-scan-pull-request.yml. Fill it with the provided template, and then push it into the .github/workflows directory at the root of your GitHub repository. You can see more advanced options in the full scan pull request template.

frogbot-scan-pull-request.yml template

name: "Frogbot Scan Pull Request"
on:
  pull_request_target:
    types: [opened, synchronize]
permissions:
  pull-requests: write
  contents: read
  # [Mandatory If using OIDC authentication protocol instead of JF_ACCESS_TOKEN]
  # id-token: write
jobs:
  scan-pull-request:
    runs-on: ubuntu-latest
    # A pull request needs to be approved before Frogbot scans it. Any GitHub user who is associated with the
    # "frogbot" GitHub environment can approve the pull request to be scanned.
    environment: frogbot
    steps:
      - uses: jfrog/frogbot@v2
        env:
          # [Mandatory]
          # JFrog platform URL
          JF_URL: ${{ secrets.JF_URL }}

          # [Mandatory if JF_USER and JF_PASSWORD are not provided]
          # JFrog access token with 'read' permissions on Xray service
          JF_ACCESS_TOKEN: ${{ secrets.JF_ACCESS_TOKEN }}

          # [Mandatory if JF_ACCESS_TOKEN is not provided]
          # JFrog username with 'read' permissions for Xray. Must be provided with JF_PASSWORD
          # JF_USER: ${{ secrets.JF_USER }}

          # [Mandatory if JF_ACCESS_TOKEN is not provided]
          # JFrog password. Must be provided with JF_USER
          # JF_PASSWORD: ${{ secrets.JF_PASSWORD }}

          # [Mandatory]
          # The GitHub token is automatically generated for the job
          JF_GIT_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          
        # [Mandatory if using OIDC authentication protocol instead of JF_ACCESS_TOKEN]
        # Insert to oidc-provider-name the 'Provider Name' defined in the OIDC integration configured in the JPD
        # with:
        #   oidc-provider-name: ""