Skip to content

docs: generate action and workflow input/output tables #2276

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ricky-undeadcoders merged 1 commit into from
Sep 9, 2026
Merged

docs: generate action and workflow input/output tables #2276

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions .github/workflows/check-action-docs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
29 changes: 29 additions & 0 deletions .github/workflows/check-drone-signature.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

<!-- BEGIN_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 |

<!-- END_INPUTS -->
105 changes: 56 additions & 49 deletions .github/workflows/docker-build-push-multiarch.md
View file
Open in desktop

Large diffs are not rendered by default.

26 changes: 14 additions & 12 deletions .github/workflows/publish-techdocs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`) |
<!-- BEGIN_INPUTS -->

[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 |

<!-- END_INPUTS -->
30 changes: 16 additions & 14 deletions .github/workflows/reusable-zizmor.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
<!-- BEGIN_INPUTS -->

| 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. |

<!-- END_INPUTS -->

## Grafana Bench (Prometheus metrics)

Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/reusable-zizmor.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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: ""
Expand Down
14 changes: 9 additions & 5 deletions .github/workflows/sign-and-attest.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
<!-- BEGIN_INPUTS -->

| 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. |

<!-- END_INPUTS -->

## Required caller permissions

Expand Down
Loading
Loading