GitHub

Frogbot integrates with GitHub through GitHub Actions.

Step 1: Set Repository Secrets

In your GitHub repository, go to Settings > Secrets and variables > Actions and add:

Step 2: Allow Frogbot to Create Pull Requests

Go to Settings > Actions > General and under Workflow permissions, select Read and write permissions and enable Allow GitHub Actions to create and approve pull requests.

Step 3: Create the Workflow Files

Create two separate workflow files in your repository.

Pull Request Scanning

Create .github/workflows/frogbot-scan-pull-request.yml:

name: "Frogbot Scan Pull Request"
on:
  pull_request_target:
    types: [ opened, synchronize ]
permissions:
  pull-requests: write
  contents: read
  security-events: write
  # [Mandatory if using OIDC authentication protocol instead of JF_ACCESS_TOKEN]
  # id-token: write

jobs:
  scan-pull-request:
    runs-on: ubuntu-latest
    environment: frogbot
    steps:
      - uses: jfrog/frogbot@v3
        env:
          JF_URL: ${{ secrets.JF_URL }}
          JF_ACCESS_TOKEN: ${{ secrets.JF_ACCESS_TOKEN }}
          JF_GIT_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        # with:
          # oidc-provider-name: <OIDC_PROVIDER_NAME>

Repository Scanning

Create .github/workflows/frogbot-scan-repository.yml:

name: "Frogbot Scan Repository"
on:
  workflow_dispatch:
  schedule:
    # The repository will be scanned once a day at 00:00 GMT.
    - cron: "0 0 * * *"
  push:
    branches:
      - main
permissions:
  pull-requests: write
  contents: 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
    name: Scan Repository (${{ matrix.branch }} branch)
    strategy:
      matrix:
        branch: [ "main" ]
    steps:
      - uses: jfrog/frogbot@v3
        env:
          JF_URL: ${{ secrets.JF_URL }}
          JF_ACCESS_TOKEN: ${{ secrets.JF_ACCESS_TOKEN }}
          JF_GIT_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          JF_GIT_BASE_BRANCH: ${{ matrix.branch }}
        # with:
          # oidc-provider-name: <OIDC_PROVIDER_NAME>

OpenID Connect (OIDC) Authentication

The sensitive connection details, such as the access token used by Frogbot, can be automatically generated by the action instead of storing it as a secret in GitHub. This is made possible by leveraging the OpenID Connect (OIDC) protocol. This protocol can authenticate the workflow issuer and supply a valid access token.

To use the OIDC protocol, follow these steps:

JFrog Platform Configuration

Step 1: Configure an OIDC Integration

This step establishes the integration between GitHub Actions and the JFrog Platform.

1. In the JFrog Platform, navigate to Administration > General Management > Manage Integrations.
2. From the New Integration dropdown list, select OpenID Connect and enter the following information:
   • Provider Name — The Provider Name value should be used as the oidc-provider-name input in Workflow Configuration Step 2.
   • Provider Type
   • Description (optional)
   • Provider URL
   • Audience (optional) — Doesn't represent the aud claim that can be added to identity-mapping configured in the Claims JSON. Only claims that are included in the Claims JSON created during Step 2 are validated.
   • Token Issuer

Step 2: Configure an Identity Mapping

This step establishes the integration between a particular GitHub repository and the JFrog Platform.

An identity mapping is a configuration object used by the JFrog Platform to associate incoming OIDC claims with particular selected fields. These fields include repository, actor, workflow, and others.

1. Select Identity Mappings > Add Identity Mapping and enter the following information:
   • Name
   • Priority (enter 1)
   • Description (optional)
   • Claims JSON — You can define any valid list of claims required for request authentication. Example:

{
    "repository": "repository-owner/my-repository"
}

Workflow Configuration

Step 1: Set the Required Permissions

During the protocol's execution, you must obtain a JSON Web Token (JWT) from GitHub's OIDC provider. To request this token, ensure that the workflow is configured with the required permission.

Configure the following permission in the workflow file:

permissions:
  id-token: write

Step 2: Pass the oidc-provider-name Input

The oidc-provider-name parameter specifies the OIDC configuration whose identity mapping should match the generated JWT claims.

Set the oidc-provider-name parameter to be the same as the Provider Name set in the OIDC configuration within the JFrog Platform.

Step 3 (Optional): Specify the oidc-audience Input

The oidc-audience input defines the intended recipients of the ID token (JWT), restricting access to authorized recipients within the JFrog Platform. By default, it's set to the GitHub repository owner's URL. This ensures that only workflows within the specified repository or organization can request an access token.

Usage Example

- uses: jfrog/frogbot@v3
  env:
    JF_URL: ${{ vars.JF_URL }}
    JF_GIT_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  with:
    oidc-provider-name: frogbot-integration

Troubleshooting

Scan Failures Due to Token Expiration

When using OIDC integration, Xray or JFrog Advanced Security scans may fail if the token expires before the scans are complete. To prevent this, consider increasing the Token Expiration Time in the Identity Mapping Configuration to ensure the token remains valid for the entire scanning process. The required duration may vary based on the project's size.

Execution Environment (Open Source Repositories)

📘

This configuration is relevant for public repositories and the scan-pull-request workflow only.

For open source repositories where secrets are not available to PRs from forks, create a GitHub Environment named frogbot with at least one reviewer or reviewer team. Then add to the workflow:

jobs:
  scan-pull-request:
    environment: frogbot