From feee556e34a973c152d8068734374a087a5c208f Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Wed, 28 Jan 2026 09:30:09 +0300 Subject: [PATCH] feat: add some readme --- README.md | 260 +++++++---------------------- admin-jest/README.md | 42 +++++ build-zip/README.md | 88 ++++++++++ cs-fixer/README.md | 35 ++++ downstream/README.md | 152 +++++++++++++++++ eslint/README.md | 81 +++++++++ extension-verifier/README.md | 50 ++++++ phpstan/README.md | 53 ++++++ phpunit/README.md | 51 ++++++ saas-preview-environment/README.md | 85 ++++++++++ setup-extension/README.md | 171 +++++++++++++++++++ shopware-version/README.md | 64 +++++++ store-release/README.md | 83 +++++++++ upstream-connect/README.md | 83 +++++++++ versions/README.md | 59 +++++++ 15 files changed, 1161 insertions(+), 196 deletions(-) create mode 100644 admin-jest/README.md create mode 100644 build-zip/README.md create mode 100644 cs-fixer/README.md create mode 100644 downstream/README.md create mode 100644 eslint/README.md create mode 100644 extension-verifier/README.md create mode 100644 phpstan/README.md create mode 100644 phpunit/README.md create mode 100644 saas-preview-environment/README.md create mode 100644 setup-extension/README.md create mode 100644 shopware-version/README.md create mode 100644 store-release/README.md create mode 100644 upstream-connect/README.md create mode 100644 versions/README.md diff --git a/README.md b/README.md index 68dc0d8..cfd014a 100644 --- a/README.md +++ b/README.md @@ -1,234 +1,102 @@ -# Reusable GitHub Actions and Workflows for Shopware extensions +# Reusable GitHub Actions for Shopware -## Workflows +A collection of reusable GitHub Actions and Workflows for Shopware extensions and projects. + +## Actions ### Code Quality -#### cs-fixer +| Action | Description | Link | +|--------|-------------|------| +| [cs-fixer](cs-fixer/) | PHP-CS-Fixer action for checking and enforcing code style | [README](cs-fixer/README.md) | +| [phpstan](phpstan/) | Runs PHPStan static analysis for Shopware extensions | [README](phpstan/README.md) | +| [eslint](eslint/) | Runs ESLint on administration or storefront files | [README](eslint/README.md) | +| [extension-verifier](extension-verifier/) | Validates and formats Shopware extensions using shopware-cli | [README](extension-verifier/README.md) | +| [project-validate](project-validate/) | Validates a Shopware project code style and structure | [README](project-validate/README.md) | -Installs PHP-CS-Fixer and runs [PER Coding Style 2.0](https://www.php-fig.org/per/coding-style/) through the plugin. +### Testing -```yaml -jobs: - cs: - uses: shopware/github-actions/.github/workflows/cs-fixer.yml@main -``` +| Action | Description | Link | +|--------|-------------|------| +| [admin-jest](admin-jest/) | Runs administration Jest tests | [README](admin-jest/README.md) | +| [phpunit](phpunit/) | Runs PHPUnit tests for Shopware extensions | [README](phpunit/README.md) | -#### phpstan +### Build & Release -Installs Shopware 6, PHPStan and the extension, then runs PHPStan +| Action | Description | Link | +|--------|-------------|------| +| [build-zip](build-zip/) | Builds the extension zip and validates it | [README](build-zip/README.md) | +| [store-release](store-release/) | Builds the extension and uploads it to the Shopware Store | [README](store-release/README.md) | -```yaml -jobs: - phpstan: - uses: shopware/github-actions/.github/workflows/phpstan.yml@main - with: - # Extension name - extensionName: MyExtensionName - # Run against Shopware version - shopwareVersion: 6.5.x -``` +### Setup & Configuration -The PHPStan check needs the file `phpstan.neon.dist` in the plugin root directory with the following content: +| Action | Description | Link | +|--------|-------------|------| +| [setup-extension](setup-extension/) | Checkouts Shopware and extension, installs dependencies | [README](setup-extension/README.md) | +| [shopware-version](shopware-version/) | Gets the Shopware version that matches the current branch | [README](shopware-version/README.md) | +| [versions](versions/) | Gets version information for current and LTS major versions | [README](versions/README.md) | -```neon -parameters: - # choose one of the available levels: https://phpstan.org/user-guide/rule-levels - level: max - # the paths are relative to the project root - # an additional path to check could be the tests directory - paths: - - src -``` +### Workflow Orchestration -#### admin-eslint +| Action | Description | Link | +|--------|-------------|------| +| [downstream](downstream/) | Triggers a downstream workflow and waits for it to finish | [README](downstream/README.md) | +| [upstream-connect](upstream-connect/) | Connects to upstream from downstream run | [README](upstream-connect/README.md) | -Runs ESLint on the administration files of the plugin -```yaml -jobs: - phpstan: - uses: shopware/github-actions/.github/workflows/admin-eslint.yml@main - with: - # Extension name - extensionName: MyExtensionName - # Run against Shopware version - shopwareVersion: 6.5.x -``` +### Deployment -### Testing +| Action | Description | Link | +|--------|-------------|------| +| [project-deployer](project-deployer/) | Builds and deploys a Shopware project using shopware-cli and deployer | [README](project-deployer/README.md) | -#### admin-jest +### SaaS -Runs administration jest tests +| Action | Description | Link | +|--------|-------------|------| +| [saas-preview-environment](saas-preview-environment/) | Creates, migrates or archives a SaaS Preview Environment | [README](saas-preview-environment/README.md) | -```yaml -jobs: - admin-jest: - uses: shopware/github-actions/.github/workflows/admin-jest.yml@main - with: - # Extension Name - extensionName: MyExtensionName - # Run against Shopware version - shopwareVersion: 6.5.x -``` +## Usage -#### phpunit +All actions follow the standard GitHub Actions format: ```yaml -jobs: - phpunit: - uses: shopware/github-actions/.github/workflows/phpunit.yml@main +steps: + - uses: shopware/github-actions/[action-name]@main with: - # Extension Name - extensionName: MyExtensionName - # Run against Shopware version - shopwareVersion: 6.5.x + # action-specific inputs ``` -With Code Coverage with [codecov](https://about.codecov.io/) - -```yaml -jobs: - phpunit: - uses: shopware/github-actions/.github/workflows/phpunit.yml@main - with: - extensionName: SwagPlatformDemoData - shopwareVersion: 6.5.x - uploadCoverage: true - secrets: - codecovToken: ${{ secrets.CODECOV_TOKEN }} -``` +## Extension Dependencies -### Build Zip - -Builds the extension zip and validates the zip using shopware-cli +For actions that support extension dependencies (e.g., `phpstan`, `phpunit`, `setup-extension`), you can specify them using the `dependencies` input: ```yaml jobs: - zip: - uses: shopware/github-actions/.github/workflows/build-zip.yml@main + phpstan: + uses: shopware/github-actions/phpstan@main with: - # Extension Name extensionName: MyExtensionName + dependencies: |- + [ + {"name": "SwagPlatformDemoData", "repo": "git@github.com:shopware/SwagPlatformDemoData.git"} + ] ``` -### Store Upload - -Upload the extension with the given Shopware account credentials into the account. It is recommended to use the `workflow_dispatch` event, so you have to manually trigger this from the Actions Tab. +For private dependencies, you can use variables that will be replaced with secrets: ```yaml -name: Release to Store -on: - workflow_dispatch: jobs: - build: - uses: shopware/github-actions/.github/workflows/store-release.yml@main + phpstan: + uses: shopware/github-actions/setup-extension@main with: - extensionName: ${{ github.event.repository.name }} - secrets: - accountUser: ${{ secrets.SHOPWARE_ACCOUNT_USER }} - accountPassword: ${{ secrets.SHOPWARE_ACCOUNT_PASSWORD }} - ghToken: ${{ secrets.GITHUB_TOKEN }} -``` - -### Extension Dependencies (For PHPUnit & phpstan) - -If your extension has dependencies, you can specify them with the `dependencies` input and they will also be installed. The -input should a JSON array of objects containing the extension name and repository URL: - -```yaml -jobs: - phpstan: - uses: shopware/github-actions/.github/workflows/phpstan.yml@main - with: - extensionName: MyExtensionName - shopwareVersion: 6.5.x - dependencies: |- - [ - {"name": "SwagPlatformDemoData", "repo": "git@github.com:shopware/SwagPlatformDemoData.git"} - ] -``` - -If your extension is private, you can specify use variables in the repository URL. They will be replaced with a corresponding secret which you can pass using the `secrets.env` input. -The secret should be defined in your GitHub repository. - -```yaml -jobs: - phpstan: - uses: shopware/github-actions/.github/workflows/phpstan.yml@main - with: - extensionName: MyExtensionName - shopwareVersion: 6.5.x - dependencies: |- - [ - {"name": "MyPrivateExtension", "repo": "https://user:$MY_EXTENSION_TOKEN@gitlab.domain.com/org/my-extension.git"} - ] - secrets: - env: MY_EXTENSION_TOKEN=${{ secrets.MY_EXTENSION_TOKEN }} -``` - -## Actions - -### Downstream - -Trigger a downstream pipeline in a project and wait for it to finish. -Job fails if downstream fails. - -You need to configure octo-sts in the downstream to allow your project to trigger a action or pass a token that has permissions to trigger the workflow. - -Example how to use the downstream action: -```yaml -permissions: - id-token: write - -jobs: - downstream: - runs-on: ubuntu-latest - steps: - - uses: shopware/github-actions/downstream@main - with: - repo: shopware/actions-test - workflow: test - ref: trunk -``` - -In your downstream workflow you also need to use the upstream-connect action: - -```yaml -on: - workflow_dispatch: - inputs: - upstream_data: - required: false - -jobs: - id: - runs-on: ubuntu-latest - steps: - - if: ${{ inputs.upstream_data }} - uses: shopware/github-actions/upstream-connect@main - with: - upstream_data: ${{ inputs.upstream_data }} -``` - -To make it work with [octo-sts](https://github.com/octo-sts/app) you need to add a trust policy like this: - -```yaml -# .github/chainguard/upstream.yaml - -issuer: https://token.actions.githubusercontent.com -subject: repo:shopware/shopware:ref:refs/heads/main -# you can also use subject_pattern, if you want to use regex - -claim_pattern: - # restrict to a specificy upstream workflow - job_workflow_ref: shopware/shopware/.github/workflows/downstream.yml@refs/heads/.* - -permissions: - actions: write - + extensionName: MyExtensionName + dependencies: |- + [ + {"name": "MyPrivateExtension", "repo": "https://user:$MY_EXTENSION_TOKEN@gitlab.domain.com/org/my-extension.git"} + ] + env: MY_EXTENSION_TOKEN=${{ secrets.MY_EXTENSION_TOKEN }} ``` -This policy only allows the `main` ref with the `downstream.yml` workflow of the `shopware/shopware` repository to get a token with the `actions:write` permissions. +## Contributing -You should make this as specific as possible. +Contributions are welcome! Please feel free to submit a Pull Request. diff --git a/admin-jest/README.md b/admin-jest/README.md new file mode 100644 index 0000000..7e7ac1f --- /dev/null +++ b/admin-jest/README.md @@ -0,0 +1,42 @@ +# Admin Jest + +Runs administration Jest tests for your Shopware extension. + +## What it does + +1. Runs Jest unit tests in the administration directory +2. Optionally uploads code coverage to Codecov + +## Inputs + +| Input | Description | Required | Default | +|-------|-------------|----------|---------| +| `extensionName` | Your extension name | Yes | - | +| `uploadCoverage` | Upload coverage to codecov (requires `CODECOV_TOKEN` secret) | No | `false` | + +## Usage + +### Basic usage + +```yaml +jobs: + admin-jest: + uses: shopware/github-actions/admin-jest@main + with: + extensionName: MyExtensionName +``` + +### With code coverage + +```yaml +jobs: + admin-jest: + uses: shopware/github-actions/admin-jest@main + with: + extensionName: MyExtensionName + uploadCoverage: true +``` + +## Requirements + +- Your extension must have Jest tests in `src/Resources/app/administration` diff --git a/build-zip/README.md b/build-zip/README.md new file mode 100644 index 0000000..4a710b2 --- /dev/null +++ b/build-zip/README.md @@ -0,0 +1,88 @@ +# Build Extension Zip + +Builds the extension zip and validates it using shopware-cli. + +## What it does + +1. Checks out the repository +2. Installs shopware-cli +3. Builds the extension zip using shopware-cli +4. Validates the zip file +5. Uploads the artifact + +## Inputs + +| Input | Description | Required | Default | +|-------|-------------|----------|---------| +| `extensionName` | Your extension name | Yes | - | +| `path` | Path to your bundle | No | `.` | +| `skipCheckout` | Skip the checkout step | No | `false` | +| `disableGit` | Use the source folder as it is | No | `false` | + +## Outputs + +| Output | Description | +|--------|-------------| +| `artifact-id` | A unique identifier for the artifact | +| `artifact-url` | A download URL for the artifact | + +## Usage + +### Basic usage + +```yaml +jobs: + build-zip: + uses: shopware/github-actions/build-zip@main + with: + extensionName: MyExtensionName +``` + +### With custom path + +```yaml +jobs: + build-zip: + uses: shopware/github-actions/build-zip@main + with: + extensionName: MyExtensionName + path: ./custom/plugins/MyExtension +``` + +### Skip checkout (if already checked out) + +```yaml +jobs: + build-zip: + uses: shopware/github-actions/build-zip@main + with: + extensionName: MyExtensionName + skipCheckout: 'true' +``` + +### Disable git (use source as-is) + +```yaml +jobs: + build-zip: + uses: shopware/github-actions/build-zip@main + with: + extensionName: MyExtensionName + disableGit: 'true' +``` + +### Using the artifact output + +```yaml +jobs: + build-zip: + uses: shopware/github-actions/build-zip@main + id: build + with: + extensionName: MyExtensionName + download: + needs: build-zip + runs-on: ubuntu-latest + steps: + - run: echo "Download from: ${{ needs.build-zip.outputs.artifact-url }}" +``` diff --git a/cs-fixer/README.md b/cs-fixer/README.md new file mode 100644 index 0000000..1fbf979 --- /dev/null +++ b/cs-fixer/README.md @@ -0,0 +1,35 @@ +# CS Fixer + +PHP-CS-Fixer action for checking and enforcing code style. + +## What it does + +1. Checks out code +2. Sets up PHP with PHP-CS-Fixer and cs2pr tools +3. Runs PHP-CS-Fixer in dry-run mode and formats output for GitHub PRs + +## Inputs + +| Input | Description | Required | Default | +|-------|-------------|----------|---------| +| `rules` | Default rules to check with php-cs-fixer | No | `@PER-CS2.0,no_unused_imports` | + +## Usage + +### Basic usage + +```yaml +jobs: + cs-fixer: + uses: shopware/github-actions/cs-fixer@main +``` + +### With custom rules + +```yaml +jobs: + cs-fixer: + uses: shopware/github-actions/cs-fixer@main + with: + rules: "@Symfony,no_unused_imports" +``` diff --git a/downstream/README.md b/downstream/README.md new file mode 100644 index 0000000..9366d2d --- /dev/null +++ b/downstream/README.md @@ -0,0 +1,152 @@ +# Downstream Workflow + +Trigger a downstream workflow in another repository and wait for it to finish. + +## What it does + +1. Gets an authentication token (via octo-sts or custom token) +2. Finds matching ref in downstream repository +3. Triggers the downstream workflow +4. Waits for the workflow to complete +5. Fails if downstream workflow fails + +## Inputs + +| Input | Description | Required | Default | +|-------|-------------|----------|---------| +| `repo` | Downstream repo | Yes | - | +| `token-scope` | Scope for the sts token | No | - | +| `workflow` | Workflow to dispatch in downstream | Yes | - | +| `ref` | Downstream ref (`.auto` to auto-detect matching refs) | No | `.auto` | +| `refFallback` | Fallback ref in case there's no matching branch | No | `trunk` | +| `env` | Environment variables to pass to downstream workflow | No | - | +| `identity` | Identity for octo-sts | No | `upstream` | +| `token` | Token to authenticate (if not provided, octo-sts is used) | No | - | +| `timeout` | Timeout for the downstream workflow | No | `30m` | +| `poll_interval` | Poll interval for checking status | No | `2m` | + +## Outputs + +| Output | Description | +|--------|-------------| +| `run_id` | The run id of the downstream workflow | +| `run_url` | The api url of the downstream workflow | + +## Usage + +### Basic usage + +```yaml +permissions: + id-token: write + +jobs: + downstream: + runs-on: ubuntu-latest + steps: + - uses: shopware/github-actions/downstream@main + with: + repo: my-org/my-repo + workflow: test + ref: trunk +``` + +### Auto-detect matching ref + +```yaml +jobs: + downstream: + runs-on: ubuntu-latest + steps: + - uses: shopware/github-actions/downstream@main + with: + repo: my-org/my-repo + workflow: test + ref: .auto + refFallback: trunk +``` + +### With environment variables + +```yaml +jobs: + downstream: + runs-on: ubuntu-latest + steps: + - uses: shopware/github-actions/downstream@main + with: + repo: my-org/my-repo + workflow: test + env: | + PLATFORM_BRANCH=trunk + FOO=bar +``` + +### With custom timeout and poll interval + +```yaml +jobs: + downstream: + runs-on: ubuntu-latest + steps: + - uses: shopware/github-actions/downstream@main + with: + repo: my-org/my-repo + workflow: test + timeout: 60m + poll_interval: 1m +``` + +### Using custom token + +```yaml +jobs: + downstream: + runs-on: ubuntu-latest + steps: + - uses: shopware/github-actions/downstream@main + with: + repo: my-org/my-repo + workflow: test + token: ${{ secrets.CUSTOM_TOKEN }} +``` + +## Octo-sts configuration + +To use octo-sts, add a trust policy in the downstream repository: + +```yaml +# .github/chainguard/upstream.yaml +issuer: https://token.actions.githubusercontent.com +subject: repo:my-org/my-upstream-repo:ref:refs/heads/main + +claim_pattern: + job_workflow_ref: my-org/my-upstream-repo/.github/workflows/downstream.yml@refs/heads/.* + +permissions: + actions: write +``` + +## Requirements + +- Downstream workflow must have `workflow_dispatch` event +- Downstream workflow must use `upstream-connect` action to handle upstream data + +### Example downstream workflow + +```yaml +on: + workflow_dispatch: + inputs: + upstream_data: + required: false + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: shopware/github-actions/upstream-connect@main + with: + upstream_data: ${{ inputs.upstream_data }} + # Your test steps here +``` diff --git a/eslint/README.md b/eslint/README.md new file mode 100644 index 0000000..bdb956c --- /dev/null +++ b/eslint/README.md @@ -0,0 +1,81 @@ +# ESLint + +Runs ESLint on the administration or storefront files of a Shopware extension. + +## What it does + +1. Clones Shopware repository +2. Clones your extension +3. Installs npm dependencies +4. Runs the lint command + +## Inputs + +| Input | Description | Required | Default | +|-------|-------------|----------|---------| +| `extensionName` | Your extension name | Yes | - | +| `projectPath` | Path to the JS project to be linted | No | `src/Resources/app/administration` | +| `npmLintCmd` | The npm command to run | No | `lint` | +| `shopwareVersion` | Shopware version (`.auto` to auto-detect) | No | `.auto` | +| `shopwareVersionFallback` | Fallback version in case there's no matching branch | No | `trunk` | +| `shopware-repository` | The shopware repository to checkout | No | `shopware/shopware` | +| `shopware-github-token` | Token used for checking out the shopware repository | No | `$GITHUB_TOKEN` | +| `forceInstallAdminDeps` | Install platform admin deps | No | - | +| `forceInstallStorefrontDeps` | Install platform storefront deps | No | - | + +## Usage + +### Basic usage (administration) + +```yaml +jobs: + eslint: + uses: shopware/github-actions/eslint@main + with: + extensionName: MyExtensionName +``` + +### Lint storefront + +```yaml +jobs: + eslint: + uses: shopware/github-actions/eslint@main + with: + extensionName: MyExtensionName + projectPath: src/Resources/app/storefront +``` + +### With custom Shopware version + +```yaml +jobs: + eslint: + uses: shopware/github-actions/eslint@main + with: + extensionName: MyExtensionName + shopwareVersion: 6.5.x +``` + +### With custom repository and token + +```yaml +jobs: + eslint: + uses: shopware/github-actions/eslint@main + with: + extensionName: MyExtensionName + shopware-repository: my-org/shopware + shopware-github-token: ${{ secrets.SHOPWARE_TOKEN }} +``` + +### With custom lint command + +```yaml +jobs: + eslint: + uses: shopware/github-actions/eslint@main + with: + extensionName: MyExtensionName + npmLintCmd: lint:fix +``` diff --git a/extension-verifier/README.md b/extension-verifier/README.md new file mode 100644 index 0000000..db03163 --- /dev/null +++ b/extension-verifier/README.md @@ -0,0 +1,50 @@ +# Extension Verifier + +Validates and formats Shopware extensions using shopware-cli. + +## What it does + +1. Installs Shopware-CLI +2. Validates extension structure and compliance +3. Optionally formats extension code + +## Inputs + +| Input | Description | Required | Default | +|-------|-------------|----------|---------| +| `version` | The extension verifier version to use | No | `latest` | +| `action` | The action to run (`check` or `format`) | Yes | `check` | +| `check-against` | The version to check against | No | `highest` | + +## Usage + +### Check extension + +```yaml +jobs: + verify: + uses: shopware/github-actions/extension-verifier@main + with: + action: check +``` + +### Check against specific version + +```yaml +jobs: + verify: + uses: shopware/github-actions/extension-verifier@main + with: + action: check + check-against: v6.6.0.0 +``` + +### Format extension (dry-run) + +```yaml +jobs: + format: + uses: shopware/github-actions/extension-verifier@main + with: + action: format +``` diff --git a/phpstan/README.md b/phpstan/README.md new file mode 100644 index 0000000..fb127e4 --- /dev/null +++ b/phpstan/README.md @@ -0,0 +1,53 @@ +# PHPStan + +Runs PHPStan static analysis for Shopware extensions. + +## What it does + +1. Creates PHPStan configuration file +2. Sets up caching for PHPStan results +3. Builds PHPStan bootstrap +4. Runs PHPStan analysis + +## Inputs + +| Input | Description | Required | Default | +|-------|-------------|----------|---------| +| `extensionName` | Your extension name | Yes | - | +| `cacheDir` | PHPStan cache directory | No | `$GITHUB_WORKSPACE/var/phpstan` | +| `errorFormat` | PHPStan error format | No | `github` | + +## Usage + +### Basic usage + +```yaml +jobs: + phpstan: + uses: shopware/github-actions/phpstan@main + with: + extensionName: MyExtensionName +``` + +### With custom cache directory + +```yaml +jobs: + phpstan: + uses: shopware/github-actions/phpstan@main + with: + extensionName: MyExtensionName + cacheDir: ./cache/phpstan +``` + +## Requirements + +- Your extension must have a `phpstan.neon.dist` file in the plugin root directory + +Example `phpstan.neon.dist`: +```neon +parameters: + level: max + paths: + - src +``` diff --git a/phpunit/README.md b/phpunit/README.md new file mode 100644 index 0000000..93d5aa9 --- /dev/null +++ b/phpunit/README.md @@ -0,0 +1,51 @@ +# PHPUnit + +Runs PHPUnit tests for Shopware extensions. + +## What it does + +1. Runs PHPUnit tests +2. Generates code coverage reports +3. Optionally uploads coverage to Codecov + +## Inputs + +| Input | Description | Required | Default | +|-------|-------------|----------|---------| +| `extensionName` | Your extension name | Yes | - | +| `uploadCoverage` | Upload coverage to codecov (requires `CODECOV_TOKEN` secret) | No | `false` | +| `filterName` | PHPUnit 11 requires a testsuite filter | No | - | + +## Usage + +### Basic usage + +```yaml +jobs: + phpunit: + uses: shopware/github-actions/phpunit@main + with: + extensionName: MyExtensionName +``` + +### With code coverage + +```yaml +jobs: + phpunit: + uses: shopware/github-actions/phpunit@main + with: + extensionName: MyExtensionName + uploadCoverage: true +``` + +### With testsuite filter (PHPUnit 11) + +```yaml +jobs: + phpunit: + uses: shopware/github-actions/phpunit@main + with: + extensionName: MyExtensionName + filterName: unit +``` diff --git a/saas-preview-environment/README.md b/saas-preview-environment/README.md new file mode 100644 index 0000000..dc91a82 --- /dev/null +++ b/saas-preview-environment/README.md @@ -0,0 +1,85 @@ +# SaaS Preview Environment + +Create, migrate or archive a SaaS Preview Environment. + +## What it does + +1. Gets an authentication token (via octo-sts or custom token) +2. Triggers the preview environment workflow in the shopware/saas repository +3. Waits for the operation to complete + +## Inputs + +| Input | Description | Required | Default | +|-------|-------------|----------|---------| +| `action` | Action to run (`create` or `archive`) | Yes | `create` | +| `token` | Token to use (if empty, octo-sts is used) | No | - | +| `refFallback` | Fallback ref in case there's no matching branch | No | `trunk` | + +## Usage + +### Create a preview environment + +```yaml +name: Create Preview Environment + +on: + pull_request: + types: [opened, synchronize] + +jobs: + preview: + runs-on: ubuntu-latest + steps: + - uses: shopware/github-actions/saas-preview-environment@main + with: + action: create +``` + +### Archive a preview environment + +```yaml +name: Archive Preview Environment + +on: + pull_request: + types: [closed] + +jobs: + preview: + runs-on: ubuntu-latest + steps: + - uses: shopware/github-actions/saas-preview-environment@main + with: + action: archive +``` + +### With custom token + +```yaml +jobs: + preview: + runs-on: ubuntu-latest + steps: + - uses: shopware/github-actions/saas-preview-environment@main + with: + action: create + token: ${{ secrets.SAAS_TOKEN }} +``` + +### With custom fallback + +```yaml +jobs: + preview: + runs-on: ubuntu-latest + steps: + - uses: shopware/github-actions/saas-preview-environment@main + with: + action: create + refFallback: trunk +``` + +## Octo-sts configuration + +This action uses octo-sts by default. Ensure you have the necessary permissions configured in the shopware/saas repository to use this feature. diff --git a/setup-extension/README.md b/setup-extension/README.md new file mode 100644 index 0000000..8077160 --- /dev/null +++ b/setup-extension/README.md @@ -0,0 +1,171 @@ +# Setup Extension + +Checkouts Shopware and extension, optionally installs dependencies and sets up the database. + +## What it does + +1. Determines the Shopware version to use +2. Sets up Shopware using the shopware/setup-shopware action +3. Clones the extension (or downloads from an artifact) +4. Handles both plugins and apps +5. Installs extension dependencies +6. Optionally installs Shopware, admin, and storefront dependencies + +## Inputs + +| Input | Description | Required | Default | +|-------|-------------|----------|---------| +| `extensionName` | Your extension name | Yes | - | +| `extensionRef` | The branch/tag to checkout | No | - | +| `shopwareVersion` | Shopware version (`.auto` to auto-detect) | No | `.auto` | +| `shopwareVersionFallback` | Fallback version | No | `trunk` | +| `shopware-repository` | The shopware repository to checkout | No | `shopware/shopware` | +| `shopware-github-token` | Token for checking out shopware repository | No | `$GITHUB_TOKEN` | +| `phpVersion` | PHP version to use | No | `8.2` | +| `mysqlVersion` | Mysql image to use or `builtin` | No | `builtin` | +| `node-version` | Node.js version to use | No | `20.x` | +| `npm-version` | NPM version to use | No | - | +| `composerRootVersion` | The COMPOSER_ROOT_VERSION | No | `.auto` | +| `dependencies` | JSON list defining dependencies | No | - | +| `extraRepositories` | Additional composer repositories | No | `{}` | +| `install` | Whether to install Shopware | No | - | +| `install-admin` | Whether to install admin npm deps | No | - | +| `install-storefront` | Whether to install storefront npm deps | No | - | +| `skip-js-build` | Skip js build step | No | `false` | +| `env` | Environment for Shopware | No | `test` | +| `keep-composer-tools` | Keep Shopware Composer tools | No | `false` | +| `extension-zip` | Artifact (extension zip) to download | No | - | +| `with-submodules` | Checkout with submodules | No | `false` | +| `allow-insecure-versions` | Allow older Shopware versions with vulnerabilities | No | `false` | + +## Usage + +### Basic usage + +```yaml +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: shopware/github-actions/setup-extension@main + with: + extensionName: MyExtensionName + shopware-github-token: ${{ secrets.GITHUB_TOKEN }} +``` + +### With installation + +```yaml +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: shopware/github-actions/setup-extension@main + with: + extensionName: MyExtensionName + install: 'true' + install-admin: 'true' + shopware-github-token: ${{ secrets.GITHUB_TOKEN }} +``` + +### With dependencies + +```yaml +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: shopware/github-actions/setup-extension@main + with: + extensionName: MyExtensionName + install: 'true' + dependencies: |- + [ + {"name": "SwagPlatformDemoData", "repo": "git@github.com:shopware/SwagPlatformDemoData.git"} + ] + shopware-github-token: ${{ secrets.GITHUB_TOKEN }} +``` + +### With custom Shopware version + +```yaml +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: shopware/github-actions/setup-extension@main + with: + extensionName: MyExtensionName + shopwareVersion: 6.5.x + shopware-github-token: ${{ secrets.GITHUB_TOKEN }} +``` + +### From extension zip artifact + +```yaml +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Build zip + run: ./build-zip.sh + - uses: actions/upload-artifact@v4 + with: + name: my-extension + path: my-extension.zip + + test: + needs: build + runs-on: ubuntu-latest + steps: + - uses: shopware/github-actions/setup-extension@main + with: + extensionName: MyExtensionName + extension-zip: my-extension + install: 'true' + shopware-github-token: ${{ secrets.GITHUB_TOKEN }} +``` + +### With additional composer repositories + +```yaml +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: shopware/github-actions/setup-extension@main + with: + extensionName: MyExtensionName + extraRepositories: |- + { + "customRepo": { + "type": "vcs", + "url": "https://my-custom-repo.example.test/foo/bar.git" + } + } + shopware-github-token: ${{ secrets.GITHUB_TOKEN }} +``` + +### With private dependencies + +```yaml +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: shopware/github-actions/setup-extension@main + with: + extensionName: MyExtensionName + install: 'true' + dependencies: |- + [ + {"name": "MyPrivateExtension", "repo": "https://user:$MY_EXTENSION_TOKEN@gitlab.domain.com/org/my-extension.git"} + ] + shopware-github-token: ${{ secrets.GITHUB_TOKEN }} +``` + +## Requirements + +- GitHub token with `repo` permissions +- For private dependencies, store tokens as repository secrets diff --git a/shopware-version/README.md b/shopware-version/README.md new file mode 100644 index 0000000..4cf3960 --- /dev/null +++ b/shopware-version/README.md @@ -0,0 +1,64 @@ +# Shopware Version + +Gets the Shopware version that matches the current branch. + +## What it does + +1. Finds a matching Shopware version based on the current git reference +2. Returns a fallback version if no matching branch is found +3. Useful for testing against specific Shopware versions + +## Inputs + +| Input | Description | Required | Default | +|-------|-------------|----------|---------| +| `fallback` | The fallback version if there's no matching branch | No | `trunk` | +| `repo` | The repo where to look for matching refs | No | `shopware/shopware` | +| `ref` | The git reference to match (defaults to `github.ref`) | No | - | +| `base-ref` | The base reference for pull requests (defaults to `github.base_ref`) | No | - | +| `head-ref` | The head reference for pull requests (defaults to `github.head_ref`) | No | - | +| `shopware-github-token` | Token used for checking out the shopware repository | No | - | + +## Outputs + +| Output | Description | +|--------|-------------| +| `shopware-version` | The matching shopware version or fallback | + +## Usage + +### Basic usage + +```yaml +- uses: shopware/github-actions/shopware-version@main + id: version +``` + +### With custom fallback + +```yaml +- uses: shopware/github-actions/shopware-version@main + id: version + with: + fallback: 6.5.0.0 +``` + +### With custom repository + +```yaml +- uses: shopware/github-actions/shopware-version@main + id: version + with: + repo: my-org/shopware + fallback: trunk + shopware-github-token: ${{ secrets.SHOPWARE_TOKEN }} +``` + +### Using the output + +```yaml +- uses: shopware/github-actions/shopware-version@main + id: version +- name: Use version + run: echo "Shopware version is ${{ steps.version.outputs.shopware-version }}" +``` diff --git a/store-release/README.md b/store-release/README.md new file mode 100644 index 0000000..8999e01 --- /dev/null +++ b/store-release/README.md @@ -0,0 +1,83 @@ +# Store Release + +Builds the extension and uploads a zip of it to the Shopware Store. + +## What it does + +1. Builds the extension zip +2. Validates the zip +3. Uploads to Shopware Store +4. Optionally creates a GitHub release +5. Optionally creates a git tag + +## Inputs + +| Input | Description | Required | Default | +|-------|-------------|----------|---------| +| `extensionName` | Your extension name | Yes | - | +| `publishOnly` | Publish only to Shopware Store and don't create a tag | No | `false` | +| `path` | Path to your bundle | No | `.` | +| `accountUser` | Your Shopware account user | Yes | - | +| `accountPassword` | Your Shopware account password | Yes | - | +| `ghToken` | GitHub token | Yes | - | +| `skipCheckout` | Skip the checkout step | No | `false` | +| `disableGit` | Use the source folder as it is | No | `false` | +| `updateInfo` | Update extension information on the Shopware Store plugin page | No | `false` | + +## Usage + +### Basic usage + +```yaml +name: Release to Store + +on: + workflow_dispatch: + +jobs: + build: + uses: shopware/github-actions/store-release@main + with: + extensionName: MyExtensionName + secrets: + accountUser: ${{ secrets.SHOPWARE_ACCOUNT_USER }} + accountPassword: ${{ secrets.SHOPWARE_ACCOUNT_PASSWORD }} + ghToken: ${{ secrets.GITHUB_TOKEN }} +``` + +### Publish only (no GitHub release) + +```yaml +jobs: + build: + uses: shopware/github-actions/store-release@main + with: + extensionName: MyExtensionName + publishOnly: 'true' + secrets: + accountUser: ${{ secrets.SHOPWARE_ACCOUNT_USER }} + accountPassword: ${{ secrets.SHOPWARE_ACCOUNT_PASSWORD }} + ghToken: ${{ secrets.GITHUB_TOKEN }} +``` + +### Update extension info + +```yaml +jobs: + build: + uses: shopware/github-actions/store-release@main + with: + extensionName: MyExtensionName + updateInfo: 'true' + secrets: + accountUser: ${{ secrets.SHOPWARE_ACCOUNT_USER }} + accountPassword: ${{ secrets.SHOPWARE_ACCOUNT_PASSWORD }} + ghToken: ${{ secrets.GITHUB_TOKEN }} +``` + +## Requirements + +- Shopware account credentials must be stored as secrets: + - `SHOPWARE_ACCOUNT_USER` + - `SHOPWARE_ACCOUNT_PASSWORD` +- GitHub token with `repo` permissions diff --git a/upstream-connect/README.md b/upstream-connect/README.md new file mode 100644 index 0000000..c6a03c8 --- /dev/null +++ b/upstream-connect/README.md @@ -0,0 +1,83 @@ +# Upstream Connect + +Connects to upstream from downstream run. + +## What it does + +1. Receives upstream data from a triggered workflow +2. Sets environment variables from the upstream run +3. Displays information about the upstream workflow that triggered the run + +## Inputs + +| Input | Description | Required | Default | +|-------|-------------|----------|---------| +| `upstream_data` | Upstream data (pass-through from workflow_dispatch event input) | Yes | - | + +## Usage + +### In downstream workflow + +```yaml +on: + workflow_dispatch: + inputs: + upstream_data: + required: false + +jobs: + id: + runs-on: ubuntu-latest + steps: + - if: ${{ inputs.upstream_data }} + uses: shopware/github-actions/upstream-connect@main + with: + upstream_data: ${{ inputs.upstream_data }} +``` + +### Accessing upstream data + +After using this action, the following environment variables are available: + +- `upstream.id`: The run ID of the upstream workflow +- `upstream.ref`: The ref of the upstream workflow +- `upstream.repo`: The repository of the upstream workflow +- `upstream.github-token`: The GitHub token from upstream +- `upstream.url`: URL to the upstream workflow run + +Any custom environment variables passed from upstream via the `env` input of the downstream action will also be set. + +## Example: Combined with downstream action + +**Upstream workflow:** +```yaml +jobs: + trigger-downstream: + runs-on: ubuntu-latest + steps: + - uses: shopware/github-actions/downstream@main + with: + repo: my-org/my-repo + workflow: test + ref: trunk +``` + +**Downstream workflow:** +```yaml +on: + workflow_dispatch: + inputs: + upstream_data: + required: false + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: shopware/github-actions/upstream-connect@main + with: + upstream_data: ${{ inputs.upstream_data }} + - run: | + echo "Triggered by: ${{ env.upstream.repo }}" + echo "Run URL: ${{ env.upstream.url }}" +``` diff --git a/versions/README.md b/versions/README.md new file mode 100644 index 0000000..996318b --- /dev/null +++ b/versions/README.md @@ -0,0 +1,59 @@ +# Versions + +Gets the first and latest versions of the current and previous (LTS) major versions. + +## What it does + +1. Retrieves version information for the current major version +2. Retrieves version information for the previous LTS major version +3. Calculates next minor and patch versions + +## Inputs + +| Input | Description | Required | Default | +|-------|-------------|----------|---------| +| `major` | Current major prefix (e.g., `v6.7.`) | No | `v6.7.` | +| `lts-major` | LTS major prefix (e.g., `v6.6.`) | No | `v6.6.` | + +## Outputs + +| Output | Description | +|--------|-------------| +| `first-version` | The first version of the current major | +| `latest-version` | The latest version of the current major | +| `next-minor` | The next minor version | +| `next-patch` | The next patch version | +| `lts-first-version` | The first version of the lts major | +| `lts-latest-version` | The latest version of the lts major | +| `lts-next-patch` | The next patch version of the lts major | + +## Usage + +### Basic usage + +```yaml +- uses: shopware/github-actions/versions@main + id: versions +``` + +### With custom major versions + +```yaml +- uses: shopware/github-actions/versions@main + id: versions + with: + major: v6.7. + lts-major: v6.6. +``` + +### Using outputs + +```yaml +- uses: shopware/github-actions/versions@main + id: versions +- name: Display versions + run: | + echo "Latest: ${{ steps.versions.outputs.latest-version }}" + echo "Next patch: ${{ steps.versions.outputs.next-patch }}" + echo "LTS latest: ${{ steps.versions.outputs.lts-latest-version }}" +```