You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -7,21 +7,21 @@ By following this guide, you will learn how to build a verifiable, auditable tra
7
7
8
8
### **What You'll Accomplish**
9
9
10
-
***Build and Publish** a multi-platform Docker image.
11
-
***Attach Signed Evidence** to four distinct types of subjects:
12
-
1. A **Generic Artifact** (a README.md file).
13
-
2. A **Software Package** (eg: a Docker image, npm, go,…etc).
14
-
3. A **Build Info** object (the CI build record).
15
-
4. An immutable **Release Bundle v2**.
10
+
***Build and Publish** a multi-platform Docker image.
11
+
***Attach Signed Evidence** to four distinct types of subjects:
12
+
1. A **Generic Artifact** (a README.md file).
13
+
2. A **Software Package** (eg: a Docker image, npm, go,…etc).
14
+
3. A **Build Info** object (the CI build record).
15
+
4. An immutable **Release Bundle v2**.
16
16
***Understand the "Why"**: Learn how this chain of evidence enables secure, policy-based promotions.
17
17
18
-
### **The Evidence Journey:**
18
+
### **The Evidence Journey:**
19
19
20
20
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.
21
21
22
22
### **Note**
23
23
24
-
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)).
24
+
For more information about evidence on the JFrog platform, see [Evidence Management](https://jfrog.com/help/r/jfrog-artifactory-documentation/evidence-management).
25
25
26
26
```mermaid
27
27
graph TD
@@ -44,57 +44,60 @@ graph TD
44
44
45
45
subgraph "4. Enable Governance"
46
46
I --> J[Ready for Secure Promotion with Policy Checks];
Before running the workflow, please ensure you have the following set up.
55
53
56
-
##**Prerequisites**
54
+
### Prerequisites
57
55
58
-
* 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).
59
-
* 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.
60
-
* Make sure the following repository variables are configured in GitHub settings:
61
-
* ARTIFACTORY\_URL (location of your Artifactory installation)
62
-
* BUILD\_NAME (planned name for the build of the Docker image)
63
-
* BUNDLE\_NAME (planned name for the Release Bundle created from the build)
64
-
* Make sure the following repository secrets are configured in GitHub settings:
65
-
* ARTIFACTORY\_ACCESS\_TOKEN (access token used for authentication)
66
-
* JF\_USER (your username in Artifactory)
67
-
* PRIVATE\_KEY (the key used to sign evidence)
56
+
Make sure JFrog CLI 2.65.0 or above is installed and in your system PATH. For installation instructions, see Install JFrog CLI.
68
57
69
-
**GitHub Secrets**
58
+
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.
70
59
71
-
| Secret Name | Description | Example Value |
72
-
| :---- | :---- | :---- |
73
-
| ARTIFACTORY\_ACCESS\_TOKEN | A valid JFrog Access Token with permissions to deploy and annotate. ||
74
-
| JF\_USER | Your JFrog Platform username, used for the docker login action. | my-user |
75
-
| PRIVATE\_KEY | The raw private key used to sign all evidence created in the workflow. |\-----BEGIN PRIVATE KEY-----... |
60
+
Make sure the following repository variables are configured in GitHub settings:
76
61
77
-
**GitHub Variables**
62
+
ARTIFACTORY_URL (location of your Artifactory installation)
78
63
79
-
| Variable Name | Description | Example Value |
80
-
| :---- | :---- | :---- |
81
-
| ARTIFACTORY\_URL | The base URL of your JFrog Platform instance. |https://mycompany.jfrog.io|
82
-
| BUILD\_NAME | A unique name for the build information in Artifactory. | evidence-example-build |
83
-
| BUNDLE\_NAME | The name of the Release Bundle that will be created. | evidence-example-bundle |
64
+
BUILD_NAME (planned name for the build of the Docker image)
84
65
85
-
---
66
+
BUNDLE_NAME (planned name for the Release Bundle created from the build)
86
67
87
-
### **The Evidence Journey: Step-by-Step**
68
+
Make sure the following repository secrets are configured in GitHub settings:
88
69
89
-
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).
70
+
ARTIFACTORY_ACCESS_TOKEN (access token used for authentication)
90
71
91
-
#### **Install JFrog CLI**
72
+
JF_USER (your username in Artifactory)
92
73
93
-
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.
74
+
PRIVATE_KEY (the key used to sign evidence)
94
75
76
+
### GitHub Secrets
95
77
78
+
| Secret Name | Description | Example Value |
79
+
|------------|-------------|---------------|
80
+
| ARTIFACTORY_ACCESS_TOKEN | A valid JFrog Access Token with permissions to deploy and annotate. ||
81
+
| JF_USER | Your JFrog Platform username, used for the docker login action. | my-user |
82
+
| PRIVATE_KEY | The raw private key used to sign all evidence created in the workflow. | -----BEGIN PRIVATE KEY-----... |
96
83
97
-
```
84
+
### GitHub Variables
85
+
86
+
| Variable Name | Description | Example Value |
87
+
|--------------|-------------|---------------|
88
+
| ARTIFACTORY_URL | The base URL of your JFrog Platform instance. |https://mycompany.jfrog.io|
89
+
| BUILD_NAME | A unique name for the build information in Artifactory. | evidence-example-build |
90
+
| BUNDLE_NAME | The name of the Release Bundle that will be created. | evidence-example-bundle |
91
+
92
+
## The Evidence Journey: Step-by-Step
93
+
94
+
This workflow demonstrates how evidence adds value at different levels of abstraction. For the complete implementation, please refer to the build.yml workflow file.
95
+
96
+
### Install JFrog CLI
97
+
98
+
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.
99
+
100
+
```yaml
98
101
jobs:
99
102
Docker-build-with-evidence:
100
103
runs-on: ubuntu-latest
@@ -108,13 +111,11 @@ jobs:
108
111
- uses: actions/checkout@v4
109
112
```
110
113
111
-
#### **Log In to the Artifactory Docker Registry**
112
-
113
-
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`).
114
+
### Log In to the Artifactory Docker Registry
114
115
116
+
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).
115
117
116
-
117
-
```
118
+
```yaml
118
119
- name: Log in to Artifactory Docker Registry
119
120
uses: docker/login-action@v3
120
121
with:
@@ -132,15 +133,11 @@ Here, we securely log in to the Artifactory Docker registry. This step also sets
132
133
install: true
133
134
```
134
135
135
-
---
136
-
137
-
### **Build the Docker Image**
136
+
### Build the Docker Image
138
137
139
-
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.
138
+
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.
140
139
141
-
142
-
143
-
```
140
+
```yaml
144
141
- name: Build Docker image
145
142
run: |
146
143
URL=$(echo ${{ vars.ARTIFACTORY_URL }} | sed 's|^https://||')
@@ -151,33 +148,25 @@ This step builds a multi-platform Docker image using the provided `Dockerfile` a
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.
151
+
### Attach Package Evidence
159
152
153
+
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.
### **Upload README File and Associated Evidence**
165
+
### Upload README File and Associated Evidence
175
166
176
-
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.
167
+
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.
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.
190
179
191
-
### **Publish Build Info and Attach Build Evidence**
180
+
### Publish Build Info and Attach Build Evidence
192
181
193
-
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.
182
+
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.
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.
197
+
### Create a Release Bundle v2 from the Build
215
198
199
+
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.
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.
### **Create an External Policy to Potentially Block Release Bundle Promotion**
227
+
### Create an External Policy to Potentially Block Release Bundle Promotion
251
228
252
229
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).
253
230
254
-
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).
231
+
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.
- [Getting Started with Artifactory as a Docker Registry](https://jfrog.com/help/r/jfrog-artifactory-documentation/getting-started-with-artifactory-as-a-docker-registry)
*[Getting Started with Artifactory as a Docker Registry](https://www.jfrog.com/confluence/display/JFROG/Getting+Started+with+Artifactory+as+a+Docker+Registry)
261
-
*[Scan Release Bundles (v2) with Xray](https://jfrog.com/help/r/jfrog-artifactory-documentation/scan-release-bundles-v2-with-xray)
0 commit comments