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:

Set either JF_ACCESS_TOKEN or both JF_USER and JF_PASSWORD.

From Frogbot 3.7.0 and Xray 3.155.0, the minimum JFrog token is Xray Admin and Catalog Admin. Earlier versions require a Platform Admin token. GitHub repo and org secrets are available to anyone who can run a workflow in that scope. For secret scope, environments, and rotation, see Best Practices for Storing Secrets Used by Frogbot.

Step 2: Allow Frogbot to Create Pull Requests

By default, Frogbot uses the automatic GITHUB_TOKEN to create pull requests.

1. Go to Settings > Actions > General.
2. Select Allow GitHub Actions to create and approve pull requests.
3. Under Workflow permissions, select Read and write permissions.

If the workflow file already defines a permissions block, for example contents: write and pull-requests: write, that block overrides the repository Workflow permissions setting. You can skip Read and write permissions. Both settings apply only to GITHUB_TOKEN. They don't apply to a personal access token or a fine-grained token.

If GITHUB_TOKEN is blocked, or you need other workflows to run following Frogbot's workflow, use a personal access token or a fine-grained token. Set the token permissions when you create the token. The permissions block and Workflow permissions don't apply to these tokens.

• Classic personal access token: Use the repo scope.
• Fine-grained personal access token: Set Contents and Pull requests to Read and write.

Save the token as the JF_GIT_TOKEN secret. In each workflow template, set the value to secrets.JF_GIT_TOKEN instead of secrets.GITHUB_TOKEN.

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
    steps:
      - uses: actions/checkout@v4

      - 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: ${{ github.ref_name }}
        # 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 for Open Source Repositories

For open source repositories where secrets are not available to pull requests from forks, create a GitHub environment named frogbot with at least one reviewer or reviewer team.

To create the environment:

1. In GitHub, go to the Settings tab.
2. From the main menu, select Environments and click New environment. The Environments window opens.
3. Create a new GitHub environment named frogbot.
4. Add people or public teams as reviewers. The chosen reviewers can trigger Frogbot scans on pull requests.
5. Add the following to the frogbot-scan-pull-request.yml workflow:

jobs:
  scan-pull-request:
    environment: frogbot