Skip to content

Commit 10817aa

Browse files
hayleycdhayleycd
committed
Adding section about containers.
Signed-off-by: hayleycd <[email protected]>
1 parent a86e9e1 commit 10817aa

File tree

1 file changed

+103
-19
lines changed

1 file changed

+103
-19
lines changed

‎content/en/quickstart/quickstart-ci.md

Lines changed: 103 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -10,22 +10,22 @@ Join us on our [Slack channel](https://sigstore.slack.com/). (Need an [invite](h
1010

1111
## Sigstore CI quickstart
1212

13-
Sigstore provides two GitHub Actions that make it easy to integrate signing and verifying into your CI system.
13+
Sigstore provides two GitHub Actions that make it easy to integrate signing and verifying into your CI system.
1414

15-
- The [`gh-action-sigstore-python` GitHub Action](https://github.com/sigstore/gh-action-sigstore-python) provides the easiest way to generate Sigstore signatures within your CI system. It uses the Sigstore Python language client ([`sigstore-python`](https://github.com/sigstore/sigstore-python)), but can be used to generate Sigstore signatures regardless of your project's language.
16-
- The [`consign-installer` GitHub Action](https://github.com/marketplace/actions/cosign-installer) installs cosign into your GitHub Action environment, making all features of Cosign available to be used within your CI System.
15+
- The [`gh-action-sigstore-python` GitHub Action](https://github.com/sigstore/gh-action-sigstore-python) provides the easiest way to generate Sigstore signatures within your CI system. It uses the Sigstore Python language client ([`sigstore-python`](https://github.com/sigstore/sigstore-python)), but can be used to generate Sigstore signatures regardless of your project's language.
16+
- The [`consign-installer` GitHub Action](https://github.com/marketplace/actions/cosign-installer) installs cosign into your GitHub Action environment, making all features of Cosign available to be used within your CI System.
1717

18-
This quickstart will walk you through the use of the `gh-action-sigstore-python` to [sign](#signing-files-using-your-ci-system) files, which is the quickest way to integrate Sigstore into your CI system. This quickstart also includes a [walkthrough](#using-cosign-within-your-ci-system) of using basic Cosign features in your workflows.
18+
This quickstart will walk you through the use of the `gh-action-sigstore-python` to [sign](#signing-files-using-your-ci-system) files, which is the quickest way to integrate Sigstore into your CI system. This quickstart also includes a [walkthrough](#using-cosign-within-your-ci-system) of using basic Cosign features in your workflows.
1919

2020
## Using `gh-action-sigstore-python` to sign files within your CI System
2121

22-
This quickstart will show you how to integrate the `gh-action-sigstore-python` GitHub Action into your workflow to generate Sigstore Signatures. The example workflow will sign the file `to_be_signed.txt` in the project's root directory whenever a push is made to the main branch.
22+
This quickstart will show you how to integrate the `gh-action-sigstore-python` GitHub Action into your workflow to generate Sigstore Signatures. The example workflow will sign the file `to_be_signed.txt` in the project's root directory whenever a push is made to the main branch.
2323

2424
Additional information and optional settings can be found in the [project's README](https://github.com/sigstore/gh-action-sigstore-python?tab=readme-ov-file#gh-action-sigstore-python).
2525

2626
### Signing files using your CI system
2727

28-
To following workflow will sign the file `to_be_signed.txt` in the project's root directory whenever a push is made to the main branch. To try it out, make sure to add the file `to_be_signed.txt` to your project, or substitute the file for one in your project.
28+
To following workflow will sign the file `to_be_signed.txt` in the project's root directory whenever a push is made to the main branch. To try it out, make sure to add the file `to_be_signed.txt` to your project, or substitute the file for one in your project.
2929

3030
```
3131
name: signing_files
@@ -42,16 +42,17 @@ jobs:
4242
steps:
4343
# This step ensures that your project is available in the workflow environment.
4444
- uses: actions/checkout@v3
45-
# This step uses 'gh-action-sigstore-python' to sign the file designated in the inputs field.
45+
# This step uses 'gh-action-sigstore-python' to sign the file designated in the inputs field.
4646
- uses: sigstore/[email protected]
4747
with:
4848
inputs: to_be_signed.txt
4949
```
50+
5051
When run, this workflow returns the ephemeral certificate used to sign the file, as well as the index for the transparency log entry.
5152

5253
### Verifying your signed files
5354

54-
The `gh-action-sigstore-python` GitHub Action includes an option to verify your generated signature. This is optional but a great way to understand the GitHub Action as you are integrating it into your CI for the first time. To verify the signature you just created, set the `verify` setting to true and include your expected `verify-cert-identity` and `verify-oidc-issuer` settings.
55+
The `gh-action-sigstore-python` GitHub Action includes an option to verify your generated signature. This is optional but a great way to understand the GitHub Action as you are integrating it into your CI for the first time. To verify the signature you just created, set the `verify` setting to true and include your expected `verify-cert-identity` and `verify-oidc-issuer` settings.
5556

5657
```
5758
- uses: sigstore/[email protected]
@@ -64,23 +65,26 @@ The `gh-action-sigstore-python` GitHub Action includes an option to verify your
6465

6566
## Using Cosign within your CI system
6667

67-
If you need functionality beyond simple signing of files and blobs, you can use the [`consign-installer` GitHub Action](https://github.com/marketplace/actions/cosign-installer) to integrate Sigstore into your CI system.
68+
If you need functionality beyond simple signing of files and blobs, you can use the [`consign-installer` GitHub Action](https://github.com/marketplace/actions/cosign-installer) to [integrate Sigstore into your CI system](#installing-cosign-on-your-ci). This quickstart covers:
69+
- How to [sign](#signing-a-blob) and [verify](#verifying-a-blob) a blob using `consign-installer`
70+
- How to [sign and verify a container image](#signing-and-verifying-a-container-image) using your CI system
6871

6972
### Installing Cosign on your CI
7073

71-
The following workflow will install Cosign into your workflow environment.
74+
The following workflow will install Cosign into your workflow environment.
7275

7376
```
74-
name: install-and-check-cosign
77+
name: install-cosign-and-use
7578
on:
7679
# This will trigger the workflow to run when commits are pushed to the main branch. This is easy for testing purposes, but for your final workflow use whatever event or schedule makes sense for your project.
7780
push:
7881
branches: [ main ]
79-
# No special permissions are required to install cosign, but depending on what you want to do with it, you may need to add permissions.
80-
permissions: read-all
82+
# No special permissions are required to install cosign, but `id-token: write` is needed to sign with your workflow identity.
83+
permissions:
84+
id-token: write
8185
8286
jobs:
83-
install-and-check-cosign:
87+
install-cosign-and-use:
8488
name: Install Cosign
8589
runs-on: ubuntu-latest
8690
steps:
@@ -90,21 +94,101 @@ jobs:
9094
run: cosign version
9195
```
9296

93-
### Signing a Blob
97+
### Signing a blob
9498

9599
Now that we've installed Cosign and checked the installation, let's use Cosign to sign a blob. Add these steps to your workflow:
96100

97101
```
102+
# This step makes sure your project is available in the workflow environment.
98103
- name: Import project
99104
uses: actions/checkout@v3
105+
# This step signs a blob (a text file in the root directory named to_be_signed.txt). The `--yes` flag agrees to Sigstore's terms of use.
100106
- name: Sign Blob
101-
run: cosign sign-blob README.md --bundle cosign.bundle --yes
107+
run: cosign sign-blob to_be_signed.txt --bundle cosign.bundle --yes
108+
```
109+
110+
### Verifying a blob
111+
112+
To veryify the signature that you just created, add the following step to your workflow.
113+
114+
```
115+
- name: Verify blob
116+
run: >
117+
cosign verify-blob README.md --bundle cosign.bundle
118+
--certificate-identity=https://github.com/USERNAME/REPOSITORY_NAME/.github/workflows/WORKFLOW_NAME@refs/heads/BRANCH_NAME
119+
--certificate-oidc-issuer=https://token.actions.githubusercontent.com
120+
```
121+
122+
### Signing and verifying a container image
123+
124+
In addition to signing and verifying blobs, you can sign and verify container images using the cosign-installer GitHub Action. The following is an example workflow that will build a container image with QEMU and Docker Buildx, push that image to the GitHub Container Registry, sign the image, and then verify it.
125+
102126
```
127+
name: container-signing-and-verifying
128+
on:
129+
push:
130+
branches: [ main ]
131+
permissions:
132+
contents: read
133+
packages: write
134+
id-token: write # needed for signing the images with GitHub OIDC Token
103135
104-
### Verifying a Blob
105-
### Signing a container
106-
### Verifying a container
136+
jobs:
137+
build-image:
138+
runs-on: ubuntu-latest
107139
140+
permissions:
141+
contents: read
142+
packages: write
143+
id-token: write # needed for signing the images with GitHub OIDC Token
108144
145+
name: build-image
146+
steps:
147+
- uses: actions/[email protected]
148+
with:
149+
fetch-depth: 1
109150
151+
- name: Install Cosign
152+
uses: sigstore/[email protected]
110153
154+
- name: Set up QEMU
155+
uses: docker/[email protected]
156+
157+
- name: Set up Docker Buildx
158+
uses: docker/[email protected]
159+
160+
- name: Login to GitHub Container Registry
161+
uses: docker/[email protected]
162+
with:
163+
registry: ghcr.io
164+
username: ${{ github.actor }}
165+
password: ${{ secrets.GITHUB_TOKEN }}
166+
167+
- id: docker_meta
168+
uses: docker/[email protected]
169+
with:
170+
images: ghcr.io/USERNAME/REPOSITORY_NAME
171+
tags: type=sha,format=long
172+
173+
- name: Build and Push container images
174+
uses: docker/[email protected]
175+
id: build-and-push
176+
with:
177+
platforms: linux/amd64,linux/arm/v7,linux/arm64
178+
push: true
179+
tags: ${{ steps.docker_meta.outputs.tags }}
180+
181+
- name: Sign and verify the images with GitHub OIDC Token
182+
env:
183+
DIGEST: ${{ steps.build-and-push.outputs.digest }}
184+
TAGS: ${{ steps.docker_meta.outputs.tags }}
185+
run: |
186+
images=""
187+
for tag in ${TAGS}; do
188+
images+="${tag}@${DIGEST} "
189+
done
190+
cosign sign --yes ${images}
191+
cosign verify ${images} \
192+
--certificate-identity=https://github.com/USERNAME/REPOSITORY_NAME/.github/workflows/WORKFLOW_NAME@refs/heads/BRANCH_NAME \
193+
--certificate-oidc-issuer=https://token.actions.githubusercontent.com
194+
```

0 commit comments

Comments
 (0)