Skip to content

feat: add some readme #127

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Soner (shyim) merged 1 commit into from
Jan 28, 2026
Merged

feat: add some readme #127

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
260 changes: 64 additions & 196 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
42 changes: 42 additions & 0 deletions admin-jest/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`
Loading