refactor(recipe): improve github actions recipe (#16)

This PR revamps the GitHub Actions recipe page to be more
action-oriented, easier to scan, and aligned with current
semantic-release security guidance.

### Notable Changes

- Reworked the page flow to be execution-first:
    1. Quick start at the top
    2. Clear publishing path selection
    3. Minimal Node workflow users can copy and run
    4. Deeper context and edge cases afterward
- Improved navigation with direct links from quick start to relevant
sections.
- Added a practical pitfalls checklist and a release readiness
checklist.
- Modernized guidance around publishing/auth:
    1. Prioritizes trusted publishing (OIDC) and npm provenance
    2. Clarifies token behavior and setup expectations
- Updated the commit-during-release guidance:
    1. Recommends GitHub App authentication as the preferred approach
    2. Adds a minimal GitHub App token example
    3. Explicitly discourages PAT usage due to security risk
- Added guidance that the workflow snippet represents a simple/default
release flow and points users to the Running semantic-release docs for
alternate invocation patterns and non-default setups.

## Screenshot/Screencast

[screen-capture
(68).webm](https://github.com/user-attachments/assets/f676ef37-6223-4305-bbf3-c748e42cbc72)

---------

Co-authored-by: Matt Travi <126441+travi@users.noreply.github.com>

Author: babblebey

astro.config.js

@@ -78,11 +78,14 @@ export default defineConfig({
             {
               label: "CI Configurations",
               items: [
-                { slug: "recipes/ci-configurations" },
-                { slug: "recipes/ci-configurations/circleci-workflows" },
-                { slug: "recipes/ci-configurations/travis" },
-                { slug: "recipes/ci-configurations/gitlab-ci" },
+                { slug: "recipes/ci-configurations", label: "Overview" },
                 { slug: "recipes/ci-configurations/github-actions" },
+                { slug: "recipes/ci-configurations/gitlab-ci" },
+                {
+                  slug: "recipes/ci-configurations/circleci-workflows",
+                  label: "CircleCI Workflows",
+                },
+                { slug: "recipes/ci-configurations/travis" },
                 { slug: "recipes/ci-configurations/jenkins-ci" },
               ],
             },

src/content/docs/foundation/considerations.md

@@ -12,7 +12,7 @@ title: Considerations
 
 If your primary attraction is for automatic release note generation rather than semantic versioning, you may want to reconsider if **semantic-release** is the right fit for your goals.
 
-:::tip[Recommendation] 
+:::tip[Recommendation]
 Adopt **semantic-release** when semantic versioning is your primary objective, with release-step automation as a secondary benefit.
 :::
 
@@ -29,7 +29,7 @@ Applications that are deployed directly to a runtime environment lack an audienc
 Docker images that are published to a registry only for the purpose of deploying directly to a runtime environment fall into this category, even though they are a published asset.
 Often, using the git SHA as the version for such assets is a better choice than versioning them semantically.
 
-:::tip[Recommendation] 
+:::tip[Recommendation]
 Prioritize semantic versioning for artifacts consumed as dependencies; for directly deployed artifacts, consider using git SHAs instead.
 :::
 
@@ -43,7 +43,7 @@ and [making commits during the release process adds significant complexity](/sup
 
 Please consider the trade-offs of adding those plugins to your release configuration for potentially unnecessary goals.
 
-:::tip[Recommendation] 
+:::tip[Recommendation]
 Keep your configuration minimal and only add release-time commits when there is a clear, justified need.
 :::
 

src/content/docs/foundation/plugins.md

@@ -8,17 +8,17 @@ This enables support for different [commit message conventions](/foundation/how-
 
 A plugin is a npm module that can implement one or more lifecycle methods for the following hooks:
 
-| Lifecycle Hook     | Related Release Step  | Required | Description                                                                                                                                                    |
-| ------------------ | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `verifyConditions` | Verify Conditions     | No       | Verify conditions necessary to proceed with the release: configuration is correct, authentication tokens are valid, and so on.                                 |
-| `analyzeCommits`   | Analyze Commits       | Yes      | Determine the type of the next release (`major`, `minor`, or `patch`). This hook is required to decide the next release type. If multiple plugins implement `analyzeCommits`, the highest release type returned wins. |
-| `verifyRelease`    | Verify Release        | No       | Verify the parameters of the release that is about to be published, such as version, type, or distribution tag.                                                |
-| `generateNotes`    | Generate Notes        | No       | Generate the content of the release note. If multiple plugins implement `generateNotes`, the release notes will be the concatenation of each plugin output.    |
-| `prepare`          | Prepare               | No       | Prepare the release, for example by creating or updating files such as `package.json`, `CHANGELOG.md`, documentation, or compiled assets and pushing a commit. |
-| `publish`          | Publish               | No       | Publish the release.                                                                                                                                           |
-| `addChannel`       | Add Channel (optional) | No       | Assign the release to a distribution channel when channel management is needed, for example by adding an npm dist-tag.                                         |
-| `success`          | Notify                | No       | Notify consumers or maintainers after a successful release.                                                                                                    |
-| `fail`             | Notify                | No       | Notify consumers or maintainers after a failed release.                                                                                                        |
+| Lifecycle Hook     | Related Release Step   | Required | Description                                                                                                                                                                                                           |
+| ------------------ | ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `verifyConditions` | Verify Conditions      | No       | Verify conditions necessary to proceed with the release: configuration is correct, authentication tokens are valid, and so on.                                                                                        |
+| `analyzeCommits`   | Analyze Commits        | Yes      | Determine the type of the next release (`major`, `minor`, or `patch`). This hook is required to decide the next release type. If multiple plugins implement `analyzeCommits`, the highest release type returned wins. |
+| `verifyRelease`    | Verify Release         | No       | Verify the parameters of the release that is about to be published, such as version, type, or distribution tag.                                                                                                       |
+| `generateNotes`    | Generate Notes         | No       | Generate the content of the release note. If multiple plugins implement `generateNotes`, the release notes will be the concatenation of each plugin output.                                                           |
+| `prepare`          | Prepare                | No       | Prepare the release, for example by creating or updating files such as `package.json`, `CHANGELOG.md`, documentation, or compiled assets and pushing a commit.                                                        |
+| `publish`          | Publish                | No       | Publish the release.                                                                                                                                                                                                  |
+| `addChannel`       | Add Channel (optional) | No       | Assign the release to a distribution channel when channel management is needed, for example by adding an npm dist-tag.                                                                                                |
+| `success`          | Notify                 | No       | Notify consumers or maintainers after a successful release.                                                                                                                                                           |
+| `fail`             | Notify                 | No       | Notify consumers or maintainers after a failed release.                                                                                                                                                               |
 
 For each [release step](/foundation/steps/), **semantic-release** runs every plugin in the [`plugins` array](plugins.md#plugins-declaration-and-execution-order) that implements the hook for that step.
 

src/content/docs/foundation/shareable-configurations.md

@@ -16,16 +16,16 @@ The shareable configurations to use can be set with the [extends](/usage/configu
 
 ```json
 {
-	"extends": "@semantic-release/gitlab-config"
+  "extends": "@semantic-release/gitlab-config"
 }
 ```
 
 For example, a project can extend a shared base config and still override its own branches locally:
 
 ```json
 {
-	"extends": "@semantic-release/gitlab-config",
-	"branches": ["main", "next"]
+  "extends": "@semantic-release/gitlab-config",
+  "branches": ["main", "next"]
 }
 ```
 
@@ -36,4 +36,3 @@ If multiple shareable configurations are defined, they are loaded in order. Loca
 See the [shareable configurations list](/extending/shareable-configurations-list) for official and community-maintained packages you can extend.
 
 If you want to build your own shareable configuration, see [Shareable configuration development](/developer-guide/shareable-configuration/).
-

src/content/docs/foundation/supported-branching.md

@@ -4,7 +4,7 @@ title: Supported Branching Models
 
 This page summarizes branching models that align well with **semantic-release** and those that are officially unsupported.
 
-:::tip[Recommendation] 
+:::tip[Recommendation]
 Default to workflows that keep changes flowing to a stable trunk quickly and continuously.
 :::
 
@@ -35,7 +35,7 @@ These models align with the delivery and release assumptions built into **semant
 
 - [Continuous Deployment](https://trunkbaseddevelopment.com/continuous-delivery/#continuous-deployment)
 
-:::tip[Recommendation] 
+:::tip[Recommendation]
 Choose a trunk-based workflow that keeps branch lifetime short and integration frequent.
 :::
 
@@ -44,7 +44,7 @@ Choose a trunk-based workflow that keeps branch lifetime short and integration f
 - [GitHub Docs: GitHub Flow](https://docs.github.com/en/get-started/using-github/github-flow)
 - [GitHub Flow](https://githubflow.github.io/)
 
-:::tip[Recommendation] 
+:::tip[Recommendation]
 GitHub Flow is a practical fit when pull requests are short-lived and releases are frequent.
 :::
 
@@ -73,15 +73,15 @@ While the [same reflection](https://nvie.com/posts/a-successful-git-branching-mo
 While some have found that the [Pre-release workflow](/foundation/workflow-configuration/#prerelease) enabled by **semantic-release** can be used to _simulate_ a git-flow-like workflow,
 it is also worth noting that this orchestration pattern is not an intended use case and requests for support when attempting to use it that way will be closed by our team.
 
-:::tip[Recommendation] 
+:::tip[Recommendation]
 Avoid Git flow-style long-lived branch orchestration when using **semantic-release**.
 :::
 
 ### Workflows that Release for Testing Before Promotion to a Stable Release
 
 - [The Importance of a Local Build](https://trunkbaseddevelopment.com/styles/#the-importance-of-a-local-build)
 
-:::tip[Recommendation] 
+:::tip[Recommendation]
 Prefer workflows where confidence comes from CI quality signals, with production release as the promotion event.
 :::
 

src/content/docs/foundation/workflow-configuration.md

@@ -23,10 +23,10 @@ The type of the branch is automatically determined based on naming conventions a
 
 ## Branch Properties
 
-| Property     | Branch type                                                        | Description                                                                                                                                                                                                      | Default                                                                                         |
-| ------------ | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `name`       | All                                                                | **Required.** The Git branch holding the commits to analyze and the code to release. See [name](#name).                                                                                 | - The value itself if defined as a `String` or the matching branches name if defined as a glob. |
-| `channel`    | All                                                                | The distribution channel on which to publish releases from this branch. Set to `false` to force the default distribution channel instead of using the default. See [channel](#channel). | `undefined` for the first release branch, the value of `name` for subsequent ones.              |
+| Property     | Branch type                               | Description                                                                                                                                                                             | Default                                                                                         |
+| ------------ | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `name`       | All                                       | **Required.** The Git branch holding the commits to analyze and the code to release. See [name](#name).                                                                                 | - The value itself if defined as a `String` or the matching branches name if defined as a glob. |
+| `channel`    | All                                       | The distribution channel on which to publish releases from this branch. Set to `false` to force the default distribution channel instead of using the default. See [channel](#channel). | `undefined` for the first release branch, the value of `name` for subsequent ones.              |
 | `range`      | [maintenance](#maintenance-branches) only | **Required unless `name` is formatted like `N.N.x` or `N.x` (`N` is a number).** The range of [semantic versions](https://semver.org) to support on this branch. See [range](#range).   | The value of `name`.                                                                            |
 | `prerelease` | [pre-release](#pre-release-branches) only | **Required.** The pre-release denotation to append to [semantic versions](https://semver.org) released from this branch. See [prerelease](#prerelease).                                 | -                                                                                               |