The convergence of continuous integration and software supply chain security has necessitated a tighter coupling between source code repositories and artifact management platforms. The integration between GitHub Actions and the JFrog Platform, primarily facilitated by the setup-jfrog-cli action, establishes a robust pipeline for building, securing, and distributing software artifacts. This integration enables organizations to maintain full lifecycle visibility, from the initial commit in GitHub to the final artifact in JFrog Artifactory, while leveraging automated attestation and evidence collection to ensure integrity. By embedding JFrog CLI directly into GitHub Actions workflows, teams can automate authentication, build information generation, and security scanning, thereby reducing manual configuration errors and enhancing traceability.
Establishing the Foundation with JFrog CLI Setup
The cornerstone of this integration is the jfrog/setup-jfrog-cli GitHub Action. This action is responsible for downloading, installing, and configuring the JFrog Command Line Interface within the GitHub Actions runner environment. It serves as the bridge between the ephemeral compute environment of GitHub Actions and the persistent storage and security features of the JFrog Platform. The action is designed to be versatile, supporting multiple authentication methods and configuration strategies to accommodate varying organizational security policies and infrastructure setups.
When the action executes, it performs several critical background tasks that simplify the workflow for developers. Most notably, it handles seamless build info generation. Traditionally, users would need to manually append build name and build number arguments to various CLI commands and explicitly run a build-publish command at the end of a workflow. The setup-jfrog-cli action automates this process; all build-related operations are automatically recorded during the workflow execution, and the collected build information is published to the JFrog Platform automatically at the conclusion of the job. This eliminates the need for explicit jf rt build-publish commands in the workflow definition, reducing the complexity of the YAML configuration and minimizing the risk of human error in metadata generation.
Furthermore, the action provides an extensive Job Summary feature. Upon completion of the workflow, a detailed summary of the key JFrog CLI commands executed is generated and displayed directly on the GitHub Actions run page. This summary includes direct links to the JFrog Platform UI, allowing developers to quickly navigate from the CI/CD run to the relevant artifacts, build logs, and security reports. To fully leverage this feature, it is recommended to use JFrog CLI version 2.66.0 or above and to set the JF_URL as a GitHub Variable rather than a GitHub Secret, ensuring that the links in the summary are functional and secure.
Authentication and Configuration Strategies
Connecting the JFrog CLI to the JFrog Platform requires providing specific connection details, such as the server URL and credentials. The setup-jfrog-cli action supports three distinct authentication methods, offering flexibility based on the security requirements of the organization.
The first method involves no authentication, suitable for public repositories or environments where access control is handled at the network level. This requires only the JF_URL environment variable.
The second method utilizes basic authentication. This approach requires the JF_URL, along with JF_USER and JF_PASSWORD. These credentials are typically stored as GitHub Secrets to prevent exposure in the workflow file.
The third and most secure method uses a JFrog Access Token. This requires the JF_URL and JF_ACCESS_TOKEN. Access tokens are often preferred in enterprise environments because they can be scoped to specific permissions and have expiration times, reducing the risk associated with long-lived credentials.
yaml
- uses: jfrog/setup-jfrog-cli@v4
env:
# JFrog Platform url
JF_URL: ${{ vars.JF_URL }}
# Basic authentication credentials
JF_USER: ${{ secrets.JF_USER }}
JF_PASSWORD: ${{ secrets.JF_PASSWORD }}
# or
# JFrog Platform access token
JF_ACCESS_TOKEN: ${{ secrets.JF_ACCESS_TOKEN }}
For organizations with complex infrastructure requirements, such as internal repositories or custom SSL certificates, additional configuration is necessary. If the JFrog instance uses a self-signed certificate, the certificate file must be accessible within the GitHub Actions environment. The NODE_EXTRA_CA_CERTS environment variable can be set to specify the location of the .pem file, ensuring that the CLI can establish a secure TLS connection.
yaml
env:
NODE_EXTRA_CA_CERTS: /path/to/certificate/server.pem
In cases where the JFrog CLI is not available from the default public repository, the action allows users to specify a custom download repository. This is particularly useful for internal mirrors or air-gapped environments. A remote repository named jfrog-cli-remote can be configured in Artifactory, pointing to https://releases.jfrog.io/artifactory/jfrog-cli/. The setup-jfrog-cli action can then be instructed to download the CLI from this remote repository using the download-repository input.
yaml
- uses: jfrog/setup-jfrog-cli@v4
env:
JF_URL: ${{ vars.JF_URL }}
JF_ACCESS_TOKEN: ${{ secrets.JF_ACCESS_TOKEN }}
with:
download-repository: jfrog-cli-remote
Advanced Configuration: Custom Server IDs and Multi-Configuration
By default, the setup-jfrog-cli action configures JFrog CLI with a unique server ID for each workflow run. This default behavior is sufficient for most simple workflows. However, advanced use cases may require more granular control over server configurations.
Users can override the default server ID by providing a custom-server-id input to the action. This allows for consistent server naming across different workflow runs, which can be beneficial for debugging and log analysis.
yaml
- uses: jfrog/setup-jfrog-cli@v4
with:
custom-server-id: my-server
Furthermore, workflows may require interaction with multiple JFrog instances or different configurations within the same platform. The action supports multi-configuration by allowing users to define multiple server IDs. Alternating between these configurations can be achieved by providing the --server-id option to specific JFrog CLI commands or by using the jf c use <server-id> command to set a default server for subsequent commands in the same job.
For those who prefer to manage configuration outside of the workflow file, it is possible to store connection details using a single Config Token. This requires JFrog CLI to be installed locally, followed by running jf c add to configure the platform details. The configuration can then be exported using jf c export <SERVER ID>, and the resulting token can be used for authentication in the workflow.
Automated Evidence Collection and Attestation
One of the most significant features of this integration is the automatic collection of evidence from GitHub Actions attestations. As supply chain security becomes increasingly critical, the ability to verify the provenance of artifacts is essential. GitHub provides supply chain actions that create attestations, including provenance, SBOMs (Software Bill of Materials), and custom attestations.
The setup-jfrog-cli action includes a post-stage that runs at the end of the job. This post-stage automatically detects any attestations created during the workflow and collects them as evidence into the JFrog Platform. This process is transparent to the user; no additional configuration is required beyond ensuring that the GitHub Actions workflow uses the standard GitHub attestation actions.
The evidence is created by calling the jf evd create command with the --sigstore-bundle flag. The command automatically detects the subject of the evidence from the attestation file, linking it to the corresponding build artifact in Artifactory. This integration ensures that all attestations generated on GitHub are ingested into JFrog Evidence, providing a comprehensive view of the artifact's history and integrity.
This feature is particularly powerful when combined with GitHub's actions/attest-build-provenance action. By using this action in the workflow, a build attestation is generated that is signed by GitHub. Once the build completes and the attestation is generated, the artifact is pushed to a JFrog Artifactory staging repository. The artifact can then be validated based on trusted conditions, such as the issuer, repository, workflow, and branch. If the validation passes, JFrog can automatically promote the artifact from the development environment to the production environment, ensuring that only verified and trusted code reaches end-users.
Security Scanning and Vulnerability Management
Security scanning is a critical component of any modern software supply chain. The setup-jfrog-cli action facilitates security scanning by enabling the execution of JFrog Xray scans directly within the GitHub Actions workflow. The action supports the display of code scanning alerts in the GitHub Actions UI, providing developers with immediate feedback on potential vulnerabilities.
Code scanning alerts are generated following the execution of the jf docker scan and jf scan commands. These alerts can be uploaded to GitHub's security events interface, integrating seamlessly with GitHub Advanced Security features. To use code scanning alerts, it is required to use JFrog CLI version 2.67.0 or above. Additionally, this feature is available only for customers with an Artifactory Enterprise license or above.
To enable the upload of code scanning results, the GitHub token used for authentication must have the security-events: write permission. This can be configured in the workflow file using the permissions block.
```yaml
permissions:
id-token: write
contents: read
security-events: write
- uses: jfrog/setup-jfrog-cli@v4
env:
JFGITTOKEN: ${{ secrets.GITHUB_TOKEN }}
```
The JF_GIT_TOKEN environment variable should be set to ${{ secrets.GITHUB_TOKEN }}, which is an automatically generated token by GitHub with the necessary permissions. This allows the workflow to upload the scan results to GitHub, making them visible in the code scanning tab of the repository.
Beyond the CI/CD pipeline, the integration extends to continuous vulnerability management. Once artifacts are promoted to production, Dependabot continues to scan the source repository for dependencies and vulnerabilities. If a critical CVE is discovered, administrators receive an alert. To correlate these alerts with the artifacts in JFrog, users can filter using the tag artifact-registry:jfrog-artifactory. This tag ensures that artifact lifecycle data is automatically pushed from JFrog to GitHub using GitHub's artifact metadata API, creating a bidirectional flow of security information.
Practical Implementation: NPM Package Example
To illustrate the practical application of these concepts, the jfrog/jfrog-npm-actions-example repository provides a comprehensive example of integrating GitHub Actions with the JFrog Platform. This repository demonstrates how to build and deploy an NPM package using the tools and techniques described above.
The example repository is structured to be easily adaptable by users. It includes the necessary files to set up the workflow, configure authentication, and execute the build and deploy steps. To use the example, users need a JFrog account, which can be obtained through a free trial. Once an account is established, users can copy the template repository to their own GitHub repository and customize it for their specific needs.
The example highlights the simplicity of the integration. By leveraging the setup-jfrog-cli action, the workflow handles the installation and configuration of the CLI, allowing the user to focus on the logic of the build and deployment process. The repository is licensed under the Apache 2.0 License and welcomes contributions, ensuring that the example remains up-to-date with the latest best practices.
Conclusion
The integration between GitHub Actions and JFrog Platform, powered by the setup-jfrog-cli action, represents a significant advancement in software supply chain security and automation. By automating the configuration, authentication, and build information generation, it reduces the operational overhead for development teams. The automatic collection of attestations and evidence ensures that artifacts are verifiable and traceable, addressing critical security concerns. Furthermore, the seamless integration of security scanning and vulnerability management provides continuous protection throughout the software lifecycle.
This integration enables organizations to enforce strict security policies, such as requiring valid provenance before promoting artifacts to production, while maintaining a developer-friendly experience. As the threat landscape evolves, the ability to link commits, builds, and artifacts with full lifecycle visibility becomes increasingly important. The GitHub-JFrog integration provides the necessary tools to achieve this, ensuring that software delivered to end-users is secure, reliable, and compliant with organizational standards.