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

Small doc changes #55

Merged
merged 1 commit into from
Oct 17, 2023
Merged

Small doc changes #55

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
20 changes: 12 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,21 @@
# tektoncd-catalog

Catalog of Tekton resources (Tasks, Pipelines, …) by Red Hat.
This is the home of the catalog of Tekton resources (Tasks, Pipelines, …) by Red Hat.

This repository contains a catalog of `Task` resources (and someday
`Pipeline`s and other resources), which are designed to be reusable in many
pipelines, authored and supported by Red Hat.
`Pipeline`s and other resources), which are designed to be reusable in many pipelines, authored and supported by Red Hat.

Each `Task` is provided in a separate directory along with a README.md and a
Kubernetes manifest, so you can choose which `Task`s to install on your
cluster. A directory can hold one task and multiple versions.
These `Task` and `Pipeline` are coming from the release of different repositories, maintained by different teams from Red Hat or from partners. See [here](https://github.com/openshift-pipelines/tektoncd-catalog/blob/main/externals.yaml) to know where they are pulled from.

The layout of this repository follows the of [TEP-003: Tekton catalog
organization](https://github.com/tektoncd/community/blob/main/teps/0003-tekton-catalog-organization.md).
As of today, they are indexed by [ArtifactHub](https://github.com/artifacthub.io) in several "catalog":
- [redhat-tekton-tasks](https://artifacthub.io/packages/search?repo=redhat-tekton-tasks&page=1)
- [redhat-tekton-pipelines](https://artifacthub.io/packages/search?repo=redhat-tekton-pipelines&page=1)
- [redhat-tekton-experimental-tasks](https://artifacthub.io/packages/search?repo=redhat-tekton-experimental-tasks)
- [redhat-tekton-experimental-pipelines](https://artifacthub.io/packages/search?repo=redhat-tekton-experimental-pipelines)

The `main` branch of the repository is holding the configuration and tooling to maintain the catalog. The `p` branch is where the the catalog is "persisted" and should be consumed.

Each `Task` is provided in a separate directory along with a README.md and aKubernetes manifest, so you can choose which `Task`s to install on your cluster. A directory can hold one task and multiple versions. The layout of this repository (branch `p`) the follows of [TEP-003: Tekton catalog organization](https://github.com/tektoncd/community/blob/main/teps/0003-tekton-catalog-organization.md).

# What is Tekton ecosystem team about

Expand Down
18 changes: 9 additions & 9 deletions docs/dot-catalog.md → docs/catalog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,34 +1,34 @@
`.catalog.yaml`
`catalog.yaml`

# Abstract

Describes what the dot-file `.catalog.yaml` contains and the use-cases indented for this **contract**. The dot-file will be placed on the root of a CVS repository containing Tekton Pipeline resources (Tasks and Pipelines).
Describes what the file `catalog.yaml` contains and the use-cases indented for this **contract**. The file will be placed on the root of a CVS repository containing Tekton Pipeline resources (Tasks and Pipelines).

The `.catalog.yaml` goal is to serve as a blueprint to find the resources managed on the respective repository, as well to provide information for software supply chain attestation, and describe continuous integration test-cases.
The `catalog.yaml` goal is to serve as a blueprint to find the resources managed on the respective repository, as well to provide information for software supply chain attestation, and describe continuous integration test-cases.

During the release of these repositories the `.catalog.yaml` is added to the payload in order to describe the Tekton resource artifacts.
During the release of these repositories the `catalog.yaml` is added to the payload in order to describe the Tekton resource artifacts.

# Use-Cases

The dot-file described on this document is meant to make possible the use-cases described below.
The file described on this document is meant to make possible the use-cases described below.

## Repository Root

The primary location for the `.catalog.yaml` file is on the root of the (Git?) repository, describing all the elements, providing software supply chain attestation data and as well descring test cases.
The primary location for the `catalog.yaml` file is on the root of the (Git?) repository, describing all the elements, providing software supply chain attestation data and as well descring test cases.

For repositories containing the direct YAML payload of Tekton resource files stored, the file will also contain `.catalog.resources` entries, reflecting the location of the data.

### Release Artifacts

The `.catalog.yaml` should be present on the repositories release payload, therefore when the maintainers decide to release a new version, the `.catalog.yaml` is able to overwrite the entries on `.catalog.resources`.
The `catalog.yaml` should be present on the repositories release payload, therefore when the maintainers decide to release a new version, the `catalog.yaml` is able to overwrite the entries on `.catalog.resources`.

This ability makes possible to template Tekton resources instead of the plain YAML files, and during the regular releases the resource are assembled.

## Continuous Integration

# `.catalog.{yml,yaml}`
# `catalog.{yml,yaml}`

The dot-file looks like the example below.
The file looks like the example below.

```yml
---
Expand Down
28 changes: 28 additions & 0 deletions docs/design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,33 @@
# Design

From repository `task-git` to `tektoncd-catalog` `p` branch.

- In `task-git` repository
- I have a "configuration file" (`catalog.yaml` ?) that lists Tasks and Pipelines from the repository that I want to release
- This file can be generated, updated, …
- When I do the release, I want to issue one command (`catalog-cd release`)
- it mutates the resources to add the version annotation
- it generates the final `catalog.yaml` with hash, digest, signature, …
- it packages the tasks and pipelines in a `tekton-resources.tar.gz` tarball (with READMEs for documentation)
- it (optionally) create, push the tag, create a GitHub release and attach content to it
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here I expect users to rely on gh directly, so catalog-cd release will do all the heavy lifting for the user be able to only upload the release.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In my head, it was more, something similar to goreleaser. Quite some project using goreleaser do not create any GitHub release using the UI or gh, just rely on the gorelease tool. The idea was kind-of the same 🙃

- In `tektoncd-catalog` repository
- `task-git` is configured in the `externals.yaml` configuration file
- A schedule action (each hours ?) does the following, for each entry in `externals.yaml`
- List releases and filter those that have a `catalog.yaml`
- Fetch the `catalog.yaml` and the `tekton-resources.tar.gz`
- Extract the tarball content and merge it with the current catalog available in the `p` branch
- Creates a pull-request to update it
- The pull request checks includes
- Lint the resources
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And for the future, we should require a proof that catalog-cd probe has run successfully 💡

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe part of the SBOM payload.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/cc @savitaashture


What is describe above is *required* for the internal launch.

What is missing from here:
- Attestation, SBOM, signature, …
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Which should go into .catalog.attestation attributes, I think the basic requirements are: https://docs.sigstore.dev/signing/quickstart/#verifying-a-signed-blob

So, we still need to describe:

  • Certificate
  • Signature
  • Identity

- How to validate the task is well tested (so that Red Hat can support it)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Then this, plus making sure the image is part of the Red Hat catalog, also, the image itself needs to provide a valid provenance attestation.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/cc @savitaashture 🙏


---

## Workflow

- `p` is where the indexed catalog is (where users can pull it from)
Expand Down