Add hooks documentation#3180
Open
Resonance1584 wants to merge 7 commits into
Open
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds comprehensive Hooks documentation for Pipelines including a new Hooks API reference documenting the environment-variable contract ( ChangesPipelines Hooks documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/2.0/docs/pipelines/guides/hooks/slack-deploy-notification.md`:
- Line 104: Update the statement about the hook reporting as a pass in the Slack
deploy notification example documentation. Currently it states that writing
nothing to output files results in a pass, but this needs qualification: clarify
that a pass is only reported when the script exits with code 0, and explain that
despite writing no output files, the example can still fail the hook if the AWS
secret lookup fails or the curl Slack API call fails (due to set -euo pipefail
and the --fail flags used in the example), causing non-zero exit codes that will
fail the entire pipeline run.
In `@docs/2.0/docs/pipelines/guides/hooks/writing-a-hook.md`:
- Around line 30-47: The documentation examples use the jq command-line tool in
multiple code snippets but do not document it as a required prerequisite. Add a
note or prerequisites section before or at the beginning of the hook writing
guide (before the section "3. Write the comment") that explicitly mentions jq as
a runtime dependency that readers must have installed on their system to use the
hook examples. This ensures users are aware of the requirement before attempting
to run the code snippets that invoke jq commands.
In `@docs/2.0/reference/pipelines/hooks-api.md`:
- Around line 90-98: The table entry for the `pass` result incorrectly states it
"Produces no comment," which contradicts the actual behavior where hooks can
still emit summary and comment output when exiting with status 0. Update the
`pass` row in the Result table to clarify that `pass` is the default result and
does not suppress hook output or comments; it simply indicates the hook executed
successfully and allows any comments the hook chooses to emit.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 9e38d549-f52b-46cf-9649-ee2d237380c3
⛔ Files ignored due to path filters (1)
static/img/pipelines/guides/affected-units-comment.pngis excluded by!**/*.png
📒 Files selected for processing (10)
docs/2.0/docs/pipelines/guides/hooks/authentication.mddocs/2.0/docs/pipelines/guides/hooks/configuring.mddocs/2.0/docs/pipelines/guides/hooks/overview.mddocs/2.0/docs/pipelines/guides/hooks/setup.mddocs/2.0/docs/pipelines/guides/hooks/slack-deploy-notification.mddocs/2.0/docs/pipelines/guides/hooks/writing-a-hook.mddocs/2.0/reference/pipelines/configurations-as-code/api.mdxdocs/2.0/reference/pipelines/hooks-api.mdsidebars/docs.jssidebars/reference.js
Comment on lines
+30
to
+47
| `PIPELINES_HOOKS_IN_UNITS_JSON_FILE` points at a JSON array of the units in the run, each with its path and (when one exists) the path to its plan JSON. For example, list the affected unit paths with `jq`: | ||
|
|
||
| ```bash | ||
| jq -r '.[].path' "$units_file" | ||
| ``` | ||
|
|
||
| For the complete list of context variables and input files, see the [Hooks API](/2.0/reference/pipelines/hooks-api). | ||
|
|
||
| ## 3. Write the comment | ||
|
|
||
| A hook returns information by writing to the files named in the `PIPELINES_HOOKS_OUT_*` namespace. Build a comment listing the affected units and write it to the comment file: | ||
|
|
||
| ```bash | ||
| { | ||
| echo "<code>$action</code> triggered by @$actor affected:" | ||
| echo | ||
| jq -r '.[] | "- <code>\(.path)</code>"' "$units_file" | ||
| } > "$PIPELINES_HOOKS_OUT_COMMENT_FILE" |
Contributor
There was a problem hiding this comment.
Call out the jq runtime dependency.
Both snippets use jq, so readers who copy this hook into an environment without it will hit a runtime failure immediately. Please mention that prerequisite in the guide.
Proposed fix
Before you start, make sure hooks are set up for your repository. See [Setup & Prerequisites](/2.0/docs/pipelines/guides/hooks/setup).
+This example also requires `jq` to be available in the hook runtime.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/2.0/docs/pipelines/guides/hooks/writing-a-hook.md` around lines 30 - 47,
The documentation examples use the jq command-line tool in multiple code
snippets but do not document it as a required prerequisite. Add a note or
prerequisites section before or at the beginning of the hook writing guide
(before the section "3. Write the comment") that explicitly mentions jq as a
runtime dependency that readers must have installed on their system to use the
hook examples. This ensures users are aware of the requirement before attempting
to run the code snippets that invoke jq commands.
oredavids
reviewed
Jun 18, 2026
oredavids
left a comment
oredavids
left a comment
Contributor
There was a problem hiding this comment.
Based on the current pages I've reviewed.
Comment on lines
+18
to
+31
| ### Required fields | ||
|
|
||
| - **`commands`**: the commands this hook runs after. One or both of `plan` and `apply`. | ||
| - **`execute`**: the command to run, given as a list of the program followed by its arguments. | ||
|
|
||
| The block label (`hello_world` in the example above) is also required and must be unique within the `repository` block. | ||
|
|
||
| ### Optional fields | ||
|
|
||
| - **`name`**: a human-readable display name for the hook. | ||
| - **`env`**: environment variables to set for the `execute` command. | ||
| - **`run_on_error`**: whether the hook runs when a preceding command or hook failed. Defaults to `false`. | ||
| - **`timeout_seconds`**: how long the hook may run before it is terminated. Defaults to `300`. | ||
| - **`authentication`**: cloud credentials and secrets for the hook. See [Authentication & Secrets](/2.0/docs/pipelines/guides/hooks/authentication). |
Contributor
There was a problem hiding this comment.
It may be best to leave out the Required and optional sections here since we link to the full spec below and can have a single source of truth for the documentation.
We should still have the text explaining the label, commands and execute meaning.
oredavids
reviewed
Jun 18, 2026
ebeneliason
reviewed
Jun 18, 2026
ebeneliason
reviewed
Jun 18, 2026
| The two text outputs serve different purposes: | ||
|
|
||
| - **Summary** (`PIPELINES_HOOKS_OUT_SUMMARY_FILE`) appears inline next to the title, after a colon, for example `⚠️ Affected Units: 3 units changed`. Use it for a short, at-a-glance headline. | ||
| - **Comment** (`PIPELINES_HOOKS_OUT_COMMENT_FILE`) is the body of the collapsible section, rendered as HTML. Use it for detailed output such as a table, a list, or links. |
Contributor
There was a problem hiding this comment.
Is HTML the expected format? I expected all comment files to be formatted as markdown. We should clarify what's supported. Can we make this markdown-enabled?
Contributor
Author
There was a problem hiding this comment.
Well, it all gets dumped into the mixed html/md comment that already exists. Some things like code blocks with backticks ` wont work on the first new line within the details block. Then they might start working after two new lines. Using <code> works straight away.
ebeneliason
reviewed
Jun 18, 2026
ebeneliason
reviewed
Jun 18, 2026
ebeneliason
reviewed
Jun 18, 2026
| @@ -0,0 +1,114 @@ | |||
| # Example: Slack Deploy Notification | |||
Contributor
There was a problem hiding this comment.
Should this live in the Tutorials section instead?
Contributor
|
What's the relationship of Hooks to the "Extending Pipelines" section? The extension talks about how to extend actions. Do we promote both approaches going forward? Recommend one over the other? Recommend one or the other for specific use cases? At the very least, it seems we might need to cross-reference so folks don't find one and miss the other, but perhaps the extending section just gets overhauled or removed? |
Co-authored-by: Oreoluwa Agunbiade <21035422+oredavids@users.noreply.github.com> Co-authored-by: Eben Eliason <eben.eliason@gmail.com>
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/2.0/docs/pipelines/guides/hooks/overview.md (1)
9-15: Add guidance distinguishing Hooks from Extending Pipelines.The intro states "Hooks are how you extend a Pipelines run," but the codebase has a separate "Extending Pipelines" guide that covers GitHub Actions workflow customization. Clarify whether Hooks complement workflow-level extensions or are an alternative path. A sentence noting that Hooks execute commands at specific pipeline points (distinct from modifying GitHub Actions workflows) would help readers choose the right approach.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/2.0/docs/pipelines/guides/hooks/overview.md` around lines 9 - 15, Add clarification to the Hooks overview section to distinguish Hooks from the separate "Extending Pipelines" guide that covers GitHub Actions workflow customization. Insert a sentence after the first paragraph explaining that Hooks specifically execute commands at defined points within the pipeline run (like after plan or apply), which is distinct from and complementary to modifying GitHub Actions workflows themselves. This will help readers understand when to use Hooks versus workflow-level extensions and which approach is appropriate for their use case.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@docs/2.0/docs/pipelines/guides/hooks/overview.md`:
- Around line 9-15: Add clarification to the Hooks overview section to
distinguish Hooks from the separate "Extending Pipelines" guide that covers
GitHub Actions workflow customization. Insert a sentence after the first
paragraph explaining that Hooks specifically execute commands at defined points
within the pipeline run (like after plan or apply), which is distinct from and
complementary to modifying GitHub Actions workflows themselves. This will help
readers understand when to use Hooks versus workflow-level extensions and which
approach is appropriate for their use case.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 0c6600d2-ee85-49c8-aede-d35d9f207379
📒 Files selected for processing (6)
docs/2.0/docs/pipelines/guides/hooks/authentication.mddocs/2.0/docs/pipelines/guides/hooks/configuring.mddocs/2.0/docs/pipelines/guides/hooks/overview.mddocs/2.0/docs/pipelines/guides/hooks/setup.mddocs/2.0/docs/pipelines/guides/hooks/slack-deploy-notification.mddocs/2.0/reference/pipelines/configurations-as-code/api.mdx
✅ Files skipped from review due to trivial changes (5)
- docs/2.0/docs/pipelines/guides/hooks/authentication.md
- docs/2.0/reference/pipelines/configurations-as-code/api.mdx
- docs/2.0/docs/pipelines/guides/hooks/setup.md
- docs/2.0/docs/pipelines/guides/hooks/configuring.md
- docs/2.0/docs/pipelines/guides/hooks/slack-deploy-notification.md
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/2.0/reference/pipelines/hooks-api.md (1)
21-21: 💤 Low valueCapitalize GitHub as a proper noun.
The CI platform
githubshould be capitalized asGitHubper official branding.-| `PIPELINES_HOOK_CTX_CI_PLATFORM` | The CI platform running the hook: `github` or `gitlab`. | +| `PIPELINES_HOOK_CTX_CI_PLATFORM` | The CI platform running the hook: `GitHub` or `GitLab`. |🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/2.0/reference/pipelines/hooks-api.md` at line 21, The documentation for the PIPELINES_HOOK_CTX_CI_PLATFORM environment variable contains the lowercase word `github` which does not follow proper branding guidelines. In the hooks-api.md file, change the lowercase `github` to the properly capitalized `GitHub` in the table row describing this CI platform constant to maintain consistency with official branding conventions.Source: Linters/SAST tools
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@docs/2.0/reference/pipelines/hooks-api.md`:
- Line 21: The documentation for the PIPELINES_HOOK_CTX_CI_PLATFORM environment
variable contains the lowercase word `github` which does not follow proper
branding guidelines. In the hooks-api.md file, change the lowercase `github` to
the properly capitalized `GitHub` in the table row describing this CI platform
constant to maintain consistency with official branding conventions.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 5965bea0-b984-4eed-a0ff-6eee42f5703d
📒 Files selected for processing (4)
docs/2.0/docs/pipelines/guides/hooks/slack-deploy-notification.mddocs/2.0/docs/pipelines/guides/hooks/writing-a-hook.mddocs/2.0/reference/pipelines/configurations-as-code/api.mdxdocs/2.0/reference/pipelines/hooks-api.md
✅ Files skipped from review due to trivial changes (2)
- docs/2.0/docs/pipelines/guides/hooks/writing-a-hook.md
- docs/2.0/docs/pipelines/guides/hooks/slack-deploy-notification.md
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/2.0/reference/pipelines/configurations-as-code/api.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary by CodeRabbit