Skip to content

Commit c0eaff6

Browse files
AlexSkrypnykAlexSkrypnyk
committed
[#2133] Added sections about CI and hosting.
1 parent 92a94c2 commit c0eaff6

6 files changed

Lines changed: 558 additions & 14 deletions

File tree

‎.vortex/docs/content/continuous-integration/README.mdx‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,3 +95,51 @@ that allows to remove data from the database dump during Drush database
9595
export command without the need for an intermediate database import step.
9696

9797
:::
98+
99+
## Maintenance
100+
101+
### Enable debug mode
102+
103+
To get verbose output when troubleshooting build failures, enable debug mode
104+
by setting the `VORTEX_DEBUG` variable to `1` in your CI provider's settings.
105+
106+
### Update CI runner image
107+
108+
The CI jobs run inside the [`drevops/ci-runner`](https://github.com/drevops/ci-runner)
109+
container - a Docker image specifically designed for CI job execution. It
110+
provides a consistent, reproducible environment with 25+ pre-installed tools:
111+
112+
- **PHP & Node.js** - PHP 8.4, Node.js, Composer, npm, Yarn
113+
- **Docker tools** - Docker, Docker Compose, Docker Buildx
114+
- **Code quality** - ShellCheck, shfmt, Bats testing framework
115+
- **Utilities** - Git, curl, rsync, jq, and more
116+
117+
Using this image ensures all CI runs have identical tooling, eliminating
118+
environment inconsistencies between local development and CI.
119+
120+
To update to a newer version, change the image tag in your CI configuration
121+
file. The image follows Year-Month-Patch versioning (e.g., `25.10.0`) with
122+
monthly releases.
123+
124+
### Skip specific linters
125+
126+
During development, you may want to allow builds to pass despite linter failures.
127+
Set the corresponding `*_IGNORE_FAILURE` variable to `1`:
128+
129+
| Variable | Tool |
130+
|----------|------|
131+
| `VORTEX_CI_PHPCS_IGNORE_FAILURE` | PHPCS |
132+
| `VORTEX_CI_PHPSTAN_IGNORE_FAILURE` | PHPStan |
133+
| `VORTEX_CI_RECTOR_IGNORE_FAILURE` | Rector |
134+
| `VORTEX_CI_PHPMD_IGNORE_FAILURE` | PHPMD |
135+
| `VORTEX_CI_PHPUNIT_IGNORE_FAILURE` | PHPUnit |
136+
| `VORTEX_CI_BEHAT_IGNORE_FAILURE` | Behat |
137+
138+
### Configure deployment skip conditions
139+
140+
To skip deployments for specific branches, set the `VORTEX_DEPLOY_SKIP_BRANCHES`
141+
variable to a comma-separated list of branch patterns:
142+
143+
```bash
144+
VORTEX_DEPLOY_SKIP_BRANCHES="feature/*,experimental/*"
145+
```

‎.vortex/docs/content/continuous-integration/circleci.mdx‎

Lines changed: 179 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,184 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
15
# CircleCI
26

3-
:::note Content coming soon
7+
[CircleCI](https://circleci.com/) is a cloud-based continuous integration and
8+
delivery platform that automates the build, test, and deployment process.
9+
10+
For general CircleCI documentation, refer to the
11+
[CircleCI Documentation](https://circleci.com/docs/).
12+
13+
:::info
14+
15+
For information about the CI workflow structure, jobs, and caching strategy,
16+
see the [CI overview](/docs/continuous-integration).
17+
18+
:::
19+
20+
## Onboarding
21+
22+
Before you begin, ensure you have:
23+
24+
- A CircleCI account connected to your repository
25+
- Repository admin access to configure project settings
26+
- API credentials for your hosting provider (if deploying)
27+
28+
### 1. Enable the project
29+
30+
[Log in to CircleCI](https://app.circleci.com/) and add your repository as a new
31+
project. CircleCI will connect to your GitHub account, detect the
32+
[`.circleci/config.yml`](https://github.com/drevops/vortex/blob/develop/.circleci/config.yml)
33+
configuration file, and start running builds automatically when you push code.
34+
35+
### 2. Add SSH key for database download
36+
37+
To download a database from your hosting provider during CI builds, you need an
38+
SSH key that has access to your hosting environments.
39+
40+
1. Generate an SSH key pair:
441

5-
This section will provide detailed information about using **Vortex** with
6-
the [CircleCI](https://circleci.com/) continuous integration platform.
42+
```bash
43+
ssh-keygen -m PEM -t rsa -b 4096 -C "deployer+myproject-circleci@example.com" -f ~/.ssh/deployer_myproject_circleci -N ""
44+
```
45+
46+
:::tip Key naming convention
47+
48+
Use the `+<project>-<service>` suffix in the email comment (e.g.,
49+
`deployer+myproject-circleci@example.com`) to identify what the key is used for.
50+
This helps when managing multiple deployment keys across different projects and
51+
services.
52+
53+
:::
54+
55+
2. Add the contents of the public key (e.g., `~/.ssh/<key>.pub`) to your hosting
56+
provider's authorized keys for read access.
57+
3. Add the private key in CircleCI under **Project Settings → SSH Keys**.
58+
CircleCI will generate a fingerprint - copy it for the next step.
59+
60+
### 3. Add SSH key for deployment
61+
62+
To deploy code to your hosting provider, you need an SSH key with write access
63+
to your hosting environments.
64+
65+
:::note
66+
67+
The database source and deployment destination may be different providers (e.g.,
68+
downloading a database from Acquia but deploying to Lagoon). If they are the
69+
same provider, you can use a single key for both operations.
770

871
:::
72+
73+
1. Generate an SSH key pair (skip if using the same key as above):
74+
75+
```bash
76+
ssh-keygen -m PEM -t rsa -b 4096 -C "deployer+myproject-circleci@example.com" -f ~/.ssh/deploy_myproject_circleci -N ""
77+
```
78+
79+
2. Add the public key to your hosting provider
80+
3. Add the private key in CircleCI under **Project Settings → SSH Keys**.
81+
Copy the fingerprint for the next step.
82+
83+
### 4. Update SSH fingerprints in config
84+
85+
CircleCI uses SSH key fingerprints to load the correct keys into the runner
86+
container. Update the YAML anchors in your
87+
[`.circleci/config.yml`](https://github.com/drevops/vortex/blob/develop/.circleci/config.yml)
88+
file:
89+
90+
- `db_ssh_fingerprint` - your database download SSH key fingerprint
91+
- `deploy_ssh_fingerprint` - your deployment SSH key fingerprint
92+
93+
### 5. Configure environment variables
94+
95+
Add the following variables in **Project Settings → Environment Variables**:
96+
97+
**Acquia:**
98+
99+
| Variable | Description |
100+
|----------|-------------|
101+
| `ACQUIA_KEY` | Acquia Cloud API key |
102+
| `ACQUIA_SECRET` | Acquia Cloud API secret |
103+
104+
**Lagoon:**
105+
106+
| Variable | Description |
107+
|----------|-------------|
108+
| `LAGOON_SSH_KEY` | SSH private key for Lagoon authentication |
109+
110+
## Maintenance
111+
112+
### Update deployment branches
113+
114+
The `deploy` job only runs for specific branch patterns. To modify which branches
115+
trigger deployments, update the `only` filter regex in the `deploy` job under
116+
the `workflows` section of `.circleci/config.yml`:
117+
118+
```yaml
119+
filters:
120+
branches:
121+
only: /^(production|main|master|develop)$|^feature\/[a-zA-Z0-9\-\.]+$/
122+
```
123+
124+
### Update nightly database schedule
125+
126+
The nightly database job caches a fresh database dump for faster builds the next
127+
day. To change when this runs, update the `nightly_db_schedule` YAML anchor
128+
(cron format, UTC timezone):
129+
130+
```yaml
131+
- &nightly_db_schedule "0 18 * * *" # 6 PM UTC daily
132+
```
133+
134+
### Reset the cache
135+
136+
If you need to force a fresh cache (e.g., after a major dependency update),
137+
increment the version tag in the cache keys:
138+
139+
```yaml
140+
# Before
141+
- v1-db-{{ checksum "/tmp/db_cache_branch" }}
142+
# After
143+
- v2-db-{{ checksum "/tmp/db_cache_branch" }}
144+
```
145+
146+
### Change runner resource class
147+
148+
For faster builds, you can upgrade the
149+
[runner resource class](https://circleci.com/docs/resource-class-overview/) in
150+
the `runner_config` section. Note that this may affect your CircleCI billing:
151+
152+
```yaml
153+
resource_class: large # Options: small, medium, large, xlarge
154+
```
155+
156+
### Change test parallelism
157+
158+
To speed up test execution, you can increase the number of parallel runners in
159+
the `build` job. See [Running tests in parallel](https://circleci.com/docs/parallelism-faster-jobs/)
160+
for more information:
161+
162+
```yaml
163+
build:
164+
parallelism: 4 # Run tests across 4 containers
165+
```
166+
167+
### SSH access for debugging
168+
169+
CircleCI provides built-in SSH access to debug failing builds. Click the
170+
**Rerun job with SSH** button on a failed job to get SSH connection details.
171+
See [Debugging with SSH](https://circleci.com/docs/ssh-access-jobs/) for more
172+
information.
173+
174+
### Adjust build timeout
175+
176+
If builds are timing out, increase the `no_output_timeout` value for
177+
long-running steps:
178+
179+
```yaml
180+
- run:
181+
name: Long running task
182+
command: ./scripts/long-task.sh
183+
no_output_timeout: 60m # Default is 10m
184+
```

0 commit comments

Comments
 (0)