Setup Frogbot Using GitHub Actions

Github Prerequisites

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

  • 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

  • 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.

  • 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.

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

• For open-source projects: 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.

Frogbot GitHub Action Templates

1. Begin by cloning the GitHub repository to your local environment.

2. Switch to the target branch where you'd like the pull requests to be scanned.

3. 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.

4. Return to the default branch.

5. Now, create a file named frogbot-scan-repository.yml. Again, populate it with the provided template and push it into the .github/workflows directory at the root of your GitHub repository.

Authenticating using OpenID Connect (OIDC)

General

The sensitive connection details, such as the access token used by JFrog 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. Learn more about this integration in this blog post. To utilize the OIDC protocol, follow these steps:

JFrog Platform configuration

1. Configure an OIDC Integration: This phase sets an integration between GitHub Actions to the JFrog platform. A) Navigate to the Administration tab In the JFrog Platform UI B) Click General | Manage Integrations C) Click New Integration | OpenID Connect: D) Configure the OIDC integration:

2. Configure an identity mapping: This phase sets an integration between a particular GitHub repository to the JFrog platform.

   An identity mapping is a configuration object utilized by the JFrog Platform to associate incoming OIDC claims with particular selected fields. These fields might include repository, actor, workflow, and others. To configure the identity mapping, click on the identity mapping created in section 1 and then click on Add Identity Mapping. In the 'priority' field insert the value '1' and fill in the rest of the required fields:

   You have the flexibility to define any valid list of claims required for request authentication. You can check a list of the possible claims here. Example Claims JSON:

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

Workflow configuration

1. Set required permissions: In the course of the protocol's execution, it's imperative to acquire a JSON Web Token (JWT) from GitHub's OIDC provider. To request this token, it's essential to configure the specified permission in the workflow file:

   permissions:
       id-token: write

2. Pass the 'oidc-provider-name' input to the Action (Required): The 'oidc-provider-name' parameter designates the OIDC configuration whose one of its identity mapping should align with the generated JWT claims. This input needs to align with the 'Provider Name' value established within the OIDC configuration in the JFrog Platform.

3. Pass the 'oidc-audience' input to the Action (Optional): The 'oidc-audience' input defines the intended recipients of an ID token (JWT), ensuring access is restricted to authorized recipients for the JFrog Platform. By default, it contains the URL of the GitHub repository owner. It enforces a condition, allowing only workflows within the designated repository/organization to request an access token. Read more about it here.

Example step utilizing OpenID Connect:

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