From 5cec460839f4388be362ee27124ecf985ee46780 Mon Sep 17 00:00:00 2001 From: Ricky Whitaker Date: Wed, 26 Aug 2026 21:13:44 -0500 Subject: [PATCH] docs: generate action and workflow input/output tables Regenerates the Inputs/Outputs tables in every action README and reusable workflow doc from the YAML that declares them, and adds a CI job that fails when they drift. Required and Default now come from the YAML rather than prose, which caught several stale values: cleanup-branches documented dry-run as defaulting to true when it is false, validate-policy-bot-config pointed at a dead endpoint, and go-flaky-tests listed three outputs it never declares. A few descriptions were corrected or enriched where the old tables carried detail the YAML lacked, including image-digests, which was described as CSV but is emitted one per line. --- .github/workflows/check-action-docs.yaml | 66 +++++++++++ .github/workflows/check-drone-signature.md | 29 +++++ .../workflows/docker-build-push-multiarch.md | 105 ++++++++++-------- .github/workflows/publish-techdocs.md | 26 +++-- .github/workflows/reusable-zizmor.md | 30 ++--- .github/workflows/reusable-zizmor.yml | 4 +- .github/workflows/sign-and-attest.md | 14 ++- actions/annotate-coverage/README.md | 20 ++-- actions/argo-lint/README.md | 11 ++ actions/aws-auth/README.md | 39 +++++-- actions/aws-auth/action.yaml | 6 +- actions/azure-trusted-signing/README.md | 49 ++++---- actions/cleanup-branches/README.md | 16 ++- actions/component-change-detection/README.md | 30 +++-- actions/create-github-app-token/README.md | 24 ++-- actions/dependabot-auto-triage/README.md | 20 ++-- actions/dependabot-auto-triage/action.yml | 2 +- actions/docker-build-push-image/README.md | 94 +++++++++------- actions/docker-export-digest/README.md | 12 +- .../README.md | 29 +++-- .../action.yaml | 5 +- .../README.md | 32 ++++-- actions/find-pr-for-commit/README.md | 26 +++-- actions/find-pr-for-commit/action.yaml | 2 +- actions/generate-openapi-clients/README.md | 28 +++-- actions/generate-openapi-clients/action.yaml | 2 +- .../get-latest-workflow-artifact/README.md | 46 +++++--- .../get-latest-workflow-artifact/action.yml | 2 +- actions/get-vault-secrets/README.md | 23 ++++ actions/go-flaky-tests/README.md | 37 +++--- .../issues-update-project-status/README.md | 18 +-- actions/lint-pr-title/README.md | 12 +- actions/login-to-gar/README.md | 12 +- actions/login-to-gcs/README.md | 27 +++-- actions/push-to-gcs/README.md | 39 ++++--- actions/push-to-gcs/action.yaml | 3 +- actions/remove-checkout-credentials/README.md | 10 ++ actions/run-capslock/README.md | 18 +-- actions/run-capslock/action.yaml | 2 +- actions/send-slack-message/README.md | 30 +++-- actions/setup-argo/README.md | 21 ++++ actions/setup-conftest/README.md | 10 ++ actions/setup-jrsonnet/README.md | 21 ++++ actions/signed-commits-info/README.md | 10 ++ actions/socket-export-sbom/README.md | 30 +++-- actions/socket-export-sbom/action.yml | 2 +- .../techdocs-rewrite-relative-links/README.md | 24 ++-- actions/trigger-argo-workflow/README.md | 30 +++-- actions/trigger-argo-workflow/action.yaml | 4 +- actions/validate-policy-bot-config/README.md | 8 +- actions/validate-renovate-config/README.md | 8 +- actions/validate-zizmor-config/README.md | 10 +- actions/wait-for-docker-publish/README.md | 24 ++-- actions/wait-for-docker-publish/action.yaml | 2 +- actions/zizmor-collection-paths/README.md | 12 ++ 55 files changed, 824 insertions(+), 392 deletions(-) create mode 100644 .github/workflows/check-action-docs.yaml create mode 100644 .github/workflows/check-drone-signature.md diff --git a/.github/workflows/check-action-docs.yaml b/.github/workflows/check-action-docs.yaml new file mode 100644 index 0000000000..ebd4d61da5 --- /dev/null +++ b/.github/workflows/check-action-docs.yaml @@ -0,0 +1,66 @@ +name: Check action and workflow docs + +on: + pull_request: + types: + - edited + - opened + - ready_for_review + - synchronize + merge_group: + +permissions: {} + +jobs: + check-action-docs: + name: Docs match their YAML + # Self-hosted so the job is covered by our runtime security monitoring. + runs-on: ubuntu-x64-small + timeout-minutes: 5 + + permissions: + contents: read + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Setup Go + uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 + + # The generator formats its output with prettier so it matches what the + # pre-commit hook would write, and it requires the exact version pinned in + # package.json. Installing it also stops the prettier-dependent tests below + # from silently skipping. + - name: Install bun package manager + uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 + with: + bun-version-file: .bun-version + + - name: Install prettier + run: bun install --frozen-lockfile --linker hoisted + + - name: Run generator tests + run: go test ./... + working-directory: scripts/generate-input-output-docs + + - name: Check reusable workflows match their actions + run: go run . parity -root-dir ../../ + working-directory: scripts/generate-input-output-docs + + - name: Regenerate docs + run: go run . generate -root-dir ../../ + working-directory: scripts/generate-input-output-docs + + # `git diff` alone would miss a doc the generator had to create from + # scratch, because a new file is untracked -- and a brand-new action with + # no README is exactly the case this check exists to catch. Staging first + # makes new files visible to the diff. + - name: Check for drift + run: | + git add -A + if ! git diff --staged --exit-code; then + echo "::error::Action and workflow docs are out of date. Regenerate them with \`cd scripts/generate-input-output-docs && go run . generate -root-dir ../../\` and commit the result." + exit 1 + fi diff --git a/.github/workflows/check-drone-signature.md b/.github/workflows/check-drone-signature.md new file mode 100644 index 0000000000..e34ba09cda --- /dev/null +++ b/.github/workflows/check-drone-signature.md @@ -0,0 +1,29 @@ +# check-drone-signature + +This is a reusable workflow that verifies the signature on a repository's Drone CI +configuration file is valid, so that an unsigned or tampered `.drone.yml` cannot +reach the Drone server. + +The signature check is skipped for forks, because the secrets needed to validate +it are not available to forked repositories. + +```yaml +name: Check Drone signature + +on: pull_request + +jobs: + check-drone-signature: + uses: grafana/shared-workflows/.github/workflows/check-drone-signature.yaml@main +``` + +## Inputs + + + +| Name | Type | Required | Default | Description | +| ------------------- | ------ | -------- | --------------------------- | --------------------------------------- | +| `drone_config_path` | string | No | `.drone.yml` | Path to the Drone CI configuration file | +| `drone_server` | string | No | `https://drone.grafana.net` | Drone CI server URL | + + diff --git a/.github/workflows/docker-build-push-multiarch.md b/.github/workflows/docker-build-push-multiarch.md index d3dbfc4af3..9c5ee8727c 100644 --- a/.github/workflows/docker-build-push-multiarch.md +++ b/.github/workflows/docker-build-push-multiarch.md @@ -20,7 +20,6 @@ actions [docker-build-push-image] and [docker-export-digest] to build and push d There is then a final job that runs the composite action [docker-import-digests-push-manifest] to push the docker manifest. -[docker/build-push-action]: https://github.com/docker/build-push-action [docker-build-push-image]: ../../docker-build-push-image/README.md [docker-export-digest]: ../../docker-export-digest/README.md [docker-import-digests-push-manifest]: ../../docker-import-digests-push-manifest/README.md @@ -44,54 +43,62 @@ jobs: ## Inputs -| Name | Type | Description | -| ----------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `build-args` | string | List of arguments necessary for the Docker image to be built. Passed to `docker/build-push-action`. | -| `build-contexts` | string | List of additional build contexts (e.g., name=path). Passed to `docker/build-push-action`. | -| `buildkitd-config` | string | The buildkitd config file to use. Defaults to `/etc/buildkitd.toml` if you're using Grafana's self-hosted runners. Passed to `docker/setup-buildx-action`. | -| `buildkitd-config-inline` | string | The buildkitd inline config to use. Passed to `docker/setup-buildx-action`. | -| `cache-from` | string | Where cache should be fetched from. Passed to `docker/build-push-action`. | -| `cache-to` | string | Where cache should be stored to. Passed to `docker/build-push-action`. | -| `context` | string | Path to the Docker build context. Passed to `docker/build-push-action`. | -| `docker-buildx-driver` | string | The driver to use for Docker Buildx. Passed to `docker/setup-buildx-action`. | -| `dockerhub-registry` | string | DockerHub Registry to store docker images in. | -| `dockerhub-repository` | string | DockerHub Repository to store docker images in. Default: github.repository | -| `file` | string | The dockerfile to use. Passed to `docker/build-push-action`. | -| `gar-delete-credentials-file` | string | Delete the Google credentials file after the action is finished. If you want to keep the credentials file for a later step, set this to false. | -| `gar-environment` | string | Environment for pushing artifacts (can be either dev or prod). This sets the GAR Project (gar-project) to either `grafanalabs-dev` or `grafanalabs-global`. | -| `gar-image` | string | Name of the image to build. Default: `${GitHub Repo Name}`. | -| `gar-registry` | string | Google Artifact Registry to store docker images in. | -| `gar-repository` | string | Override the 'repo_name' used to construct the GAR repository name. Only necessary when the GAR includes a repo name that doesn't match the GitHub repo name. Default: `docker-${GitHub Repo Name}-${gar-environment}` | -| `include-tags-in-push` | string | Disables the pushing of tags, and instead includes just a list of images as docker tags. Used when pushing docker digests instead of docker tags. | -| `labels` | string | List of custom labels to add to the image as metadata (passed to `docker/build-push-action`). Passed to `docker/build-push-action`. | -| `load` | string | Whether to load the built image into the local docker daemon (passed to `docker/build-push-action`). Passed to `docker/build-push-action`. | -| `outputs` | string | List of docker output destinations. Passed to `docker/build-push-action`. | -| `platforms` | string | List of platforms to build the image for. Passed to `docker/build-push-action`. | -| `push` | string | Whether to push the image to the configured registries. Passed to `docker/build-push-action`. | -| `registries` | string | CSV list of registries to build images for. Accepted registries are "gar" and "dockerhub". | -| `runner-type` | string | Setting this flag will dictate the default instance types to use. If runner-type-x64, runner-type-arm64, and runner-type-manifest are all set then this value is superseded because no defaults will be used. | -| `runner-type-arm64` | string | The instance type to use for arm64 builds. | -| `runner-type-manifest` | string | The instance type to use when building and pushing the manifest. | -| `runner-type-x64` | string | The instance type to use for x64 builds. | -| `generate-summary` | string | Generates a markdown step summary and sets the `OCI_MANIFEST_OUTPUT_JSON` env variable and `image-digests` output after pushing the manifest. Default: `false`. | -| `secrets` | string | Secrets to expose to the build. Only needed when authenticating to private repositories outside the repository in which the image is being built. Passed to `docker/build-push-action`. | -| `ssh` | string | List of SSH agent socket or keys to expose to the build Passed to `docker/build-push-action`. | -| `tags` | string | List of Docker tags to be pushed. Passed to `docker/build-push-action`. | -| `target` | string | Sets the target stage to build. Passed to `docker/build-push-action`. | + + +| Name | Type | Required | Default | Description | +| ----------------------------- | ------ | -------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `build-args` | string | No | | List of arguments necessary for the Docker image to be built. Passed to `docker/build-push-action`. | +| `build-contexts` | string | No | | List of additional build contexts (e.g., name=path). Passed to `docker/build-push-action`. | +| `buildkitd-config` | string | No | | The buildkitd config file to use. Defaults to `/etc/buildkitd.toml` if you're using Grafana's self-hosted runners. Passed to `docker/setup-buildx-action`. | +| `buildkitd-config-inline` | string | No | | The buildkitd inline config to use. Passed to `docker/setup-buildx-action`. | +| `cache-from` | string | No | `type=gha` | Where cache should be fetched from. Passed to `docker/build-push-action`. | +| `cache-to` | string | No | `type=gha,mode=max` | Where cache should be stored to. Passed to `docker/build-push-action`. | +| `context` | string | No | `.` | Path to the Docker build context. Passed to `docker/build-push-action`. | +| `docker-buildx-driver` | string | No | `docker-container` | The driver to use for Docker Buildx. Passed to `docker/setup-buildx-action`. | +| `dockerhub-registry` | string | No | `docker.io` | DockerHub Registry to store docker images in. | +| `dockerhub-repository` | string | No | `${{ github.repository }}` | DockerHub Repository to store docker images in. Default: github.repository | +| `file` | string | No | | The dockerfile to use. Passed to `docker/build-push-action`. | +| `gar-delete-credentials-file` | string | No | `true` | Delete the Google credentials file after the action is finished. If you want to keep the credentials file for a later step, set this to false. | +| `gar-environment` | string | No | `dev` | Environment for pushing artifacts (can be either dev or prod). This sets the GAR Project (gar-project) to either `grafanalabs-dev` or `grafanalabs-global`. | +| `gar-image` | string | No | | Name of the image to build. Default: `${GitHub Repo Name}`. | +| `gar-registry` | string | No | `us-docker.pkg.dev` | Google Artifact Registry to store docker images in. | +| `gar-repository` | string | No | | Override the 'repo_name' used to construct the GAR repository name. Only necessary when the GAR includes a repo name that doesn't match the GitHub repo name. Default: `docker-${GitHub Repo Name}-${gar-environment}` | +| `generate-summary` | string | No | `false` | Generates a markdown step summary and sets the OCI_MANIFEST_OUTPUT_JSON env variable and image-digests output after pushing the manifest. | +| `include-tags-in-push` | string | No | `true` | Disables the pushing of tags, and instead includes just a list of images as docker tags. Used when pushing docker digests instead of docker tags. | +| `labels` | string | No | | List of custom labels to add to the image as metadata (passed to `docker/build-push-action`). Passed to `docker/build-push-action`. | +| `load` | string | No | `false` | Whether to load the built image into the local docker daemon (passed to `docker/build-push-action`). Passed to `docker/build-push-action`. | +| `outputs` | string | No | | List of docker output destinations. Passed to `docker/build-push-action`. | +| `platforms` | string | No | | List of platforms to build the image for. Passed to `docker/build-push-action`. | +| `push` | string | No | | Whether to push the image to the configured registries. Passed to `docker/build-push-action`. | +| `registries` | string | No | | CSV list of registries to build images for. Accepted registries are "gar" and "dockerhub". | +| `runner-type` | string | No | `self-hosted` | Setting this flag will dictate the default instance types to use. Allowed values are 'self-hosted' or 'github'. | +| `runner-type-arm64` | string | No | | The instance type to use for arm64 builds. | +| `runner-type-manifest` | string | No | | The instance type to use when building and pushing the manifest. | +| `runner-type-x64` | string | No | | The instance type to use for x64 builds. | +| `secrets` | string | No | | Secrets to expose to the build. Only needed when authenticating to private repositories outside the repository in which the image is being built. Passed to `docker/build-push-action`. | +| `ssh` | string | No | | List of SSH agent socket or keys to expose to the build Passed to `docker/build-push-action`. | +| `tags` | string | Yes | | List of Docker tags to be pushed. Passed to `docker/build-push-action`. | +| `target` | string | No | | Sets the target stage to build. Passed to `docker/build-push-action`. | + + ## Outputs -| Name | Type | Description | -| -------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------- | -| `annotations` | String | Generated annotations (from docker/metadata-action) | -| `digest` | String | Image digest (from docker/build-push-action) | -| `imageid` | String | Image ID (from docker/build-push-action) | -| `images` | String | Comma separated list of the images that were built | -| `json` | String | JSON output of tags and labels (from docker/metadata-action) | -| `labels` | String | Generated Docker labels (from docker/metadata-action) | -| `metadata` | String | Build result metadata (from docker/build-push-action) | -| `runner_arches` | String | The list of OS used to build images (for mapping to self hosted runners) | -| `image-digests` | String | Newline-separated list of image digests in the format `:@` (requires `generate-summary: true`) | -| `oci-manifest-output-json` | String | JSON array of manifests with tag, indexDigest, and per-platform digest information (requires `generate-summary: true`) | -| `tags` | String | Generated Docker tags (from docker/metadata-action) | -| `version` | String | Generated Docker image version (from docker/metadata-action) | + + +| Name | Description | +| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `annotations` | Generated annotations (from docker/metadata-action) | +| `digest` | Image digest (from docker/build-push-action) | +| `image-digests` | Newline-separated list of image digests in the format <image>:<tag>@<digest> (from docker-import-digests-push-manifest) | +| `imageid` | Image ID (from docker/build-push-action) | +| `images` | Comma separated list of the images that were built | +| `json` | JSON output of tags and labels (from docker/metadata-action) | +| `labels` | Generated Docker labels (from docker/metadata-action) | +| `metadata` | Build result metadata (from docker/build-push-action) | +| `oci-manifest-output-json` | JSON array of manifests with tag, indexDigest, and per-platform digest information (from docker-import-digests-push-manifest) | +| `runner-arches` | The list of OS used to build images (for mapping to self hosted runners) | +| `tags` | Generated Docker tags (from docker/metadata-action) | +| `version` | Generated Docker image version (from docker/metadata-action) | + + diff --git a/.github/workflows/publish-techdocs.md b/.github/workflows/publish-techdocs.md index fe1cf94505..8a97044014 100644 --- a/.github/workflows/publish-techdocs.md +++ b/.github/workflows/publish-techdocs.md @@ -34,16 +34,18 @@ jobs: ## Inputs -| Name | Type | Description | -| -------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `namespace` | string | The entity's namespace within EngHub (usually `default`) | -| `kind` | string | The kind of the entity in EngHub (usually `component`) | -| `name` | string | The name of the entity in EngHub (usually matches the name of the repository) | -| `default-working-directory` | string | The working directory to use for doc generation. Useful for cases without an mkdocs.yml file at the project root. | -| `rewrite-relative-links` | boolean | Execute [rewrite-relative-links][rewrite-action] step to rewrite relative links in the docs to point to the correct location in the GitHub repository | -| `rewrite-relative-links-dry-run` | boolean | Execute [rewrite-relative-links][rewrite-action] step but only print the diff without modifying the files | -| `publish` | boolean | Enable or disable publishing after building the docs | -| `checkout-submodules` | string | Checkout submodules in the repository. Options are `true` (checkout submodules), `false` (don't checkout submodules), or `recursive` (recursively checkout submodules) | -| `instance` | string | The name of the instance to which the docs should be published (`ops` (default), `dev`) | + -[rewrite-action]: ../../actions/techdocs-rewrite-relative-links/README.md +| Name | Type | Required | Default | Description | +| -------------------------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `checkout-submodules` | string | No | `false` | Checkout submodules in the repository. Options are `true` (checkout submodules), `false` (don't checkout submodules), or `recursive` (recursively checkout submodules) | +| `default-working-directory` | string | No | `.` | The working directory to use for doc generation. Useful for cases without an mkdocs.yml file at the project root. | +| `instance` | string | No | `ops` | The instance to use (`dev` or `ops`). Defaults to `ops`. | +| `kind` | string | Yes | | The kind of the entity in EngHub (usually `component`) | +| `name` | string | Yes | | The name of the entity in EngHub (usually matches the name of the repository) | +| `namespace` | string | Yes | | The entity's namespace within EngHub (usually `default`) | +| `publish` | boolean | No | `true` | Enable or disable publishing after building the docs | +| `rewrite-relative-links` | boolean | No | `false` | Execute rewrite-relative-links step to rewrite relative links in the docs to point to the correct location in the GitHub repository | +| `rewrite-relative-links-dry-run` | boolean | No | `false` | Execute rewrite-relative-links step but only print the diff without modifying the files | + + diff --git a/.github/workflows/reusable-zizmor.md b/.github/workflows/reusable-zizmor.md index 4a47eb2632..b54634b141 100644 --- a/.github/workflows/reusable-zizmor.md +++ b/.github/workflows/reusable-zizmor.md @@ -103,20 +103,22 @@ jobs: ## Inputs -| Name | Type | Description | Default Value | Required | -| ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | -------- | -| min-severity | string | Only show results at or above this severity [possible values: unknown, informational, low, medium, high] | medium | false | -| min-confidence | string | Only show results at or above this confidence level [possible values: unknown, low, medium, high] | low | false | -| fail-severity | string | Fail the build if any result is at or above this severity [possible values: never, any, informational, low, medium, high] | high | false | -| runs-on | string | The runner to use for jobs. Configure this to use self-hosted runners. | ubuntu-latest | false | -| always-use-default-config | boolean | Whether to always use the [default configuration]. When `false`, `.zizmor.yml` or `.github/zizmor.yml` will be used, if present. | false | false | -| github-token | string | The GitHub token to use when authenticating with the GitHub API | ${github.token} | false | -| extra-args | string | Extra arguments to pass into zizmor | "" | false | -| send-bench-metrics | boolean | If true, run Grafana Bench after analysis to send zizmor metrics to Prometheus. Uses shared Vault secrets (grafana-bench); no caller secrets required. Set to false to skip. | true | false | -| auto-delete-dangerous-branches | boolean | If true, on `push` to a non-default branch, delete the branch when zizmor reports `dangerous-triggers` findings. Sends a Slack notification first. Caller must grant `contents: write` and `id-token: write`. | false | false | -| auto-delete-slack-channel-id | string | Slack channel ID to notify before deleting a branch. Required when `auto-delete-dangerous-branches` is `true`. | "" | false | - -[default configuration]: ../zizmor.yml + + +| Name | Type | Required | Default | Description | +| -------------------------------- | ------- | -------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `always-use-default-config` | boolean | No | `false` | Whether to always use the default configuration. When `false`, `.zizmor.yml` or `.github/zizmor.yml` will be used, if present. | +| `auto-delete-dangerous-branches` | boolean | No | `false` | If true, automatically delete non-default branches on push events when zizmor finds dangerous-triggers findings. Sends a Slack notification before deletion. Caller must grant contents:write and id-token:write permissions. | +| `auto-delete-slack-channel-id` | string | No | | Slack channel ID to notify before deleting a branch. Required when `auto-delete-dangerous-branches` is `true`. | +| `extra-args` | string | No | | Extra arguments to pass to Zizmor | +| `fail-severity` | string | No | `high` | Fail the build if any result is at or above this severity [possible values: never, any, informational, low, medium, high] | +| `github-token` | string | No | `${{ github.token }}` | Use a different token to the default | +| `min-confidence` | string | No | `low` | Only show results at or above this confidence level [possible values: unknown, low, medium, high] | +| `min-severity` | string | No | `low` | Only show results at or above this severity [possible values: unknown, informational, low, medium, high] | +| `runs-on` | string | No | `ubuntu-latest` | The runner to use for jobs. Set this to use self-hosted runners. | +| `send-bench-metrics` | boolean | No | `true` | If true, run Grafana Bench after analysis (Vault Prometheus creds). Job only runs for grafana org and non-fork PRs; fork PRs have no OIDC/Vault access. | + + ## Grafana Bench (Prometheus metrics) diff --git a/.github/workflows/reusable-zizmor.yml b/.github/workflows/reusable-zizmor.yml index 38a4eb302e..f68434534b 100644 --- a/.github/workflows/reusable-zizmor.yml +++ b/.github/workflows/reusable-zizmor.yml @@ -22,7 +22,7 @@ on: default: "high" runs-on: - description: "The runner to use for jobs" + description: "The runner to use for jobs. Set this to use self-hosted runners." required: false type: string default: "ubuntu-latest" @@ -64,7 +64,7 @@ on: default: false auto-delete-slack-channel-id: - description: Slack channel ID to notify before deleting a branch. + description: Slack channel ID to notify before deleting a branch. Required when `auto-delete-dangerous-branches` is `true`. required: false type: string default: "" diff --git a/.github/workflows/sign-and-attest.md b/.github/workflows/sign-and-attest.md index 33528fbb12..c948240597 100644 --- a/.github/workflows/sign-and-attest.md +++ b/.github/workflows/sign-and-attest.md @@ -53,11 +53,15 @@ therefore rejects refs without `@sha256:`. ## Inputs -| Name | Type | Description | -| ---------------- | ------ | ------------------------------------------------------------------------------------------------- | -| `image` | string | **Required.** Digest-pinned image reference under `registry`, e.g. `us-docker.pkg.dev/…@sha256:…` | -| `registry` | string | GAR hostname (`*.pkg.dev`) to authenticate against and sign in. Default: `us-docker.pkg.dev` | -| `cosign-version` | string | Cosign release tag to install (e.g. `v3.1.1`). Defaults to the workflow's pinned version. | + + +| Name | Type | Required | Default | Description | +| ---------------- | ------ | -------- | ------------------- | --------------------------------------------------------------------------------------------------------------------- | +| `cosign-version` | string | No | | Cosign release tag to install (e.g. v3.1.1). Defaults to the workflow's pinned version. | +| `image` | string | Yes | | Digest-pinned image reference, e.g. us-docker.pkg.dev/grafanalabs-global/dockerhub-tanka-prod-mirror/tanka@sha256:... | +| `registry` | string | No | `us-docker.pkg.dev` | GAR (Artifact Registry) hostname to authenticate against when writing the signature and attestation. | + + ## Required caller permissions diff --git a/actions/annotate-coverage/README.md b/actions/annotate-coverage/README.md index bcca792ab2..750cd7c024 100644 --- a/actions/annotate-coverage/README.md +++ b/actions/annotate-coverage/README.md @@ -45,14 +45,18 @@ jobs: ## Inputs -| Input | Description | Required | Default | -| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------- | -| `coverage-path` | Directory containing Go coverage files (`*.out`) | No | `.coverage` | -| `format` | Output format: `Text`, `Markdown`, or `GitHubAnnotations` | No | `GitHubAnnotations` | -| `base-ref` | Base ref to compare against (e.g., the PR base SHA). When set, diff is `..`. | No | - | -| `commit-sha` | Commit ref to compare to. With `base-ref`, diff is `..`. Without `base-ref`, diff is the changes introduced by `` alone. | No | - | -| `repository-directory` | Path to the git repository to analyze | No | `${{ github.workspace }}` | -| `go-version` | Go version used to build the action binary | No | `1.25` | + + +| Name | Type | Required | Default | Description | +| ---------------------- | ------ | -------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `base-ref` | String | No | | Base ref to compare against (e.g., the PR base branch). When set, diff is computed as <base-ref>..<commit-sha or HEAD>. | +| `commit-sha` | String | No | | Commit ref to compare to. With base-ref, diff is <base-ref>..<commit-sha>. Without base-ref, diff is the changes introduced by <commit-sha>. Defaults to HEAD when used with base-ref. | +| `coverage-path` | String | No | `.coverage` | Directory containing Go coverage files (*.out) | +| `format` | String | No | `GitHubAnnotations` | Output format: Text, Markdown, or GitHubAnnotations | +| `go-version` | String | No | `1.25` | Go version to use when building the binary | +| `repository-directory` | String | No | `${{ github.workspace }}` | Path to the git repository to analyze | + + ## Diff modes diff --git a/actions/argo-lint/README.md b/actions/argo-lint/README.md index 6f71fa5d27..160a2ee6ac 100644 --- a/actions/argo-lint/README.md +++ b/actions/argo-lint/README.md @@ -14,3 +14,14 @@ with: ``` + +## Inputs + + + +| Name | Type | Required | Default | Description | +| -------------- | ------ | -------- | -------- | ------------------------------------------- | +| `argo-version` | String | No | `3.7.10` | Version of the Argo CLI to use for linting. | +| `path` | String | Yes | | Path to files for linting. | + + diff --git a/actions/aws-auth/README.md b/actions/aws-auth/README.md index 796402fd71..cce689df84 100644 --- a/actions/aws-auth/README.md +++ b/actions/aws-auth/README.md @@ -37,22 +37,39 @@ jobs: -| Name | Type | Description | -| -------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `aws-region` | String | Specify AWS region to use that contain your resources (default: `us-east-2`) | -| `role-arn` | String | Specify custom workload role. Role ARN must be prefixed with `github-actions` e.g. `arn:aws:iam::366620023056:role/github-actions/s3-test-access` [^1] | -| `pass-claims` | String | `, `-separated list of [GitHub Actions claims](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token) (session tags) to make available to `role-arn`. Currently supported claims (default): `"repository_owner, repository_name, job_workflow_ref, ref, event_name"` [^2] | -| `set-creds-in-environment` | Bool | Set environment variables for AWS CLI and SDKs (default: `true`) | -| `role-duration-seconds` | String | Role duration in seconds (default: `"3600"`) | + - +| Name | Type | Required | Default | Description | +| ---------------------------------- | ------- | -------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `aws-region` | String | Yes | `us-east-2` | AWS region that contains the resources you want to use | +| `checkout-actions-repository-path` | String | No | | The path in the filesystem where this repository has been checked out. This is mandatory for setups where executing this action inside a local clone of the repository. | +| `pass-claims` | String | Yes | `event_name, repository_owner, repository_name, job_workflow_ref, ref` | `, `-separated [GitHub Actions claims](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token) (session tags) to make available to `role-arn`. Claims must be mapped to the Cognito Identity Pool before they can be used. | +| `role-arn` | String | Yes | | ARN of the workload role to assume. Must be prefixed with `github-actions`, e.g. `arn:aws:iam::366620023056:role/github-actions/s3-test-access`. See the Setting up Workload Role section below for an example. | +| `role-duration-seconds` | String | No | `3600` | Role duration in seconds | +| `set-creds-in-environment` | Boolean | No | `true` | Set environment variables for AWS CLI and SDKs | + + -[^1]: See [Setting up Workload Role](#setting-up-workload-role) for an example + -[^2]: GitHub OIDC token claims must be mapped to the Cognito Identity Pool before they can be used. If you would like to use a claim that is not listed, file an issue in this repo or reach out to `@platform-productivity` in `#platform`. +See [Setting up Workload Role](#setting-up-workload-role) for an example of a `role-arn`. If you would like to pass a claim that is not in the `pass-claims` default, file an issue in this repo or reach out to `@platform-productivity` in `#platform`. This uses the [`cognito-idpool-auth`](https://github.com/catnekaise/cognito-idpool-auth) action to perform authentication with an Amazon Cognito Identity Pool using the GitHub Actions OIDC access token. +## Outputs + + + +| Name | Description | +| ------------------------------------ | ---------------------------------- | +| `aws_access_key_id` | AWS Access Key Id | +| `aws_region` | AWS Region | +| `aws_secret_access_key` | AWS Secret Access Key | +| `aws_session_token` | AWS Session Name | +| `cognito_identity_oidc_access_token` | Cognito Identity OIDC Access Token | + + + ## Setting up Workload Role IAM workload roles are used to grant permissions to AWS in a secure manner. From a workflow run, once authenticated, the role is granted temporary credentials to access AWS resources permitted by the associated IAM role and attached trust/permission policies. The following steps will guide you through the process of setting up an IAM workload role for read access to a single object in an S3 bucket. @@ -65,7 +82,7 @@ The role should only be present in the account that contains the resources it ne ### Trust Policy -This is where you provide additional constraints for when permissions are applied. The condition block can be customized as you see fit with additional [GitHub OIDC token claims](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token) [^2]. +This is where you provide additional constraints for when permissions are applied. The condition block can be customized as you see fit with additional [GitHub OIDC token claims](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token), as long as those claims are passed via `pass-claims`. As this defines which GitHub Actions runs are allowed to use the role's permissions, it is critical to make these configurations as precise as possible. Furthermore, all runs are limited to be triggered exclusively from repositories under `grafana/`, and it is not possible to exceed this restriction. diff --git a/actions/aws-auth/action.yaml b/actions/aws-auth/action.yaml index f02465ea0f..37fa17560c 100644 --- a/actions/aws-auth/action.yaml +++ b/actions/aws-auth/action.yaml @@ -5,15 +5,15 @@ inputs: aws-region: default: "us-east-2" required: true - description: "AWS region" + description: "AWS region that contains the resources you want to use" role-arn: default: "" required: true - description: "ARN of workload role" + description: "ARN of the workload role to assume. Must be prefixed with `github-actions`, e.g. `arn:aws:iam::366620023056:role/github-actions/s3-test-access`. See the Setting up Workload Role section below for an example." pass-claims: default: "event_name, repository_owner, repository_name, job_workflow_ref, ref" required: true - description: "`, `-separated claims from GitHub ID token to make available to `role-arn`" + description: "`, `-separated [GitHub Actions claims](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token) (session tags) to make available to `role-arn`. Claims must be mapped to the Cognito Identity Pool before they can be used." set-creds-in-environment: default: "true" required: false diff --git a/actions/azure-trusted-signing/README.md b/actions/azure-trusted-signing/README.md index 1ea7f2233d..f18885c7b9 100644 --- a/actions/azure-trusted-signing/README.md +++ b/actions/azure-trusted-signing/README.md @@ -92,33 +92,34 @@ jobs: ## Inputs -### Required - -| **Name** | **Description** | -| :------------------------ | :------------------------------------------------------------------------------------------------------ | -| `application-description` | The description of the application to sign the file(s) for. | -| `artifact-to-sign` | The name of the GitHub Actions workflow artifact from the current workflow run to sign the contents of. | -| `azure-client-id` | The client ID to use to authenticate with Azure. | -| `azure-subscription-id` | The subscription ID to use to authenticate with Azure. | -| `azure-tenant-id` | The tenant ID to use to authenticate with Azure. | -| `signed-artifact-name` | The name of the GitHub Actions workflow artifact to upload the signed files to. | - -### Optional - -| **Name** | **Description** | **Default** | -| :------------------------- | :------------------------------------------------------------------------------- | :----------------------------------------------------- | -| `application-url` | The URL of the application to sign the file(s) for. | The URL of the GitHub repository running the workflow. | -| `file-filter` | The path filter of which files to sign from the artifact. | `'**/*'` | -| `file-list` | The path to a file containing paths of files to sign or to exclude from signing. | - | -| `publisher-name` | The name of the publisher of the application the signed file(s) belong to. | `'Grafana Labs'` | -| `trusted-signing-account` | The name of the Azure Trusted Signing account to use. | - | -| `trusted-signing-endpoint` | The endpoint URL of the Azure Trusted Signing service to use. | - | -| `trusted-signing-profile` | The name of the Azure Trusted Signing profile to use. | - | + + +| Name | Type | Required | Default | Description | +| -------------------------- | ------ | -------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | +| `application-description` | String | Yes | | The description of the application to sign the file(s) for. | +| `application-url` | String | No | `${{ format('{0}/{1}', github.server_url, github.repository) }}` | The optional URL of the application to sign the file(s) for. Defaults to the current GitHub repository URL. | +| `artifact-to-sign` | String | Yes | | The name of the GitHub Actions workflow artifact from the current workflow run to sign the contents of. | +| `azure-client-id` | String | Yes | | The client ID to use to authenticate with Azure. | +| `azure-subscription-id` | String | Yes | | The subscription ID to use to authenticate with Azure. | +| `azure-tenant-id` | String | Yes | | The tenant ID to use to authenticate with Azure. | +| `file-filter` | String | No | `**/*` | The optional path filter of which files to sign from the artifact. Defaults to all files. | +| `file-list` | String | No | | The optional path to a file containing paths of files to sign or to exclude from signing. | +| `publisher-name` | String | No | `Grafana Labs` | The optional name of the publisher of the application the signed file(s) belong to. Defaults to "Grafana Labs". | +| `signed-artifact-name` | String | Yes | | The name of the GitHub Actions workflow artifact to upload the signed files to. | +| `trusted-signing-account` | String | No | `grafana-premium-eastus` | The optional name of the Azure Trusted Signing account to use. | +| `trusted-signing-endpoint` | String | No | `https://eus.codesigning.azure.net/` | The optional endpoint URL of the Azure Trusted Signing service to use. | +| `trusted-signing-profile` | String | No | `grafana-production` | The optional name of the Azure Trusted Signing profile to use. | + + ## Outputs -| **Name** | **Description** | -| :-------------- | :------------------------------------------------------------------------------ | + + +| Name | Description | +| --------------- | ------------------------------------------------------------------------------- | | `artifact-name` | The name of the GitHub Actions workflow artifact containing the signed file(s). | + + [azure-trusted-signing]: https://learn.microsoft.com/azure/trusted-signing/ diff --git a/actions/cleanup-branches/README.md b/actions/cleanup-branches/README.md index 7bad61e8b9..9b72c88896 100644 --- a/actions/cleanup-branches/README.md +++ b/actions/cleanup-branches/README.md @@ -4,12 +4,16 @@ Composite action (step) to query for branches that are not in an open PR, and de ## Inputs -| Name | Type | Description | Default Value | Required | -| ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | -------- | -| `token` | `string` | GitHub token used to authenticate with `gh`. Requires permission to query for protected branches and delete branches (`contents: write`) and pull requests (`pull_requests: read`) | `${{ github.token }}` | true | -| `dry-run` | `bool` | If `'true'`, then the action will print branches to be deleted, but will not delete them | `'true'` | true | -| `max-date` | `string` | Value passed to `date -d`; a human readable date string. Maximum date of the head ref of a branch in order to be deleted. | `"3 months ago"` | false | -| `exclude-patterns` | `string` | Newline-separated list of glob patterns. Branches whose names match any pattern are excluded from deletion. Empty lines are ignored. | `""` | false | + + +| Name | Type | Required | Default | Description | +| ------------------ | ------- | -------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `dry-run` | Boolean | No | `false` | If 'true', then the action will print branches to be deleted, but will not delete them | +| `exclude-patterns` | String | No | | Optional list of glob patterns. Branches whose names match any pattern are excluded from deletion. Patterns use bash glob syntax (e.g. `release/*`). | +| `max-date` | String | No | `3 months ago` | Value provided to `date -d={}. From `man date`: "The --date=STRING is a mostly free format human readable date string such as "Sun, 29 Feb 2004 16:21:42 -0800" or "2004-02-29 16:21:42" or even "next Thursday". A date string may contain items indicating calendar date, time of day, time zone, day of week, relative time, relative date, and numbers. An empty string indicates the beginning of the day. The date string format is more complex than is easily documented here but is fully described in the info documentation." | +| `token` | String | No | `${{ github.token }}` | GitHub token used to authenticate with `gh`. Requires permission to query for protected branches and delete branches (contents: write) and pull requests (pull_requests: read) | + + ## Examples diff --git a/actions/component-change-detection/README.md b/actions/component-change-detection/README.md index e770e4f7d8..b133647597 100644 --- a/actions/component-change-detection/README.md +++ b/actions/component-change-detection/README.md @@ -43,20 +43,28 @@ jobs: ## Inputs -| Name | Type | Description | Default | -| ---------------------- | ------- | --------------------------------------------------------------- | ------- | -| `config-file` | String | Path to component dependencies YAML file | | -| `previous-tags-source` | String | Workflow name to download previous component-tags artifact from | | -| `target-ref` | String | Git ref to compare against | `HEAD` | -| `force-rebuild-all` | Boolean | Force rebuild all components | `false` | -| `force-components` | String | Force rebuild specific components (comma-separated) | | + + +| Name | Type | Required | Default | Description | +| ---------------------- | ------- | -------- | ------- | --------------------------------------------------- | +| `config-file` | String | Yes | | Path to component dependencies YAML file | +| `force-components` | String | No | | Force rebuild specific components (comma-separated) | +| `force-rebuild-all` | Boolean | No | `false` | Force rebuild all components | +| `previous-tags-source` | String | Yes | | Workflow name to get previous tags from | +| `target-ref` | String | No | `HEAD` | Git ref to compare against | + + ## Outputs -| Name | Type | Description | -| ----------------- | ------ | --------------------------------------------------------------------------------------- | -| `changes_json` | String | All component changes as JSON object (e.g., `{"apiserver": true, "controller": false}`) | -| `components_json` | String | List of all components as JSON array (e.g., `["apiserver", "controller"]`) | + + +| Name | Description | +| ----------------- | ------------------------------------------------------------------------------------- | +| `changes_json` | All component changes as JSON object (e.g., {"apiserver": true, "controller": false}) | +| `components_json` | List of all components as JSON array (e.g., ["apiserver", "controller"]) | + + ## Configuration File diff --git a/actions/create-github-app-token/README.md b/actions/create-github-app-token/README.md index 0ba75afc5c..df961f3db7 100644 --- a/actions/create-github-app-token/README.md +++ b/actions/create-github-app-token/README.md @@ -11,17 +11,25 @@ when its Vault lease TTL elapses. ## Inputs -| Name | Type | Description | Default Value | Required | -| ---------------- | ------ | --------------------------- | ------------- | -------- | -| `permission_set` | String | The required permission set | `default` | Yes | -| `github_app` | String | The required GitHub app | | Yes | -| `vault_instance` | String | Vault instance to point | `ops` | No | + + +| Name | Type | Required | Default | Description | +| ---------------- | ------ | -------- | --------- | ------------------------------------------------------------------------------------------------------ | +| `github_app` | String | Yes | | GitHub app name in Vault. You can define multiple apps for load balancing in a comma-separated format. | +| `permission_set` | String | No | `default` | Permission set name. | +| `vault_instance` | String | No | `ops` | The Vault instance to use (`dev` or `ops`). Defaults to `ops`. | + + ## Outputs -| Name | Type | Description | -| ------- | ------ | -------------------------- | -| `token` | String | The generated GitHub token | + + +| Name | Description | +| ------- | --------------------------------- | +| `token` | GitHub installation access token. | + + ## Action Permissions diff --git a/actions/dependabot-auto-triage/README.md b/actions/dependabot-auto-triage/README.md index e460e1ce75..b63c672ae3 100644 --- a/actions/dependabot-auto-triage/README.md +++ b/actions/dependabot-auto-triage/README.md @@ -67,14 +67,18 @@ jobs: ### Inputs -| Name | Description | Required | Default | -| ------------------- | ----------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------- | -| `token` | GitHub token with permissions to dismiss alerts | Yes | N/A | -| `alert-types` | Comma-separated list of alert types to dismiss | No | `dependency` | -| `paths` | Multi-line list of glob patterns to match manifest paths to dismiss | Yes | N/A | -| `dismissal-comment` | Default comment to add when dismissing alerts | No | `Auto-dismissed based on manifest path configuration` | -| `dismissal-reason` | Default reason for dismissal (options: `fix_started`, `inaccurate`, `no_bandwidth`, `not_used`, `tolerable_risk`) | No | `not_used` | -| `close-prs` | Whether to close associated Dependabot pull requests before dismissing alerts | No | `false` | + + +| Name | Type | Required | Default | Description | +| ------------------- | ------- | -------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | +| `alert-types` | String | No | `dependency` | Comma-separated list of alert types to dismiss (default: "dependency") | +| `close-prs` | Boolean | No | `false` | Whether to close associated pull requests when dismissing alerts | +| `dismissal-comment` | String | No | `Auto-dismissed based on manifest path configuration` | Default comment to add when dismissing alerts | +| `dismissal-reason` | String | No | `not_used` | Default reason for dismissal. One of `fix_started`, `inaccurate`, `no_bandwidth`, `not_used` or `tolerable_risk`. | +| `paths` | String | Yes | | Multi-line list of glob patterns to match manifest paths to dismiss | +| `token` | String | Yes | | GitHub token with permissions to dismiss alerts | + + ### How It Works diff --git a/actions/dependabot-auto-triage/action.yml b/actions/dependabot-auto-triage/action.yml index 111f5ac992..38426bf4ce 100644 --- a/actions/dependabot-auto-triage/action.yml +++ b/actions/dependabot-auto-triage/action.yml @@ -19,7 +19,7 @@ inputs: required: false default: "Auto-dismissed based on manifest path configuration" dismissal-reason: - description: "Default reason for dismissal" + description: "Default reason for dismissal. One of `fix_started`, `inaccurate`, `no_bandwidth`, `not_used` or `tolerable_risk`." required: false default: "not_used" # Options: 'fix_started', 'inaccurate', 'no_bandwidth', 'not_used', 'tolerable_risk' diff --git a/actions/docker-build-push-image/README.md b/actions/docker-build-push-image/README.md index cdfdd65255..b5250fb3d2 100644 --- a/actions/docker-build-push-image/README.md +++ b/actions/docker-build-push-image/README.md @@ -56,52 +56,60 @@ jobs: ## Inputs -| Name | Type | Description | -| ----------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `annotations` | String | List of custom annotations to add to the image as metadata. Passed to `docker/build-push-action`. | -| `build-args` | String | List of arguments necessary for the Docker image to be built. Passed to `docker/build-push-action`. | -| `build-contexts` | String | List of additional build contexts (e.g., name=path). Passed to `docker/build-push-action`. | -| `builder` | String | Name of the buildx builder to use. If not specified, a new builder will be created. This is useful when you need to reuse a builder, for example with buildkit-cache-dance. | -| `buildkitd-config` | String | The buildkitd config file to use. Defaults to `/etc/buildkitd.toml` if you're using Grafana's self-hosted runners. Passed to `docker/setup-buildx-action`. | -| `buildkitd-config-inline` | String | The buildkitd inline config to use. Passed to `docker/setup-buildx-action`. | -| `cache-from` | String | Where cache should be fetched from. Passed to `docker/build-push-action`. | -| `cache-to` | String | Where cache should be stored to. Passed to `docker/build-push-action`. | -| `context` | String | Path to the Docker build context. Passed to `docker/build-push-action`. | -| `docker-buildx-driver` | String | The driver to use for Docker Buildx. Passed to `docker/setup-buildx-action`. | -| `dockerhub-registry` | String | DockerHub Registry to store docker images in. | -| `dockerhub-repository` | String | DockerHub Repository to store docker images in. Default: github.repository | -| `file` | String | The dockerfile to use. Passed to `docker/build-push-action`. | -| `gar-delete-credentials-file` | Boolean | Delete the Google credentials file after the action is finished. If you want to keep the credentials file for a later step, set this to false. | -| `gar-environment` | String | Environment for pushing artifacts (can be either dev or prod). This sets the GAR Project (gar-project) to either `grafanalabs-dev` or `grafanalabs-global`. | -| `gar-image` | String | Name of the image to build. Default: `${GitHub Repo Name}`. | -| `gar-registry` | String | Google Artifact Registry to store docker images in. | -| `gar-repository` | String | Override the 'repo_name' used to construct the GAR repository name. Only necessary when the GAR includes a repo name that doesn't match the GitHub repo name. Default: `docker-${GitHub Repo Name}-${gar-environment}` | -| `include-tags-in-push` | Boolean | Disables the pushing of tags, and instead includes just a list of images as docker tags. Used when pushing docker digests instead of docker tags. | -| `labels` | String | List of custom labels to add to the image as metadata (passed to `docker/build-push-action`). Passed to `docker/build-push-action`. | -| `load` | Boolean | Whether to load the built image into the local docker daemon (passed to `docker/build-push-action`). Passed to `docker/build-push-action`. | -| `outputs` | String | List of docker output destinations. Passed to `docker/build-push-action`. | -| `platforms` | String | List of platforms to build the image for. Passed to `docker/build-push-action`. | -| `push` | String | Whether to push the image to the configured registries. **Defaults to `false`** (matching Docker's official action). Set to `true` to push images. Passed to `docker/build-push-action`. | -| `registries` | String | CSV list of registries to build images for. Accepted registries are "gar" and "dockerhub". | -| `secrets` | String | Secrets to expose to the build. Only needed when authenticating to private repositories outside the repository in which the image is being built. Passed to `docker/build-push-action`. | -| `ssh` | String | List of SSH agent socket or keys to expose to the build Passed to `docker/build-push-action`. | -| `tags` | String | List of Docker tags to be pushed. Passed to `docker/build-push-action`. | -| `target` | String | Sets the target stage to build. Passed to `docker/build-push-action`. | + + +| Name | Type | Required | Default | Description | +| ----------------------------- | ------- | -------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `annotations` | String | No | | List of custom annotations to add to the image as metadata (passed to `docker/build-push-action`). Passed to `docker/build-push-action`. | +| `build-args` | String | No | | List of arguments necessary for the Docker image to be built. Passed to [docker/build-push-action](https://github.com/docker/build-push-action?tab=readme-ov-file#inputs). | +| `build-contexts` | String | No | | List of additional build contexts (e.g., name=path). Passed to [docker/build-push-action](https://github.com/docker/build-push-action?tab=readme-ov-file#inputs). | +| `builder` | String | No | | Name of the buildx builder to use. If not specified, a new builder will be created. This is useful when you need to reuse a builder, for example with buildkit-cache-dance. | +| `buildkitd-config` | String | No | | The buildkitd config file to use. Defaults to `/etc/buildkitd.toml` if you're using Grafana's self-hosted runners. Passed to [docker/setup-buildx-action](https://github.com/docker/setup-buildx-action?tab=readme-ov-file#inputs). | +| `buildkitd-config-inline` | String | No | | The buildkitd inline config to use. Passed to [docker/setup-buildx-action](https://github.com/docker/setup-buildx-action?tab=readme-ov-file#inputs). | +| `cache-from` | String | No | `type=gha` | Where cache should be fetched from. Passed to [docker/build-push-action](https://github.com/docker/build-push-action?tab=readme-ov-file#inputs). [More about GHA and container caching](https://www.kenmuse.com/blog/implementing-docker-layer-caching-in-github-actions/) | +| `cache-to` | String | No | `type=gha,mode=max` | Where cache should be stored to. Passed to [docker/build-push-action](https://github.com/docker/build-push-action?tab=readme-ov-file#inputs). [More about GHA and container caching](https://www.kenmuse.com/blog/implementing-docker-layer-caching-in-github-actions/) | +| `context` | String | No | `.` | Path to the Docker build context. Passed to [docker/build-push-action](https://github.com/docker/build-push-action?tab=readme-ov-file#inputs). | +| `docker-buildx-driver` | String | No | `docker-container` | The driver to use for Docker Buildx. Passed to [docker/setup-buildx-action](https://github.com/docker/setup-buildx-action?tab=readme-ov-file#inputs). | +| `dockerhub-registry` | String | No | `docker.io` | DockerHub Registry to store docker images in. | +| `dockerhub-repository` | String | No | `${{ github.repository }}` | DockerHub Repository to store docker images in. Default: github.repository | +| `file` | String | No | | The dockerfile to use. Passed to [docker/build-push-action](https://github.com/docker/build-push-action?tab=readme-ov-file#inputs). | +| `gar-delete-credentials-file` | Boolean | No | `true` | Delete the Google credentials file after the action is finished. If you want to keep the credentials file for a later step, set this to false. | +| `gar-environment` | String | No | `dev` | Environment for pushing artifacts (can be either dev or prod). This sets the GAR Project (gar-project) to either `grafanalabs-dev` or `grafanalabs-global`. | +| `gar-image` | String | No | | Name of the image to build. Default: `${GitHub Repo Name}`. | +| `gar-registry` | String | No | `us-docker.pkg.dev` | Google Artifact Registry to store docker images in. | +| `gar-repository` | String | No | | Override the 'repo_name' used to construct the GAR repository name. Only necessary when the GAR includes a repo name that doesn't match the GitHub repo name. Default: `docker-${GitHub Repo Name}-${gar-environment}` | +| `include-tags-in-push` | Boolean | No | `true` | Disables the pushing of tags, and instead includes just a list of images as docker tags. Used when pushing docker digests instead of docker tags. | +| `labels` | String | No | | List of custom labels to add to the image as metadata (Passed to [docker/build-push-action](https://github.com/docker/build-push-action?tab=readme-ov-file#inputs)). Passed to [docker/build-push-action](https://github.com/docker/build-push-action?tab=readme-ov-file#inputs). | +| `load` | Boolean | No | `false` | Whether to load the built image into the local docker daemon (Passed to [docker/build-push-action](https://github.com/docker/build-push-action?tab=readme-ov-file#inputs)). Passed to [docker/build-push-action](https://github.com/docker/build-push-action?tab=readme-ov-file#inputs). | +| `outputs` | String | No | | List of docker output destinations. Passed to [docker/build-push-action](https://github.com/docker/build-push-action?tab=readme-ov-file#inputs). | +| `platforms` | String | No | | List of platforms to build the image for. Passed to [docker/build-push-action](https://github.com/docker/build-push-action?tab=readme-ov-file#inputs). | +| `push` | String | No | | Whether to push the image to the configured registries. Defaults to false (matching Docker's official action). Set to true to push images. Passed to [docker/build-push-action](https://github.com/docker/build-push-action?tab=readme-ov-file#inputs). | +| `registries` | String | No | | CSV list of registries to build images for. Accepted registries are "gar" and "dockerhub". | +| `secrets` | String | No | | Secrets to expose to the build. Only needed when authenticating to private repositories outside the repository in which the image is being built. Passed to [docker/build-push-action](https://github.com/docker/build-push-action?tab=readme-ov-file#inputs). | +| `ssh` | String | No | | List of SSH agent socket or keys to expose to the build Passed to [docker/build-push-action](https://github.com/docker/build-push-action?tab=readme-ov-file#inputs). | +| `tags` | String | Yes | | List of Docker tags to be pushed. Passed to [docker/build-push-action](https://github.com/docker/build-push-action?tab=readme-ov-file#inputs). | +| `target` | String | No | | Sets the target stage to build. Passed to [docker/build-push-action](https://github.com/docker/build-push-action?tab=readme-ov-file#inputs). | + + ## Outputs -| Name | Type | Description | -| -------------- | ------ | ------------------------------------------------------------ | -| `annotations` | String | Generated annotations (from docker/metadata-action) | -| `digest` | String | Image digest (from docker/build-push-action) | -| `imageid` | String | Image ID (from docker/build-push-action) | -| `images` | String | Comma separated list of the images that were built | -| `json` | String | JSON output of tags and labels (from docker/metadata-action) | -| `labels` | String | Generated Docker labels (from docker/metadata-action) | -| `metadata` | String | Build result metadata (from docker/build-push-action) | -| `metadatajson` | String | Metadata JSON (from docker/metadata) | -| `tags` | String | Generated Docker tags (from docker/metadata-action) | -| `version` | String | Generated Docker image version (from docker/metadata-action) | + + +| Name | Description | +| -------------- | ------------------------------------------------------------ | +| `annotations` | Generated annotations (from docker/metadata-action) | +| `digest` | Image digest (from docker/build-push-action) | +| `imageid` | Image ID (from docker/build-push-action) | +| `images` | Comma separated list of the images that were built | +| `json` | JSON output of tags and labels (from docker/metadata-action) | +| `labels` | Generated Docker labels (from docker/metadata-action) | +| `metadata` | Build result metadata (from docker/build-push-action) | +| `metadatajson` | Metadata JSON (from docker/metadata) | +| `tags` | Generated Docker tags (from docker/metadata-action) | +| `version` | Generated Docker image version (from docker/metadata-action) | + + ## How we construct Google Artifact Registry Images diff --git a/actions/docker-export-digest/README.md b/actions/docker-export-digest/README.md index dbee0ff7fd..553365b439 100644 --- a/actions/docker-export-digest/README.md +++ b/actions/docker-export-digest/README.md @@ -37,7 +37,11 @@ jobs: ## Inputs -| Name | Type | Description | -| ---------- | ------ | ---------------------------------------------------------------------------------------------------------- | -| `digest` | String | Docker digest. This is included as an output for `docker-build-push-image` and `docker/build-push-action`. | -| `platform` | String | Docker platform, ex: linux/arm64. | + + +| Name | Type | Required | Default | Description | +| ---------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------- | +| `digest` | String | Yes | | Docker digest. This is included as an output for `docker-build-push-image` and `docker/build-push-action`. | +| `platform` | String | Yes | | Docker platform, ex: linux/arm64. | + + diff --git a/actions/docker-import-digests-push-manifest/README.md b/actions/docker-import-digests-push-manifest/README.md index 2c2c16dbc9..fbe7af1b58 100644 --- a/actions/docker-import-digests-push-manifest/README.md +++ b/actions/docker-import-digests-push-manifest/README.md @@ -42,19 +42,28 @@ jobs: ## Inputs -| Name | Type | Default | Description | -| ------------------ | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `gar-environment` | String | `dev` | Environment for pushing artifacts (can be either dev or prod). This sets the GAR Project to either `grafanalabs-dev` or `grafanalabs-global`. | -| `generate-summary` | Boolean | `false` | Generates a markdown job summary and sets the `OCI_MANIFEST_OUTPUT_JSON` env var with structured manifest data. Only runs when `push` is also `true`. | -| `images` | String | | CSV of Docker images to push. These images should not include tags. Ex: us-docker.pkg.dev/grafanalabs-dev/gar-registry/image-name,docker.io/grafana/dockerhub-image | -| `push` | Boolean | `false` | Whether to push the manifest to the configured registries. | -| `tags` | String | | List of Docker tags to be pushed. | + + +| Name | Type | Required | Default | Description | +| ------------------ | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `gar-environment` | String | No | `dev` | Environment for pushing artifacts (can be either dev or prod). This sets the GAR Project to either `grafanalabs-dev` or `grafanalabs-global`. | +| `generate-summary` | Boolean | No | `false` | Generates both a markdown summary and outputs the env variable OCI_MANIFEST_OUTPUT_JSON. Only runs when `push` is also `true`. | +| `images` | String | Yes | | CSV of Docker images to push. These images should not include tags. Ex: us-docker.pkg.dev/grafanalabs-dev/gar-registry/image-name,docker.io/grafana/dockerhub-image | +| `push` | Boolean | No | `false` | Whether to push the manifest to the configured registries. | +| `tags` | String | Yes | | List of Docker tags to be pushed. | + + ## Outputs -| Name | Description | -| --------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `image-digests` | Newline-separated list of `tag@digest` pairs for every pushed manifest. Empty if `push` is false or `generate-summary` is false. | + + +| Name | Description | +| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| `image-digests` | Newline-separated list of image digests in the format `:@`. Empty unless both `push` and `generate-summary` are `true`. | +| `oci-manifest-output-json` | JSON array of manifests with tag, indexDigest, and per-platform digest information. Empty unless both `push` and `generate-summary` are `true`. | + + ### `OCI_MANIFEST_OUTPUT_JSON` environment variable diff --git a/actions/docker-import-digests-push-manifest/action.yaml b/actions/docker-import-digests-push-manifest/action.yaml index dd1ed63223..09b9d60a6e 100644 --- a/actions/docker-import-digests-push-manifest/action.yaml +++ b/actions/docker-import-digests-push-manifest/action.yaml @@ -15,6 +15,7 @@ inputs: generate-summary: description: | Generates both a markdown summary and outputs the env variable OCI_MANIFEST_OUTPUT_JSON. + Only runs when `push` is also `true`. default: "false" push: description: | @@ -26,10 +27,10 @@ inputs: required: true outputs: image-digests: - description: CSV list of image digests. + description: Newline-separated list of image digests in the format `:@`. Empty unless both `push` and `generate-summary` are `true`. value: ${{ steps.summary.outputs.image-digests }} oci-manifest-output-json: - description: JSON array of manifests with tag, indexDigest, and per-platform digest information. + description: JSON array of manifests with tag, indexDigest, and per-platform digest information. Empty unless both `push` and `generate-summary` are `true`. value: ${{ steps.summary.outputs.oci-manifest-output-json }} runs: diff --git a/actions/download-branch-workflow-artifact/README.md b/actions/download-branch-workflow-artifact/README.md index 62376432f1..d3ad8e8c29 100644 --- a/actions/download-branch-workflow-artifact/README.md +++ b/actions/download-branch-workflow-artifact/README.md @@ -6,21 +6,29 @@ Uses only first-party GitHub actions (`actions/github-script` and `actions/downl ## Inputs -| Name | Type | Description | Default Value | Required | -| --------------- | -------- | ------------------------------------------- | --------------------- | -------- | -| `workflow` | `string` | Workflow filename to download artifact from | | true | -| `artifact-name` | `string` | Name of the artifact to download | | true | -| `branch` | `string` | Branch to filter workflow runs by | `main` | false | -| `path` | `string` | Directory to download the artifact to | `.` | false | -| `github-token` | `string` | GitHub token with `actions:read` permission | `${{ github.token }}` | false | + + +| Name | Type | Required | Default | Description | +| --------------- | ------ | -------- | --------------------- | ------------------------------------------------------------------ | +| `artifact-name` | String | Yes | | Name of the artifact to download | +| `branch` | String | No | `main` | Branch to filter workflow runs by | +| `github-token` | String | No | `${{ github.token }}` | GitHub token with actions:read permission | +| `path` | String | No | `.` | Directory to download the artifact to | +| `workflow` | String | Yes | | Workflow filename to download artifact from (e.g. deploy-prod.yml) | + + ## Outputs -| Name | Type | Description | -| --------------- | -------- | -------------------------------------------------------------- | -| `found` | `string` | Whether the artifact was found and downloaded (`true`/`false`) | -| `run-id` | `string` | The workflow run ID the artifact was downloaded from | -| `download-path` | `string` | Path where the artifact was downloaded | + + +| Name | Description | +| --------------- | ------------------------------------------------------------------------- | +| `download-path` | Path where the artifact was downloaded | +| `found` | Whether the artifact was found and downloaded (true/false) | +| `run-id` | The workflow run ID the artifact was downloaded from (empty if not found) | + + ## Permissions diff --git a/actions/find-pr-for-commit/README.md b/actions/find-pr-for-commit/README.md index 1d2f7bb231..093eebd3e9 100644 --- a/actions/find-pr-for-commit/README.md +++ b/actions/find-pr-for-commit/README.md @@ -8,18 +8,26 @@ action will return the most recently updated PR. ## Inputs -| Name | Type | Description | Default Value | Required | -| ----------- | ------ | ----------------------------------------------------------------------------------------------------- | -------------------------------- | -------- | -| `owner` | String | The owner of the repository | `${{ github.repository_owner }}` | No | -| `repo` | String | The repository name | `${{ github.repository }}` | No | -| `commitrev` | String | The commit SHA or revision name (like `refs/heads/main`) to find the PR for | `${{ github.sha }}` | No | -| `token` | String | The GitHub token to use for the query. Must have `contents:read` and `pull-requests:read` permissions | `${{ github.token }}` | No | + + +| Name | Type | Required | Default | Description | +| ----------- | ------ | -------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `commitrev` | String | No | `${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha \|\| github.sha }}` | The commit SHA, or revision name such as `refs/heads/main`, to find the PR for | +| `owner` | String | No | `${{ github.repository_owner }}` | The owner of the repository | +| `repo` | String | No | `${{ github.event.repository.name }}` | The repository name | +| `token` | String | No | `${{ github.token }}` | The GitHub token to use for the query. Must have `contents:read` and `pull-requests:read` permissions on the target repository. | + + ## Outputs -| Name | Type | Description | -| ----------- | ------ | ---------------------------------------- | -| `pr_number` | String | The PR number associated with the commit | + + +| Name | Description | +| ----------- | ---------------------------------------- | +| `pr_number` | The PR number associated with the commit | + + ## Usage diff --git a/actions/find-pr-for-commit/action.yaml b/actions/find-pr-for-commit/action.yaml index c1aa41502f..1f58656f77 100644 --- a/actions/find-pr-for-commit/action.yaml +++ b/actions/find-pr-for-commit/action.yaml @@ -13,7 +13,7 @@ inputs: required: false commitrev: - description: The commit SHA to find the PR for + description: The commit SHA, or revision name such as `refs/heads/main`, to find the PR for # If this is a PR, use the PR head SHA. This is because `github.sha` is the # merge commit SHA which will not have a PR associated with it. The PR head # SHA is the commit that was pushed to the PR branch. diff --git a/actions/generate-openapi-clients/README.md b/actions/generate-openapi-clients/README.md index e9e848878a..81f26fbf11 100644 --- a/actions/generate-openapi-clients/README.md +++ b/actions/generate-openapi-clients/README.md @@ -6,18 +6,22 @@ _Note: For now, it only generates Go code. But it's structured in a way that any ## Inputs -| Name | Type | Description | Default Value | Required | -| ------------------ | ------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -------- | -| generator-version | string | The version of the OpenAPI generator to use | "7.7.0" | false | -| spec-path | string | The path to the OpenAPI spec to generate the client from. Supports JSON or YAML | N/A | true | -| output-dir | string | The directory to output the generated client to | "." | false | -| commit-changes | boolean | If true, the action will commit and push the changes to the repository, if there's a diff. | true | false | -| commit-message | string | The commit message to use when committing the changes | "Update clients and publish" | false | -| commit-author | string | The author string to use for the commit | "github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>" | false | -| commit-user-name | string | The username to use for the commit | "github-actions[bot]" | false | -| commit-user-email | string | The email address to use for the commit | "41898282+github-actions[bot]@users.noreply.github.com" | false | -| package-name | string | The name of the package to generate | N/A | true | -| modify-spec-script | string | The path to an executable script that modifies the OpenAPI spec before generating the client. | "" | false | + + +| Name | Type | Required | Default | Description | +| -------------------- | ------- | -------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `commit-author` | String | No | `github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>` | Specify the author for the commit | +| `commit-changes` | Boolean | No | `true` | If true, the action will commit and push the changes to the repository, if there's a diff. | +| `commit-message` | String | No | `Update clients and publish` | The commit message to use when committing the changes | +| `commit-user-email` | String | No | `41898282+github-actions[bot]@users.noreply.github.com` | Use a different email address for the commit | +| `commit-user-name` | String | No | `github-actions[bot]` | Use a different username for the commit | +| `generator-version` | String | No | `7.7.0` | The version of the OpenAPI generator to use | +| `modify-spec-script` | String | No | | The path to an executable script that modifies the OpenAPI spec before generating the client. The spec will be piped into the script and the script should output the modified spec to stdout. Note: This is used as a workaround for the OpenAPI generator not supporting certain features. By using this feature, the spec will be modified temporarily, and the changes will not be committed. | +| `output-dir` | String | No | `.` | The directory to output the generated client to | +| `package-name` | String | Yes | | The name of the package to generate | +| `spec-path` | String | Yes | | The path to the OpenAPI spec to generate the client from. Supports JSON or YAML. | + + ## Example workflow diff --git a/actions/generate-openapi-clients/action.yaml b/actions/generate-openapi-clients/action.yaml index b6c7e668cb..a7b6214d2a 100644 --- a/actions/generate-openapi-clients/action.yaml +++ b/actions/generate-openapi-clients/action.yaml @@ -7,7 +7,7 @@ inputs: required: false default: "7.7.0" spec-path: - description: "The path to the OpenAPI spec to generate the client from" + description: "The path to the OpenAPI spec to generate the client from. Supports JSON or YAML." required: true output-dir: description: "The directory to output the generated client to" diff --git a/actions/get-latest-workflow-artifact/README.md b/actions/get-latest-workflow-artifact/README.md index a95347699c..d813272415 100644 --- a/actions/get-latest-workflow-artifact/README.md +++ b/actions/get-latest-workflow-artifact/README.md @@ -8,20 +8,32 @@ Required permissions: - `pull-requests: read` - `actions: read` -| Input | Description | Required | Default | -| --------------------- | -------------------------------------------------------------- | -------- | ----------------------------------------- | -| `workflow-id` | ID or filename of the workflow | yes | | -| `artifact-name` | Name of the artifact to download | yes | | -| `repository` | Owner/Name | no | `${{ github.repository }}` | -| `pr-number` | Number of the PR to consider | no | `${{ github.event.pull_request.number }}` | -| `path` | Directory to store the artifact in | no | `${{ github.workspace }}` | -| `github-token` | GitHub token | no | `${{ github.token }}` | -| `consider-inprogress` | Not only consider completed but also in-progress workflow runs | no | `false` | -| `consider-comments` | Also look for workflow runs triggered by comments | no | `false` | - -| Output | Description | -| ------------------------ | ------------------------------------------------------ | -| `artifact-download-path` | Path where the artifact was downloaded | -| `artifact-id` | ID of the artifact that was downloaded | -| `workflow-run-id` | ID of the Workflow Run | -| `workflow-run-status` | Status of the found run (`in_progress` or `completed`) | +## Inputs + + + +| Name | Type | Required | Default | Description | +| --------------------- | ------ | -------- | ----------------------------------------- | ---------------------------------------------------------- | +| `artifact-name` | String | Yes | | Name of a specific artifact | +| `consider-comments` | String | No | | Also look for workflow runs triggered by comments | +| `consider-inprogress` | String | No | | Allow to also return artifacts from in-progress runs | +| `github-token` | String | No | `${{ github.token }}` | GitHub token to access the workflow and artifact | +| `path` | String | No | `${{ github.workspace }}` | Destination path | +| `pr-number` | String | No | `${{ github.event.pull_request.number }}` | Pull request the workflow run is associated with | +| `repository` | String | No | `${{ github.repository }}` | Repository of the target workflow (e.g. `grafana/grafana`) | +| `workflow-id` | String | Yes | | ID of the workflow inside the current repository | + + + +## Outputs + + + +| Name | Description | +| ------------------------ | --------------------------------------------------------------------------------- | +| `artifact-download-path` | Path of the downloaded artifact | +| `artifact-id` | ID of the downloaded artifact | +| `workflow-run-id` | ID of the considered workflow run | +| `workflow-run-status` | Status of the workflow run containing the artifact (`in_progress` or `completed`) | + + diff --git a/actions/get-latest-workflow-artifact/action.yml b/actions/get-latest-workflow-artifact/action.yml index 939d28f23f..9be523c368 100644 --- a/actions/get-latest-workflow-artifact/action.yml +++ b/actions/get-latest-workflow-artifact/action.yml @@ -41,7 +41,7 @@ outputs: description: ID of the considered workflow run value: ${{ steps.get-artifact.outputs.workflow-run-id }} workflow-run-status: - description: Status of the workflow run containing the artifact + description: Status of the workflow run containing the artifact (`in_progress` or `completed`) value: ${{ steps.get-artifact.outputs.workflow-run-status }} runs: diff --git a/actions/get-vault-secrets/README.md b/actions/get-vault-secrets/README.md index 6b1ba98a0a..f6b9ddad05 100644 --- a/actions/get-vault-secrets/README.md +++ b/actions/get-vault-secrets/README.md @@ -50,3 +50,26 @@ jobs: ``` + +## Inputs + + + +| Name | Type | Required | Default | Description | +| ---------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `common_secrets` | String | No | | Common secrets mapping. Only Grafana Labs employees can list these secrets in Vault. These secrets are stored in the `ci/data/common/` path in Vault. Ex: `repo_secrets: \| ENVVAR1=secretpath:key ENVVAR2=secretpath:key2` | +| `ignore_missing` | Boolean | No | `false` | When set to true, prevents the action from failing when a secret does not exist. | +| `repo_secrets` | String | No | | Repository-specific secret mapping. Only Grafana Labs employees can list these secrets in Vault. These secrets are stored in the `ci/data/repo/grafana//` path in Vault. Ex: `repo_secrets: \| ENVVAR1=secretpath:key ENVVAR2=secretpath:key2` | +| `vault_instance` | String | No | `ops` | The Vault instance to use (`dev` or `ops`). Defaults to `ops`. | + + + +## Outputs + + + +| Name | Description | +| --------- | -------------------------------------- | +| `secrets` | JSON object containing all the secrets | + + diff --git a/actions/go-flaky-tests/README.md b/actions/go-flaky-tests/README.md index b2c90e72ae..a60e76cfd7 100644 --- a/actions/go-flaky-tests/README.md +++ b/actions/go-flaky-tests/README.md @@ -43,25 +43,30 @@ jobs: ## Inputs -| Input | Description | Required | Default | -| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------- | -| `loki-url` | Loki endpoint URL | ✅ | - | -| `loki-username` | Username for Loki authentication | ❌ | - | -| `loki-password` | Password for Loki authentication. If using Grafana Cloud, then the access policy for this token needs the `logs:read` scope. | ❌ | - | -| `repository` | Repository name in 'owner/repo' format | ✅ | - | -| `time-range` | Time range for the query (e.g., '1h', '24h', '7d') | ❌ | `1h` | -| `repository-directory` | Relative path to the directory with a git repository | ❌ | `${{ github.workspace }}` | -| `github-token` | GitHub token for repository access | ❌ | `${{ github.token }}` | -| `skip-posting-issues` | Skip creating/updating GitHub issues (dry-run mode) | ❌ | `true` | -| `top-k` | Include only the top K flaky tests by distinct branches count | ❌ | `3` | + + +| Name | Type | Required | Default | Description | +| ---------------------- | ------- | -------- | ------------------------- | ------------------------------------------------------------------------- | +| `github-token` | String | No | `${{ github.token }}` | GitHub token for repository access | +| `ignored-tests` | String | No | | Comma-delimited test names to skip failures for | +| `loki-password` | String | No | | Password for Loki authentication | +| `loki-url` | String | Yes | | Loki endpoint URL | +| `loki-username` | String | No | | Username for Loki authentication | +| `repository` | String | Yes | | Repository name in 'owner/repo' format (e.g., 'grafana/grafana') | +| `repository-directory` | String | No | `${{ github.workspace }}` | Relative path to the directory with a git repository | +| `skip-posting-issues` | Boolean | No | `true` | Skip creating/updating GitHub issues (dry-run mode) | +| `time-range` | String | No | `1h` | Time range for the query (e.g., '1h', '24h', '7d') | +| `top-k` | String | No | `3` | Include only the top K flaky tests by distinct branches count in analysis | + + ## Outputs -| Output | Description | -| ------------------ | ----------------------------------------------- | -| `test-count` | Number of flaky tests found | -| `analysis-summary` | Summary of the analysis results | -| `report-path` | Path to the generated analysis report JSON file | + + +_None._ + + ## How It Works diff --git a/actions/issues-update-project-status/README.md b/actions/issues-update-project-status/README.md index ca670b79a1..45e24863a1 100644 --- a/actions/issues-update-project-status/README.md +++ b/actions/issues-update-project-status/README.md @@ -6,13 +6,17 @@ The calling job must have `id-token: write` permission for Vault authentication. ## Inputs -| Name | Type | Description | Default | Required | -| ------------------------- | ------ | ------------------------------------------------------------------------------------------------------------ | --------- | -------- | -| `github-app` | String | The required GitHub app name | | Yes | -| `permission-set` | String | The optional permission set name. Defaults to `default` | `default` | Yes | -| `project-id` | String | Node ID of the GitHub Project (v2). Retrieve with: `gh project view --owner --format json` | | Yes | -| `status-field-id` | String | Node ID of the Status field. Retrieve with: `gh project field-list --owner --format json` | | Yes | -| `target-status-option-id` | String | ID of the status option to set. Retrieve with: `gh project field-list --owner --format json` | | Yes | + + +| Name | Type | Required | Default | Description | +| ------------------------- | ------ | -------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `github-app` | String | Yes | | GitHub app name in Vault. | +| `permission-set` | String | No | `default` | Permission set name | +| `project-id` | String | Yes | | The node ID of the GitHub Project (v2) board. Retrieve with: gh project view <number> --owner <org> --format json | +| `status-field-id` | String | Yes | | The node ID of the Status field on the project board. Retrieve with: gh project field-list <number> --owner <org> --format json | +| `target-status-option-id` | String | Yes | | The ID of the status option to set on the project item (e.g. the "In Progress" option ID). Retrieve with: gh project field-list <number> --owner <org> --format json | + + ## Filtering by label diff --git a/actions/lint-pr-title/README.md b/actions/lint-pr-title/README.md index 570b0d09e7..b90609f876 100644 --- a/actions/lint-pr-title/README.md +++ b/actions/lint-pr-title/README.md @@ -26,10 +26,14 @@ so these are the commits that need to be validated. ## Inputs -| Name | Description | Default | Required | -| ------------- | ------------------------------------------------------------------------------------ | ------------------------ | -------- | -| `config-path` | Path to the commitlint configuration file, relative to the action's directory. | `./commitlint.config.js` | No | -| `title-only` | Check only the PR/commit title. If false, it will check the whole PR/commit message. | `true` | No | + + +| Name | Type | Required | Default | Description | +| ------------- | ------- | -------- | ------------------------ | ------------------------------------------------------------------------------------ | +| `config-path` | String | No | `./commitlint.config.js` | Path to the commitlint configuration file, relative to the action's directory. | +| `title-only` | Boolean | No | `true` | Check only the PR/commit title. If false, it will check the whole PR/commit message. | + + ## Validation diff --git a/actions/login-to-gar/README.md b/actions/login-to-gar/README.md index 25b3bdc356..49ef32a6d3 100644 --- a/actions/login-to-gar/README.md +++ b/actions/login-to-gar/README.md @@ -37,12 +37,14 @@ jobs: ## Inputs -| Name | Description | Default | -| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------- | -| `registry` | Google Artifact Registry to authenticate against. | `us-docker.pkg.dev` | -| `workspace_credentials` | Whether to place the GCP credentials file in the workspace. Off by default. See [Docker Actions Compatibility] for more. | `false` | + -[Docker Actions Compatibility]: #docker-actions-compatibility +| Name | Type | Required | Default | Description | +| ----------------------- | ------- | -------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `registry` | String | No | `us-docker.pkg.dev` | Google Artifact Registry to authenticate against. | +| `workspace_credentials` | Boolean | No | `false` | Keep credentials file in workspace for Docker action compatibility. When false (default), credentials are moved to a temporary location so they aren't in the working directory where they can be accidentally committed or printed. Set to true if you need to use Docker-based GitHub Actions that require workspace access in a later step. | + + ## Docker Actions Compatibility diff --git a/actions/login-to-gcs/README.md b/actions/login-to-gcs/README.md index fa2f331a50..dc6ba41e36 100644 --- a/actions/login-to-gcs/README.md +++ b/actions/login-to-gcs/README.md @@ -38,15 +38,24 @@ $ gcloud storage cp OBJECT_LOCATION gs://DESTINATION_BUCKET_NAME ## Inputs -| Name | Type | Description | -| ----------------- | ------- | ----------------------------------------------------------------------------------------------------------------- | -| `bucket` | String | Name of bucket to upload to. Will default to grafanalabs-${repository.name}-${environment} | -| `environment` | String | Environment for pushing artifacts (can be either dev or prod). | -| `service_account` | String | Service account to use for authentication. Use it only when the service account is different than the default one | -| `use_wif_auth` | Boolean | Use WIF authentication. Overrides the `service_account` input. | + + +| Name | Type | Required | Default | Description | +| ------------------------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| `bucket` | String | No | | Name of bucket to upload to. Will default to grafanalabs-${repository.name}-${environment} | +| `delete_credentials_file` | Boolean | No | `false` | Delete the credentials file after the action is finished. If you want to keep the credentials file for a later step, set this to false. | +| `environment` | String | No | `dev` | Environment for uploading objects (can be either dev or prod). | +| `service_account` | String | No | | Custom service account to use for authentication. | +| `use_wif_auth` | Boolean | No | `false` | Use WIF for authentication instead of service account. | + + ## Outputs -| Name | Type | Description | -| -------- | ------ | --------------------------------------------- | -| `bucket` | String | Name of the bucket that was authenticated to. | + + +| Name | Description | +| -------- | ----------------------------------------------------- | +| `bucket` | The name of the bucket that we have authenticated to. | + + diff --git a/actions/push-to-gcs/README.md b/actions/push-to-gcs/README.md index 5ff7efb907..93c27352f3 100644 --- a/actions/push-to-gcs/README.md +++ b/actions/push-to-gcs/README.md @@ -115,26 +115,33 @@ jobs: ## Inputs -| Name | Type | Description | -| ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `bucket` | String | (Required) Name of bucket to upload to. Can be gathered from `login-to-gcs` action. | -| `path` | String | (Required) The path to a file or folder inside the action's filesystem that should be uploaded to the bucket. You can specify either the absolute path or the relative path from the action. | -| `bucket_path` | String | Bucket path where objects will be uploaded. Default is the bucket root. | -| `environment` | String | Environment for pushing artifacts (can be either dev or prod). | -| `service_account` | String | Service account to use for authentication, different than the default one. Used only when bucket input is not empty (i.e. when the bucket is not the default one). | -| `glob` | String | Glob pattern. | -| `parent` | String | Whether parent dir should be included in GCS destination. Dirs included in the `glob` statement are unaffected by this setting. | -| `predefinedAcl` | String | Predefined ACL applied to the uploaded objects. Default is `projectPrivate`. See [Google Documentation][gcs-docs-upload-options] for a list of available options. | -| `delete_credentials_file` | Boolean | Delete the credentials file after the action is finished. If you want to keep the credentials file for a later step, set this to false. (Default: `true`) | -| `use_wif_auth` | Boolean | Use WIF authentication. Overrides the `service_account` input. | + + +| Name | Type | Required | Default | Description | +| ------------------------- | ------- | -------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `bucket` | String | No | | Name of bucket to upload to. Can be gathered from the `login-to-gcs` action. Will default to grafanalabs-${repository.name}-${environment} | +| `bucket_path` | String | No | | Bucket path where objects will be uploaded. Default is the bucket root. | +| `delete_credentials_file` | Boolean | No | `true` | Delete the credentials file after the action is finished. If you want to keep the credentials file for a later step, set this to false. | +| `environment` | String | No | `dev` | Environment for uploading objects (can be either dev or prod). | +| `glob` | String | No | | Glob pattern. | +| `gzip` | Boolean | No | `true` | If true, then upload files with `content-encoding: gzip` | +| `parent` | Boolean | No | `true` | Whether parent dir should be included in GCS destination. Dirs included in the `glob` statement are unaffected by this setting. | +| `path` | String | Yes | | The path to a file or folder inside the action's filesystem that should be uploaded to the bucket. You can specify either the absolute path or the relative path from the action. | +| `predefinedAcl` | String | No | `projectPrivate` | Apply a predefined set of access controls to the file(s). Default is projectPrivate (See https://googleapis.dev/nodejs/storage/latest/global.html#UploadOptions) | +| `service_account` | String | No | | Custom service account to use for authentication. | +| `use_wif_auth` | Boolean | No | `false` | Use WIF for authentication instead of service account. | + + > [!TIP] > To use WIF authentication you must enable `uniform_bucket_level_access` on the destination bucket. If you are at Grafana Labs, instructions can be found [here](https://enghub.grafana-ops.net/docs/default/component/deployment-tools/platform/continuous-integration/google-artifact-registry/). More info can be found in [Google's docs](https://cloud.google.com/storage/docs/uniform-bucket-level-access). ## Outputs -| Name | Type | Description | -| ---------- | ------ | -------------------------------------------------- | -| `uploaded` | String | The list of files that were successfully uploaded. | + -[gcs-docs-upload-options]: https://googleapis.dev/nodejs/storage/latest/global.html#UploadOptions +| Name | Description | +| ---------- | ---------------------------------------- | +| `uploaded` | The list of successfully uploaded files. | + + diff --git a/actions/push-to-gcs/action.yaml b/actions/push-to-gcs/action.yaml index ac25f30809..19b95e5ce6 100644 --- a/actions/push-to-gcs/action.yaml +++ b/actions/push-to-gcs/action.yaml @@ -3,7 +3,8 @@ description: Composite action to push to Google Cloud Storage inputs: bucket: description: | - Name of bucket to upload to. Will default to grafanalabs-${repository.name}-${environment} + Name of bucket to upload to. Can be gathered from the `login-to-gcs` action. + Will default to grafanalabs-${repository.name}-${environment} default: "" path: description: | diff --git a/actions/remove-checkout-credentials/README.md b/actions/remove-checkout-credentials/README.md index 94e189d0c9..b2c27efffc 100644 --- a/actions/remove-checkout-credentials/README.md +++ b/actions/remove-checkout-credentials/README.md @@ -29,3 +29,13 @@ jobs: # Actions that do not need the credentials anymore # ... ``` + +## Inputs + + + +| Name | Type | Required | Default | Description | +| ------ | ------ | -------- | ------- | -------------------- | +| `path` | String | No | | Path of the checkout | + + diff --git a/actions/run-capslock/README.md b/actions/run-capslock/README.md index 42b9eff3bf..7e408232b9 100644 --- a/actions/run-capslock/README.md +++ b/actions/run-capslock/README.md @@ -19,13 +19,17 @@ jobs: ## Inputs -| Name | Description | Default | -| ------------------ | ------------------------------------------------------ | ---------- | -| `go-version` | Go version to use | 1.24.6 | -| `capslock-version` | Capslock version to use | v0.2.8 | -| `scope` | Path to run | | -| `main-branch` | Main branch name | main | -| `output-place` | Output place (options: pr-comment\*, summary and log ) | pr-comment | + + +| Name | Type | Required | Default | Description | +| ------------------ | ------ | -------- | ------------ | ------------------------------------------------------------------- | +| `capslock-version` | String | Yes | `v0.2.8` | Capslock version used | +| `go-version` | String | Yes | `1.24.6` | Go version used | +| `main-branch` | String | Yes | `main` | Name of the main branch | +| `output-place` | String | Yes | `pr-comment` | Where to write the report. One of `pr-comment`, `summary` or `log`. | +| `scope` | String | Yes | | The scope of analysis | + + \* For pr-comment the permission pull-request: write it's needed diff --git a/actions/run-capslock/action.yaml b/actions/run-capslock/action.yaml index 17d4185b84..89d29e1193 100644 --- a/actions/run-capslock/action.yaml +++ b/actions/run-capslock/action.yaml @@ -21,7 +21,7 @@ inputs: output-place: default: "pr-comment" required: true - description: "Output place" + description: "Where to write the report. One of `pr-comment`, `summary` or `log`." runs: using: composite steps: diff --git a/actions/send-slack-message/README.md b/actions/send-slack-message/README.md index 63912e3f02..2755f56d61 100644 --- a/actions/send-slack-message/README.md +++ b/actions/send-slack-message/README.md @@ -96,17 +96,25 @@ jobs: ## Inputs -| Name | Type | Description | -| ------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| `payload` | String | JSON payload to send. | -| `method` | String | The Slack API method to call. | -| `payload-templated` | String | To replace templated variables provided from the step env or default GitHub event context and payload, set the payload-templated variable to true. | + + +| Name | Type | Required | Default | Description | +| ------------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| `method` | String | Yes | | The Slack API method to call | +| `payload` | String | No | | JSON payload to send | +| `payload-templated` | Boolean | No | `false` | To replace templated variables provided from the step env or default GitHub event context and payload, set the payload-templated variable to true | + + ## Outputs -| Name | Type | Description | -| ------------ | ------ | -------------------------------------------------- | -| `time` | String | The time the message was sent. | -| `thread_ts` | String | Threaded timestamp on the message that was posted. | -| `ts` | String | Timestamp on the message that was posted | -| `channel_id` | String | The ID of the Slack channel that was posted to. | + + +| Name | Description | +| ------------ | -------------------------------------------------------- | +| `channel_id` | The channel id of the message that was posted into Slack | +| `thread_ts` | The timestamp on the latest thread posted into Slack | +| `time` | The time that the Slack message was sent | +| `ts` | The timestamp on the message that was posted into Slack | + + diff --git a/actions/setup-argo/README.md b/actions/setup-argo/README.md index d84232b4d8..de597dd988 100644 --- a/actions/setup-argo/README.md +++ b/actions/setup-argo/README.md @@ -13,3 +13,24 @@ with: ``` + +## Inputs + + + +| Name | Type | Required | Default | Description | +| -------------- | ------ | -------- | ------- | ----------------------------------- | +| `cache-prefix` | String | No | `argo` | Prefix for the cache key. | +| `version` | String | No | `4.0.3` | Version of the Argo CLI to install. | + + + +## Outputs + + + +| Name | Description | +| ----------- | --------------------------------- | +| `cache-hit` | Whether the cache was hit or not. | + + diff --git a/actions/setup-conftest/README.md b/actions/setup-conftest/README.md index 9622e2312a..0c9aaec1f9 100644 --- a/actions/setup-conftest/README.md +++ b/actions/setup-conftest/README.md @@ -13,3 +13,13 @@ with: ``` + +## Inputs + + + +| Name | Type | Required | Default | Description | +| --------- | ------ | -------- | -------- | ------------------------------- | +| `version` | String | No | `0.55.0` | Version of conftest to install. | + + diff --git a/actions/setup-jrsonnet/README.md b/actions/setup-jrsonnet/README.md index d1936d2b64..c64afb14fd 100644 --- a/actions/setup-jrsonnet/README.md +++ b/actions/setup-jrsonnet/README.md @@ -13,3 +13,24 @@ with: ``` + +## Inputs + + + +| Name | Type | Required | Default | Description | +| -------------- | ------ | -------- | ------------------ | --------------------------------------- | +| `cache-prefix` | String | No | `jrsonnet` | Prefix for the cache key. | +| `version` | String | No | `0.5.0-pre96-test` | Version of the jrsonnet CLI to install. | + + + +## Outputs + + + +| Name | Description | +| ----------- | --------------------------------- | +| `cache-hit` | Whether the cache was hit or not. | + + diff --git a/actions/signed-commits-info/README.md b/actions/signed-commits-info/README.md index 08cb996edb..c188cc2bd4 100644 --- a/actions/signed-commits-info/README.md +++ b/actions/signed-commits-info/README.md @@ -36,6 +36,16 @@ jobs: +## Inputs + + + +| Name | Type | Required | Default | Description | +| -------------- | ------ | -------- | --------------------- | --------------------------------- | +| `github-token` | String | No | `${{ github.token }}` | Token used to call the GitHub API | + + + ## Development This project uses the [bun](https://bun.sh) toolchain. diff --git a/actions/socket-export-sbom/README.md b/actions/socket-export-sbom/README.md index 483c194afb..fdd3decf2e 100644 --- a/actions/socket-export-sbom/README.md +++ b/actions/socket-export-sbom/README.md @@ -8,14 +8,28 @@ A good use case is including this sbom as part of a public repo's release artifa ## Inputs -| Name | Type | Description | Default Value | Required | -| ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ | -------- | -| `socket_api_token` | `string` | API Key used to authenticate to socket.dev, requires the `full-scans:create` (for `socket scan create`) and `report:read` (for the SPDX export) scopes | `none` | true | -| `socket_base_url` | `string` | Base URL of the socket api endpoint. Must end in a trailing slash: the Socket CLI appends endpoint paths to it without adding a separator. | `"https://api.socket.dev/v0/"` | false | -| `socket_org` | `string` | Name of the socket org. | `"grafana"` | true | -| `branch` | `string` | Branch to scan and export the SBOM for. The caller must have already checked out this branch's source tree before invoking this action, since the Socket CLI scans the local manifest files rather than reading a pre-existing scan. | `none` | true | -| `output_file` | `string` | Name of the file to save the socket sbom on the runner. Defaults to `-.spdx.json`, e.g. `grafana-v1.2.3.spdx.json`. | `none` | false | -| `export_timeout_seconds` | `string` | Max seconds to wait, with backoff, for the SBOM export to become available after scan creation. The full scan report is generated lazily by Socket, so raise this for repos larger than grafana/grafana. | `"180"` | false | + + +| Name | Type | Required | Default | Description | +| ------------------------ | ------ | -------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `branch` | String | Yes | | Branch to scan and export the SBOM for. The caller must have already checked out this branch before invoking this action. | +| `export_timeout_seconds` | String | No | `180` | Max seconds to wait for the SBOM export to become available after scan creation. The full scan report is generated lazily, so the export endpoint may 404 for a while after `socket scan create` returns. 180s comfortably covers grafana/grafana (our largest repo), which took up to 85s in testing. | +| `output_file` | String | No | | Name of the file to save the sbom. Defaults to '<repo>-<branch>.spdx.json' if not set. | +| `socket_api_token` | String | Yes | | Socket API token for authentication. Requires the `full-scans:create` and `report:read` scopes. | +| `socket_base_url` | String | No | `https://api.socket.dev/v0/` | Socket base url. Must end in a trailing slash: the Socket CLI appends endpoint paths to it without adding a separator, so a base of `https://api.socket.dev/v0` requests `/v0report/supported` and 404s. | +| `socket_org` | String | Yes | `grafana` | Socket org name | + + + +## Outputs + + + +| Name | Description | +| ------ | ------------------------------ | +| `path` | Path to the exported sbom file | + + ## Export behaviour diff --git a/actions/socket-export-sbom/action.yml b/actions/socket-export-sbom/action.yml index b81391614c..212b15b317 100644 --- a/actions/socket-export-sbom/action.yml +++ b/actions/socket-export-sbom/action.yml @@ -3,7 +3,7 @@ description: Export SPDX SBOM from Socket.dev API for a given repository. inputs: socket_api_token: - description: "Socket API token for authentication" + description: "Socket API token for authentication. Requires the `full-scans:create` and `report:read` scopes." required: true socket_base_url: description: "Socket base url. Must end in a trailing slash: the Socket CLI appends endpoint paths to it without adding a separator, so a base of `https://api.socket.dev/v0` requests `/v0report/supported` and 404s." diff --git a/actions/techdocs-rewrite-relative-links/README.md b/actions/techdocs-rewrite-relative-links/README.md index bb5542dccc..b0031c2cdd 100644 --- a/actions/techdocs-rewrite-relative-links/README.md +++ b/actions/techdocs-rewrite-relative-links/README.md @@ -54,13 +54,17 @@ Follow that up with the actions that should publish the docs to EngHub. See [the ## Inputs -| Name | Type | Description | -| ------------------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------- | -| `default-branch` (required) | string | Default branch name of the repository | -| `repo-url` (required) | string | Full URL to the GitHub repository | -| `working-directory` (required) | string | Directory containing the `mkdocs.yml` file | -| `dry-run` | boolean | Do not modify the files but print a diff | -| `checkout-action-repository-path` (default: `_action`) | string | Folder where the repository should be checked out to for running the action or where a checkout already exists | -| `checkout-action-repository` (default: `true`) | boolean | If the workflow already checks out the shared-workflows repository, you can set this to false | -| `verbose` (default `false`) | boolean | Log on info level | -| `debug` (default `false`) | boolean | Log on debug level | + + +| Name | Type | Required | Default | Description | +| --------------------------------- | ------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| `checkout-action-repository` | Boolean | No | `true` | By default this action checks out its own code. If you want to skip this, set to false. | +| `checkout-action-repository-path` | String | No | `_action` | Path where the action checks out its own code. If you disable the checkout, make sure to set this to where a previous checkout has been made to. | +| `debug` | Boolean | No | `false` | Log output on debug level | +| `default-branch` | String | Yes | | Default branch name of the repository | +| `dry-run` | Boolean | No | `false` | Execute link rewriting without updating the underlying files | +| `repo-url` | String | Yes | | Full URL to the GitHub repository | +| `verbose` | Boolean | No | `false` | Log output on info level | +| `working-directory` | String | Yes | | Directory containing the `mkdocs.yml` file | + + diff --git a/actions/trigger-argo-workflow/README.md b/actions/trigger-argo-workflow/README.md index e0b8de2eb4..a2cd9b5bda 100644 --- a/actions/trigger-argo-workflow/README.md +++ b/actions/trigger-argo-workflow/README.md @@ -18,9 +18,21 @@ to fork and modify to run on your own instances. See [#21][issue-21]. ## Inputs -- `instance`: The instance to use (`dev` or `ops`). Defaults to `ops`. -- `namespace`: Required. The namespace to trigger the workflow in. -- `parameters`: The newline-separated parameters to pass to the Argo workflow. Example: + + +| Name | Type | Required | Default | Description | +| ------------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------ | +| `extra_args` | String | No | | Extra arguments to pass to the Argo CLI. Ex: `--generate-name foo-` | +| `instance` | String | No | `ops` | The instance to use (`dev` or `ops`). Defaults to `ops`. | +| `log_level` | String | No | `info` | The log level to use. Choose from `debug`, `info`, `warn` or `error`. Defaults to `info`. | +| `namespace` | String | Yes | | Required. The namespace to trigger the workflow in. | +| `output_summary` | Boolean | No | `false` | If `true`, write the triggered workflow URL to the GitHub job summary. Defaults to `false`. | +| `parameters` | String | No | | The newline-separated parameters to pass to the Argo workflow. Ex: `param1=value1 param2=value2` | +| `workflow_template` | String | Yes | | Name of the Argo workflow template to submit. | + + + +`parameters` takes one `key=value` pair per line: ```yaml parameters: | @@ -28,13 +40,15 @@ parameters: | param2=value2 ``` -- `workflow_template`: The workflow template to use. Required if `command` is `submit` (the default). -- `extra_args`: Extra arguments to pass to the Argo CLI. Example: `--generate-name foo-` -- `log_level`: The log level to use. Choose from `debug`, `info`, `warn` or `error`. Defaults to `info`. - ## Outputs -- `uri`: The URI of the workflow that was created. + + +| Name | Description | +| ----- | ------------------------------------------- | +| `uri` | The URI of the workflow that was triggered. | + + ## Required permissions diff --git a/actions/trigger-argo-workflow/action.yaml b/actions/trigger-argo-workflow/action.yaml index 0801eb7e17..6ea35f4fb4 100644 --- a/actions/trigger-argo-workflow/action.yaml +++ b/actions/trigger-argo-workflow/action.yaml @@ -20,11 +20,11 @@ inputs: ``` workflow_template: description: | - The workflow template to use. Defaults to `grafana-ci`. + Name of the Argo workflow template to submit. required: true extra_args: description: | - Extra arguments to pass to the Argo CLI. Ex: `--generate-name foo-" + Extra arguments to pass to the Argo CLI. Ex: `--generate-name foo-` log_level: description: | The log level to use. Choose from `debug`, `info`, `warn` or `error`. Defaults to `info`. diff --git a/actions/validate-policy-bot-config/README.md b/actions/validate-policy-bot-config/README.md index 4f7df7ce1f..a92a6de43b 100644 --- a/actions/validate-policy-bot-config/README.md +++ b/actions/validate-policy-bot-config/README.md @@ -6,7 +6,13 @@ See [Policy Bot's documentation](https://github.com/palantir/policy-bot?tab=read ## Inputs -- `validation_endpoint`: The endpoint to validate the configuration against. Defaults to `https://policy-bot.grafana.net/api/v1/validate`. + + +| Name | Type | Required | Default | Description | +| --------------------- | ------ | -------- | -------------------------------------------------------- | ------------------------ | +| `validation_endpoint` | String | No | `https://github-policy-bot.grafana-ops.net/api/validate` | Validation API endpoint. | + + Example workflow: diff --git a/actions/validate-renovate-config/README.md b/actions/validate-renovate-config/README.md index 66afa013d1..fd3ecc6569 100644 --- a/actions/validate-renovate-config/README.md +++ b/actions/validate-renovate-config/README.md @@ -4,7 +4,13 @@ Validates Renovate configuration files using [renovate-config-validator](https:/ ## Inputs -- `path`: Path to the Renovate config file to validate. Defaults to `renovate.json`. + + +| Name | Type | Required | Default | Description | +| ------ | ------ | -------- | --------------- | -------------------------------------------------------------------- | +| `path` | String | No | `renovate.json` | Path to the Renovate config file to validate (e.g., 'renovate.json') | + + ## Example workflow diff --git a/actions/validate-zizmor-config/README.md b/actions/validate-zizmor-config/README.md index dbc6354af2..ea159a9102 100644 --- a/actions/validate-zizmor-config/README.md +++ b/actions/validate-zizmor-config/README.md @@ -6,8 +6,14 @@ Intended to be called from [`.github/workflows/reusable-zizmor.yml`](../../.gith ## Inputs -- `config_path`: Path to the zizmor config file relative to the workspace (e.g. `zizmor.yml`). Required. -- `sarif_output`: Optional path for a SARIF report written when validation fails (used by reusable-zizmor so Grafana Bench and Loki ingestion still receive results). + + +| Name | Type | Required | Default | Description | +| -------------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| `config_path` | String | Yes | | Path to the zizmor config file relative to the workspace (e.g. zizmor.yml). | +| `sarif_output` | String | No | | Optional path for a SARIF report written when validation fails (used by reusable-zizmor so Grafana Bench and Loki ingestion still receive results). | + + ## Requirements diff --git a/actions/wait-for-docker-publish/README.md b/actions/wait-for-docker-publish/README.md index d73c1ed259..371df109aa 100644 --- a/actions/wait-for-docker-publish/README.md +++ b/actions/wait-for-docker-publish/README.md @@ -9,16 +9,26 @@ loop, so the action works against any OCI-conformant registry. ## Inputs -| Name | Required | Default | Description | -| ------------------ | -------- | ------- | ---------------------------------------------------------------------------------- | -| `image` | yes | — | OCI image reference. **Must include a `:tag` or an `@sha256:…` digest** (or both). | -| `timeout` | no | `10m` | Total wall-clock budget. Accepts `s`/`m`/`h` suffixes. | -| `initial-interval` | no | `5s` | First sleep after a miss. | -| `max-interval` | no | `60s` | Upper bound on the exponential backoff. | + + +| Name | Type | Required | Default | Description | +| ------------------ | ------ | -------- | ------- | ----------------------------------------------------------------------------- | +| `image` | String | Yes | | Full image reference. Must include a `:tag` or `@sha256:...` digest (or both) | +| `initial-interval` | String | No | `5s` | First sleep after a miss (e.g. 5s). | +| `max-interval` | String | No | `60s` | Upper bound on the backoff (e.g. 60s). | +| `timeout` | String | No | `10m` | Total wall-clock budget (e.g. 10m, 600s, 1h). | + + ## Outputs -None. The step exits 0 on success and 1 on timeout. + + +_None._ + + + +The step exits 0 on success and 1 on timeout. ## Behaviour diff --git a/actions/wait-for-docker-publish/action.yaml b/actions/wait-for-docker-publish/action.yaml index 7e7e433366..75f6e410a4 100644 --- a/actions/wait-for-docker-publish/action.yaml +++ b/actions/wait-for-docker-publish/action.yaml @@ -7,7 +7,7 @@ description: >- inputs: image: description: >- - Full image reference. Must include a :tag or @sha256:... digest + Full image reference. Must include a `:tag` or `@sha256:...` digest (or both) required: true timeout: description: Total wall-clock budget (e.g. 10m, 600s, 1h). diff --git a/actions/zizmor-collection-paths/README.md b/actions/zizmor-collection-paths/README.md index a4409f6ed7..9aa532f873 100644 --- a/actions/zizmor-collection-paths/README.md +++ b/actions/zizmor-collection-paths/README.md @@ -7,3 +7,15 @@ Runs from the Actions cache (`GITHUB_ACTION_PATH`); nothing is checked out into ```bash cd actions/zizmor-collection-paths && python3 -m unittest discover -v ``` + +## Outputs + + + +| Name | Description | +| -------------------- | ------------------------------------------------------------------------------------- | +| `helper_root` | Directory containing collection_paths.py and run_zizmor.py (GITHUB_ACTION_PATH). | +| `paths_list` | Path to the newline-separated explicit inputs file (when use_explicit_paths is true). | +| `use_explicit_paths` | true when ignore prefixes are active; false to scan . | + +