Skip to content

update README.md #85

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 12, 2025
Merged

update README.md #85

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
180 changes: 80 additions & 100 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,21 +7,21 @@ By following this guide, you will learn how to build a verifiable, auditable tra

### **What You'll Accomplish**

* **Build and Publish** a multi-platform Docker image.
* **Attach Signed Evidence** to four distinct types of subjects:
1. A **Generic Artifact** (a README.md file).
2. A **Software Package** (eg: a Docker image, npm, go,…etc).
3. A **Build Info** object (the CI build record).
4. An immutable **Release Bundle v2**.
* **Build and Publish** a multi-platform Docker image.
* **Attach Signed Evidence** to four distinct types of subjects:
1. A **Generic Artifact** (a README.md file).
2. A **Software Package** (eg: a Docker image, npm, go,…etc).
3. A **Build Info** object (the CI build record).
4. An immutable **Release Bundle v2**.
* **Understand the "Why"**: Learn how this chain of evidence enables secure, policy-based promotions.

### **The Evidence Journey:**
### **The Evidence Journey:**

The GitHub Actions workflow (.github/workflows/build.yml) performs a sequence of operations to build a chain of trust. Evidence is attached at each critical step.

### **Note**

For more information about evidence on the JFrog platform, see [Evidence Management]([https://github.com/jfrog/Evidence-Examples/blob/main/README.md#bootstrapping](https://jfrog.com/help/r/jfrog-artifactory-documentation/evidence-management)).
For more information about evidence on the JFrog platform, see [Evidence Management](https://jfrog.com/help/r/jfrog-artifactory-documentation/evidence-management).

```mermaid
graph TD
Expand All @@ -44,57 +44,60 @@ graph TD

subgraph "4. Enable Governance"
I --> J[Ready for Secure Promotion with Policy Checks];

end
```

```

### **Getting Started: Prerequisites & Configuration**
## Getting Started: Prerequisites & Configuration

Before running the workflow, please ensure you have the following set up.

## **Prerequisites**
### Prerequisites

* Make sure JFrog CLI 2.65.0 or above is installed and in your system PATH. For installation instructions, see [Install JFrog CLI](https://github.com/jfrog/Evidence-Examples/blob/main/README.md#bootstrapping).
* Make sure Artifactory can be used as a Docker registry. Please refer to [Getting Started with Artifactory as a Docker Registry](https://www.jfrog.com/confluence/display/JFROG/Getting+Started+with+Artifactory+as+a+Docker+Registry) in the JFrog Artifactory User Guide. You should end up with a Docker registry URL, which is mapped to a local Docker repository (or a virtual Docker repository with a local deployment target) in Artifactory. You'll need to know the name of the Docker repository to later collect the published image build-info.
* Make sure the following repository variables are configured in GitHub settings:
* ARTIFACTORY\_URL (location of your Artifactory installation)
* BUILD\_NAME (planned name for the build of the Docker image)
* BUNDLE\_NAME (planned name for the Release Bundle created from the build)
* Make sure the following repository secrets are configured in GitHub settings:
* ARTIFACTORY\_ACCESS\_TOKEN (access token used for authentication)
* JF\_USER (your username in Artifactory)
* PRIVATE\_KEY (the key used to sign evidence)
Make sure JFrog CLI 2.65.0 or above is installed and in your system PATH. For installation instructions, see Install JFrog CLI.

**GitHub Secrets**
Make sure Artifactory can be used as a Docker registry. Please refer to Getting Started with Artifactory as a Docker Registry in the JFrog Artifactory User Guide. You should end up with a Docker registry URL, which is mapped to a local Docker repository (or a virtual Docker repository with a local deployment target) in Artifactory. You'll need to know the name of the Docker repository to later collect the published image build-info.

| Secret Name | Description | Example Value |
| :---- | :---- | :---- |
| ARTIFACTORY\_ACCESS\_TOKEN | A valid JFrog Access Token with permissions to deploy and annotate. | |
| JF\_USER | Your JFrog Platform username, used for the docker login action. | my-user |
| PRIVATE\_KEY | The raw private key used to sign all evidence created in the workflow. | \-----BEGIN PRIVATE KEY-----... |
Make sure the following repository variables are configured in GitHub settings:

**GitHub Variables**
ARTIFACTORY_URL (location of your Artifactory installation)

| Variable Name | Description | Example Value |
| :---- | :---- | :---- |
| ARTIFACTORY\_URL | The base URL of your JFrog Platform instance. | https://mycompany.jfrog.io |
| BUILD\_NAME | A unique name for the build information in Artifactory. | evidence-example-build |
| BUNDLE\_NAME | The name of the Release Bundle that will be created. | evidence-example-bundle |
BUILD_NAME (planned name for the build of the Docker image)

---
BUNDLE_NAME (planned name for the Release Bundle created from the build)

### **The Evidence Journey: Step-by-Step**
Make sure the following repository secrets are configured in GitHub settings:

This workflow demonstrates how evidence adds value at different levels of abstraction. For the complete implementation, please refer to the [build.yml workflow file](https://github.com/jfrog/Evidence-Examples/tree/main/.github/workflows/build.yml).
ARTIFACTORY_ACCESS_TOKEN (access token used for authentication)

#### **Install JFrog CLI**
JF_USER (your username in Artifactory)

This step uses the `jfrog/setup-jfrog-cli` action to install the JFrog CLI into the GitHub Actions runner and configures it with your Artifactory URL and access token.
PRIVATE_KEY (the key used to sign evidence)

### GitHub Secrets

| Secret Name | Description | Example Value |
|------------|-------------|---------------|
| ARTIFACTORY_ACCESS_TOKEN | A valid JFrog Access Token with permissions to deploy and annotate. | |
| JF_USER | Your JFrog Platform username, used for the docker login action. | my-user |
| PRIVATE_KEY | The raw private key used to sign all evidence created in the workflow. | -----BEGIN PRIVATE KEY-----... |

```
### GitHub Variables

| Variable Name | Description | Example Value |
|--------------|-------------|---------------|
| ARTIFACTORY_URL | The base URL of your JFrog Platform instance. | https://mycompany.jfrog.io |
| BUILD_NAME | A unique name for the build information in Artifactory. | evidence-example-build |
| BUNDLE_NAME | The name of the Release Bundle that will be created. | evidence-example-bundle |

## The Evidence Journey: Step-by-Step

This workflow demonstrates how evidence adds value at different levels of abstraction. For the complete implementation, please refer to the build.yml workflow file.

### Install JFrog CLI

This step uses the jfrog/setup-jfrog-cli action to install the JFrog CLI into the GitHub Actions runner and configures it with your Artifactory URL and access token.

```yaml
jobs:
Docker-build-with-evidence:
runs-on: ubuntu-latest
Expand All @@ -108,13 +111,11 @@ jobs:
- uses: actions/checkout@v4
```

#### **Log In to the Artifactory Docker Registry**

Here, we securely log in to the Artifactory Docker registry. This step also sets up QEMU and Docker Buildx, which are required to build multi-platform Docker images (e.g., for `linux/amd64` and `linux/arm64`).
### Log In to the Artifactory Docker Registry

Here, we securely log in to the Artifactory Docker registry. This step also sets up QEMU and Docker Buildx, which are required to build multi-platform Docker images (e.g., for linux/amd64 and linux/arm64).


```
```yaml
- name: Log in to Artifactory Docker Registry
uses: docker/login-action@v3
with:
Expand All @@ -132,15 +133,11 @@ Here, we securely log in to the Artifactory Docker registry. This step also sets
install: true
```

---

### **Build the Docker Image**
### Build the Docker Image

This step builds a multi-platform Docker image using the provided `Dockerfile` and pushes it to your Artifactory repository. The `jfrog rt build-docker-create` command captures the image details and associates them with a build name and number, laying the groundwork for creating build information.
This step builds a multi-platform Docker image using the provided Dockerfile and pushes it to your Artifactory repository. The jfrog rt build-docker-create command captures the image details and temporarily associates them with a build name and number in the local JFrog CLI cache, laying the groundwork for creating the final Build Info object.



```
```yaml
- name: Build Docker image
run: |
URL=$(echo ${{ vars.ARTIFACTORY_URL }} | sed 's|^https://||')
Expand All @@ -151,33 +148,25 @@ This step builds a multi-platform Docker image using the provided `Dockerfile` a
jfrog rt build-docker-create example-project-docker-dev --image-file build-metadata --build-name ${{ vars.BUILD_NAME }} --build-number ${{ github.run_number }}
```

---

### **Attach Package Evidence**

Now we attach the first piece of evidence directly to the Docker image **package**. This signed evidence acts as a verifiable record, attesting that a specific action (like a signature from a CI process) was performed on this package version.
### Attach Package Evidence

Now we attach the first piece of evidence directly to the Docker image package. This signed evidence acts as a verifiable record, attesting that a specific action (like a signature from a CI process) was performed on this package version.


```
```yaml
- name: Evidence on docker
run: |
echo '{ "actor": "${{ github.actor }}", "date": "'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'" }' > sign.json
jf evd create --package-name example-project-app --package-version 32 --package-repo-name example-project-docker-dev \
--key "${{ secrets.PRIVATE_KEY }}" \
--predicate ./sign.json --predicate-type https://jfrog.com/evidence/signature/v1
echo ' Evidence attached: `signature` '
echo ' Evidence attached: `signature` '
```

---

### **Upload README File and Associated Evidence**
### Upload README File and Associated Evidence

To demonstrate that evidence can be attached to *any* artifact, not just packages, this step uploads the `README.md` file to a generic repository and attaches similar signed evidence to it.
To demonstrate that evidence can be attached to any artifact, not just packages, this step uploads the README.md file to a generic repository and attaches similar signed evidence to it.



```
```yaml
- name: Upload readme file
run: |
jf rt upload ./README.md example-project-generic-dev/readme/${{ github.run_number }}/ --build-name ${{ vars.BUILD_NAME }} --build-number ${{ github.run_number }}
Expand All @@ -186,15 +175,13 @@ To demonstrate that evidence can be attached to *any* artifact, not just package
--predicate ./sign.json --predicate-type https://jfrog.com/evidence/signature/v1
```

---
The crucial flags --build-name and --build-number in the jf rt upload command ensure this uploaded artifact is also added to the local build info record created in the previous step.

### **Publish Build Info and Attach Build Evidence**
### Publish Build Info and Attach Build Evidence

This step aggregates all the artifacts and metadata captured so far (the Docker image and the README) into a comprehensive **Build Info** object in Artifactory. Immediately after, it attaches signed evidence to this entire build, attesting to the integrity of the build process itself.
This step performs the final action: it aggregates all previously linked artifacts (the Docker image from build-docker-create and the README from jf rt upload) and their metadata, which are stored locally in the CLI's temporary cache, and publishes this comprehensive Build Info object to Artifactory. Immediately after, it attaches signed evidence to this entire build, attesting to the integrity of the build process itself.



```
```yaml
- name: Publish build info
run: jfrog rt build-publish ${{ vars.BUILD_NAME }} ${{ github.run_number }}

Expand All @@ -207,15 +194,11 @@ This step aggregates all the artifacts and metadata captured so far (the Docker
echo ' Evidence attached: `build-signature` ' >> $GITHUB_STEP_SUMMARY
```

---

### **Create a Release Bundle v2 from the Build**

The workflow now creates an immutable **Release Bundle** from the build we just published. This bundle is a tamper-proof, versioned collection that is ideal for promoting through your SDLC stages.
### Create a Release Bundle v2 from the Build

The workflow now creates an immutable Release Bundle from the build we just published. This bundle is a tamper-proof, versioned collection that is ideal for promoting through your SDLC stages.


```
```yaml
- name: Create release bundle
run: |
echo '{ "files": [ {"build": "'"${{ vars.BUILD_NAME }}/${{ github.run_number }}"'" } ] }' > bundle-spec.json
Expand All @@ -225,15 +208,11 @@ The workflow now creates an immutable **Release Bundle** from the build we just
echo ' Release bundle ['${{ vars.BUNDLE_NAME }}']('${NAME_LINK}'):['${{ github.run_number }}']('${VER_LINK}') created' >> $GITHUB_STEP_SUMMARY
```

---

### **Attach Release Bundle Evidence**
### Attach Release Bundle Evidence

Finally, we attach signed evidence to the immutable Release Bundle itself. This could represent a successful integration test or final approval, providing a verifiable gate for promotion to production environments.



```
```yaml
- name: Evidence on release-bundle v2
run: |
echo '{ "actor": "${{ github.actor }}", "date": "'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'" }' > rbv2_evidence.json
Expand All @@ -242,23 +221,24 @@ Finally, we attach signed evidence to the immutable Release Bundle itself. This
jf evd create --release-bundle ${{ vars.BUNDLE_NAME }} --release-bundle-version ${{ github.run_number }} \
--predicate ./rbv2_evidence.json --predicate-type https://jfrog.com/evidence/rbv2-signature/v1 \
--key "${{ secrets.PRIVATE_KEY }}"
echo ' Evidence attached: integration-test ' >> $GITHUB_STEP_SUMMARY
echo ' Evidence attached: integration-test ' >> $GITHUB_STEP_SUMMARY
```

---

### **Create an External Policy to Potentially Block Release Bundle Promotion**
### Create an External Policy to Potentially Block Release Bundle Promotion

When the Evidence service is used in conjunction with JFrog Xray, each Release Bundle promotion generates evidence in the form of a CycloneDX SBOM. You can create a policy in an external tool (for example, a rego policy) that reviews the contents of the CycloneDX evidence file and decides whether to block the promotion (because the Release Bundle fails to meet all your organization's requirements for promotion to the next stage of your SDLC).

To see a sample rego policy, go [here](https://github.com/jfrog/Evidence-Examples/blob/main/policy/policy.rego). For more information about integrating Release Lifecycle Management and Evidence with Xray, see [Scan Release Bundles (v2) with Xray](https://jfrog.com/help/r/jfrog-artifactory-documentation/scan-release-bundles-v2-with-xray).
To see a sample rego policy, go here. For more information about integrating Release Lifecycle Management and Evidence with Xray, see Scan Release Bundles (v2) with Xray.

## References

### Product Documentation:

- [Evidence Management Overview](https://jfrog.com/help/r/jfrog-artifactory-documentation/evidence-management)
- [Getting Started with Artifactory as a Docker Registry](https://jfrog.com/help/r/jfrog-artifactory-documentation/getting-started-with-artifactory-as-a-docker-registry)
- [Xray](https://jfrog.com/help/r/xray-release-information/xray-release-notes)

### **References**
### JFrog CLI Documentation:

* **Product Documentation:**
* [Evidence Management Overview](https://jfrog.com/help/r/jfrog-artifactory-documentation/evidence-management)
* [Getting Started with Artifactory as a Docker Registry](https://www.jfrog.com/confluence/display/JFROG/Getting+Started+with+Artifactory+as+a+Docker+Registry)
* [Scan Release Bundles (v2) with Xray](https://jfrog.com/help/r/jfrog-artifactory-documentation/scan-release-bundles-v2-with-xray)
* **JFrog CLI Documentation:**
* [JFrog CLI Command Reference](https://www.google.com/search?q=https://jfrog.com/help/r/jfrog-cli/jfrog-cli-command-reference)
* [Release Lifecycle Management with CLI](https://www.google.com/search?q=https://jfrog.com/help/r/jfrog-cli/release-lifecycle-management)
- [JFrog CLI Command Reference](https://jfrog.com/help/r/jfrog-applications-and-cli-documentation/jfrog-cli)
- [Release Lifecycle Management with CLI](https://jfrog.com/help/r/jfrog-applications-and-cli-documentation/release-lifecycle-management)