From 93eb4d352e03a5fd8d60c067d519f506a9bc69b9 Mon Sep 17 00:00:00 2001 From: Roshan Ramani Date: Tue, 20 Oct 2026 11:13:58 +0530 Subject: [PATCH 1/2] docs(integrations): update CLI commands to current flags The integration docs still used the pre-2024 commands: describe and attach by ID, a removed `workflow integration attach`, and attach without the `--project` flag that is now required, so each example fails flag validation. The smtp registration example was also missing the required `--name`, and a comment inside the oci-registry continuation ended the command early. Assisted-by: Claude Code Signed-off-by: Roshan Ramani --- app/controlplane/plugins/README.md | 2 +- .../plugins/core/discord-webhook/v1/README.md | 2 +- app/controlplane/plugins/core/guac/v1/README.md | 2 +- app/controlplane/plugins/core/slack-webhook/v1/README.md | 2 +- app/controlplane/plugins/core/smtp/v1/README.md | 6 +++--- app/controlplane/plugins/core/webhook/v1/README.md | 2 +- devel/integrations.md | 8 ++++---- 7 files changed, 12 insertions(+), 12 deletions(-) diff --git a/app/controlplane/plugins/README.md b/app/controlplane/plugins/README.md index 12dd51e55..1f3484872 100644 --- a/app/controlplane/plugins/README.md +++ b/app/controlplane/plugins/README.md @@ -57,7 +57,7 @@ $ chainloop integration available list And the information of how to use it can be found in the describe command. ```console -$ chainloop integration available describe --id dependencytrack +$ chainloop integration available describe --name dependency-track ┌─────────────────┬─────────┬──────────────────────┬────────────────────────────────────────────────────────┐ │ ID │ VERSION │ MATERIAL REQUIREMENT │ DESCRIPTION │ ├─────────────────┼─────────┼──────────────────────┼────────────────────────────────────────────────────────┤ diff --git a/app/controlplane/plugins/core/discord-webhook/v1/README.md b/app/controlplane/plugins/core/discord-webhook/v1/README.md index 0fc0f1a94..2f5a12831 100644 --- a/app/controlplane/plugins/core/discord-webhook/v1/README.md +++ b/app/controlplane/plugins/core/discord-webhook/v1/README.md @@ -18,7 +18,7 @@ $ chainloop integration registered add discord-webhook --name [my-registration] 2. Attach the integration to your workflow. ```console -chainloop integration attached add --workflow $WID --integration $IID +chainloop integration attached add --workflow [workflow-name] --project [project-name] --integration [my-registration] ``` ## Registration Input Schema diff --git a/app/controlplane/plugins/core/guac/v1/README.md b/app/controlplane/plugins/core/guac/v1/README.md index c8fe6d5fa..bbb2335af 100644 --- a/app/controlplane/plugins/core/guac/v1/README.md +++ b/app/controlplane/plugins/core/guac/v1/README.md @@ -48,7 +48,7 @@ $ chainloop integration registered add guac --name [my-registration] --opt bucke Then, in order to use the integration, you need to attach it to a workflow by providing the IDs of the workflow and integration you just registered. ```sh -$ chainloop integration attached add --workflow $WID --integration $ID +$ chainloop integration attached add --workflow [workflow-name] --project [project-name] --integration [my-registration] ``` That's all on the Chainloop side. Now all new attestation and SBOM metadata files will get uploaded to your Google Cloud Storage bucket. diff --git a/app/controlplane/plugins/core/slack-webhook/v1/README.md b/app/controlplane/plugins/core/slack-webhook/v1/README.md index 858d28cbd..8914be320 100644 --- a/app/controlplane/plugins/core/slack-webhook/v1/README.md +++ b/app/controlplane/plugins/core/slack-webhook/v1/README.md @@ -13,7 +13,7 @@ $ chainloop integration registered add slack-webhook --name [my-registration] -- 2. Attach the integration to your workflow. ```console -chainloop integration attached add --workflow $WID --integration $IID +chainloop integration attached add --workflow [workflow-name] --project [project-name] --integration [my-registration] ``` ## Registration Input Schema diff --git a/app/controlplane/plugins/core/smtp/v1/README.md b/app/controlplane/plugins/core/smtp/v1/README.md index 0cd67ca06..1d19b1006 100644 --- a/app/controlplane/plugins/core/smtp/v1/README.md +++ b/app/controlplane/plugins/core/smtp/v1/README.md @@ -8,19 +8,19 @@ In the following example, we will use the AWS SES service. 1. To get started, you need to register the plugin in your Chainloop organization. ``` -chainloop integration registered add smtp --opt user=AHDHSYEE7e73 --opt password=kjsdfda8asd**** --opt host=email-smtp.us-east-1.amazonaws.com --opt port=587 --opt to=platform-team@example.com --opt from=notifier@example.com +chainloop integration registered add smtp --name [my-registration] --opt user=AHDHSYEE7e73 --opt password=kjsdfda8asd**** --opt host=email-smtp.us-east-1.amazonaws.com --opt port=587 --opt to=platform-team@example.com --opt from=notifier@example.com ``` 2. When attaching the integration to your workflow, you have the option to specify CC: ``` -chainloop integration attached add --workflow $WID --integration $IID --opt cc=security@example.com +chainloop integration attached add --workflow [workflow-name] --project [project-name] --integration [my-registration] --opt cc=security@example.com ``` cc is optional: ``` -chainloop workflow integration attach --workflow $WID --integration $IID +chainloop integration attached add --workflow [workflow-name] --project [project-name] --integration [my-registration] ``` Starting now, every time a workflow run occurs, an email notification will be sent containing the details of the run and attestation. diff --git a/app/controlplane/plugins/core/webhook/v1/README.md b/app/controlplane/plugins/core/webhook/v1/README.md index 14887c7a2..575365c98 100644 --- a/app/controlplane/plugins/core/webhook/v1/README.md +++ b/app/controlplane/plugins/core/webhook/v1/README.md @@ -15,7 +15,7 @@ chainloop integration registered add webhook --name [my-registration] --opt url= 1. Attach the integration to your workflow. ```console -chainloop integration attached add --workflow $WID --integration $IID +chainloop integration attached add --workflow [workflow-name] --project [project-name] --integration [my-registration] ``` > **Note:** You can specify the `send_attestation` and `send_sbom` options to control what is sent to the webhook. `--opt "send_attestation=false"` will disable sending attestations, and `--opt "send_sbom=true"` will enable sending SBOMs. diff --git a/devel/integrations.md b/devel/integrations.md index e7858c85e..4b8139a94 100644 --- a/devel/integrations.md +++ b/devel/integrations.md @@ -47,7 +47,7 @@ Registration is when a specific instance of the integration is configured on a C In our case, we want to register an instance of the `oci-registry` integration. To do so, we need to first figure out what configuration parameters are required by the integration. We can do so by running: ```sh -$ chainloop integration available describe --id oci-registry +$ chainloop integration available describe --name oci-registry ┌──────────────┬─────────┬──────────────────────┬────────────────────────────────────────────────┐ │ ID │ VERSION │ MATERIAL REQUIREMENT │ DESCRIPTION │ ├──────────────┼─────────┼──────────────────────┼────────────────────────────────────────────────┤ @@ -74,9 +74,9 @@ $ chainloop integration available describe --id oci-registry In the console output we can see a registration section that indicates that 3 parameters are required, let's go ahead and register it using our Google Artifact Registry Credentials by running: ```sh +# repository i.e us-east1-docker.pkg.dev/my-project/chainloop-cas-devel $ chainloop integration registered add oci-registry \ --name [unique-registration-name] \ - # i.e us-east1-docker.pkg.dev/my-project/chainloop-cas-devel --opt repository=[region]-docker.pkg.dev/[my-project]/[my-repository] \ --opt username=_json_key \ --opt "password=$(cat service-account.json)" @@ -88,10 +88,10 @@ $ chainloop integration registered add oci-registry \ Once the integration is registered, we can attach it to any workflow. In practice this means that attestations and material information generated in this workflow will be sent to the registered integration. -The attachment process has at least two required parameters, the `workflowID` and the registered `integrationID`. Additionally each integration might have additional to customize its behavior per-workflow. In our case, on the table above, we can see that the `oci-registry` integration has an optional parameter called `prefix` that allows you to customize the name of the image that will be pushed to the registry. +The attachment process has three required parameters: the workflow name, the name of the project it belongs to, and the name of the registered integration. Additionally each integration might have additional to customize its behavior per-workflow. In our case, on the table above, we can see that the `oci-registry` integration has an optional parameter called `prefix` that allows you to customize the name of the image that will be pushed to the registry. ```console -$ chainloop integration attached add --workflow $WID --integration $IID --opt prefix=custom-prefix +$ chainloop integration attached add --workflow [workflow-name] --project [project-name] --integration [unique-registration-name] --opt prefix=custom-prefix ``` Congratulations, you are done now! Every new attestation from this workflow will be uploaded to your OCI registry! From 4c453c33bb91a76b7f72a4b17df011df6603d8f7 Mon Sep 17 00:00:00 2001 From: Roshan Ramani Date: Tue, 20 Oct 2026 11:28:50 +0530 Subject: [PATCH 2/2] docs(integrations): describe attach arguments as names The guac README still said the attach command takes IDs, and the attachment paragraph in devel/integrations.md was missing a word. Assisted-by: Claude Code Signed-off-by: Roshan Ramani --- app/controlplane/plugins/core/guac/v1/README.md | 2 +- devel/integrations.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/app/controlplane/plugins/core/guac/v1/README.md b/app/controlplane/plugins/core/guac/v1/README.md index bbb2335af..fd7d2a14c 100644 --- a/app/controlplane/plugins/core/guac/v1/README.md +++ b/app/controlplane/plugins/core/guac/v1/README.md @@ -45,7 +45,7 @@ $ chainloop integration registered add guac --name [my-registration] --opt bucke ### Attachment -Then, in order to use the integration, you need to attach it to a workflow by providing the IDs of the workflow and integration you just registered. +Then, in order to use the integration, you need to attach it to a workflow by providing the names of the workflow, its project and the integration you just registered. ```sh $ chainloop integration attached add --workflow [workflow-name] --project [project-name] --integration [my-registration] diff --git a/devel/integrations.md b/devel/integrations.md index 4b8139a94..83875f094 100644 --- a/devel/integrations.md +++ b/devel/integrations.md @@ -88,7 +88,7 @@ $ chainloop integration registered add oci-registry \ Once the integration is registered, we can attach it to any workflow. In practice this means that attestations and material information generated in this workflow will be sent to the registered integration. -The attachment process has three required parameters: the workflow name, the name of the project it belongs to, and the name of the registered integration. Additionally each integration might have additional to customize its behavior per-workflow. In our case, on the table above, we can see that the `oci-registry` integration has an optional parameter called `prefix` that allows you to customize the name of the image that will be pushed to the registry. +The attachment process has three required parameters: the workflow name, the name of the project it belongs to, and the name of the registered integration. Additionally, each integration might have additional options to customize its behavior per-workflow. In our case, on the table above, we can see that the `oci-registry` integration has an optional parameter called `prefix` that allows you to customize the name of the image that will be pushed to the registry. ```console $ chainloop integration attached add --workflow [workflow-name] --project [project-name] --integration [unique-registration-name] --opt prefix=custom-prefix