diff --git a/CLAUDE.md b/CLAUDE.md index ca4efc5..d3dfd9e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,7 +1,31 @@ -# CLAUDE.md - Development Guide +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. **gh-action-readme** - CLI tool for GitHub Actions documentation generation +## 📝 Template Updates + +**Templates are embedded from:** `templates_embed/templates/` + +**To modify templates:** + +1. Edit template files directly in `templates_embed/templates/` +2. Rebuild the binary: `go build .` +3. Templates are automatically embedded via `//go:embed` directive + +**Available template locations:** + +- Default: `templates_embed/templates/readme.tmpl` +- GitHub theme: `templates_embed/templates/themes/github/readme.tmpl` +- GitLab theme: `templates_embed/templates/themes/gitlab/readme.tmpl` +- Minimal theme: `templates_embed/templates/themes/minimal/readme.tmpl` +- Professional: `templates_embed/templates/themes/professional/readme.tmpl` +- AsciiDoc theme: `templates_embed/templates/themes/asciidoc/readme.adoc` + +**Template embedding:** Handled by `templates_embed/embed.go` using Go's embed directive. +The embedded filesystem is used by default, with fallback to filesystem for development. + ## 🚨 CRITICAL: README Protection **NEVER overwrite `/README.md`** - The root README.md is the main project documentation. diff --git a/README.md b/README.md index 7468f01..cdd0a11 100644 --- a/README.md +++ b/README.md @@ -164,7 +164,7 @@ gh-action-readme config init gh-action-readme gen --recursive --theme github --output-dir docs/ # Custom themes -cp -r templates/themes/github templates/themes/custom +cp -r templates_embed/templates/themes/github templates_embed/templates/themes/custom gh-action-readme gen --theme custom ``` diff --git a/appconstants/constants.go b/appconstants/constants.go index 56a0e1a..0f01e80 100644 --- a/appconstants/constants.go +++ b/appconstants/constants.go @@ -150,6 +150,8 @@ const ( ConfigKeyRepository = "repository" // ConfigKeyVersion is the version config key. ConfigKeyVersion = "version" + // ConfigKeyUseDefaultBranch is the configuration key for use default branch behavior. + ConfigKeyUseDefaultBranch = "use_default_branch" // Template Configuration // ConfigKeyTheme is the configuration key for theme. diff --git a/integration_test.go b/integration_test.go index a507e26..6eca191 100644 --- a/integration_test.go +++ b/integration_test.go @@ -2,7 +2,6 @@ package main import ( "encoding/json" - "io" "os" "os/exec" "path/filepath" @@ -38,47 +37,6 @@ func TestMain(m *testing.M) { os.Exit(code) } -// copyDir recursively copies a directory. -func copyDir(src, dst string) error { - return filepath.Walk(src, func(path string, info os.FileInfo, err error) error { - if err != nil { - return err - } - - relPath, err := filepath.Rel(src, path) - if err != nil { - return err - } - - dstPath := filepath.Join(dst, relPath) - - if info.IsDir() { - return os.MkdirAll(dstPath, info.Mode()) - } - - // Copy file - srcFile, err := os.Open(path) // #nosec G304 -- copying test files - if err != nil { - return err - } - defer func() { _ = srcFile.Close() }() - - if err := os.MkdirAll(filepath.Dir(dstPath), 0750); err != nil { // #nosec G301 -- test directory permissions - return err - } - - dstFile, err := os.Create(dstPath) // #nosec G304 -- creating test files - if err != nil { - return err - } - defer func() { _ = dstFile.Close() }() - - _, err = io.Copy(dstFile, srcFile) - - return err - }) -} - // getSharedTestBinary returns the path to the shared test binary, building it once if needed. func getSharedTestBinary(t *testing.T) string { t.Helper() @@ -108,14 +66,6 @@ func getSharedTestBinary(t *testing.T) string { return } - // Copy templates directory to binary directory (for compatibility with embedded templates fallback) - templatesDir := filepath.Join(filepath.Dir(binaryPath), "templates") - if err := copyDir("templates", templatesDir); err != nil { - errSharedBinary = err - - return - } - sharedBinaryPath = binaryPath }) diff --git a/internal/config.go b/internal/config.go index 639efd0..a5b116c 100644 --- a/internal/config.go +++ b/internal/config.go @@ -25,9 +25,10 @@ type AppConfig struct { GitHubToken string `mapstructure:"github_token" yaml:"github_token,omitempty"` // Only in global config // Repository Information (auto-detected, overridable) - Organization string `mapstructure:"organization" yaml:"organization,omitempty"` - Repository string `mapstructure:"repository" yaml:"repository,omitempty"` - Version string `mapstructure:"version" yaml:"version,omitempty"` + Organization string `mapstructure:"organization" yaml:"organization,omitempty"` + Repository string `mapstructure:"repository" yaml:"repository,omitempty"` + Version string `mapstructure:"version" yaml:"version,omitempty"` + UseDefaultBranch bool `mapstructure:"use_default_branch" yaml:"use_default_branch"` // Template Settings Theme string `mapstructure:"theme" yaml:"theme"` @@ -214,9 +215,10 @@ func resolveThemeTemplate(theme string) string { func DefaultAppConfig() *AppConfig { return &AppConfig{ // Repository Information (will be auto-detected) - Organization: "", - Repository: "", - Version: "", + Organization: "", + Repository: "", + Version: "", + UseDefaultBranch: true, // Use detected default branch (main/master) in usage examples // Template Settings Theme: "default", // default, github, gitlab, minimal, professional @@ -340,6 +342,9 @@ func mergeBooleanFields(dst *AppConfig, src *AppConfig) { if src.Quiet { dst.Quiet = src.Quiet } + if src.UseDefaultBranch { + dst.UseDefaultBranch = src.UseDefaultBranch + } } // mergeSecurityFields merges security-sensitive fields if allowed. diff --git a/internal/template.go b/internal/template.go index 45fc410..a15e05d 100644 --- a/internal/template.go +++ b/internal/template.go @@ -2,6 +2,7 @@ package internal import ( "bytes" + "path/filepath" "strings" "text/template" @@ -37,6 +38,10 @@ type TemplateData struct { // Computed Values UsesStatement string `json:"uses_statement"` + // Path information for subdirectory extraction + ActionPath string `json:"action_path,omitempty"` + RepoRoot string `json:"repo_root,omitempty"` + // Dependencies (populated by dependency analysis) Dependencies []dependencies.Dependency `json:"dependencies,omitempty"` } @@ -122,41 +127,98 @@ func formatVersion(version string) string { return version } -// buildUsesString constructs the uses string with optional action name. +// buildUsesString constructs the uses string with optional subdirectory path. func buildUsesString(td *TemplateData, org, repo, version string) string { // Use the validation package's FormatUsesStatement for consistency if org == "" || repo == "" { return appconstants.DefaultUsesPlaceholder } - // For actions within subdirectories, include the action name - if td.Name != "" && repo != "" { - actionName := validation.SanitizeActionName(td.Name) - if actionName != "" && actionName != repo { - // Check if this looks like a subdirectory action - return validation.FormatUsesStatement(org, repo+"/"+actionName, version) - } + // For monorepo actions in subdirectories, extract the actual directory path + subdir := extractActionSubdirectory(td.ActionPath, td.RepoRoot) + + if subdir != "" { + // Action is in a subdirectory: org/repo/subdir@version + return validation.FormatUsesStatement(org, repo+"/"+subdir, version) } + // Action is at repo root: org/repo@version return validation.FormatUsesStatement(org, repo, version) } -// getActionVersion returns the action version from template data. -func getActionVersion(data any) string { - if td, ok := data.(*TemplateData); ok { - if td.Config.Version != "" { - return td.Config.Version - } +// extractActionSubdirectory extracts the subdirectory path for an action relative to repo root. +// For monorepo actions (e.g., org/repo/subdir/action.yml), returns "subdir". +// For repo-root actions (e.g., org/repo/action.yml), returns empty string. +// Returns empty string if paths cannot be determined. +func extractActionSubdirectory(actionPath, repoRoot string) string { + // Validate inputs + if actionPath == "" || repoRoot == "" { + return "" } + // Get absolute paths for reliable comparison + absActionPath, err := filepath.Abs(actionPath) + if err != nil { + return "" + } + + absRepoRoot, err := filepath.Abs(repoRoot) + if err != nil { + return "" + } + + // Get the directory containing action.yml + actionDir := filepath.Dir(absActionPath) + + // Calculate relative path from repo root to action directory + relPath, err := filepath.Rel(absRepoRoot, actionDir) + if err != nil { + return "" + } + + // If relative path is "." or empty, action is at repo root + if relPath == "." || relPath == "" { + return "" + } + + // If relative path starts with "..", action is outside repo (shouldn't happen) + if strings.HasPrefix(relPath, "..") { + return "" + } + + // Return the subdirectory path (e.g., "actions/csharp-build") + return relPath +} + +// getActionVersion returns the action version from template data. +// Priority: 1) Config.Version (explicit override), 2) Default branch (if enabled), 3) "v1" (fallback). +func getActionVersion(data any) string { + td, ok := data.(*TemplateData) + if !ok { + return "v1" + } + + // Priority 1: Explicit version override + if td.Config.Version != "" { + return td.Config.Version + } + + // Priority 2: Use default branch if enabled and available + if td.Config.UseDefaultBranch && td.Git.DefaultBranch != "" { + return td.Git.DefaultBranch + } + + // Priority 3: Fallback return "v1" } // BuildTemplateData constructs comprehensive template data from action and configuration. func BuildTemplateData(action *ActionYML, config *AppConfig, repoRoot, actionPath string) *TemplateData { data := &TemplateData{ - ActionYML: action, - Config: config, + ActionYML: action, + Config: config, + ActionPath: actionPath, + RepoRoot: repoRoot, } // Populate Git information diff --git a/templates/footer.tmpl b/templates/footer.tmpl deleted file mode 100644 index e9123e0..0000000 --- a/templates/footer.tmpl +++ /dev/null @@ -1,5 +0,0 @@ - - - diff --git a/templates/header.tmpl b/templates/header.tmpl deleted file mode 100644 index bcd7d24..0000000 --- a/templates/header.tmpl +++ /dev/null @@ -1,15 +0,0 @@ - - - - - {{.Name}} GitHub Action Documentation - - - - diff --git a/templates/readme.tmpl b/templates/readme.tmpl deleted file mode 100644 index c0537ef..0000000 --- a/templates/readme.tmpl +++ /dev/null @@ -1,37 +0,0 @@ -# {{.Name}} - -{{if .Branding}} -> {{.Description}} - -## Usage - -```yaml -- uses: {{gitUsesString .}} - with: -{{- range $key, $val := .Inputs}} - {{$key}}: # {{$val.Description}}{{if $val.Default}} (default: {{$val.Default}}){{end}} -{{- end}} -``` - -## Inputs - -{{range $key, $input := .Inputs}} -- **{{$key}}**: {{$input.Description}}{{if $input.Required}} (**required**){{end}}{{if $input.Default}} (default: {{$input.Default}}){{end}} -{{end}} - -{{if .Outputs}} -## Outputs - -{{range $key, $output := .Outputs}} -- **{{$key}}**: {{$output.Description}} -{{end}} -{{end}} - -## Example - -See the [action.yml](./action.yml) for a full reference. - ---- - -*Auto-generated by [gh-action-readme](https://github.com/ivuorinen/gh-action-readme)* -{{end}} diff --git a/templates/themes/asciidoc/readme.adoc b/templates/themes/asciidoc/readme.adoc deleted file mode 100644 index dd99d8c..0000000 --- a/templates/themes/asciidoc/readme.adoc +++ /dev/null @@ -1,176 +0,0 @@ -= {{.Name}} -:toc: left -:toclevels: 3 -:icons: font -:source-highlighter: highlight.js - -{{if .Branding}}image:https://img.shields.io/badge/icon-{{.Branding.Icon}}-{{.Branding.Color}}[{{.Branding.Icon}}] {{end}}+ -image:https://img.shields.io/badge/GitHub%20Action-{{.Name | replace " " "%20"}}-blue[GitHub Action] + -image:https://img.shields.io/badge/license-MIT-green[License] - -[.lead] -{{.Description}} - -== Quick Start - -Add this action to your GitHub workflow: - -[source,yaml] ----- -name: CI Workflow -on: [push, pull_request] - -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - name: {{.Name}} - uses: {{gitUsesString .}} - {{if .Inputs}}with: - {{- range $key, $val := .Inputs}} - {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"value"{{end}} - {{- end}}{{end}} ----- - -{{if .Inputs}} -== Input Parameters - -[cols="1,3,1,2", options="header"] -|=== -| Parameter | Description | Required | Default - -{{range $key, $input := .Inputs}} -| `{{$key}}` -| {{$input.Description}} -| {{if $input.Required}}✓{{else}}✗{{end}} -| {{if $input.Default}}`{{$input.Default}}`{{else}}_none_{{end}} - -{{end}} -|=== - -=== Parameter Details - -{{range $key, $input := .Inputs}} -==== {{$key}} - -{{$input.Description}} - -[horizontal] -Type:: String -Required:: {{if $input.Required}}Yes{{else}}No{{end}} -{{if $input.Default}}Default:: `{{$input.Default}}`{{end}} - -.Example -[source,yaml] ----- -with: - {{$key}}: {{if $input.Default}}"{{$input.Default}}"{{else}}"your-value"{{end}} ----- - -{{end}} -{{end}} - -{{if .Outputs}} -== Output Parameters - -[cols="1,3", options="header"] -|=== -| Parameter | Description - -{{range $key, $output := .Outputs}} -| `{{$key}}` -| {{$output.Description}} - -{{end}} -|=== - -=== Using Outputs - -[source,yaml] ----- -- name: {{.Name}} - id: action-step - uses: {{gitUsesString .}} - -- name: Use Output - run: | - {{- range $key, $output := .Outputs}} - echo "{{$key}}: \${{"{{"}} steps.action-step.outputs.{{$key}} {{"}}"}}" - {{- end}} ----- -{{end}} - -== Examples - -=== Basic Usage - -[source,yaml] ----- -- name: Basic {{.Name}} - uses: {{gitUsesString .}} - {{if .Inputs}}with: - {{- range $key, $val := .Inputs}} - {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"example-value"{{end}} - {{- end}}{{end}} ----- - -=== Advanced Configuration - -[source,yaml] ----- -- name: Advanced {{.Name}} - uses: {{gitUsesString .}} - {{if .Inputs}}with: - {{- range $key, $val := .Inputs}} - {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"\${{"{{"}} vars.{{$key | upper}} {{"}}"}}"{{end}} - {{- end}}{{end}} - env: - GITHUB_TOKEN: \${{"{{"}} secrets.GITHUB_TOKEN {{"}}"}} ----- - -=== Conditional Usage - -[source,yaml] ----- -- name: Conditional {{.Name}} - if: github.event_name == 'push' - uses: {{gitUsesString .}} - {{if .Inputs}}with: - {{- range $key, $val := .Inputs}} - {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"production-value"{{end}} - {{- end}}{{end}} ----- - -== Troubleshooting - -[TIP] -==== -Common issues and solutions: - -1. **Authentication Errors**: Ensure required secrets are configured -2. **Permission Issues**: Verify GitHub token permissions -3. **Configuration Errors**: Validate input parameters -==== - -== Development - -For development information, see the link:./action.yml[action.yml] specification. - -=== Contributing - -Contributions are welcome! Please: - -1. Fork the repository -2. Create a feature branch -3. Make your changes -4. Add tests -5. Submit a pull request - -== License - -This project is licensed under the MIT License. - ---- - -_Documentation generated with https://github.com/ivuorinen/gh-action-readme[gh-action-readme]_ diff --git a/templates/themes/github/readme.tmpl b/templates/themes/github/readme.tmpl deleted file mode 100644 index 7b5f03d..0000000 --- a/templates/themes/github/readme.tmpl +++ /dev/null @@ -1,141 +0,0 @@ -# {{.Name}} - -{{if .Branding}}![{{.Branding.Icon}}](https://img.shields.io/badge/icon-{{.Branding.Icon}}-{{.Branding.Color}}) {{end}} -![GitHub](https://img.shields.io/badge/GitHub%20Action-{{.Name | replace " " "%20"}}-blue) -![License](https://img.shields.io/badge/license-MIT-green) - -> {{.Description}} - -## 🚀 Quick Start - -```yaml -name: My Workflow -on: [push, pull_request] - -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - name: {{.Name}} - uses: {{gitUsesString .}} - {{if .Inputs}}with: - {{- range $key, $val := .Inputs}} - {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"value"{{end}} - {{- end}}{{end}} -``` - -{{if .Inputs}} -## 📥 Inputs - -| Parameter | Description | Required | Default | -|-----------|-------------|----------|---------| -{{- range $key, $input := .Inputs}} -| `{{$key}}` | {{$input.Description}} | {{if $input.Required}}✅{{else}}❌{{end}} | {{if $input.Default}}`{{$input.Default}}`{{else}}-{{end}} | -{{- end}} -{{end}} - -{{if .Outputs}} -## 📤 Outputs - -| Parameter | Description | -|-----------|-------------| -{{- range $key, $output := .Outputs}} -| `{{$key}}` | {{$output.Description}} | -{{- end}} -{{end}} - -## 💡 Examples - -
-Basic Usage - -```yaml -- name: {{.Name}} - uses: {{gitUsesString .}} - {{if .Inputs}}with: - {{- range $key, $val := .Inputs}} - {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"example-value"{{end}} - {{- end}}{{end}} -``` -
- -
-Advanced Configuration - -```yaml -- name: {{.Name}} with custom settings - uses: {{gitUsesString .}} - {{if .Inputs}}with: - {{- range $key, $val := .Inputs}} - {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"custom-value"{{end}} - {{- end}}{{end}} -``` -
- -{{if .Dependencies}} -## 📦 Dependencies - -This action uses the following dependencies: - -| Action | Version | Author | Description | -|--------|---------|--------|-------------| -{{- range .Dependencies}} -| {{if .MarketplaceURL}}[{{.Name}}]({{.MarketplaceURL}}){{else}}{{.Name}}{{end}} | {{if .IsPinned}}🔒{{end}}{{.Version}} | [{{.Author}}](https://github.com/{{.Author}}) | {{.Description}} | -{{- end}} - -
-📋 Dependency Details - -{{range .Dependencies}} -### {{.Name}}{{if .Version}} @ {{.Version}}{{end}} - -{{if .IsPinned}} -- 🔒 **Pinned Version**: Locked to specific version for security -{{else}} -- 📌 **Floating Version**: Using latest version (consider pinning for security) -{{end}} -- 👤 **Author**: [{{.Author}}](https://github.com/{{.Author}}) -{{if .MarketplaceURL}}- 🏪 **Marketplace**: [View on GitHub Marketplace]({{.MarketplaceURL}}){{end}} -{{if .SourceURL}}- 📂 **Source**: [View Source]({{.SourceURL}}){{end}} -{{if .WithParams}} -- **Configuration**: - ```yaml - with: - {{- range $key, $value := .WithParams}} - {{$key}}: {{$value}} - {{- end}} - ``` -{{end}} - -{{end}} - -{{$hasLocalDeps := false}} -{{range .Dependencies}}{{if .IsLocalAction}}{{$hasLocalDeps = true}}{{end}}{{end}} -{{if $hasLocalDeps}} -### Same Repository Dependencies -{{range .Dependencies}}{{if .IsLocalAction}} -- [{{.Name}}]({{.SourceURL}}) - {{.Description}} -{{end}}{{end}} -{{end}} - -
-{{end}} - -## 🔧 Development - -See the [action.yml](./action.yml) for the complete action specification. - -## 📄 License - -This action is distributed under the MIT License. See [LICENSE](LICENSE) for more information. - -## 🤝 Contributing - -Contributions are welcome! Please feel free to submit a Pull Request. - ---- - -
- 🚀 Generated with gh-action-readme -
diff --git a/templates/themes/gitlab/readme.tmpl b/templates/themes/gitlab/readme.tmpl deleted file mode 100644 index 77e22ea..0000000 --- a/templates/themes/gitlab/readme.tmpl +++ /dev/null @@ -1,94 +0,0 @@ -# {{.Name}} - -{{if .Branding}}**{{.Branding.Icon}}** {{end}}**{{.Description}}** - ---- - -## Installation - -Add this action to your GitLab CI/CD pipeline or GitHub workflow: - -### GitHub Actions - -```yaml -steps: - - name: {{.Name}} - uses: {{gitUsesString .}} - {{if .Inputs}}with: - {{- range $key, $val := .Inputs}} - {{$key}}: {{if $val.Default}}{{$val.Default}}{{else}}value{{end}} - {{- end}}{{end}} -``` - -### GitLab CI/CD - -```yaml -{{.Name | lower | replace " " "-"}}: - stage: build - image: node:20 - script: - - # Your action logic here - {{if .Inputs}}variables: - {{- range $key, $val := .Inputs}} - {{$key | upper}}: {{if $val.Default}}{{$val.Default}}{{else}}value{{end}} - {{- end}}{{end}} -``` - -## Configuration - -{{if .Inputs}} -### Input Parameters - -{{range $key, $input := .Inputs}} -#### `{{$key}}` -- **Description**: {{$input.Description}} -- **Type**: String{{if $input.Required}} -- **Required**: Yes{{else}} -- **Required**: No{{end}}{{if $input.Default}} -- **Default**: `{{$input.Default}}`{{end}} - -{{end}} -{{end}} - -{{if .Outputs}} -### Output Parameters - -{{range $key, $output := .Outputs}} -#### `{{$key}}` -- **Description**: {{$output.Description}} - -{{end}} -{{end}} - -## Usage Examples - -### Basic Example - -```yaml -{{.Name | lower | replace " " "-"}}: - stage: deploy - script: - - echo "Using {{.Name}}" - {{if .Inputs}}variables: - {{- range $key, $val := .Inputs}} - {{$key | upper}}: "{{if $val.Default}}{{$val.Default}}{{else}}example{{end}}" - {{- end}}{{end}} -``` - -### Advanced Example - -For more complex scenarios, refer to the [action.yml](./action.yml) specification. - -## Documentation - -- [Action specification](./action.yml) -- [Usage examples](./examples/) -- [Contributing guidelines](./CONTRIBUTING.md) - -## License - -This project is licensed under the MIT License. - ---- - -*Generated with [gh-action-readme](https://github.com/ivuorinen/gh-action-readme)* diff --git a/templates/themes/minimal/readme.tmpl b/templates/themes/minimal/readme.tmpl deleted file mode 100644 index 199f934..0000000 --- a/templates/themes/minimal/readme.tmpl +++ /dev/null @@ -1,33 +0,0 @@ -# {{.Name}} - -{{.Description}} - -## Usage - -```yaml -- uses: {{gitUsesString .}} - {{if .Inputs}}with: - {{- range $key, $val := .Inputs}} - {{$key}}: {{if $val.Default}}{{$val.Default}}{{else}}value{{end}} - {{- end}}{{end}} -``` - -{{if .Inputs}} -## Inputs - -{{range $key, $input := .Inputs}} -- `{{$key}}` - {{$input.Description}}{{if $input.Required}} (required){{end}}{{if $input.Default}} (default: `{{$input.Default}}`){{end}} -{{end}} -{{end}} - -{{if .Outputs}} -## Outputs - -{{range $key, $output := .Outputs}} -- `{{$key}}` - {{$output.Description}} -{{end}} -{{end}} - -## License - -MIT diff --git a/templates/themes/professional/readme.tmpl b/templates/themes/professional/readme.tmpl deleted file mode 100644 index b2eba1e..0000000 --- a/templates/themes/professional/readme.tmpl +++ /dev/null @@ -1,245 +0,0 @@ -# {{.Name}} - -{{if .Branding}} -
- {{.Branding.Icon}} - Status - License -
-{{end}} - -## Overview - -{{.Description}} - -This GitHub Action provides a robust solution for your CI/CD pipeline with comprehensive configuration options and detailed output information. - -## Table of Contents - -- [Quick Start](#quick-start) -- [Configuration](#configuration) -{{if .Inputs}}- [Input Parameters](#input-parameters){{end}} -{{if .Outputs}}- [Output Parameters](#output-parameters){{end}} -- [Examples](#examples) -{{if .Dependencies}}- [Dependencies](#-dependencies){{end}} -- [Troubleshooting](#troubleshooting) -- [Contributing](#contributing) -- [License](#license) - -## Quick Start - -Add the following step to your GitHub Actions workflow: - -```yaml -name: CI/CD Pipeline -on: - push: - branches: [ main, develop ] - pull_request: - branches: [ main ] - -jobs: - build: - runs-on: ubuntu-latest - - steps: - - name: Checkout Repository - uses: actions/checkout@v4 - - - name: {{.Name}} - uses: {{gitUsesString .}} - {{if .Inputs}}with: - {{- range $key, $val := .Inputs}} - {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"your-value-here"{{end}} - {{- end}}{{end}} -``` - -## Configuration - -This action supports various configuration options to customize its behavior according to your needs. - -{{if .Inputs}} -### Input Parameters - -| Parameter | Description | Type | Required | Default Value | -|-----------|-------------|------|----------|---------------| -{{- range $key, $input := .Inputs}} -| **`{{$key}}`** | {{$input.Description}} | `string` | {{if $input.Required}}✅ Yes{{else}}❌ No{{end}} | {{if $input.Default}}`{{$input.Default}}`{{else}}_None_{{end}} | -{{- end}} - -#### Parameter Details - -{{range $key, $input := .Inputs}} -##### `{{$key}}` - -{{$input.Description}} - -- **Type**: String -- **Required**: {{if $input.Required}}Yes{{else}}No{{end}}{{if $input.Default}} -- **Default**: `{{$input.Default}}`{{end}} - -```yaml -with: - {{$key}}: {{if $input.Default}}"{{$input.Default}}"{{else}}"your-value-here"{{end}} -``` - -{{end}} -{{end}} - -{{if .Outputs}} -### Output Parameters - -This action provides the following outputs that can be used in subsequent workflow steps: - -| Parameter | Description | Usage | -|-----------|-------------|-------| -{{- range $key, $output := .Outputs}} -| **`{{$key}}`** | {{$output.Description}} | `\${{"{{"}} steps.{{$.Name | lower | replace " " "-"}}.outputs.{{$key}} {{"}}"}}` | -{{- end}} - -#### Using Outputs - -```yaml -- name: {{.Name}} - id: action-step - uses: {{gitUsesString .}} - -- name: Use Output - run: | - {{- range $key, $output := .Outputs}} - echo "{{$key}}: \${{"{{"}} steps.action-step.outputs.{{$key}} {{"}}"}}" - {{- end}} -``` -{{end}} - -## Examples - -### Basic Usage - -```yaml -- name: Basic {{.Name}} - uses: {{gitUsesString .}} - {{if .Inputs}}with: - {{- range $key, $val := .Inputs}} - {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"example-value"{{end}} - {{- end}}{{end}} -``` - -### Advanced Configuration - -```yaml -- name: Advanced {{.Name}} - uses: {{gitUsesString .}} - {{if .Inputs}}with: - {{- range $key, $val := .Inputs}} - {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"\${{"{{"}} vars.{{$key | upper}} {{"}}"}}"{{end}} - {{- end}}{{end}} - env: - GITHUB_TOKEN: \${{"{{"}} secrets.GITHUB_TOKEN {{"}}"}} -``` - -### Conditional Usage - -```yaml -- name: Conditional {{.Name}} - if: github.event_name == 'push' - uses: {{gitUsesString .}} - {{if .Inputs}}with: - {{- range $key, $val := .Inputs}} - {{$key}}: {{if $val.Default}}"{{$val.Default}}"{{else}}"production-value"{{end}} - {{- end}}{{end}} -``` - -{{if .Dependencies}} -## 📦 Dependencies - -This action uses the following dependencies: - -| Action | Version | Author | Description | -|--------|---------|--------|-------------| -{{- range .Dependencies}} -| {{if .MarketplaceURL}}[{{.Name}}]({{.MarketplaceURL}}){{else}}{{.Name}}{{end}} | {{if .IsPinned}}🔒{{end}}{{.Version}} | [{{.Author}}](https://github.com/{{.Author}}) | {{.Description}} | -{{- end}} - -
-📋 Dependency Details - -{{range .Dependencies}} -### {{.Name}}{{if .Version}} @ {{.Version}}{{end}} - -{{if .IsPinned}} -- 🔒 **Pinned Version**: Locked to specific version for security -{{else}} -- 📌 **Floating Version**: Using latest version (consider pinning for security) -{{end}} -- 👤 **Author**: [{{.Author}}](https://github.com/{{.Author}}) -{{if .MarketplaceURL}}- 🏪 **Marketplace**: [View on GitHub Marketplace]({{.MarketplaceURL}}){{end}} -{{if .SourceURL}}- 📂 **Source**: [View Source]({{.SourceURL}}){{end}} -{{if .WithParams}} -- **Configuration**: - ```yaml - with: - {{- range $key, $value := .WithParams}} - {{$key}}: {{$value}} - {{- end}} - ``` -{{end}} - -{{end}} - -{{$hasLocalDeps := false}} -{{range .Dependencies}}{{if .IsLocalAction}}{{$hasLocalDeps = true}}{{end}}{{end}} -{{if $hasLocalDeps}} -### Same Repository Dependencies -{{range .Dependencies}}{{if .IsLocalAction}} -- [{{.Name}}]({{.SourceURL}}) - {{.Description}} -{{end}}{{end}} -{{end}} - -
-{{end}} - -## Troubleshooting - -### Common Issues - -1. **Authentication Errors**: Ensure you have set up the required secrets in your repository settings. -2. **Permission Issues**: Check that your GitHub token has the necessary permissions. -3. **Configuration Errors**: Validate your input parameters against the schema. - -### Getting Help - -- Check the [action.yml](./action.yml) for the complete specification -- Review the [examples](./examples/) directory for more use cases -- Open an issue if you encounter problems - -## Contributing - -We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details. - -### Development Setup - -1. Fork this repository -2. Create a feature branch -3. Make your changes -4. Add tests if applicable -5. Submit a pull request - -## License - -This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details. - -## Support - -If you find this action helpful, please consider: - -- ⭐ Starring this repository -- 🐛 Reporting issues -- 💡 Suggesting improvements -- 🤝 Contributing code - ---- - -
- 📚 Documentation generated with gh-action-readme -