docs: generate action readmes using action-docs

open-turo · Jan 27, 2024 · 21fef18 · 21fef18
1 parent 0bfb681
commit 21fef18
Show file tree

Hide file tree

Showing 6 changed files with 153 additions and 157 deletions.
diff --git a/auth/README.md b/auth/README.md
@@ -1,8 +1,12 @@
-# GitHub Action Auth
+# GitHub Action: Prerelease
 
+<!-- prettier-ignore-start -->
+<!-- action-docs-description -->
 ## Description
 
 GitHub Action that conditionally creates the Terraform command line interface config file that is used to authenticate with Terraform. Created only if not found.
+<!-- action-docs-description -->
+<!-- prettier-ignore-end -->
 
 ## Usage
 
@@ -17,19 +21,37 @@ jobs:
           terraform-cli-credentials-token: ${{ secrets.TCCT }}
 ```
 
+**IMPORTANT**: `GITHUB_TOKEN` does not have the required permissions to operate on protected branches.
+If you are using this action for protected branches, replace `GITHUB_TOKEN`
+with [Personal Access Token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line).
+If using the `@semantic-release/git` plugin for protected branches, avoid persisting credentials as part
+of `actions/checkout@v4` by setting the parameter `persist-credentials: false`. This credential does not have the
+required permission to operate on protected branches.
+
+<!-- prettier-ignore-start -->
+<!-- action-docs-inputs -->
 ## Inputs
 
-| parameter                       | description                                    | required | default      |
-| ------------------------------- | ---------------------------------------------- | -------- | ------------ |
-| terraform-cli-credentials-token | The terraform cli config credentials token     | `true`   |              |
-| terraform-cli-config-file       | Relative path to the terraform cli config file | `false`  | .terraformrc |
+| parameter | description | required | default |
+| --- | --- | --- | --- |
+| terraform-cli-credentials-token | The terraform cli config credentials token | `true` |  |
+| terraform-cli-config-file | Relative path to the terraform cli config file | `false` | .terraformrc |
+<!-- action-docs-inputs -->
 
+<!-- action-docs-outputs -->
 ## Outputs
 
-| parameter                         | description                                                       |
-| --------------------------------- | ----------------------------------------------------------------- |
+| parameter | description |
+| --- | --- |
 | terraform-cli-config-file-created | Indicates whether or not this action created the cli config file. |
+<!-- action-docs-outputs -->
 
+<!-- action-docs-runs -->
 ## Runs
 
-This action is an `composite` action.
+This action is a `composite` action.
+<!-- action-docs-runs -->
+
+<!-- action-docs-usage  -->
+<!-- action-docs-usage -->
+<!-- prettier-ignore-end -->
diff --git a/check-for-breaking-changes/README.md b/check-for-breaking-changes/README.md
@@ -1,8 +1,12 @@
-# GitHub Action Check for Breaking Changes
+# GitHub Action: Prerelease
 
+<!-- prettier-ignore-start -->
+<!-- action-docs-description -->
 ## Description
 
 GitHub Action that check the current branch for any breaking change commits based on the commit message.
+<!-- action-docs-description -->
+<!-- prettier-ignore-end -->
 
 ## Usage
 
@@ -14,21 +18,39 @@ jobs:
         uses: open-turo/actions-tf/check-for-breaking-changes@v3
 ```
 
+**IMPORTANT**: `GITHUB_TOKEN` does not have the required permissions to operate on protected branches.
+If you are using this action for protected branches, replace `GITHUB_TOKEN`
+with [Personal Access Token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line).
+If using the `@semantic-release/git` plugin for protected branches, avoid persisting credentials as part
+of `actions/checkout@v4` by setting the parameter `persist-credentials: false`. This credential does not have the
+required permission to operate on protected branches.
+
+<!-- prettier-ignore-start -->
+<!-- action-docs-inputs -->
 ## Inputs
 
-| parameter          | description                              | required | default                                          |
-| ------------------ | ---------------------------------------- | -------- | ------------------------------------------------ |
-| checkout-repo      | Perform checkout as first step of action | `false`  | true                                             |
-| commit-base-ref    | Commit range to exclude from check       | `false`  | $GITHUB_BASE_REF                                 |
-| commit-head-ref    | Commit range to include in check         | `false`  | $GITHUB_HEAD_REF                                 |
-| commit-msg-pattern | Pattern used to check                    | `false`  | 'BREAKING:\|BREAKING CHANGE:\|BREAKING CHANGES:' |
+| parameter | description | required | default |
+| --- | --- | --- | --- |
+| checkout-repo | Perform checkout as first step of action | `false` | true |
+| commit-base-ref | Commit range to exclude from check | `false` | $GITHUB_BASE_REF |
+| commit-head-ref | Commit range to include in check | `false` | $GITHUB_HEAD_REF |
+| commit-msg-pattern | Pattern used to check | `false` | BREAKING:\|BREAKING CHANGE:\|BREAKING CHANGES: |
+<!-- action-docs-inputs -->
 
+<!-- action-docs-outputs -->
 ## Outputs
 
-| parameter                 | description                                                                          |
-| ------------------------- | ------------------------------------------------------------------------------------ |
-| contains-breaking-changes | Indicates whether or not the action found a ny breaking changes in the commit range. |
+| parameter | description |
+| --- | --- |
+| contains-breaking-changes | Indicates whether or not the action found any breaking changes in the commit range. |
+<!-- action-docs-outputs -->
 
+<!-- action-docs-runs -->
 ## Runs
 
-This action is an `composite` action.
+This action is a `composite` action.
+<!-- action-docs-runs -->
+
+<!-- action-docs-usage  -->
+<!-- action-docs-usage -->
+<!-- prettier-ignore-end -->
diff --git a/generate-breaking-changes-doc/README.md b/generate-breaking-changes-doc/README.md
@@ -1,14 +1,12 @@
-# GitHub Action Generate Breaking Changes Document
+# GitHub Action: Prerelease
 
+<!-- prettier-ignore-start -->
 <!-- action-docs-description -->
-
 ## Description
 
 GitHub Action that creates a breaking changes document based on the configured template.
-
 <!-- action-docs-description -->
-
-\_\_
+<!-- prettier-ignore-end -->
 
 ## Usage
 
@@ -37,35 +35,41 @@ jobs:
           github-token: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-<!-- action-docs-inputs -->
+**IMPORTANT**: `GITHUB_TOKEN` does not have the required permissions to operate on protected branches.
+If you are using this action for protected branches, replace `GITHUB_TOKEN`
+with [Personal Access Token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line).
+If using the `@semantic-release/git` plugin for protected branches, avoid persisting credentials as part
+of `actions/checkout@v4` by setting the parameter `persist-credentials: false`. This credential does not have the
+required permission to operate on protected branches.
 
+<!-- prettier-ignore-start -->
+<!-- action-docs-inputs -->
 ## Inputs
 
-| parameter               | description                                                                                                 | required | default                                                                                                         |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
-| checkout-repo           | Perform checkout as first step of action                                                                    | `false`  | true                                                                                                            |
-| github-token            | GitHub token that can checkout the consumer repository as well push against it. e.g. 'secrets.GITHUB_TOKEN' | `true`   |                                                                                                                 |
-| template-url            | Breaking changes document template URL                                                                      | `false`  | https://raw.githubusercontent.com/open-turo/standards-terraform/main/templates/breaking-changes-doc-template.md |
-| pr-comment              | Adds a comment to the pull request informing that the breaking changes document was added                   | `false`  | true                                                                                                            |
-| pr-comment-author-name  | The pull request comment author name                                                                        | `false`  |                                                                                                                 |
-| pr-comment-author-email | The pull request comment author email                                                                       | `false`  |                                                                                                                 |
-
+| parameter | description | required | default |
+| --- | --- | --- | --- |
+| checkout-repo | Perform checkout as first step of action | `false` | true |
+| github-token | GitHub token that can checkout the consumer repository as well push against it. e.g. 'secrets.GITHUB_TOKEN' | `true` |  |
+| template-url | Breaking changes document template URL | `false` | https://raw.githubusercontent.com/open-turo/standards-terraform/main/templates/breaking-changes-doc-template.md |
+| pr-comment | Adds a comment to the pull request informing that the breaking changes document was added | `false` | true |
+| pr-comment-author-name | The pull request comment author name | `false` |  |
+| pr-comment-author-email | The pull request comment author email | `false` |  |
 <!-- action-docs-inputs -->
 
 <!-- action-docs-outputs -->
-
 ## Outputs
 
-| parameter     | description                                 |
-| ------------- | ------------------------------------------- |
+| parameter | description |
+| --- | --- |
 | document-path | The relative path to the generated document |
-
 <!-- action-docs-outputs -->
 
 <!-- action-docs-runs -->
-
 ## Runs
 
 This action is a `composite` action.
-
 <!-- action-docs-runs -->
+
+<!-- action-docs-usage  -->
+<!-- action-docs-usage -->
+<!-- prettier-ignore-end -->
diff --git a/lint/README.md b/lint/README.md
@@ -1,8 +1,12 @@
-# GitHub Action Lint
+# GitHub Action: Prerelease
 
+<!-- prettier-ignore-start -->
+<!-- action-docs-description -->
 ## Description
 
 GitHub Action that lints a Terraform based repository via [action-pre-commit](https://github.com/open-turo/action-pre-commit)
+<!-- action-docs-description -->
+<!-- prettier-ignore-end -->
 
 ## Usage
 
@@ -17,25 +21,34 @@ jobs:
           terraform-cli-credentials-token: ${{ secrets.TCCT }}
 ```
 
-## Inputs
-
-| parameter                       | description                                                | required | default        |
-| ------------------------------- | ---------------------------------------------------------- | -------- | -------------- |
-| checkout-repo                   | Perform checkout as first step of action                   | `false`  | true           |
-| terraform-cli-credentials-token | The terraform cli config credentials token                 | `true`   |                |
-| terraform-cli-config-file       | Relative or absolute path to the terraform cli config file | `false`  | ./.terraformrc |
+**IMPORTANT**: `GITHUB_TOKEN` does not have the required permissions to operate on protected branches.
+If you are using this action for protected branches, replace `GITHUB_TOKEN`
+with [Personal Access Token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line).
+If using the `@semantic-release/git` plugin for protected branches, avoid persisting credentials as part
+of `actions/checkout@v4` by setting the parameter `persist-credentials: false`. This credential does not have the
+required permission to operate on protected branches.
 
-## Runs
+<!-- prettier-ignore-start -->
+<!-- action-docs-inputs -->
+## Inputs
 
-This action is an `composite` action.
+| parameter | description | required | default |
+| --- | --- | --- | --- |
+| checkout-repo | Perform checkout as first step of action | `false` | true |
+| terraform-cli-credentials-token | The terraform cli config credentials token | `true` |  |
+| terraform-cli-config-file | Relative path to the terraform cli config file | `false` | .terraformrc |
+<!-- action-docs-inputs -->
 
-## Lint Checks
+<!-- action-docs-outputs -->
 
-This action runs the following lint checks:
+<!-- action-docs-outputs -->
 
-- [action-pre-commit](https://github.com/open-turo/action-pre-commit)
+<!-- action-docs-runs -->
+## Runs
 
-## Notes
+This action is a `composite` action.
+<!-- action-docs-runs -->
 
-- By default, this action will perform actions/checkout as its first step.
-- This expects that the `.commitlintrc.yaml` file will be present at the root level of the consumer repository to enforce [`conventional-commit`](https://github.com/wagoid/commitlint-github-action).
+<!-- action-docs-usage  -->
+<!-- action-docs-usage -->
+<!-- prettier-ignore-end -->
diff --git a/prerelease/README.md b/prerelease/README.md
@@ -4,7 +4,7 @@
 <!-- action-docs-description -->
 ## Description
 
-< GitHub Action to compute a prerelease version based on the latest release version and the number of commits since the latest release. This will also generate a docker tag based on the computed version if the label `prerelease` is specified on the PR.
+GitHub Action to compute a prerelease version based on the latest release version and the number of commits since the latest release.
 <!-- action-docs-description -->
 <!-- prettier-ignore-end -->
 
@@ -40,14 +40,9 @@ required permission to operate on protected branches.
 | parameter | description | required | default |
 | --- | --- | --- | --- |
 | checkout-repo | Perform checkout as first step of action | `false` | true |
-| create-prerelease | Whether semantic-release should create a prerelease or do a dry run. This can be useful to set to true when a prerelease requires pushing artifacts semantic-release is in charge of generating | `false` | false |
-| docker-config-file | Path to the docker config file (defaults to .docker-config.json) Must contain imageName, may contain dockerfile. | `false` | .docker-config.json |
-| dockerhub-user | username for dockerhub | `true` |  |
-| dockerhub-password | password for dockerhub | `true` |  |
+| create-prerelease | Whether semantic-release should create a prerelease or do a dry run. This can be useful to set to true when a prerelease requires pushing artifacts semantic-release is in charge of generating | `false` | true |
 | github-token | GitHub token that can checkout the repository as well as create tags/releases against it. e.g. 'secrets.GITHUB_TOKEN' | `true` |  |
 | extra-plugins | Extra plugins for pre-install. You can also specify specifying version range for the extra plugins if you prefer.  Defaults to install @open-turo/semantic-release-config. | `false` | @open-turo/semantic-release-config  |
-| artifactory-username | Artifactory user name usually secrets.ARTIFACTORY_USERNAME | `true` |  |
-| artifactory-auth-token | Artifactory auth token usually secrets.ARTIFACTORY_AUTH_TOKEN | `true` |  |
 <!-- action-docs-inputs -->
 
 <!-- action-docs-outputs -->
@@ -58,8 +53,6 @@ required permission to operate on protected branches.
 | new-release-published | Whether a new release was published |
 | new-release-version | Version of the new release |
 | new-release-major-version | Major version of the new release |
-| image-name | Docker image name |
-| image-with-tag | Full image with tag - <image-name>:<image-version> |
 | pull-request-number | Pull request number |
 | run-url | URL to the GHA run |
 <!-- action-docs-outputs -->