Skip to content

Commit e7bf700

Browse files
dottxadodottxado
committed
Add documentation
1 parent 8acacc9 commit e7bf700

File tree

2 files changed

+124
-2
lines changed

2 files changed

+124
-2
lines changed

‎.github/workflows/deploy-deployer.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,10 +30,10 @@ on:
3030
secrets:
3131
COMPOSER_AUTH_JSON:
3232
description: Authentication for privately hosted packages and repositories as a JSON formatted object.
33-
required: false
33+
required: true
3434
GITHUB_USER_SSH_KEY:
3535
description: Private SSH key to be used to reach remote destinations.
36-
required: false
36+
required: true
3737
DEPLOY_HOSTNAME:
3838
description: Name of the target host.
3939
required: false

‎docs/deploy-deployer.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Deploy with Deployer
2+
3+
This workflow automates deployments using [Deployer](https://deployer.org/), executing the deployment recipe defined in
4+
the consuming repository's `deployment/` directory.
5+
6+
To achieve that, the reusable workflow:
7+
8+
1. Checks out the repository
9+
2. Sets up PHP and installs Composer dependencies (production only)
10+
3. Optionally establishes a WireGuard VPN tunnel to reach private networks
11+
4. Detects and builds npm workspaces if present
12+
5. Installs Deployer from the `deployment/` directory
13+
6. Configures SSH access to the target host
14+
7. Runs the Deployer `deploy` command for the specified environment
15+
16+
## Repository structure
17+
18+
The consuming repository is expected to have a `deployment/` directory with its own `composer.json` that includes
19+
Deployer as a dependency. The `deploy.php` recipe inside that directory should read connection parameters from
20+
environment variables to avoid storing sensitive data in the repository.
21+
The following is a basic configuration for the host in the `deploy.php` file:
22+
23+
```php
24+
$hostname = getenv('DEPLOY_HOSTNAME');
25+
$port = getenv('DEPLOY_PORT');
26+
$user = getenv('DEPLOY_USER');
27+
28+
host('acme_staging')
29+
->setHostname($hostname)
30+
->setRemoteUser($user)
31+
->setPort((int) $port)
32+
->setDeployPath('~/deployments')
33+
->setSshArguments([
34+
'-o UserKnownHostsFile=/dev/null'
35+
'-o StrictHostKeyChecking=no',
36+
]);
37+
```
38+
39+
## Simple usage example
40+
41+
```yml
42+
name: Deploy
43+
on:
44+
workflow_dispatch:
45+
inputs:
46+
ENVIRONMENT:
47+
description: 'Target environment'
48+
required: true
49+
type: choice
50+
options:
51+
- staging
52+
- production
53+
jobs:
54+
deploy:
55+
uses: inpsyde/reusable-workflows/.github/workflows/deploy-deployer.yml@main
56+
secrets:
57+
DEPLOY_HOSTNAME: ${{ secrets.DEPLOY_HOSTNAME }}
58+
DEPLOY_PORT: ${{ secrets.DEPLOY_PORT }}
59+
DEPLOY_USER: ${{ secrets.DEPLOY_USER }}
60+
GITHUB_USER_SSH_KEY: ${{ secrets.DEPLOYBOT_SSH_PRIVATE_KEY }}
61+
COMPOSER_AUTH_JSON: ${{ secrets.PACKAGIST_AUTH_JSON }}
62+
with:
63+
ENVIRONMENT: ${{ inputs.ENVIRONMENT }}
64+
```
65+
66+
## Configuration parameters
67+
68+
### Inputs
69+
70+
| Name | Default | Description |
71+
|-----------------------|---------------------------------|----------------------------------------------------------|
72+
| `ENVIRONMENT` | | Name of the target environment to load Deployer settings |
73+
| `VERBOSITY` | `'v'` | Deployer command verbosity |
74+
| `PHP_VERSION` | `'8.2'` | PHP version with which the scripts are executed |
75+
| `NODE_VERSION` | `'22'` | Node.js version to use when npm workspaces are detected |
76+
| `NPM_REGISTRY_DOMAIN` | `'https://npm.pkg.github.com/'` | Domain of the private npm registry |
77+
| `COMPOSER_ARGS` | `''` | Set of arguments passed to Composer |
78+
79+
### Secrets
80+
81+
| Name | Required | Description |
82+
|---------------------------|----------|------------------------------------------------------------------------------------------|
83+
| `DEPLOY_HOSTNAME` | Yes | Hostname or IP address of the target server |
84+
| `DEPLOY_PORT` | Yes | SSH port on the target server |
85+
| `DEPLOY_USER` | Yes | SSH user on the target server |
86+
| `GITHUB_USER_SSH_KEY` | Yes | Private SSH key used for repository checkout and remote server access |
87+
| `COMPOSER_AUTH_JSON` | Yes | Authentication for privately hosted packages and repositories as a JSON formatted object |
88+
| `WIREGUARD_CONFIGURATION` | No | The full content of the WireGuard configuration file for VPN tunnel setup |
89+
| `NPM_REGISTRY_TOKEN` | No | Authentication for the private npm registry |
90+
91+
**Example with configuration parameters:**
92+
93+
```yml
94+
name: Deploy
95+
on:
96+
workflow_dispatch:
97+
inputs:
98+
ENVIRONMENT:
99+
description: 'Target environment'
100+
required: true
101+
type: choice
102+
options:
103+
- staging
104+
- production
105+
jobs:
106+
deploy:
107+
uses: inpsyde/reusable-workflows/.github/workflows/deploy-deployer.yml@main
108+
secrets:
109+
DEPLOY_HOSTNAME: ${{ secrets.DEPLOY_HOSTNAME }}
110+
DEPLOY_PORT: ${{ secrets.DEPLOY_PORT }}
111+
DEPLOY_USER: ${{ secrets.DEPLOY_USER }}
112+
GITHUB_USER_SSH_KEY: ${{ secrets.DEPLOYBOT_SSH_PRIVATE_KEY }}
113+
COMPOSER_AUTH_JSON: ${{ secrets.PACKAGIST_AUTH_JSON }}
114+
WIREGUARD_CONFIGURATION: ${{ secrets.WIREGUARD_CONFIGURATION }}
115+
NPM_REGISTRY_TOKEN: ${{ secrets.NPM_REGISTRY_TOKEN }}
116+
with:
117+
ENVIRONMENT: ${{ inputs.ENVIRONMENT }}
118+
PHP_VERSION: '8.3'
119+
NODE_VERSION: '22'
120+
VERBOSITY: 'vvv'
121+
COMPOSER_ARGS: '--no-plugins'
122+
```

0 commit comments

Comments
 (0)