Skip to content

feat: custom wiki usage block #235

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
merged 19 commits into from
Aug 19, 2025
Merged

feat: custom wiki usage block #235

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
ab4425c
Add wiki-custom-usage-string setting
polleuretan Jul 28, 2025
0214a7f
Use config.wikiCustomUsageString in the wiki generation logic
polleuretan Jul 28, 2025
7ff9ac3
Extract default usage block into a separate function
polleuretan Jul 29, 2025
0dd7a8d
A couple of test cases to check the new logic of "usage" block genera…
polleuretan Jul 29, 2025
6a9e715
Mention wiki-custom-usage-string in the README
polleuretan Jul 29, 2025
4c39fa2
Fix linter errors
polleuretan Jul 29, 2025
67f2b2e
Replace wiki-custom-usage-string with wiki-custom-usage-template in c…
polleuretan Jul 30, 2025
2088bd4
New method to get the version number without "v"
polleuretan Jul 30, 2025
968ed7f
Add new module to handle template rendering
polleuretan Jul 30, 2025
f02a756
Use newly defined render function for the wiki generation
polleuretan Jul 30, 2025
19ae9bc
Tests for new templated "usage" block genration
polleuretan Jul 30, 2025
f4384fc
Update README
polleuretan Jul 31, 2025
73fd851
Update config name and default value in action.yaml
polleuretan Jul 31, 2025
5986d7b
Drop DEFAULT_USAGE_BLOCK function and use just render helper
polleuretan Jul 31, 2025
998d6d5
Rename wikiCustomUsageTemplate -> wikiUsageTemplate in existing tests
polleuretan Jul 31, 2025
efd1dcd
Add new variables to the test case
polleuretan Jul 31, 2025
8226aef
Linter feedback
polleuretan Jul 31, 2025
76cd96b
Use `key in variables` to make sure the key is present
polleuretan Jul 31, 2025
f69595a
Add default wiki usage template to test mocks
polleuretan Jul 31, 2025
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
65 changes: 48 additions & 17 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -184,21 +184,22 @@ resources.
While the out-of-the-box defaults are suitable for most use cases, you can further customize the action's behavior by
configuring the following optional input parameters as needed.

| Input | Description | Default |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `major-keywords` | Keywords in commit messages that indicate a major release | `major change,breaking change` |
| `minor-keywords` | Keywords in commit messages that indicate a minor release | `feat,feature` |
| `patch-keywords` | Keywords in commit messages that indicate a patch release | `fix,chore,docs` |
| `default-first-tag` | Specifies the default tag version | `v1.0.0` |
| `terraform-docs-version` | Specifies the terraform-docs version used to generate documentation for the wiki | `v0.19.0` |
| `delete-legacy-tags` | Specifies a boolean that determines whether tags and releases from Terraform modules that have been deleted should be automatically removed | `true` |
| `disable-wiki` | Whether to disable wiki generation for Terraform modules | `false` |
| `wiki-sidebar-changelog-max` | An integer that specifies how many changelog entries are displayed in the sidebar per module | `5` |
| `disable-branding` | Controls whether a small branding link to the action's repository is added to PR comments. Recommended to leave enabled to support OSS. | `false` |
| `module-path-ignore` | Comma-separated list of module paths to completely ignore. Modules matching any pattern here are excluded from all versioning, releases, and documentation.<br><sub>[Read more here](#understanding-the-filtering-options)</sub> | `` (empty string) |
| `module-change-exclude-patterns` | Comma-separated list of file patterns (relative to each module) to exclude from triggering version changes. Lets you release a module but control which files inside it do not force a version bump.<br><sub>[Read more here](#understanding-the-filtering-options)</sub> | `.gitignore,*.md,*.tftest.hcl,tests/**` |
| `module-asset-exclude-patterns` | A comma-separated list of file patterns to exclude when bundling a Terraform module for tag/release. Patterns follow glob syntax (e.g., `tests/\*\*`) and are relative to each Terraform module directory. Files matching these patterns will be excluded from the bundled output. | `.gitignore,*.md,*.tftest.hcl,tests/**` |
| `use-ssh-source-format` | If enabled, all links to source code in generated Wiki documentation will use SSH standard format (e.g., `git::ssh://[email protected]/owner/repo.git`) instead of HTTPS format (`git::https://github.com/owner/repo.git`) | `false` |
| Input | Description | Default |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `major-keywords` | Keywords in commit messages that indicate a major release | `major change,breaking change` |
| `minor-keywords` | Keywords in commit messages that indicate a minor release | `feat,feature` |
| `patch-keywords` | Keywords in commit messages that indicate a patch release | `fix,chore,docs` |
| `default-first-tag` | Specifies the default tag version | `v1.0.0` |
| `terraform-docs-version` | Specifies the terraform-docs version used to generate documentation for the wiki | `v0.19.0` |
| `delete-legacy-tags` | Specifies a boolean that determines whether tags and releases from Terraform modules that have been deleted should be automatically removed | `true` |
| `disable-wiki` | Whether to disable wiki generation for Terraform modules | `false` |
| `wiki-sidebar-changelog-max` | An integer that specifies how many changelog entries are displayed in the sidebar per module | `5` |
| `disable-branding` | Controls whether a small branding link to the action's repository is added to PR comments. Recommended to leave enabled to support OSS. | `false` |
| `module-path-ignore` | Comma-separated list of module paths to completely ignore. Modules matching any pattern here are excluded from all versioning, releases, and documentation.<br><sub>[Read more here](#understanding-the-filtering-options)</sub> | `` (empty string) |
| `module-change-exclude-patterns` | Comma-separated list of file patterns (relative to each module) to exclude from triggering version changes. Lets you release a module but control which files inside it do not force a version bump.<br><sub>[Read more here](#understanding-the-filtering-options)</sub> | `.gitignore,*.md,*.tftest.hcl,tests/**` |
| `module-asset-exclude-patterns` | A comma-separated list of file patterns to exclude when bundling a Terraform module for tag/release. Patterns follow glob syntax (e.g., `tests/\*\*`) and are relative to each Terraform module directory. Files matching these patterns will be excluded from the bundled output. | `.gitignore,*.md,*.tftest.hcl,tests/**` |
| `use-ssh-source-format` | If enabled, all links to source code in generated Wiki documentation will use SSH standard format (e.g., `git::ssh://[email protected]/owner/repo.git`) instead of HTTPS format (`git::https://github.com/owner/repo.git`) | `false` |
| `wiki-usage-template` | A raw, multi-line string to override the default 'Usage' section in the generated wiki. Allows using variables like {{module_name}}, {{latest_tag}}, {{latest_tag_version_number}} and more.<br><sub>[Read more here](#configuring-the-usage-template)</sub> | [See action.yml](https://github.com/polleuretan/terraform-module-releaser/blob/main/action.yml#L108) |

### Understanding the filtering options

Expand Down Expand Up @@ -281,9 +282,22 @@ similar to those used in `.gitignore` files. For more details on the pattern mat
[source code](https://github.com/techpivot/terraform-module-releaser/blob/main/src/utils/file.ts) or visit the
[minimatch documentation](https://github.com/isaacs/minimatch).

### Configuring the Usage Template

The `wiki-usage-template` input allows you to customize the "Usage" section of the generated wiki page for each module.
You can use the following dynamic variables in your template:

| Variable | Description | Example |
| ------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `{{module_name}}` | The name of the module. | `aws/s3-bucket` |
| `{{latest_tag}}` | The latest Git tag for the module. | `aws/s3-bucket/v1.2.3` |
| `{{latest_tag_version_number}}` | The version number of the latest tag. | `1.2.3` |
| `{{module_source}}` | The Git source URL for the module, respecting the `use-ssh-source-format` input. | `git::https://github.com/owner/repo.git` |
| `{{module_name_terraform}}` | A Terraform-safe version of the module name (e.g., special characters replaced with underscores). | `aws_s3_bucket` |

### Example Usage with Inputs

```yml
````yml
name: Terraform Module Releaser
on:
pull_request:
Expand Down Expand Up @@ -317,7 +331,24 @@ jobs:
module-change-exclude-patterns: .gitignore,*.md,docs/**,examples/**,*.tftest.hcl,tests/**
module-asset-exclude-patterns: .gitignore,*.md,*.tftest.hcl,tests/**
use-ssh-source-format: false
```
wiki-usage-template: |
# My Custom Usage Instructions

This is a custom usage block.

You can add any markdown you want here.

And use variables like {{module_name}}, {{latest_tag}}, {{latest_tag_version_number}},
{{module_source}} and {{module_name_terraform}}.

```hcl
module "{{module_name_terraform}}" {
source = "{{module_source}}?ref={{latest_tag}}"
version = "{{latest_tag_version_number}}"
# ...
}
```
````

## Outputs

Expand Down
11 changes: 11 additions & 0 deletions __mocks__/config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,17 @@ const defaultConfig: Config = {
moduleAssetExcludePatterns: ['tests/**', 'examples/**'],
githubToken: 'ghp_test_token_2c6912E7710c838347Ae178B4',
useSSHSourceFormat: false,
wikiUsageTemplate: `
To use this module in your Terraform, refer to the below module example:

\`\`\`hcl
module "{{module_name_terraform}}" {
source = "git::{{module_source}}?ref={{latest_tag}}"

# See inputs below for additional required parameters
}
\`\`\`
`
};

/**
Expand Down
39 changes: 39 additions & 0 deletions __tests__/templating.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
import { describe, it, expect } from 'vitest';
import { render } from '../src/templating';

describe('templating', () => {
it('should replace a single placeholder', () => {
const template = 'Hello, {{name}}!';
const variables = { name: 'World' };
const result = render(template, variables);
expect(result).toBe('Hello, World!');
});

it('should replace multiple placeholders', () => {
const template = '{{greeting}}, {{name}}!';
const variables = { greeting: 'Hi', name: 'There' };
const result = render(template, variables);
expect(result).toBe('Hi, There!');
});

it('should handle templates with no placeholders', () => {
const template = 'Just a plain string.';
const variables = { name: 'World' };
const result = render(template, variables);
expect(result).toBe('Just a plain string.');
});

it('should handle empty string values', () => {
const template = 'A{{key}}B';
const variables = { key: '' };
const result = render(template, variables);
expect(result).toBe('AB');
});

it('should leave unmapped placeholders untouched', () => {
const template = 'Hello, {{name}} and {{unmapped}}!';
const variables = { name: 'World' };
const result = render(template, variables);
expect(result).toBe('Hello, World and {{unmapped}}!');
});
});
Loading
Loading