Skip to content
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

Jump to bottom

Add documentation for private-repository input #1165

Merged
merged 5 commits into from
Oct 27, 2022
Merged

Add documentation for private-repository input #1165

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d424501
Add documentation for private-repository input
Oct 27, 2022
3f99853
Fix input table
Oct 27, 2022
3b68661
Add more extensive docs on private repositories
Oct 27, 2022
8f52715
Update private-repository input doc
Oct 27, 2022
9173f08
Add links
Oct 27, 2022
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
38 changes: 32 additions & 6 deletions internal/builders/container/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ project simply generates provenance as a separate step in an existing workflow.
- [Generating Provenance](#generating-provenance)
- [Getting Started](#getting-started)
- [Referencing the SLSA generator](#referencing-the-slsa-generator)
- [Private Repositories](#private-repositories)
- [Supported Triggers](#supported-triggers)
- [Workflow Inputs](#workflow-inputs)
- [Provenance Format](#provenance-format)
Expand Down Expand Up @@ -149,13 +150,37 @@ jobs:
secrets:
registry-password: ${{ secrets.GITHUB_TOKEN }}
```

### Referencing the SLSA generator

At present, the generator **MUST** be referenced
by a tag of the form `@vX.Y.Z`, because the build will fail if you reference it via a shorter tag like `@vX.Y` or `@vX` or if you reference it by a hash.

For more information about this design decision and how to configure renovatebot,see the main repository [README.md](../../../README.md).

### Private Repositories

Private repositories are supported with some caveats. Currently all builds
generate and post a new entry in the public
[Rekor](https://github.com/sigstore/rekor) API server instance at
rekor.sigstore.dev. This entry includes the repository name. This will cause the
private repository name to leak and be discoverable via the public Rekor API
server.

If this is ok with you, you can set the `private-repository` flag in order to
opt in to publishing to the public Rekor instance from a private repository.

```yaml
with:
private-repository: true
```

If you do not set this flag then private repositories will generate an error in
order to prevent leaking repository name information.

Support for private transparency log instances that would not leak repository
name information is tracked on [issue #372](https://github.com/slsa-framework/slsa-github-generator/issues/372).

### Supported Triggers

The following [GitHub trigger events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows) are fully supported and tested:
Expand All @@ -177,12 +202,13 @@ The [container workflow](https://github.com/slsa-framework/slsa-github-generator

Inputs:

| Name | Required | Description |
| ------------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `image` | yes | The OCI image name. This must not include a tag or digest. |
| `digest` | yes | The OCI image digest. The image digest of the form '<algorithm>:<digest>' (e.g. 'sha256:abcdef...') |
| `registry-username` | yes | Username to log into the container registry. |
| `compile-generator` | false | Whether to build the generator from source. This increases build time by ~2m. |
| Name | Required | Default | Description |
| -------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `image` | yes | | The OCI image name. This must not include a tag or digest. |
| `digest` | yes | | The OCI image digest. The image digest of the form '<algorithm>:<digest>' (e.g. 'sha256:abcdef...') |
| `registry-username` | yes | | Username to log into the container registry. |
| `compile-generator` | false | false | Whether to build the generator from source. This increases build time by ~2m. |
| `private-repository` | no | false | Set to true to opt-in to posting to the public transparency log. Will generate an error if false for private repositories. This input has no effect for public repositories. See [Private Repositories](#private-repositories). |

Secrets:

Expand Down
39 changes: 32 additions & 7 deletions internal/builders/generic/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ project simply generates provenance as a separate step in an existing workflow.
- [Generating Provenance](#generating-provenance)
- [Getting Started](#getting-started)
- [Referencing the SLSA generator](#referencing-the-slsa-generator)
- [Private Repositories](#private-repositories)
- [Supported Triggers](#supported-triggers)
- [Workflow Inputs](#workflow-inputs)
- [Workflow Outputs](#workflow-outputs)
Expand Down Expand Up @@ -81,7 +82,7 @@ provenance:
base64-subjects: "${{ needs.build.outputs.hashes }}"
```

**Note**: Make sure that you reference the generator with a semantic version of the form `@vX.Y.Z`.
**Note**: Make sure that you reference the generator with a semantic version of the form `@vX.Y.Z`.
More information [here](/README.md#referencing-slsa-builders-and-generators).

Here's an example of what it might look like all together.
Expand Down Expand Up @@ -170,6 +171,29 @@ by a tag of the form `@vX.Y.Z`, because the build will fail if you reference it

For more information about this design decision and how to configure renovatebot,see the main repository [README.md](../../../README.md).

### Private Repositories

Private repositories are supported with some caveats. Currently all builds
generate and post a new entry in the public
[Rekor](https://github.com/sigstore/rekor) API server instance at
rekor.sigstore.dev. This entry includes the repository name. This will cause the
private repository name to leak and be discoverable via the public Rekor API
server.

If this is ok with you, you can set the `private-repository` flag in order to
opt in to publishing to the public Rekor instance from a private repository.

```yaml
with:
private-repository: true
```

If you do not set this flag then private repositories will generate an error in
order to prevent leaking repository name information.

Support for private transparency log instances that would not leak repository
name information is tracked on [issue #372](https://github.com/slsa-framework/slsa-github-generator/issues/372).

### Supported Triggers

The following [GitHub trigger events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows) are fully supported and tested:
Expand All @@ -189,12 +213,13 @@ issue](https://github.com/slsa-framework/slsa-github-generator/issues/new/choose

The [generic workflow](https://github.com/slsa-framework/slsa-github-generator/blob/main/.github/workflows/generator_generic_slsa3.yml) accepts the following inputs:

| Name | Required | Default | Description |
| ------------------ | -------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `base64-subjects` | yes | | Artifact(s) for which to generate provenance, formatted the same as the output of sha256sum (SHA256 NAME\n[...]) and base64 encoded. The encoded value should decode to, for example: `90f3f7d6c862883ab9d856563a81ea6466eb1123b55bff11198b4ed0030cac86 foo.zip` |
| `upload-assets` | no | false | If true provenance is uploaded to a GitHub release for new tags. |
| `provenance-name` | no | "(subject name).intoto.jsonl" if a single subject. "multiple.intoto.json" if multiple subjects. | The artifact name of the signed provenance. The file must have the `intoto.jsonl` extension. |
| `attestation-name` | no | "(subject name).intoto.jsonl" if a single subject. "multiple.intoto.json" if multiple subjects. | The artifact name of the signed provenance. The file must have the `intoto.jsonl` extension. DEPRECATED: use `provenance-name` instead. |
| Name | Required | Default | Description |
| -------------------- | -------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `base64-subjects` | yes | | Artifact(s) for which to generate provenance, formatted the same as the output of sha256sum (SHA256 NAME\n[...]) and base64 encoded. The encoded value should decode to, for example: `90f3f7d6c862883ab9d856563a81ea6466eb1123b55bff11198b4ed0030cac86 foo.zip` |
| `upload-assets` | no | false | If true provenance is uploaded to a GitHub release for new tags. |
| `provenance-name` | no | "(subject name).intoto.jsonl" if a single subject. "multiple.intoto.json" if multiple subjects. | The artifact name of the signed provenance. The file must have the `intoto.jsonl` extension. |
| `attestation-name` | no | "(subject name).intoto.jsonl" if a single subject. "multiple.intoto.json" if multiple subjects. | The artifact name of the signed provenance. The file must have the `intoto.jsonl` extension. DEPRECATED: use `provenance-name` instead. |
| `private-repository` | no | false | Set to true to opt-in to posting to the public transparency log. Will generate an error if false for private repositories. This input has no effect for public repositories. See [Private Repositories](#private-repositories). |

### Workflow Outputs

Expand Down
Loading