From 4183c711f97abbb33565835e61bddd96922402ae Mon Sep 17 00:00:00 2001 From: Romain Lespinasse Date: Sun, 3 Nov 2024 16:09:39 +0100 Subject: [PATCH] rewrited by raise --- README.md | 153 +++++++++++-------------- docs/conflicts.md | 74 ------------ docs/getting-started/basic-usage.md | 118 +++++++++++++++++++ docs/getting-started/installation.md | 82 +++++++++++++ docs/getting-started/quick-start.md | 48 ++++++++ docs/github-variables.md | 64 ----------- docs/guides/linux-usage.md | 74 ++++++++++++ docs/guides/macos-usage.md | 75 ++++++++++++ docs/guides/migration-guide.md | 78 +++++++++++++ docs/guides/url-usage.md | 70 +++++++++++ docs/guides/windows-usage.md | 77 +++++++++++++ docs/migration.md | 79 ------------- docs/partial-variables.md | 48 -------- docs/reference/conflicts.md | 92 +++++++++++++++ docs/reference/troubleshooting.md | 95 +++++++++++++++ docs/short-variables.md | 44 ------- docs/slug-url-variables.md | 88 -------------- docs/slug-variables.md | 77 ------------- docs/variables/overview.md | 75 ++++++++++++ docs/variables/repository-variables.md | 79 +++++++++++++ docs/variables/short-sha-variables.md | 57 +++++++++ docs/variables/slug-variables.md | 67 +++++++++++ docs/variables/url-safe-variables.md | 69 +++++++++++ examples/linux-usage.yml | 42 ------- examples/macos-usage.yml | 42 ------- examples/url-use.yml | 30 ----- examples/windows-usage.yml | 42 ------- 27 files changed, 1223 insertions(+), 716 deletions(-) delete mode 100644 docs/conflicts.md create mode 100644 docs/getting-started/basic-usage.md create mode 100644 docs/getting-started/installation.md create mode 100644 docs/getting-started/quick-start.md delete mode 100644 docs/github-variables.md create mode 100644 docs/guides/linux-usage.md create mode 100644 docs/guides/macos-usage.md create mode 100644 docs/guides/migration-guide.md create mode 100644 docs/guides/url-usage.md create mode 100644 docs/guides/windows-usage.md delete mode 100644 docs/migration.md delete mode 100644 docs/partial-variables.md create mode 100644 docs/reference/conflicts.md create mode 100644 docs/reference/troubleshooting.md delete mode 100644 docs/short-variables.md delete mode 100644 docs/slug-url-variables.md delete mode 100644 docs/slug-variables.md create mode 100644 docs/variables/overview.md create mode 100644 docs/variables/repository-variables.md create mode 100644 docs/variables/short-sha-variables.md create mode 100644 docs/variables/slug-variables.md create mode 100644 docs/variables/url-safe-variables.md delete mode 100644 examples/linux-usage.yml delete mode 100644 examples/macos-usage.yml delete mode 100644 examples/url-use.yml delete mode 100644 examples/windows-usage.yml diff --git a/README.md b/README.md index a3ebee1..993b951 100644 --- a/README.md +++ b/README.md @@ -1,116 +1,97 @@ # GitHub Slug Action -A powerful GitHub Action that exposes slug/short versions of GitHub environment variables for enhanced workflow management. +Generate slug and url-safe variables for your GitHub Actions workflows based on GitHub environment variables. -## Features - -- Converts environment variables to slug format (lowercase, URL-friendly) -- Provides URL-safe versions of variables -- Generates shortened versions of commit SHAs -- Maintains case-sensitive options -- Supports custom prefixes and length configurations - -## Quick Start - -```yaml -- name: Enhanced GitHub environment variables - uses: rlespinasse/github-slug-action@v5 -``` - -## Configuration Options - -### Basic Usage - -```yaml -- name: Enhanced GitHub environment variables - uses: rlespinasse/github-slug-action@v5 -``` - -### With Custom Prefix - -```yaml -- name: Enhanced GitHub environment variables - uses: rlespinasse/github-slug-action@v5 - with: - prefix: CI_ -``` - -### With Custom Slug Length - -```yaml -- name: Enhanced GitHub environment variables - uses: rlespinasse/github-slug-action@v5 - with: - slug-maxlength: 80 # Use 'nolimit' for unlimited length (Default: 63) -``` - -### With Custom Short Length +## ๐Ÿš€ Quick Start ```yaml -- name: Enhanced GitHub environment variables - uses: rlespinasse/github-slug-action@v5 - with: - short-length: 7 # Default: Git-determined, use 8 for v3.x compatibility +steps: + - uses: rlespinasse/github-slug-action@v5 + - name: Print slug variables + run: | + echo "Repository: ${{ env.GITHUB_REPOSITORY_SLUG }}" + echo "Branch Name: ${{ env.GITHUB_REF_NAME }}" + echo "Branch Ref: ${{ env.GITHUB_REF_SLUG }}" + echo "SHA: ${{ env.GITHUB_SHA_SHORT }}" ``` -## Available Variables - -### Enhanced Variables - -- `GITHUB_REF_NAME`: Reference name (branch/tag) +## ๐Ÿ“– Table of Contents -### Partial Variables +- [GitHub Slug Action](#github-slug-action) + - [๐Ÿš€ Quick Start](#-quick-start) + - [๐Ÿ“– Table of Contents](#-table-of-contents) + - [โœจ Features](#-features) + - [๐Ÿ”ง Usage](#-usage) + - [๐Ÿ“‹ Available Variables](#-available-variables) + - [๐Ÿ’ก Examples](#-examples) + - [Branch Deployment](#branch-deployment) + - [๐Ÿ“š Documentation](#-documentation) + - [๐Ÿค Contributing](#-contributing) + - [๐Ÿ“„ License](#-license) -- `GITHUB_REPOSITORY_OWNER_PART` -- `GITHUB_REPOSITORY_NAME_PART` +## โœจ Features -### Slug Variables +- Generates clean, URL-safe slugs from GitHub variables +- Supports Windows and Linux runners +- Provides multiple variable formats: + - Standard slugs + - URL-safe slugs + - Short SHA versions +- Zero configuration required +- Lightweight and fast execution -- `GITHUB_REPOSITORY_SLUG` -- `GITHUB_REF_SLUG` -- `GITHUB_HEAD_REF_SLUG` -- And more... +## ๐Ÿ”ง Usage -### Short Variables +1. Add the action to your workflow +2. Access generated variables in subsequent steps +3. Use in conditions, environment names, or deployment URLs -- `GITHUB_SHA_SHORT` -- `GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT` +See our [Getting Started Guide](docs/getting-started/quick-start.md) for detailed instructions. -## Troubleshooting +## ๐Ÿ“‹ Available Variables -### Common Issues +| Category | Original | Generated Slug | URL-Safe | +| ---------- | ------------------- | ------------------------ | ---------------------------- | +| Repository | `GITHUB_REPOSITORY` | `GITHUB_REPOSITORY_SLUG` | `GITHUB_REPOSITORY_SLUG_URL` | +| Branch/Tag | `GITHUB_REF` | `GITHUB_REF_SLUG` | `GITHUB_REF_SLUG_URL` | +| SHA | `GITHUB_SHA` | `GITHUB_SHA_SHORT` | - | -1. **Short Variable Length Changes** - - Use `short-length` input to maintain consistent lengths - - Minimum length: 4 characters +[View all available variables โ†’](docs/variables/overview.md) -2. **Environment Variable Conflicts** - - Use prefix to avoid conflicts with GitHub defaults - - Check [known conflicts documentation](docs/conflicts.md) +## ๐Ÿ’ก Examples -### Best Practices +### Branch Deployment -- Use [Dependabot](https://docs.github.com/en/code-security/dependabot) to keep the action updated -- Always specify version tags (e.g., `@v5`) instead of branch names -- Test variables in your specific workflow context +```yaml +name: Deploy +on: push +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: rlespinasse/github-slug-action@v5 + - run: echo "Deploying to ${{ env.GITHUB_REF_SLUG }}" +``` -## Documentation +[More examples โ†’](docs/guides/) -Detailed documentation available for: +## ๐Ÿ“š Documentation -- [Slug Variables](docs/slug-variables.md) -- [URL Variables](docs/slug-url-variables.md) -- [Short Variables](docs/short-variables.md) -- [GitHub Variables](docs/github-variables.md) +- [Getting Started](docs/getting-started/) +- [Variable Reference](docs/variables/) +- [Usage Guides](docs/guides/) +- [Troubleshooting](docs/reference/troubleshooting.md) -## Contributing +## ๐Ÿค Contributing -Issues and pull requests are welcome! Please check our [contribution guidelines](CONTRIBUTING.md). +Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details. -## License +## ๐Ÿ“„ License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. --- -For detailed examples and advanced usage, visit our [GitHub repository](https://github.com/rlespinasse/github-slug-action). +โญ If this action helps you, please consider giving it a star! + +[Report Bug](https://github.com/rlespinasse/github-slug-action/issues) ยท [Request Feature](https://github.com/rlespinasse/github-slug-action/issues) diff --git a/docs/conflicts.md b/docs/conflicts.md deleted file mode 100644 index a8d873e..0000000 --- a/docs/conflicts.md +++ /dev/null @@ -1,74 +0,0 @@ -# Known Environment Variable Conflicts - -This document details known conflicts between GitHub Slug Action variables and GitHub Actions default environment variables. - -## GITHUB_REF_NAME - -> [!CAUTION] -> This conflict happen with the version 3 and 4 for GitHub Slug Action. -> For a smooth transition, check our [migration guide to v5](docs/migration.md). - -### Issue Description - -A conflict exists in the behavior of `GITHUB_REF_NAME` during `pull_request*` workflows. - -### Behavior Differences - -- **GitHub Slug Action**: Returns the branch name -- **GitHub Actions Default**: Returns `/merge` - -### Usage Impact - -```yaml -# Different behaviors: -${{ env.GITHUB_REF_NAME }} # GitHub Slug Action behavior -$GITHUB_REF_NAME # GitHub Actions default behavior -``` - -### Recommended Solution - -Use the `prefix` input to avoid conflicts: - -```yaml -- name: Enhanced GitHub environment variables - uses: rlespinasse/github-slug-action@v5 - with: - prefix: CI_ - -# Then use: -${{ env.CI_GITHUB_REF_NAME }} # GitHub Slug Action behavior -$CI_GITHUB_REF_NAME # GitHub Slug Action behavior -$GITHUB_REF_NAME # GitHub Actions default behavior -``` - -## General Conflict Prevention - -### Best Practices - -1. Always use the `prefix` input when working with sensitive variables -2. Test variable behavior in your specific workflow context -3. Document any custom prefixes in your workflow files -4. Consider using explicit variable references (`${{ env.VAR_NAME }}`) for clarity - -### Default Variables Protection - -GitHub Actions prevents overriding default environment variables. If you attempt to set a variable that matches a default name: - -- The assignment will be ignored -- The default behavior will be preserved -- No error message will be displayed - -For a complete list of protected variables, see [GitHub's Default Environment Variables](https://docs.github.com/en/actions/learn-github-actions/environment-variables#default-environment-variables). - -## Reporting New Conflicts - -If you discover a new conflict: - -1. Create an issue in the [GitHub repository](https://github.com/rlespinasse/github-slug-action/issues) -2. Include: - - The conflicting variable name - - Expected vs. actual behavior - - Your workflow context - - Steps to reproduce - -This helps maintain documentation and find appropriate solutions for the community. diff --git a/docs/getting-started/basic-usage.md b/docs/getting-started/basic-usage.md new file mode 100644 index 0000000..1d6c507 --- /dev/null +++ b/docs/getting-started/basic-usage.md @@ -0,0 +1,118 @@ +# Basic Usage Guide + +## Overview + +GitHub Slug Action converts GitHub environment variables into URL-safe slugs. Here's how to use them effectively. + +## Core Variables + +```yaml +steps: + - uses: rlespinasse/github-slug-action@v5 + - name: Example Usage + run: | + # Branch or tag slug + echo ${{ env.GITHUB_REF_SLUG }} + + # Repository slug + echo ${{ env.GITHUB_REPOSITORY_SLUG }} + + # Short SHA + echo ${{ env.GITHUB_SHA_SHORT }} +``` + +## Common Patterns + +### Environment Names + +```yaml +environment: ${{ env.GITHUB_REF_SLUG }} +``` + +### Dynamic URLs + +```yaml +url: https://${{ env.GITHUB_REF_SLUG }}.example.com +``` + +### Docker Tags + +```yaml +tags: ${{ env.GITHUB_REPOSITORY_SLUG }}:${{ env.GITHUB_SHA_SHORT }} +``` + +## Platform-Specific Usage + +### Linux/macOS + +```bash +echo $GITHUB_REF_SLUG +``` + +### Windows CMD + +```cmd +echo %GITHUB_REF_SLUG% +``` + +### PowerShell + +```powershell +Write-Host $env:GITHUB_REF_SLUG +``` + +## Variable Availability + +- Variables are available after the action runs +- Accessible within the same job +- Must re-run action in different jobs +- Available in both scripts and workflow files + +## Examples + +### Pull Request Environments + +```yaml +name: Deploy Preview +on: pull_request + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: rlespinasse/github-slug-action@v5 + - name: Deploy + run: | + deploy --env="pr-${{ env.GITHUB_HEAD_REF_SLUG }}" +``` + +### Branch Deployments + +```yaml +name: Deploy Branch +on: push + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: rlespinasse/github-slug-action@v5 + - name: Deploy + run: | + deploy --env="${{ env.GITHUB_REF_SLUG }}" +``` + +## Best Practices + +- Run the action early in your workflow +- Use consistent variable references +- Consider error handling for critical steps +- Cache slugs for reuse when possible + +## Related Resources + +- [Available Variables](../variables/overview.md) +- [Advanced Usage](../guides/advanced-usage.md) +- [Troubleshooting](../reference/troubleshooting.md) + +Need help? [Open an issue](https://github.com/rlespinasse/github-slug-action/issues) diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md new file mode 100644 index 0000000..42b7c06 --- /dev/null +++ b/docs/getting-started/installation.md @@ -0,0 +1,82 @@ +# Installation Guide + +## Requirements + +- GitHub Actions workflow +- GitHub-hosted or self-hosted runner + +## Basic Installation + +Add this step to your workflow: + +```yaml +steps: + - uses: rlespinasse/github-slug-action@v5 +``` + +## Version Selection + +### Latest Version (Recommended) + +```yaml +- uses: rlespinasse/github-slug-action@v5 +``` + +### Specific Version + +```yaml +- uses: rlespinasse/github-slug-action@v5.2.0 +``` + +### Main Branch (Not Recommended) + +```yaml +- uses: rlespinasse/github-slug-action@v5.x +``` + +## Installation Options + +### Minimal Setup + +```yaml +steps: + - uses: rlespinasse/github-slug-action@v5 +``` + +### With Error Handling + +```yaml +steps: + - uses: rlespinasse/github-slug-action@v5 + id: slug + continue-on-error: true +``` + +## Verification + +Add this step after installation to verify: + +```yaml +- name: Verify Installation + shell: bash + run: | + echo "GITHUB_REPOSITORY_SLUG: ${{ env.GITHUB_REPOSITORY_SLUG }}" + echo "GITHUB_REF_SLUG: ${{ env.GITHUB_REF_SLUG }}" +``` + +## Next Steps + +1. Review the [Quick Start Guide](quick-start.md) +2. Explore [Available Variables](../variables/overview.md) +3. Check [Common Patterns](../guides/common-patterns.md) + +## Troubleshooting + +If you encounter issues: + +1. Verify your workflow syntax +2. Check runner compatibility +3. Ensure proper permissions +4. Review [Troubleshooting Guide](../reference/troubleshooting.md) + +Need help? [Open an issue](https://github.com/rlespinasse/github-slug-action/issues) diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md new file mode 100644 index 0000000..6e71114 --- /dev/null +++ b/docs/getting-started/quick-start.md @@ -0,0 +1,48 @@ +# Quick Start Guide + +## Installation + +```yaml +- uses: rlespinasse/github-slug-action@v5 +``` + +## Basic Example + +```yaml +name: Example Workflow +on: [push] + +jobs: + example: + runs-on: ubuntu-latest + steps: + - uses: rlespinasse/github-slug-action@v5 + - name: Print Slugs + run: | + echo "Repository: ${{ env.GITHUB_REPOSITORY_SLUG }}" + echo "Branch: ${{ env.GITHUB_REF_SLUG }}" + echo "SHA: ${{ env.GITHUB_SHA_SHORT }}" +``` + +## Key Features + +- ๐Ÿ”„ Automatic slug generation +- ๐Ÿ”’ URL-safe variable creation +- ๐Ÿ’จ Zero configuration needed +- โšก Instant availability + +## Common Variables + +| Original | Slug Version | Example | +| --------------------- | ------------------------ | --------------------- | +| `feature/new-page` | `GITHUB_REF_SLUG` | `feature-new-page` | +| `octocat/Hello-World` | `GITHUB_REPOSITORY_SLUG` | `octocat-hello-world` | +| `a1b2c3d4e5f6` | `GITHUB_SHA_SHORT` | `a1b2c3d4` | + +## Next Steps + +1. Check [available variables](../variables/overview.md) +2. See [usage examples](../guides/common-patterns.md) +3. Review [best practices](../guides/best-practices.md) + +Need help? [Open an issue](https://github.com/rlespinasse/github-slug-action/issues) diff --git a/docs/github-variables.md b/docs/github-variables.md deleted file mode 100644 index 5811a60..0000000 --- a/docs/github-variables.md +++ /dev/null @@ -1,64 +0,0 @@ -# GitHub Variables Reference - -This document outlines the GitHub variables available in your workflows, including those provided by GitHub Slug Action. - -## Default Environment Variables - -For a complete list of default variables, see the [GitHub Actions Environment Variables documentation][1]. - -### Action-Enhanced Variables - -The following default GitHub variables can be enhanced with additional formats: - -| Base Variable | Available Enhancements | -| ----------------- | ---------------------- | -| GITHUB_REPOSITORY | `_SLUG`, `_SLUG_URL` | -| GITHUB_REF | `_SLUG`, `_SLUG_URL` | -| GITHUB_HEAD_REF | `_SLUG`, `_SLUG_URL` | -| GITHUB_BASE_REF | `_SLUG`, `_SLUG_URL` | -| GITHUB_SHA | `_SHORT` | - -Example: - -```yaml -# Original: refs/heads/feature/new.branch -${{ env.GITHUB_REF_SLUG }} # feature-new.branch -${{ env.GITHUB_REF_SLUG_URL }} # feature-new-branch -``` - -## Event-Specific Variables - -Additional variables are available based on the triggering event. See [Events that trigger workflows][2] for details. - -### Available Event Variables - -#### Create and Delete Events - -Reference: [Create][3] and [Delete][4] webhook payloads - -| Event Variable | Enhanced Format | -| ---------------- | ---------------------------------------------------- | -| github.event.ref | `GITHUB_EVENT_REF_SLUG`, `GITHUB_EVENT_REF_SLUG_URL` | - -#### Pull Request Events - -Applies to: `pull_request`, `pull_request_review`, `pull_request_review_comment`, and `pull_request_target` - -Reference: [Pull Request webhook payload][5] - -| Event Variable | Enhanced Format | -| ---------------------------------- | ------------------------------------------ | -| github.event.pull_request.head.sha | `GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT` | - -Example: - -```yaml -# Original SHA: 8f166fd75f36c896c63a9a0c0ccd2b42f5b0c040 -${{ env.GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT }} # 8f166fd7 -``` - -[1]: https://docs.github.com/en/actions/reference/environment-variables#default-environment-variables -[2]: https://docs.github.com/en/actions/reference/events-that-trigger-workflows -[3]: https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#create -[4]: https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#delete -[5]: https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#pull_request diff --git a/docs/guides/linux-usage.md b/docs/guides/linux-usage.md new file mode 100644 index 0000000..a754267 --- /dev/null +++ b/docs/guides/linux-usage.md @@ -0,0 +1,74 @@ +# Linux Usage Guide + +## Overview + +Guidelines for using GitHub Slug Action in Linux environments with specific considerations and best practices. + +## Linux-Specific Setup + +### Basic Configuration + +```yaml +name: Linux Build +runs-on: ubuntu-latest +steps: + - uses: rlespinasse/github-slug-action@v5 +``` + +### Shell Integration + +```yaml +steps: + - uses: rlespinasse/github-slug-action@v5 + - run: | + echo "Branch: ${{ env.GITHUB_REF_SLUG }}" + echo "Path: $GITHUB_WORKSPACE/${{ env.GITHUB_REF_SLUG }}" + shell: bash +``` + +## Common Linux Scenarios + +### Bash Usage + +```yaml +steps: + - uses: rlespinasse/github-slug-action@v5 + - shell: bash + run: | + echo "Current branch: ${GITHUB_REF_SLUG}" + echo "Working directory: ${GITHUB_WORKSPACE}/${GITHUB_REF_SLUG}" +``` + +### File Operations + +```yaml +steps: + - uses: rlespinasse/github-slug-action@v5 + - run: | + mkdir -p "build/${GITHUB_REF_SLUG}" + touch "build/${GITHUB_REF_SLUG}/build.log" +``` + +## Best Practices + +- Use proper file permissions +- Handle path separators +- Implement error checking +- Quote variable expansions +- Follow shell scripting standards + +## Shell Features + +- Variable expansion +- Command substitution +- Path manipulation +- File operations +- Environment variables + +## Related Documentation + +- [Windows Usage](windows-usage.md) +- [URL Usage](url-usage.md) +- [Version Variables](version-variables.md) + +Need help? [Open an issue](https://github.com/rlespinasse/github-slug-action/issues) diff --git a/docs/guides/macos-usage.md b/docs/guides/macos-usage.md new file mode 100644 index 0000000..6b1f35c --- /dev/null +++ b/docs/guides/macos-usage.md @@ -0,0 +1,75 @@ +# macOS Usage Guide + +## Overview + +Guidelines for using GitHub Slug Action in macOS environments with specific considerations and best practices. + +## macOS-Specific Setup + +### Basic Configuration + +```yaml +name: macOS Build +runs-on: macos-latest +steps: + - uses: rlespinasse/github-slug-action@v5 +``` + +### Shell Integration + +```yaml +steps: + - uses: rlespinasse/github-slug-action@v5 + - run: | + echo "Branch: ${{ env.GITHUB_REF_SLUG }}" + echo "Path: $GITHUB_WORKSPACE/${{ env.GITHUB_REF_SLUG }}" + shell: bash +``` + +## Common macOS Scenarios + +### Bash Usage + +```yaml +steps: + - uses: rlespinasse/github-slug-action@v5 + - shell: bash + run: | + echo "Current branch: ${GITHUB_REF_SLUG}" + echo "Working directory: ${GITHUB_WORKSPACE}/${GITHUB_REF_SLUG}" +``` + +### Xcode Integration + +```yaml +steps: + - uses: rlespinasse/github-slug-action@v5 + - run: | + xcodebuild -scheme "MyApp" \ + -configuration Release \ + -derivedDataPath "build/${GITHUB_REF_SLUG}" +``` + +## Best Practices + +- Handle case sensitivity +- Use proper file permissions +- Quote path variables +- Consider Unicode support +- Follow POSIX compliance + +## Shell Features + +- Variable expansion +- Command substitution +- Path manipulation +- File operations +- Environment variables + +## Related Documentation + +- [Linux Usage](linux-usage.md) +- [Windows Usage](windows-usage.md) +- [URL Usage](url-usage.md) + +Need help? [Open an issue](https://github.com/rlespinasse/github-slug-action/issues) diff --git a/docs/guides/migration-guide.md b/docs/guides/migration-guide.md new file mode 100644 index 0000000..f31a1b8 --- /dev/null +++ b/docs/guides/migration-guide.md @@ -0,0 +1,78 @@ +# Migration Guide + +## Overview + +This guide helps you migrate between different versions of the GitHub Slug Action. + +## v4 to v5 Migration + +### Key Changes + +- Removed deprecated variables +- Updated transformation rules +- Enhanced URL-safe handling +- Added new environment variables +- Improved performance + +### Required Updates + +1. Replace deprecated variables: + + ```diff + - ${{ env.GITHUB_REF_SLUG_URL }} + + ${{ env.GITHUB_REF_SLUG }} + ``` + +2. Update workflow syntax: + + ```yaml + steps: + - uses: rlespinasse/github-slug-action@v5 # Update version + ``` + +## v3 to v4 Migration + +### Key Changes + +- Standardized variable naming +- Simplified transformation rules +- Removed legacy support +- Added validation checks + +### Required Updates + +1. Update variable references: + + ```diff + - ${{ env.URL_SAFE_BRANCH }} + + ${{ env.GITHUB_REF_SLUG }} + ``` + +2. Review transformation outputs: + + - Lowercase conversion is now default + - Special characters handling updated + - Hyphen usage standardized + +## Best Practices + +- Test migrations in staging environment +- Update documentation references +- Review dependent workflows +- Validate transformed values +- Monitor for edge cases + +## Troubleshooting + +- Check logs for deprecation warnings +- Verify variable availability +- Test transformations +- Review GitHub Actions documentation + +## Related Documentation + +- [Slug Variables](slug-variables.md) +- [URL-Safe Variables](url-safe-variables.md) +- [Short SHA Variables](short-sha-variables.md) + +Need help? [Open an issue](https://github.com/rlespinasse/github-slug-action/issues) diff --git a/docs/guides/url-usage.md b/docs/guides/url-usage.md new file mode 100644 index 0000000..f14ba50 --- /dev/null +++ b/docs/guides/url-usage.md @@ -0,0 +1,70 @@ +# URL Usage Guide + +## Overview + +Learn how to use URL-safe variables for web-friendly references in your workflows. + +## Available URL Variables + +| Variable | Description | Input Example | Output Example | +| ---------------------- | ----------------------- | ------------------------------ | ---------------------- | +| `GITHUB_REF_SLUG` | URL-safe reference name | `refs/heads/feature/new-stuff` | `feature-new-stuff` | +| `GITHUB_HEAD_REF_SLUG` | URL-safe head reference | `feature/user/testing` | `feature-user-testing` | +| `GITHUB_BASE_REF_SLUG` | URL-safe base reference | `main/prod` | `main-prod` | + +## Usage Examples + +### Dynamic URLs + +```yaml +name: Deploy Preview +steps: + - uses: rlespinasse/github-slug-action@v5 + - run: | + echo "Preview URL: https://preview-${{ env.GITHUB_REF_SLUG }}.example.com" + shell: bash +``` + +### Artifact Naming + +```yaml +name: Build Assets +steps: + - uses: rlespinasse/github-slug-action@v5 + - uses: actions/upload-artifact@v3 + with: + name: build-${{ env.GITHUB_REF_SLUG }} + path: dist/ +``` + +## Transformation Rules + +- Converts to lowercase +- Replaces spaces with hyphens +- Removes special characters +- Trims leading/trailing hyphens +- Collapses multiple hyphens + +## Common Use Cases + +- Preview environments +- Artifact identification +- URL routing +- Branch-specific deployments +- Resource naming + +## Best Practices + +- Validate URL length limits +- Test with special characters +- Consider case sensitivity +- Document URL patterns +- Handle URL collisions + +## Related Documentation + +- [Slug Variables](slug-variables.md) +- [Version Variables](version-variables.md) +- [Migration Guide](migration-guide.md) + +Need help? [Open an issue](https://github.com/rlespinasse/github-slug-action/issues) diff --git a/docs/guides/windows-usage.md b/docs/guides/windows-usage.md new file mode 100644 index 0000000..5ccc7e7 --- /dev/null +++ b/docs/guides/windows-usage.md @@ -0,0 +1,77 @@ +# Windows Usage Guide + +## Overview + +Guidelines for using GitHub Slug Action in Windows environments with specific considerations and best practices. + +## Windows-Specific Setup + +### Environment Configuration + +```yaml +name: Windows Build +runs-on: windows-latest +steps: + - uses: rlespinasse/github-slug-action@v5 + env: + ACTIONS_ALLOW_UNSECURE_COMMANDS: true # If required for legacy systems +``` + +### Path Handling + +```yaml +steps: + - uses: rlespinasse/github-slug-action@v5 + - run: | + echo "Path: ${{ env.GITHUB_REF_SLUG }}" + echo "Full Path: %GITHUB_WORKSPACE%\${{ env.GITHUB_REF_SLUG }}" + shell: cmd +``` + +## Common Windows Scenarios + +### PowerShell Usage + +```yaml +steps: + - uses: rlespinasse/github-slug-action@v5 + - run: | + Write-Host "Branch: $env:GITHUB_REF_SLUG" + Write-Host "Path: $env:GITHUB_WORKSPACE\$env:GITHUB_REF_SLUG" + shell: pwsh +``` + +### Batch Script Integration + +```yaml +steps: + - uses: rlespinasse/github-slug-action@v5 + - run: | + echo Branch: %GITHUB_REF_SLUG% + echo Path: %GITHUB_WORKSPACE%\%GITHUB_REF_SLUG% + shell: cmd +``` + +## Best Practices + +- Use appropriate shell syntax +- Handle path separators correctly +- Consider case sensitivity +- Test variable expansion +- Validate file paths + +## Known Limitations + +- Path length restrictions +- Character encoding differences +- Shell-specific escaping +- Environment variable persistence +- Command prompt limitations + +## Related Documentation + +- [URL Usage](url-usage.md) +- [Version Variables](version-variables.md) +- [Migration Guide](migration-guide.md) + +Need help? [Open an issue](https://github.com/rlespinasse/github-slug-action/issues) diff --git a/docs/migration.md b/docs/migration.md deleted file mode 100644 index e23a080..0000000 --- a/docs/migration.md +++ /dev/null @@ -1,79 +0,0 @@ -# Migration Guide - -This guide helps you migrate between different versions of GitHub Slug Action. - -## Migrating to v5.x - -### Key Changes - -1. **GITHUB_REF_NAME Behavior Change** - - Now follows GitHub Actions default behavior - - Returns `/merge` during pull request workflows - - Previous branch name behavior available via `GITHUB_HEAD_REF` - -### Required Actions - -#### Update Pull Request Workflows - -```yaml -# Before (v4.x) -${{ env.GITHUB_REF_NAME }} # Returns branch name - -# After (v5.x) -${{ env.GITHUB_HEAD_REF }} # Returns branch name -${{ env.GITHUB_REF_NAME }} # Returns /merge -``` - -#### Review Dependent Workflows - -1. Identify workflows using `GITHUB_REF_NAME` -2. Update variable references based on intended behavior: - - ```yaml - # For branch name in pull requests - - name: Use branch name - run: echo ${{ env.GITHUB_HEAD_REF }} - - # For PR reference - - name: Use PR reference - run: echo ${{ env.GITHUB_REF_NAME }} - ``` - -### Other Improvements - -- Enhanced prefix support -- Improved slug generation consistency -- Better error handling - -## Migrating from v3.x - -### Breaking Changes - -1. **Short SHA Length** - - Default: Git-determined length - - For v3.x compatibility: - - ```yaml - with: - short-length: 8 - ``` - -2. **Variable Naming** - - More consistent naming patterns - - Better alignment with GitHub Actions standards - -### Recommended Updates - -1. Review and update workflow files -2. Test in a non-production environment -3. Update action version reference: - - ```yaml - uses: rlespinasse/github-slug-action@v5 - ``` - -## Need Help? - -- [Open an issue](https://github.com/rlespinasse/github-slug-action/issues) -- Review [documentation](https://github.com/rlespinasse/github-slug-action) -- Check [known conflicts](docs/conflicts.md) diff --git a/docs/partial-variables.md b/docs/partial-variables.md deleted file mode 100644 index f138a15..0000000 --- a/docs/partial-variables.md +++ /dev/null @@ -1,48 +0,0 @@ -# Repository Part Variables Reference - -This document details the variables that provide individual components of the repository name from the GitHub Slug Action. - -## Available Part Variables - -### GITHUB_REPOSITORY_OWNER_PART - -Extracts the owner (user or organization) name from `GITHUB_REPOSITORY` - -```yaml -# Examples -GITHUB_REPOSITORY: "octocat/Hello-World" -โ†’ GITHUB_REPOSITORY_OWNER_PART: "octocat" - -GITHUB_REPOSITORY: "rlespinasse/Hello-World.go" -โ†’ GITHUB_REPOSITORY_OWNER_PART: "rlespinasse" -``` - -### GITHUB_REPOSITORY_NAME_PART - -Extracts the repository name from `GITHUB_REPOSITORY` - -```yaml -# Examples -GITHUB_REPOSITORY: "octocat/Hello-World" -โ†’ GITHUB_REPOSITORY_NAME_PART: "Hello-World" - -GITHUB_REPOSITORY: "rlespinasse/Hello-World.go" -โ†’ GITHUB_REPOSITORY_NAME_PART: "Hello-World.go" -``` - -## Usage Details - -- Variables preserve the original case and special characters -- Useful for: - - Accessing repository components separately - - Creating custom naming patterns - - Repository-specific configurations - -## Related Variables - -- For URL-safe versions, see [Slug URL Variables](slug-url-variables.md) -- For slug versions, see [Slug Variables](slug-variables.md) - -## Related Documentation - -- [GitHub Environment Variables](https://docs.github.com/en/actions/reference/environment-variables) diff --git a/docs/reference/conflicts.md b/docs/reference/conflicts.md new file mode 100644 index 0000000..08b9112 --- /dev/null +++ b/docs/reference/conflicts.md @@ -0,0 +1,92 @@ +# Conflict Resolution Guide + +## Overview + +Guidelines for resolving conflicts when using GitHub Slug Action in your workflows, particularly when dealing with multiple actions or variable naming conflicts. + +## Common Conflicts + +### Environment Variable Conflicts + +```yaml +# Potential conflict with existing variables +steps: + - name: Previous step setting variables + run: | + echo "GITHUB_REF_SLUG=custom-value" >> $GITHUB_ENV + + - uses: rlespinasse/github-slug-action@v5 # Will override previous values +``` + +### Action Order Conflicts + +```yaml +# Order matters for variable availability +steps: + - name: Step requiring slug variables + run: echo ${{ env.GITHUB_REF_SLUG }} # Will be empty if placed before the action + + - uses: rlespinasse/github-slug-action@v5 +``` + +## Resolution Strategies + +### Custom Variable Names using prefix + +```yaml +steps: + - name: Previous step setting variables + run: | + echo "GITHUB_REF_SLUG=custom-value" >> $GITHUB_ENV + + - uses: rlespinasse/github-slug-action@v5 + with: + prefix: CUSTOM_ + + - name: Step requiring slug variables + run: echo ${{ env.CUSTOM_GITHUB_REF_SLUG }} # Will be empty if placed before the action +``` + +### Variable Preservation + +```yaml +steps: + - name: Save original value + run: echo "ORIGINAL_REF=${{ env.GITHUB_REF_SLUG }}" >> $GITHUB_ENV + + - uses: rlespinasse/github-slug-action@v5 +``` + +### Manual Custom Variable Names + +```yaml +steps: + - uses: rlespinasse/github-slug-action@v5 + - name: Use custom variables + run: | + echo "CUSTOM_SLUG=${GITHUB_REF_SLUG}" >> $GITHUB_ENV +``` + +## Best Practices + +- Document variable usage +- Check for existing variables +- Use descriptive custom names +- Maintain consistent naming +- Follow workflow order dependencies + +## Troubleshooting + +- Verify action version compatibility +- Check environment variable scope +- Review workflow execution order +- Validate variable naming conventions +- Monitor for override warnings + +## Related Documentation + +- [GitHub Variables](reference/github-variables.md) +- [Migration Guide](reference/migration-guide.md) +- [Troubleshooting](reference/troubleshooting.md) + +Need help? [Open an issue](https://github.com/rlespinasse/github-slug-action/issues) diff --git a/docs/reference/troubleshooting.md b/docs/reference/troubleshooting.md new file mode 100644 index 0000000..965dc9f --- /dev/null +++ b/docs/reference/troubleshooting.md @@ -0,0 +1,95 @@ +# Troubleshooting Guide + +## Common Issues + +### Missing Variables + +```yaml +# Problem: Variables not available +steps: + - run: echo ${{ env.GITHUB_REF_SLUG }} # Empty output + - uses: rlespinasse/github-slug-action@v5 + +# Solution: Correct order +steps: + - uses: rlespinasse/github-slug-action@v5 + - run: echo ${{ env.GITHUB_REF_SLUG }} +``` + +### Variable Scope Issues + +```yaml +# Problem: Variables not persisting between jobs +jobs: + job1: + steps: + - uses: rlespinasse/github-slug-action@v5 + job2: + steps: + - run: echo ${{ env.GITHUB_REF_SLUG }} # Empty + +# Solution: Re-run action in each job +jobs: + job2: + steps: + - uses: rlespinasse/github-slug-action@v5 + - run: echo ${{ env.GITHUB_REF_SLUG }} +``` + +## Debug Steps + +### Enable Debug Logging + +```yaml +steps: + - uses: rlespinasse/github-slug-action@v5 + with: + debug: true +``` + +### Variable Inspection + +```yaml +steps: + - uses: rlespinasse/github-slug-action@v5 + - name: Debug variables + run: | + echo "REF_SLUG: ${{ env.GITHUB_REF_SLUG }}" + echo "SHA_SHORT: ${{ env.GITHUB_SHA_SHORT }}" + env | grep GITHUB_ +``` + +## Known Issues + +- Case sensitivity on different OS +- Special character handling +- Unicode support limitations +- Environment variable persistence +- Action version compatibility + +## Solutions + +### Version Specific + +```yaml +# Use specific version for stability +steps: + - uses: rlespinasse/github-slug-action@v5.2.0 +``` + +### OS Compatibility + +```yaml +steps: + - uses: rlespinasse/github-slug-action@v5 + with: + platform: ${{ runner.os }} +``` + +## Support Resources + +- [GitHub Issues](https://github.com/rlespinasse/github-slug-action/issues) +- [Documentation](https://github.com/rlespinasse/github-slug-action/blob/main/README.md) +- [Release Notes](https://github.com/rlespinasse/github-slug-action/releases) + +Need more help? [Open an issue](https://github.com/rlespinasse/github-slug-action/issues) diff --git a/docs/short-variables.md b/docs/short-variables.md deleted file mode 100644 index d59a64b..0000000 --- a/docs/short-variables.md +++ /dev/null @@ -1,44 +0,0 @@ -# Short SHA Variables Reference - -This document details the shortened SHA hash variables provided by GitHub Slug Action, which provide convenient abbreviated versions of commit hashes. - -## Available Short Variables - -### GITHUB_SHA_SHORT - -Shortened version of the commit SHA that triggered the workflow - -```yaml -# Example -GITHUB_SHA: "ffac537e6cbbf934b08745a378932722df287a53" -โ†’ GITHUB_SHA_SHORT: "ffac537e" -``` - -### GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT - -Shortened version of the latest commit SHA from pull request events - -```yaml -# Example -github.event.pull_request.head.sha: "ffac537e6cbbf934b08745a378932722df287a53" -โ†’ GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT: "ffac537e" -``` - -## Usage Details - -- Short variables contain the first 8 characters of the full SHA -- Useful for: - - Display purposes - - Brief references in logs or messages - - Creating concise artifact names - - Generating unique identifiers - -## Availability - -- `GITHUB_SHA_SHORT`: Available in all workflow runs -- `GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT`: Only available during pull request events - -## Related Documentation - -- [GitHub SHA Documentation](https://docs.github.com/en/actions/reference/environment-variables#default-environment-variables) -- [Pull Request Events](https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#pull_request) diff --git a/docs/slug-url-variables.md b/docs/slug-url-variables.md deleted file mode 100644 index 64ef182..0000000 --- a/docs/slug-url-variables.md +++ /dev/null @@ -1,88 +0,0 @@ -# URL-Safe Slug Variables Reference - -This document details the URL-safe versions of slug variables provided by GitHub Slug Action. These variables are specially formatted for use in URLs and paths, with proper percent-encoding of special characters. - -## Repository URL Variables - -### GITHUB_REPOSITORY_SLUG_URL - -URL-safe version of repository name, combining owner and repository - -```yaml -# Examples -GITHUB_REPOSITORY: "octocat/Hello-World" -โ†’ GITHUB_REPOSITORY_SLUG_URL: "octocat-hello-world" - -GITHUB_REPOSITORY: "rlespinasse/Hello-World.go" -โ†’ GITHUB_REPOSITORY_SLUG_URL: "rlespinasse-hello-world-go" -``` - -### Repository Part Variables - -#### Owner and Name Components - -- **GITHUB_REPOSITORY_OWNER_PART_SLUG_URL**: URL-safe owner name -- **GITHUB_REPOSITORY_NAME_PART_SLUG_URL**: URL-safe repository name - -```yaml -# Example -GITHUB_REPOSITORY: "AnotherPerson/Some.Repository" -GITHUB_REPOSITORY_OWNER_PART_SLUG_URL: "anotherperson" -GITHUB_REPOSITORY_NAME_PART_SLUG_URL: "some-repository" -``` - -## Reference URL Variables - -### GITHUB_REF_SLUG_URL - -URL-safe version of the triggering reference - -```yaml -# Examples -GITHUB_REF: "refs/heads/feat/new_feature" -โ†’ GITHUB_REF_SLUG_URL: "feat-new-feature" - -GITHUB_REF: "refs/tags/v1.0.0" -โ†’ GITHUB_REF_SLUG_URL: "v1-0-0" - -GITHUB_REF: "refs/pull/42-merge" -โ†’ GITHUB_REF_SLUG_URL: "42-merge" -``` - -> **Note**: Version 3.3.0 fixed incorrect handling of pull request references (previously `refs-pull-42-merge` instead of `42-merge` in v3.0.0-v3.2.0) - -### Pull Request Reference Variables - -Available during pull request events: - -- **GITHUB_HEAD_REF_SLUG_URL**: URL-safe source branch name -- **GITHUB_BASE_REF_SLUG_URL**: URL-safe target branch name - -```yaml -# Example -GITHUB_HEAD_REF: "feat/new_feature" -โ†’ GITHUB_HEAD_REF_SLUG_URL: "feat-new-feature" -``` - -### GITHUB_EVENT_REF_SLUG_URL - -Available during `create` and `delete` events, provides URL-safe reference name - -```yaml -# Example -github.event.ref: "refs/heads/New_Awesome_Product" -โ†’ GITHUB_EVENT_REF_SLUG_URL: "new-awesome-product" -``` - -## URL-Safe Formatting Rules - -- Converts to lowercase -- Replaces special characters with hyphens -- Encodes remaining special characters using percent-encoding -- Removes leading/trailing special characters -- Converts periods to hyphens (unlike regular slug variables) - -## Related Documentation - -- [GitHub Events Documentation](https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads) -- [Partial Variables Reference](partial-variables.md) diff --git a/docs/slug-variables.md b/docs/slug-variables.md deleted file mode 100644 index 4a142d1..0000000 --- a/docs/slug-variables.md +++ /dev/null @@ -1,77 +0,0 @@ -# Slug Variables Reference - -This document details the slug-formatted variables provided by GitHub Slug Action, which convert GitHub variables into URL and path-safe formats. - -## Available Slug Variables - -### Repository Variables - -#### GITHUB_REPOSITORY_SLUG - -Slugified version of `GITHUB_REPOSITORY` (owner/repository) - -```yaml -# Examples -GITHUB_REPOSITORY: "octocat/Hello-World" โ†’ GITHUB_REPOSITORY_SLUG: "octocat-hello-world" -GITHUB_REPOSITORY: "rlespinasse/Hello-World.go" โ†’ GITHUB_REPOSITORY_SLUG: "rlespinasse-hello-world.go" -``` - -#### Repository Parts - -- **GITHUB_REPOSITORY_OWNER_PART_SLUG**: Owner name in slug format -- **GITHUB_REPOSITORY_NAME_PART_SLUG**: Repository name in slug format - -```yaml -# Example -GITHUB_REPOSITORY: "AnotherPerson/SomeRepository" -GITHUB_REPOSITORY_OWNER_PART_SLUG: "anotherperson" -GITHUB_REPOSITORY_NAME_PART_SLUG: "somerepository" -``` - -### Reference Variables - -#### GITHUB_REF_SLUG - -Slugified branch or tag reference that triggered the workflow - -```yaml -# Examples -GITHUB_REF: "refs/heads/feat/new_feature" โ†’ GITHUB_REF_SLUG: "feat-new-feature" -GITHUB_REF: "refs/tags/product@1.0.0-rc.2" โ†’ GITHUB_REF_SLUG: "product-1.0.0-rc.2" -``` - -#### Pull Request References - -Available during pull request events: - -- **GITHUB_HEAD_REF_SLUG**: Source branch in slug format -- **GITHUB_BASE_REF_SLUG**: Target branch in slug format - -```yaml -# Example -GITHUB_HEAD_REF: "feat/new_feature" โ†’ GITHUB_HEAD_REF_SLUG: "feat-new-feature" -GITHUB_BASE_REF: "main" โ†’ GITHUB_BASE_REF_SLUG: "main" -``` - -#### GITHUB_EVENT_REF_SLUG - -Available during `create` and `delete` events, provides the slugified reference name - -```yaml -# Example -github.event.ref: "refs/heads/New_Awesome_Product" โ†’ GITHUB_EVENT_REF_SLUG: "new-awesome-product" -``` - -## Slugification Rules - -- Converts to lowercase -- Replaces spaces and special characters with hyphens -- Preserves dots and version numbers -- Removes leading/trailing special characters - -For URL-safe versions of these variables, append `_URL` to access percent-encoded formats. - -## Related Documentation - -- [GitHub Events Documentation](https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads) -- [Partial Variables Reference](partial-variables.md) diff --git a/docs/variables/overview.md b/docs/variables/overview.md new file mode 100644 index 0000000..655d181 --- /dev/null +++ b/docs/variables/overview.md @@ -0,0 +1,75 @@ +# Available Variables + +## Core Variables + +| Environment Variable | Description | Example Input | Example Output | +| ------------------------ | --------------------- | ----------------------------- | --------------------- | +| `GITHUB_REF_SLUG` | Current branch or tag | `refs/heads/feature/new-page` | `feature-new-page` | +| `GITHUB_REPOSITORY_SLUG` | Repository name | `octocat/Hello-World` | `octocat-hello-world` | +| `GITHUB_SHA_SHORT` | Short commit SHA | `a1b2c3d4e5f6g7h8` | `a1b2c3d4` | + +## Reference Variables + +### Branch Related + +| Variable | Description | Example | +| ---------------------- | ------------------------------- | --------------------------------- | +| `GITHUB_REF_NAME_SLUG` | Branch name without refs/heads/ | `main` โ†’ `main` | +| `GITHUB_HEAD_REF_SLUG` | PR source branch | `feature/login` โ†’ `feature-login` | +| `GITHUB_BASE_REF_SLUG` | PR target branch | `develop` โ†’ `develop` | + +### Repository Related + +| Variable | Description | Example | +| ------------------------------ | ---------------- | ----------------------------- | +| `GITHUB_REPOSITORY_OWNER_SLUG` | Repository owner | `Octo-Corp` โ†’ `octo-corp` | +| `GITHUB_REPOSITORY_NAME_SLUG` | Repository name | `My-Project` โ†’ `my-project` | +| `GITHUB_EVENT_REF_SLUG` | Event reference | `refs/tags/v1.0.0` โ†’ `v1-0-0` | + +## Slug Transformation Rules + +- Converts to lowercase +- Replaces spaces with hyphens +- Removes special characters +- Shortens SHA to 8 characters +- Makes URLs safe + +## Usage Examples + +### Branch Deployments + +```yaml +environment: ${{ env.GITHUB_REF_SLUG }} +url: https://${{ env.GITHUB_REF_SLUG }}.staging.com +``` + +### Docker Images + +```yaml +image: ${{ env.GITHUB_REPOSITORY_SLUG }}:${{ env.GITHUB_SHA_SHORT }} +``` + +### PR Environments + +```yaml +preview_url: https://pr-${{ env.GITHUB_HEAD_REF_SLUG }}.dev.com +``` + +## Variable Availability + +- Available after action execution +- Persists within the same job +- Must be re-run in new jobs +- Accessible in: + - Workflow files + - Shell commands + - Scripts + - Other actions + +## Related Documentation + +- [Basic Usage](../guides/basic-usage.md) +- [Advanced Patterns](../guides/advanced-patterns.md) +- [Troubleshooting](../reference/troubleshooting.md) + +Need help? [Open an issue](https://github.com/rlespinasse/github-slug-action/issues) diff --git a/docs/variables/repository-variables.md b/docs/variables/repository-variables.md new file mode 100644 index 0000000..c571fbe --- /dev/null +++ b/docs/variables/repository-variables.md @@ -0,0 +1,79 @@ +# Repository Variables + +## Overview + +Repository variables provide URL-safe slugs for repository-related GitHub environment variables. + +## Available Variables + +| Variable | Description | Input Example | Output Example | +| ------------------------------ | -------------------- | ---------------------- | ---------------------- | +| `GITHUB_REPOSITORY_SLUG` | Full repository path | `Octo-Corp/My-Project` | `octo-corp-my-project` | +| `GITHUB_REPOSITORY_OWNER_SLUG` | Repository owner | `Octo-Corp` | `octo-corp` | +| `GITHUB_REPOSITORY_NAME_SLUG` | Repository name | `My-Project` | `my-project` | + +## Usage Examples + +### Docker Image Naming + +```yaml +name: Build Docker Image +steps: + - uses: rlespinasse/github-slug-action@v5 + - name: Build + run: | + docker build -t ${{ env.GITHUB_REPOSITORY_SLUG }}:latest . +``` + +### Deployment Paths + +```yaml +name: Deploy +steps: + - uses: rlespinasse/github-slug-action@v5 + - name: Deploy + run: | + deploy --path="/${{ env.GITHUB_REPOSITORY_OWNER_SLUG }}/${{ env.GITHUB_REPOSITORY_NAME_SLUG }}" +``` + +### URL Generation + +```yaml +name: Generate URLs +steps: + - uses: rlespinasse/github-slug-action@v5 + - name: Set URLs + run: | + echo "APP_URL=https://${{ env.GITHUB_REPOSITORY_SLUG }}.example.com" >> $GITHUB_ENV +``` + +## Transformation Rules + +- Converts all characters to lowercase +- Replaces spaces and underscores with hyphens +- Removes special characters +- Maintains hyphens between components +- Preserves alphanumeric characters + +## Common Use Cases + +- Docker image tagging +- Subdomain generation +- Storage path creation +- Environment naming +- Resource identification + +## Best Practices + +- Use full repository slug for unique identifiers +- Use owner slug for organization-level resources +- Use name slug for project-specific resources +- Combine with other slugs for more specific naming + +## Related Variables + +- [Reference Variables](reference-variables.md) +- [Branch Variables](branch-variables.md) +- [Event Variables](event-variables.md) + +Need help? [Open an issue](https://github.com/rlespinasse/github-slug-action/issues) diff --git a/docs/variables/short-sha-variables.md b/docs/variables/short-sha-variables.md new file mode 100644 index 0000000..43ee97a --- /dev/null +++ b/docs/variables/short-sha-variables.md @@ -0,0 +1,57 @@ +# Short SHA Variables + +## Overview + +Short SHA variables provide truncated versions of Git commit hashes for more manageable use in workflows. + +## Available Variables + +| Variable | Description | Input Example | Output Example | +| ------------------------ | --------------------------------- | ------------------------------------------ | -------------- | +| `GITHUB_SHA_SHORT` | First 8 characters of commit SHA | `f6a65a2b47e54e5ed7d0d06e1b9162fd43b24daa` | `f6a65a2b` | +| `GITHUB_EVENT_SHA_SHORT` | Short SHA of event-related commit | `89ab12cd34ef56gh78ij90kl12mn34op56qr78st` | `89ab12cd` | + +## Usage Examples + +### Docker Tags + +```yaml +name: Build Docker +steps: + - uses: rlespinasse/github-slug-action@v5 + - run: docker build -t myapp:${{ env.GITHUB_SHA_SHORT }} . +``` + +### Commit References + +```yaml +name: Deploy +steps: + - uses: rlespinasse/github-slug-action@v5 + - run: | + echo "Deploying commit ${{ env.GITHUB_SHA_SHORT }}" +``` + +## Common Use Cases + +- Docker image tagging +- Artifact versioning +- Deployment tracking +- Log references +- Build identifiers + +## Best Practices + +- Use consistent length across workflows +- Document SHA usage +- Consider collision probability +- Maintain traceability +- Combine with other identifiers when needed + +## Related Documentation + +- [Slug Variables](slug-variables.md) +- [Event Variables](event-variables.md) +- [Reference Variables](reference-variables.md) + +Need help? [Open an issue](https://github.com/rlespinasse/github-slug-action/issues) diff --git a/docs/variables/slug-variables.md b/docs/variables/slug-variables.md new file mode 100644 index 0000000..945866b --- /dev/null +++ b/docs/variables/slug-variables.md @@ -0,0 +1,67 @@ +# Slug Variables + +## Overview + +GitHub Slug Action provides URL-safe versions of GitHub environment variables. + +## Core Variables + +| Variable | Description | Input Example | Output Example | +| ------------------------ | --------------------- | ----------------------------- | ---------------------- | +| `GITHUB_REF_SLUG` | Current branch or tag | `refs/heads/feature/new-page` | `feature-new-page` | +| `GITHUB_REPOSITORY_SLUG` | Full repository path | `Octo-Corp/My-Project` | `octo-corp-my-project` | +| `GITHUB_SHA_SHORT` | Short commit SHA | `a1b2c3d4e5f6g7h8` | `a1b2c3d4` | + +## Transformation Rules + +All variables undergo these transformations: + +- Converts to lowercase +- Replaces spaces with hyphens +- Removes special characters +- Maintains alphanumeric characters +- Preserves existing hyphens + +## Common Use Cases + +- URL generation +- Docker image tagging +- Environment naming +- File path creation +- Resource identification + +## Usage Examples + +### Docker Images + +```yaml +name: Build +steps: + - uses: rlespinasse/github-slug-action@v5 + - run: docker build -t app:${{ env.GITHUB_SHA_SHORT }} . +``` + +### Deployment URLs + +```yaml +name: Deploy +steps: + - uses: rlespinasse/github-slug-action@v5 + - run: echo "URL=https://${{ env.GITHUB_REF_SLUG }}.dev.com" >> $GITHUB_ENV +``` + +## Best Practices + +- Use consistent naming patterns +- Combine slugs for unique identifiers +- Validate transformed values +- Document usage in workflows +- Consider variable availability + +## Related Documentation + +- [Repository Variables](repository-variables.md) +- [Reference Variables](reference-variables.md) +- [Branch Variables](branch-variables.md) + +Need help? [Open an issue](https://github.com/rlespinasse/github-slug-action/issues) diff --git a/docs/variables/url-safe-variables.md b/docs/variables/url-safe-variables.md new file mode 100644 index 0000000..4b5073c --- /dev/null +++ b/docs/variables/url-safe-variables.md @@ -0,0 +1,69 @@ +# URL-Safe Variables + +## Overview + +URL-safe variables ensure GitHub environment variables can be safely used in URLs and file paths. + +## Available Variables + +| Variable | Description | Input Example | Output Example | +| ---------------------------- | --------------- | --------------------- | --------------------- | +| `GITHUB_EVENT_NAME_URL_SAFE` | Event name | `pull_request` | `pull-request` | +| `GITHUB_ACTOR_URL_SAFE` | Actor username | `john.doe` | `john-doe` | +| `GITHUB_REPOSITORY_URL_SAFE` | Repository path | `My-Org/Project.Name` | `my-org/project-name` | + +## Transformation Rules + +The following rules are applied to create URL-safe values: + +- Replaces underscores with hyphens +- Converts to lowercase +- Removes special characters +- Preserves forward slashes +- Maintains alphanumeric characters + +## Usage Examples + +### URL Generation + +```yaml +name: Generate URLs +steps: + - uses: rlespinasse/github-slug-action@v5 + - run: | + echo "DEPLOY_URL=https://${{ env.GITHUB_ACTOR_URL_SAFE }}.example.com" >> $GITHUB_ENV +``` + +### File Path Creation + +```yaml +name: Create Paths +steps: + - uses: rlespinasse/github-slug-action@v5 + - run: | + mkdir -p "artifacts/${{ env.GITHUB_EVENT_NAME_URL_SAFE }}" +``` + +## Common Use Cases + +- Web endpoint creation +- Storage path generation +- Resource naming +- URL routing +- File organization + +## Best Practices + +- Validate transformed values +- Use consistent patterns +- Document transformations +- Test edge cases +- Consider URL length limits + +## Related Documentation + +- [Slug Variables](slug-variables.md) +- [Repository Variables](repository-variables.md) +- [Event Variables](event-variables.md) + +Need help? [Open an issue](https://github.com/rlespinasse/github-slug-action/issues) diff --git a/examples/linux-usage.yml b/examples/linux-usage.yml deleted file mode 100644 index 8a0d252..0000000 --- a/examples/linux-usage.yml +++ /dev/null @@ -1,42 +0,0 @@ -name: Linux Usage Example - -on: push - -jobs: - demonstrate-variables: - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Enhanced GitHub environment variables - uses: rlespinasse/github-slug-action@v5 - - - name: Display All Variables - shell: bash - run: | - echo "=== Repository Part Variables ===" - echo "Owner : ${{ env.GITHUB_REPOSITORY_OWNER_PART }}" - echo "Name : ${{ env.GITHUB_REPOSITORY_NAME_PART }}" - - echo -e "\n=== Slug Variables ===" - echo "Repository: ${{ env.GITHUB_REPOSITORY_SLUG }}" - echo "Owner : ${{ env.GITHUB_REPOSITORY_OWNER_PART_SLUG }}" - echo "Name : ${{ env.GITHUB_REPOSITORY_NAME_PART_SLUG }}" - echo "Ref : ${{ env.GITHUB_REF_SLUG }}" - echo "Head Ref : ${{ env.GITHUB_HEAD_REF_SLUG }}" - echo "Base Ref : ${{ env.GITHUB_BASE_REF_SLUG }}" - echo "Event Ref : ${{ env.GITHUB_EVENT_REF_SLUG }}" - - echo -e "\n=== URL-Safe Slug Variables ===" - echo "Repository: ${{ env.GITHUB_REPOSITORY_SLUG_URL }}" - echo "Owner : ${{ env.GITHUB_REPOSITORY_OWNER_PART_SLUG_URL }}" - echo "Name : ${{ env.GITHUB_REPOSITORY_NAME_PART_SLUG_URL }}" - echo "Ref : ${{ env.GITHUB_REF_SLUG_URL }}" - echo "Head Ref : ${{ env.GITHUB_HEAD_REF_SLUG_URL }}" - echo "Base Ref : ${{ env.GITHUB_BASE_REF_SLUG_URL }}" - echo "Event Ref : ${{ env.GITHUB_EVENT_REF_SLUG_URL }}" - - echo -e "\n=== Short SHA Variables ===" - echo "SHA : ${{ env.GITHUB_SHA_SHORT }}" - echo "Pull Request : ${{ env.GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT }}" diff --git a/examples/macos-usage.yml b/examples/macos-usage.yml deleted file mode 100644 index b89f48e..0000000 --- a/examples/macos-usage.yml +++ /dev/null @@ -1,42 +0,0 @@ -name: MacOS Usage Example - -on: push - -jobs: - demonstrate-variables: - runs-on: macos-latest - steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Enhanced GitHub environment variables - uses: rlespinasse/github-slug-action@v5 - - - name: Display All Variables - shell: bash - run: | - echo "=== Repository Part Variables ===" - echo "Owner : ${{ env.GITHUB_REPOSITORY_OWNER_PART }}" - echo "Name : ${{ env.GITHUB_REPOSITORY_NAME_PART }}" - - echo -e "\n=== Slug Variables ===" - echo "Repository: ${{ env.GITHUB_REPOSITORY_SLUG }}" - echo "Owner : ${{ env.GITHUB_REPOSITORY_OWNER_PART_SLUG }}" - echo "Name : ${{ env.GITHUB_REPOSITORY_NAME_PART_SLUG }}" - echo "Ref : ${{ env.GITHUB_REF_SLUG }}" - echo "Head Ref : ${{ env.GITHUB_HEAD_REF_SLUG }}" - echo "Base Ref : ${{ env.GITHUB_BASE_REF_SLUG }}" - echo "Event Ref : ${{ env.GITHUB_EVENT_REF_SLUG }}" - - echo -e "\n=== URL-Safe Slug Variables ===" - echo "Repository: ${{ env.GITHUB_REPOSITORY_SLUG_URL }}" - echo "Owner : ${{ env.GITHUB_REPOSITORY_OWNER_PART_SLUG_URL }}" - echo "Name : ${{ env.GITHUB_REPOSITORY_NAME_PART_SLUG_URL }}" - echo "Ref : ${{ env.GITHUB_REF_SLUG_URL }}" - echo "Head Ref : ${{ env.GITHUB_HEAD_REF_SLUG_URL }}" - echo "Base Ref : ${{ env.GITHUB_BASE_REF_SLUG_URL }}" - echo "Event Ref : ${{ env.GITHUB_EVENT_REF_SLUG_URL }}" - - echo -e "\n=== Short SHA Variables ===" - echo "SHA : ${{ env.GITHUB_SHA_SHORT }}" - echo "Pull Request : ${{ env.GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT }}" diff --git a/examples/url-use.yml b/examples/url-use.yml deleted file mode 100644 index f434869..0000000 --- a/examples/url-use.yml +++ /dev/null @@ -1,30 +0,0 @@ -name: URL Usage Examples - -on: push - -jobs: - deploy_to_subdomain: - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Generate URL-safe slugs - uses: rlespinasse/github-slug-action@v5 - - - name: Deploy to subdomain environment - run: | - ./deploy-application.sh --url "https://${{ env.GITHUB_REF_SLUG_URL }}.staging.app.example.com" - - deploy_to_path: - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Generate URL-safe slugs - uses: rlespinasse/github-slug-action@v5 - - - name: Deploy to path-based environment - run: | - ./deploy-application.sh --url "https://staging.app.example.com/${{ env.GITHUB_REF_SLUG_URL }}" diff --git a/examples/windows-usage.yml b/examples/windows-usage.yml deleted file mode 100644 index a69b457..0000000 --- a/examples/windows-usage.yml +++ /dev/null @@ -1,42 +0,0 @@ -name: Windows Usage Example - -on: push - -jobs: - display_variables: - runs-on: windows-latest - steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Enhanced GitHub environment variables - uses: rlespinasse/github-slug-action@v5 - - - name: Display environment variables - shell: pwsh - run: | - Write-Host "=== Repository Part Variables ===" - Write-Host "Owner : $env:GITHUB_REPOSITORY_OWNER_PART" - Write-Host "Name : $env:GITHUB_REPOSITORY_NAME_PART" - - Write-Host "`n=== Slug Variables ===" - Write-Host "Repository: $env:GITHUB_REPOSITORY_SLUG" - Write-Host "Owner : $env:GITHUB_REPOSITORY_OWNER_PART_SLUG" - Write-Host "Name : $env:GITHUB_REPOSITORY_NAME_PART_SLUG" - Write-Host "Ref : $env:GITHUB_REF_SLUG" - Write-Host "Head Ref : $env:GITHUB_HEAD_REF_SLUG" - Write-Host "Base Ref : $env:GITHUB_BASE_REF_SLUG" - Write-Host "Event Ref : $env:GITHUB_EVENT_REF_SLUG" - - Write-Host "`n=== URL-Safe Slug Variables ===" - Write-Host "Repository: $env:GITHUB_REPOSITORY_SLUG_URL" - Write-Host "Owner : $env:GITHUB_REPOSITORY_OWNER_PART_SLUG_URL" - Write-Host "Name : $env:GITHUB_REPOSITORY_NAME_PART_SLUG_URL" - Write-Host "Ref : $env:GITHUB_REF_SLUG_URL" - Write-Host "Head Ref : $env:GITHUB_HEAD_REF_SLUG_URL" - Write-Host "Base Ref : $env:GITHUB_BASE_REF_SLUG_URL" - Write-Host "Event Ref : $env:GITHUB_EVENT_REF_SLUG_URL" - - Write-Host "`n=== Short SHA Variables ===" - Write-Host "SHA : $env:GITHUB_SHA_SHORT" - Write-Host "Pull Request : $env:GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT"