-
Notifications
You must be signed in to change notification settings - Fork 92
CI Quickstart #358
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.
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
CI Quickstart #358
Changes from 3 commits
a86e9e1
10817aa
1e5654e
18e1cf4
c7437e6
80a7d4c
33b763d
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,195 @@ | ||
--- | ||
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. | ||
|
||
```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: | ||
push: | ||
branches: [ main ] | ||
hayleycd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
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 | ||
hayleycd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
# This step uses 'gh-action-sigstore-python' to sign the file designated in the inputs field. | ||
- uses: sigstore/[email protected] | ||
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. | ||
|
||
```console | ||
hayleycd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
- uses: sigstore/[email protected] | ||
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 | ||
hayleycd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
``` | ||
|
||
## Using Cosign within your CI system | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Do we prefer to only feature container signing for the cosign-installer section, since we've already signed and verified a blob with the python action? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think both are fine to feature. Could we flip the order so container signing is first? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Will do. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @haydentherapper Done! Please review changes. |
||
|
||
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. | ||
|
||
```console | ||
hayleycd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
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 `id-token: write` is needed to sign with your workflow identity. | ||
permissions: | ||
id-token: write | ||
hayleycd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
jobs: | ||
install-cosign-and-use: | ||
name: Install Cosign | ||
runs-on: ubuntu-latest | ||
steps: | ||
- name: Install Cosign | ||
uses: sigstore/[email protected] | ||
- 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: | ||
|
||
```console | ||
# 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 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. | ||
|
||
```console | ||
- 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. | ||
|
||
```console | ||
hayleycd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
name: container-signing-and-verifying | ||
on: | ||
push: | ||
branches: [ main ] | ||
hayleycd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
permissions: | ||
contents: read | ||
packages: write | ||
id-token: write # needed for signing the images with GitHub OIDC Token | ||
hayleycd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
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/[email protected] | ||
hayleycd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
with: | ||
fetch-depth: 1 | ||
hayleycd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
- name: Install Cosign | ||
uses: sigstore/[email protected] | ||
|
||
- name: Set up QEMU | ||
uses: docker/[email protected] | ||
|
||
- name: Set up Docker Buildx | ||
uses: docker/[email protected] | ||
|
||
- name: Login to GitHub Container Registry | ||
uses: docker/[email protected] | ||
with: | ||
registry: ghcr.io | ||
username: ${{ github.actor }} | ||
password: ${{ secrets.GITHUB_TOKEN }} | ||
|
||
- id: docker_meta | ||
uses: docker/[email protected] | ||
with: | ||
images: ghcr.io/USERNAME/REPOSITORY_NAME | ||
tags: type=sha,format=long | ||
|
||
- name: Build and Push container images | ||
uses: docker/[email protected] | ||
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 | ||
``` |
Uh oh!
There was an error while loading. Please reload this page.