Skip to content

Commit ece99fb

Browse files
deviantintegraldeviantintegral
committed
docs: rewrite example to be a single workflow
1 parent 72923ce commit ece99fb

File tree

1 file changed

+144
-63
lines changed

1 file changed

+144
-63
lines changed

‎src/content/blog/ddev-ci-warpbuild.md‎

Lines changed: 144 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -36,73 +36,154 @@ We had three parallel jobs that all required DDEV:
3636

3737
Note that our Playwright tests themselves run in parallel on a single worker as well, using [lullabot/playwright-drupal](https://github.com/lullabot/playwright-drupal). This allows us to optimize the additional startup time for installing Drupal itself (which can't be cached in a snapshot) across many tests.
3838

39-
After linking WarpBuild to our GitHub repository, we had to update our workflows. Here's the changes we made [after enabling Snapshots](https://docs.warpbuild.com/ci/snapshot-runners) in the WarpBuild UI.
40-
41-
1. Update workflows to use the WarpBuild runner such as `warp-ubuntu-2404-x64-16x`. WarpBuild has _many_ runner options available, including ARM and spot instances to reduce costs further. We'll explain `snapshot.key` and `inputs.snapshot` below.
42-
```yaml
43-
runs-on:
44-
"${{ contains(github.event.head_commit.message, '[warp-no-snapshot]') &&
45-
'warp-ubuntu-2404-x64-16x' ||
46-
format('warp-ubuntu-2404-x64-16x;snapshot.key=PROJECT-NAME-playwright-snapshot-1.24.10-v1-{0}', inputs.snapshot) }}"
47-
```
48-
2. Switch `actions/cache` to `WarpBuilds/cache`:
49-
```yaml
50-
- uses: WarpBuilds/cache@v1
51-
with:
52-
path: |
53-
${{ github.workspace }}/.ddev/.drainpipe-composer-cache
54-
${{ github.workspace }}/vendor
55-
${{ github.workspace }}/web/core
56-
${{ github.workspace }}/web/modules/contrib
57-
key: ${{ runner.os }}-composer-full-${{ hashFiles('**/composer.lock') }}
58-
```
59-
3. Create a hash of key files to know when the snapshot should be rebuilt.
60-
```yaml
61-
- name: Determine Snapshot Base
62-
id: snapshot-base
63-
run: |
64-
set -x
65-
hash=$(cat .github/actions/ddev/action.yml test/playwright/.yarnrc.yml test/playwright/yarn.lock | md5sum | cut -c 1-8)
66-
echo "snapshot=$hash" >> $GITHUB_OUTPUT
67-
shell: bash
68-
```
69-
This hash is used as a part of the `runs-on` key above, and when saving a snapshot below. That way, if DDEV or Playwright are upgraded, the pull request will build from scratch and create a new snapshot automatically.
70-
4. We check to see if we are running from a snapshot or not by testing for DDEV.
71-
```yaml
72-
- name: Find ddev
73-
id: find-ddev
74-
shell: bash
75-
run: |
76-
set -x
77-
DDEV_PATH=$(which ddev) || DDEV_PATH=''
78-
echo "ddev-path=$DDEV_PATH" >> "$GITHUB_OUTPUT"
79-
```
80-
5. After installing DDEV and running `ddev install-playwright`, we run tests. If they pass, we run a `Create snapshot` step. `matrix.shard` prevents us from wasting time creating multiple snapshots on all shards (we selected shard 2 randomly).
81-
```yaml
82-
- name: Clean up for the snapshot
83-
if: ${{ matrix.shard == 2 && steps.find-ddev.outputs.ddev-path != '/usr/bin/ddev'}}
84-
run: |
85-
ddev poweroff
86-
git clean -ffdx
87-
- name: Create snapshot
88-
uses: WarpBuilds/snapshot-save@v1
89-
if: ${{ matrix.shard == 2 && steps.find-ddev.outputs.ddev-path != '/usr/bin/ddev'}}
90-
with:
91-
alias: "PROJECT-NAME-playwright-snapshot-1.24.10-v1-${{ inputs.snapshot }}"
92-
fail-on-error: true
93-
wait-timeout-minutes: 60
94-
```
95-
It was important to include the DDEV version in the snapshot name so we could clear it when updating DDEV. We also had a version number in case we messed up the cache. We recommend using Renovate Custom Managers to keep it in sync with other ddev versions in your project.
96-
97-
We don't pin actions to hashes in these examples for easy copy-paste, but for security we always [use Renovate to pin hashes for us](https://docs.renovatebot.com/modules/manager/github-actions/#digest-pinning-and-updating).
98-
99-
The results?
39+
After linking WarpBuild to our GitHub repository, we had to update our workflows. Here is an example representing the changes we made to our workflow [after enabling Snapshots](https://docs.warpbuild.com/ci/snapshot-runners) in the WarpBuild UI.
40+
41+
Start with a basic workflow to trigger on pull requests and on merges to `main`.
42+
43+
```yaml
44+
name: "WarpBuild Snapshot Example"
45+
46+
on:
47+
push:
48+
branches: [main]
49+
pull_request:
50+
```
51+
52+
Before running our real work, we need to know what snapshot we could restore from. We start by creating a hash of key files that affect what gets saved in the snapshot. For example, if Playwright (and it's browser and system dependencies) are upgraded by Renovate, we want a new snapshot to be created. Extend or modify these files to match your own project setup.
53+
54+
```yaml
55+
jobs:
56+
determine-snapshot:
57+
steps:
58+
- uses: actions/checkout@v6
59+
60+
- name: Determine Snapshot Base
61+
id: snapshot-base
62+
run: |
63+
set -x
64+
hash=$(cat .github/workflows/test.yml test/playwright/.yarnrc.yml test/playwright/yarn.lock | md5sum | cut -c 1-8)
65+
echo "snapshot=$hash" >> $GITHUB_OUTPUT
66+
shell: bash
67+
```
68+
69+
WarpBuild needs some additional configuration to tell GitHub Actions to use it as a runner. This could be as simple as `runs-on: 'warp-<runner-type>'` if you aren't using snapshots. WarpBuild has _many_ runner options available, including ARM and spot instances to reduce costs further.
70+
71+
The runs-on statement:
72+
73+
1. [Skips snapshots via commit messages](https://github.com/WarpBuilds/snapshot-save#conditional-snapshot-usage).
74+
2. Uses a "16x" sized runner so we can run tests in parallel.
75+
3. Creates a snapshot key with the project name, the ddev version, a manual version number, and the short hash of the files from above.
76+
77+
We also switch to the WarpBuild cache (so it's local to the runner) and check out the project. Update the cache paths as appropriate for your project.
78+
79+
```yaml
80+
build-and-test:
81+
needs: [ determine-snapshot ]
82+
runs-on:
83+
"${{ contains(github.event.head_commit.message, '[warp-no-snapshot]') &&
84+
'warp-ubuntu-2404-x64-16x' ||
85+
'warp-ubuntu-2404-x64-16x;snapshot.key=my-project-ddev-1.24.10-v1-{0}', inputs.snapshot }}"
86+
87+
steps:
88+
- uses: WarpBuilds/cache@v1
89+
with:
90+
path: |
91+
${{ github.workspace }}/.ddev/.drainpipe-composer-cache
92+
${{ github.workspace }}/vendor
93+
${{ github.workspace }}/web/core
94+
${{ github.workspace }}/web/modules/contrib
95+
key: ${{ runner.os }}-composer-full-${{ hashFiles('**/composer.lock') }}
96+
97+
- uses: actions/checkout@v6
98+
```
99+
100+
We need to add logic to either start from scratch and install everything or restore from a snapshot. Since DDEV isn't installed by default in runners, we can use its presence to easily determine if we're running from inside a snapshot or not. We save these values for later use.
101+
102+
```yaml
103+
- name: Find ddev
104+
id: find-ddev
105+
run: |
106+
DDEV_PATH=$(which ddev) || DDEV_PATH=''
107+
echo "ddev-path=$DDEV_PATH" >> "$GITHUB_OUTPUT"
108+
if [ -n "$DDEV_PATH" ]; then
109+
echo "ddev found at: $DDEV_PATH (restored from snapshot)"
110+
else
111+
echo "ddev not found (fresh runner, will install)"
112+
fi
113+
```
114+
115+
If ddev exists, we can skip installing it:
116+
117+
```yaml
118+
- name: Install ddev
119+
uses: ddev/github-action-setup-ddev@v1
120+
if: ${{ steps.find-ddev.outputs.ddev-path != '/usr/bin/ddev' }}
121+
with:
122+
autostart: false
123+
# When updating this version, also update the snapshot key above
124+
version: 1.24.10
125+
```
126+
127+
At this point, we've got DDEV ready to go, so we can start it and run tests or anything else.
128+
129+
```yaml
130+
- name: Start ddev
131+
run: |
132+
# Playwright users may want to run `ddev install-playwright` here.
133+
ddev start
134+
ddev describe
135+
136+
- name: Run tests
137+
run: |
138+
ddev exec echo "Running tests..."
139+
# Replace this with one or more test commands for your project.
140+
ddev task test:playwright
141+
```
142+
143+
Now, tests have passed and we can create a snapshot if needed. If tests fail, we never create a snapshot so that we don't accidentally commit a broken environment.
144+
145+
We shut down DDEV since we're going to clean up generated files. Thsi keeps our snapshot a bit smaller, and gives us an opportunity to clean up any credentials that might be used as a part of the job. While we don't typically need a Pantheon token for tests, we do need it for some other jobs we run with DDEV.
146+
147+
```yaml
148+
- name: Clean up for snapshot
149+
if: ${{ steps.find-ddev.outputs.ddev-path != '/usr/bin/ddev' }}
150+
run: |
151+
# Stop ddev to ensure clean state
152+
ddev poweroff
153+
# Remove any cached credentials or tokens
154+
rm -f ~/.terminus/cache/session
155+
# Clean git state and temporary files
156+
git clean -ffdx
157+
```
158+
159+
Now we can actually save the snapshot. We skip this if we can since it takes a bit of time to save and upload. There's no point in rewriting our snapshot if it hasn't changed! The `wait-timeout-minutes` is set very high, but in practice this step only takes a minute or two. We just don't want this step to fail if Amazon is slow.
160+
161+
```yaml
162+
- name: Save WarpBuild snapshot
163+
uses: WarpBuilds/snapshot-save@v1
164+
if: ${{ steps.find-ddev.outputs.ddev-path != '/usr/bin/ddev' }}
165+
# Using a matrix build? Avoid thrashing snapshots by only saving from one shard.
166+
# if: ${{ matrix.shard == 1 && steps.find-ddev.outputs.ddev-path != '/usr/bin/ddev'}}
167+
with:
168+
# Must match the snapshot.key in runs-on above
169+
alias: "my-project-ddev-1.24.10-v1-${{ inputs.snapshot }}"
170+
fail-on-error: true
171+
wait-timeout-minutes: 30
172+
```
173+
174+
To test, once you have jobs passing, you can rerun them from the GitHub Actions UI. If everything is working, you will see all steps related to installing DDEV skipped.
175+
176+
177+
Note: We don't pin actions to hashes in these examples for easy copy-paste, but for security we always [use Renovate to pin hashes for us](https://docs.renovatebot.com/modules/manager/github-actions/#digest-pinning-and-updating). We would also like to use [Renovate Custom Managers](https://docs.renovatebot.com/modules/manager/regex/) to automatically offer DDEV upgrades and keep the version number in sync across all files and locations.
178+
179+
## The Results?
100180

101181
- The time to start Playwright tests was reduced from **4 to 5 minutes** to **1 to 2 minutes**. Now, the longest time in the workflow is the `ddev start` command.
102-
- We thought costs would go down, but we ended up writing many more tests! CI costs stayed roughly similar to our previous GitHub costs but with greater test coverage and faster reports.
182+
- This project uses eight parallel runners, so we're saving about 24 minutes of CI costs _per commit_.
183+
- We thought costs would go down, but we ended up writing many more tests! CI costs with WarpBuild stayed roughly similar to our previous GitHub costs but with greater test coverage and faster reports.
103184
- While ZAP tests needed browsers like Playwright, static tests didn't. However, restoring snapshots was fast enough creating separate snapshots without browsers wasn't worth the complexity.
104185
- Snapshot storage costs are inexpensive enough to not matter compared to the CI runner cost.
105186

106-
While this seems like a lot of work, it was only about half a day to set up and test - and that was with a new, in-beta service with minimal documentation and rough edges. We haven't really had to touch this code since. Setting up new projects is an hour, at most.
187+
While this seems like a lot of work, it was only about half a day to set up and test – and that was when WarpBuild was in beta, had minimal documentation and some rough edges. We haven't really had to touch this code since. Setting up new projects is an hour, at most.
107188

108189
Do you have other optimizations for DDEV in CI to share? Post in the comments, we'd love to hear them!

0 commit comments

Comments
 (0)