From a86e9e171c1e227cc9e66d007f4a7bd7c2f74c7a Mon Sep 17 00:00:00 2001 From: hayleycd Date: Tue, 7 Jan 2025 11:40:35 -0800 Subject: [PATCH 1/3] CI Quickstart Signed-off-by: hayleycd --- content/en/quickstart/quickstart-ci.md | 110 +++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 content/en/quickstart/quickstart-ci.md diff --git a/content/en/quickstart/quickstart-ci.md b/content/en/quickstart/quickstart-ci.md new file mode 100644 index 00000000..2b5b7ada --- /dev/null +++ b/content/en/quickstart/quickstart-ci.md @@ -0,0 +1,110 @@ +--- +type: docs +category: Quickstart +description: Integrate Sigstore into your CI system +title: Sigstore CI Quickstart +weight: 10 +--- + +Join us on our [Slack channel](https://sigstore.slack.com/). (Need an [invite](https://links.sigstore.dev/slack-invite)?) + +## Sigstore CI quickstart + +Sigstore provides two GitHub Actions that make it easy to integrate signing and verifying into your CI system. + +- 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. +- 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. + +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. + +## Using `gh-action-sigstore-python` to sign files within your CI System + +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. + +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). + +### Signing files using your CI system + +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. + +``` +name: signing_files +# 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. +on: + push: + branches: [ main ] +jobs: + signing_files: + runs-on: ubuntu-latest + # 'id-token' needs write permission to retrieve the OIDC token, which is required for authentication. + permissions: + id-token: write + steps: + # This step ensures that your project is available in the workflow environment. + - uses: actions/checkout@v3 + # This step uses 'gh-action-sigstore-python' to sign the file designated in the inputs field. + - uses: sigstore/gh-action-sigstore-python@v3.0.0 + with: + inputs: to_be_signed.txt +``` +When run, this workflow returns the ephemeral certificate used to sign the file, as well as the index for the transparency log entry. + +### Verifying your signed files + +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. + +``` + - uses: sigstore/gh-action-sigstore-python@v3.0.0 + with: + inputs: to_be_signed.txt + verify: true + verify-cert-identity: https://github.com/USERNAME/REPOSITORY_NAME/.github/workflows/WORKFLOW_NAME@refs/heads/BRANCH_NAME + verify-oidc-issuer: https://token.actions.githubusercontent.com +``` + +## Using Cosign within your CI system + +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 + +The following workflow will install Cosign into your workflow environment. + +``` +name: install-and-check-cosign +on: + # 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. + push: + branches: [ main ] +# No special permissions are required to install cosign, but depending on what you want to do with it, you may need to add permissions. +permissions: read-all + +jobs: + install-and-check-cosign: + name: Install Cosign + runs-on: ubuntu-latest + steps: + - name: Install Cosign + uses: sigstore/cosign-installer@v3.7.0 + - name: Check install! + run: cosign version +``` + +### Signing a Blob + +Now that we've installed Cosign and checked the installation, let's use Cosign to sign a blob. Add these steps to your workflow: + +``` + - name: Import project + uses: actions/checkout@v3 + - name: Sign Blob + run: cosign sign-blob README.md --bundle cosign.bundle --yes +``` + +### Verifying a Blob +### Signing a container +### Verifying a container + + + + From 10817aad91a1c8c35444d8b562bd9f67dc16ad56 Mon Sep 17 00:00:00 2001 From: hayleycd Date: Mon, 13 Jan 2025 13:09:39 -0800 Subject: [PATCH 2/3] Adding section about containers. Signed-off-by: hayleycd --- content/en/quickstart/quickstart-ci.md | 122 +++++++++++++++++++++---- 1 file changed, 103 insertions(+), 19 deletions(-) diff --git a/content/en/quickstart/quickstart-ci.md b/content/en/quickstart/quickstart-ci.md index 2b5b7ada..52af85bc 100644 --- a/content/en/quickstart/quickstart-ci.md +++ b/content/en/quickstart/quickstart-ci.md @@ -10,22 +10,22 @@ Join us on our [Slack channel](https://sigstore.slack.com/). (Need an [invite](h ## Sigstore CI quickstart -Sigstore provides two GitHub Actions that make it easy to integrate signing and verifying into your CI system. +Sigstore provides two GitHub Actions that make it easy to integrate signing and verifying into your CI system. -- 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. -- 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. +- 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. +- 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. -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. +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. ## Using `gh-action-sigstore-python` to sign files within your CI System -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. +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. 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). ### Signing files using your CI system -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. +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. ``` name: signing_files @@ -42,16 +42,17 @@ jobs: steps: # This step ensures that your project is available in the workflow environment. - uses: actions/checkout@v3 - # This step uses 'gh-action-sigstore-python' to sign the file designated in the inputs field. + # This step uses 'gh-action-sigstore-python' to sign the file designated in the inputs field. - uses: sigstore/gh-action-sigstore-python@v3.0.0 with: inputs: to_be_signed.txt ``` + When run, this workflow returns the ephemeral certificate used to sign the file, as well as the index for the transparency log entry. ### Verifying your signed files -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. +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. ``` - uses: sigstore/gh-action-sigstore-python@v3.0.0 @@ -64,23 +65,26 @@ The `gh-action-sigstore-python` GitHub Action includes an option to verify your ## Using Cosign within your CI system -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. +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: +- How to [sign](#signing-a-blob) and [verify](#verifying-a-blob) a blob using `consign-installer` +- How to [sign and verify a container image](#signing-and-verifying-a-container-image) using your CI system ### Installing Cosign on your CI -The following workflow will install Cosign into your workflow environment. +The following workflow will install Cosign into your workflow environment. ``` -name: install-and-check-cosign +name: install-cosign-and-use on: # 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. push: branches: [ main ] -# No special permissions are required to install cosign, but depending on what you want to do with it, you may need to add permissions. -permissions: read-all +# No special permissions are required to install cosign, but `id-token: write` is needed to sign with your workflow identity. +permissions: + id-token: write jobs: - install-and-check-cosign: + install-cosign-and-use: name: Install Cosign runs-on: ubuntu-latest steps: @@ -90,21 +94,101 @@ jobs: run: cosign version ``` -### Signing a Blob +### Signing a blob Now that we've installed Cosign and checked the installation, let's use Cosign to sign a blob. Add these steps to your workflow: ``` + # This step makes sure your project is available in the workflow environment. - name: Import project uses: actions/checkout@v3 + # 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. - name: Sign Blob - run: cosign sign-blob README.md --bundle cosign.bundle --yes + run: cosign sign-blob to_be_signed.txt --bundle cosign.bundle --yes +``` + +### Verifying a blob + +To veryify the signature that you just created, add the following step to your workflow. + +``` +- name: Verify blob + run: > + cosign verify-blob README.md --bundle cosign.bundle + --certificate-identity=https://github.com/USERNAME/REPOSITORY_NAME/.github/workflows/WORKFLOW_NAME@refs/heads/BRANCH_NAME + --certificate-oidc-issuer=https://token.actions.githubusercontent.com +``` + +### Signing and verifying a container image + +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. + ``` +name: container-signing-and-verifying +on: + push: + branches: [ main ] +permissions: + contents: read + packages: write + id-token: write # needed for signing the images with GitHub OIDC Token -### Verifying a Blob -### Signing a container -### Verifying a container +jobs: + build-image: + runs-on: ubuntu-latest + permissions: + contents: read + packages: write + id-token: write # needed for signing the images with GitHub OIDC Token + name: build-image + steps: + - uses: actions/checkout@v3.5.2 + with: + fetch-depth: 1 + - name: Install Cosign + uses: sigstore/cosign-installer@v3.7.0 + - name: Set up QEMU + uses: docker/setup-qemu-action@v2.1.0 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v2.5.0 + + - name: Login to GitHub Container Registry + uses: docker/login-action@v2.1.0 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - id: docker_meta + uses: docker/metadata-action@v4.4.0 + with: + images: ghcr.io/USERNAME/REPOSITORY_NAME + tags: type=sha,format=long + + - name: Build and Push container images + uses: docker/build-push-action@v4.0.0 + id: build-and-push + with: + platforms: linux/amd64,linux/arm/v7,linux/arm64 + push: true + tags: ${{ steps.docker_meta.outputs.tags }} + + - name: Sign and verify the images with GitHub OIDC Token + env: + DIGEST: ${{ steps.build-and-push.outputs.digest }} + TAGS: ${{ steps.docker_meta.outputs.tags }} + run: | + images="" + for tag in ${TAGS}; do + images+="${tag}@${DIGEST} " + done + cosign sign --yes ${images} + cosign verify ${images} \ + --certificate-identity=https://github.com/USERNAME/REPOSITORY_NAME/.github/workflows/WORKFLOW_NAME@refs/heads/BRANCH_NAME \ + --certificate-oidc-issuer=https://token.actions.githubusercontent.com +``` From 1e5654ee6e71ad9d4164272e48fc5cb29c94d2e6 Mon Sep 17 00:00:00 2001 From: hayleycd Date: Mon, 13 Jan 2025 13:17:56 -0800 Subject: [PATCH 3/3] Lint comments Signed-off-by: hayleycd --- content/en/quickstart/quickstart-ci.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/content/en/quickstart/quickstart-ci.md b/content/en/quickstart/quickstart-ci.md index 52af85bc..663592c1 100644 --- a/content/en/quickstart/quickstart-ci.md +++ b/content/en/quickstart/quickstart-ci.md @@ -27,7 +27,7 @@ Additional information and optional settings can be found in the [project's READ 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. -``` +```console name: signing_files # 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. on: @@ -54,7 +54,7 @@ When run, this workflow returns the ephemeral certificate used to sign the file, 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. -``` +```console - uses: sigstore/gh-action-sigstore-python@v3.0.0 with: inputs: to_be_signed.txt @@ -66,6 +66,7 @@ The `gh-action-sigstore-python` GitHub Action includes an option to verify your ## Using Cosign within your CI system 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: + - How to [sign](#signing-a-blob) and [verify](#verifying-a-blob) a blob using `consign-installer` - How to [sign and verify a container image](#signing-and-verifying-a-container-image) using your CI system @@ -73,7 +74,7 @@ If you need functionality beyond simple signing of files and blobs, you can use The following workflow will install Cosign into your workflow environment. -``` +```console name: install-cosign-and-use on: # 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. @@ -98,7 +99,7 @@ jobs: Now that we've installed Cosign and checked the installation, let's use Cosign to sign a blob. Add these steps to your workflow: -``` +```console # This step makes sure your project is available in the workflow environment. - name: Import project uses: actions/checkout@v3 @@ -111,7 +112,7 @@ Now that we've installed Cosign and checked the installation, let's use Cosign t To veryify the signature that you just created, add the following step to your workflow. -``` +```console - name: Verify blob run: > cosign verify-blob README.md --bundle cosign.bundle @@ -121,9 +122,9 @@ To veryify the signature that you just created, add the following step to your w ### Signing and verifying a container image -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. +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. -``` +```console name: container-signing-and-verifying on: push: