From bcb538b69483b97ad78ff73259fd296c421f012c Mon Sep 17 00:00:00 2001 From: Randy Fay Date: Fri, 19 Sep 2025 09:56:09 -0600 Subject: [PATCH 01/10] Create AGENTS.md with team communication style and development guidelines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace CLAUDE.md with symlink to AGENTS.md. Added communication style guidelines including banned vague superlatives and team development patterns from main DDEV repo. 🤖 Developed with assistance from [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- AGENTS.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 39b278c8..12b7a69e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -61,13 +61,12 @@ Only commit when explicitly requested by the user. Use descriptive branch names that include: - Date in YYYYMMDD format -- Your GitHub username +- Your GitHub username - Brief description of the work Format: `YYYYMMDD__` Examples: - - `20250919_rfay_update_quickstart` - `20250919_username_fix_blog_styling` - `20250919_contributor_add_sponsor` @@ -200,7 +199,6 @@ Post content here... ### Authors Add new authors to `src/content/authors/` with schema: - - name (must match blog post frontmatter) - firstName - avatarUrl (optional) @@ -257,4 +255,4 @@ Production requires `GITHUB_TOKEN` environment variable in Cloudflare Pages sett - [Astro Documentation](https://docs.astro.build) - [DDEV Documentation](https://ddev.readthedocs.io/) -- [Contributing to ddev.com Training](https://ddev.com/blog/ddev-website-for-contributors/) +- [Contributing to ddev.com Training](https://ddev.com/blog/ddev-website-for-contributors/) \ No newline at end of file From 46f7a2244009d486c97f59545616b3175adf610e Mon Sep 17 00:00:00 2001 From: Randy Fay Date: Fri, 19 Sep 2025 10:25:51 -0600 Subject: [PATCH 02/10] Pacify prettier --- .github/FORK_PREVIEW_SETUP.md | 30 ++++++++++++++---------------- AGENTS.md | 6 ++++-- 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/.github/FORK_PREVIEW_SETUP.md b/.github/FORK_PREVIEW_SETUP.md index 587bc7b8..d4326104 100644 --- a/.github/FORK_PREVIEW_SETUP.md +++ b/.github/FORK_PREVIEW_SETUP.md @@ -13,9 +13,13 @@ The workflow in `.github/workflows/cloudflare-preview-forks.yml` implements a se ### 1. Cloudflare Pages Project -The workflow uses the existing `ddev-com-front-end` Cloudflare Pages project that serves the main site. This provides consistent preview URLs and centralized management. +Create a **Direct Upload** Cloudflare Pages project (not Git-connected): -**No additional project setup needed** - the workflow will create `pr-{number}` branch deployments within the existing project using Cloudflare's Direct Upload API. +1. Go to [Cloudflare Pages](https://dash.cloudflare.com/pages) +2. Click "Create a project" +3. Choose "Direct Upload" (not "Connect to Git") +4. Name your project (e.g., `ddev-com-fork-previews`) +5. Note the project name for step 3 ### 2. Cloudflare API Token @@ -31,19 +35,13 @@ Create an API token with Pages permissions: 5. Set account and zone resources as needed 6. Save the token -### 3. Repository Secrets and Variables +### 3. Repository Secrets -Add these in GitHub repository settings → Secrets and variables → Actions: - -**Repository Secrets:** - -- `TESTS_SERVICE_ACCOUNT_TOKEN`: 1Password service account token (if not already configured) -- Note: `CF_API_TOKEN` is loaded from 1Password `test-secrets` vault, not directly as a repository secret - -**Repository Variables:** +Add these secrets in GitHub repository settings → Secrets and variables → Actions: +- `CF_API_TOKEN`: The API token from step 2 - `CF_ACCOUNT_ID`: Your Cloudflare Account ID (found in dashboard sidebar) -- `CF_PAGES_PROJECT`: Set to `ddev-com-front-end` (the main site's Cloudflare project) +- `CF_PAGES_PROJECT`: The project name from step 1 ### 4. Repository Variables (Optional) @@ -95,7 +93,7 @@ The workflow is triggered automatically for: 1. Downloads build artifact from Stage 1 2. Deploys to Cloudflare Pages using API -3. Creates stable preview URL: `https://pr-{number}.ddev-com-front-end.pages.dev` +3. Creates stable preview URL: `https://project.pages.dev/pr-{number}` 4. Comments preview URL on the PR 5. Updates comment on subsequent pushes @@ -129,9 +127,9 @@ The workflow is triggered automatically for: ### Preview URL Issues -- Verify `ddev-com-front-end` Cloudflare Pages project exists and is accessible -- Check account ID matches the project's organization -- Ensure `CF_PAGES_PROJECT` is set to `ddev-com-front-end` +- Verify Cloudflare Pages project exists +- Check account ID matches organization +- Ensure project name in `CF_PAGES_PROJECT` is exact ## Manual Testing diff --git a/AGENTS.md b/AGENTS.md index 12b7a69e..39b278c8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -61,12 +61,13 @@ Only commit when explicitly requested by the user. Use descriptive branch names that include: - Date in YYYYMMDD format -- Your GitHub username +- Your GitHub username - Brief description of the work Format: `YYYYMMDD__` Examples: + - `20250919_rfay_update_quickstart` - `20250919_username_fix_blog_styling` - `20250919_contributor_add_sponsor` @@ -199,6 +200,7 @@ Post content here... ### Authors Add new authors to `src/content/authors/` with schema: + - name (must match blog post frontmatter) - firstName - avatarUrl (optional) @@ -255,4 +257,4 @@ Production requires `GITHUB_TOKEN` environment variable in Cloudflare Pages sett - [Astro Documentation](https://docs.astro.build) - [DDEV Documentation](https://ddev.readthedocs.io/) -- [Contributing to ddev.com Training](https://ddev.com/blog/ddev-website-for-contributors/) \ No newline at end of file +- [Contributing to ddev.com Training](https://ddev.com/blog/ddev-website-for-contributors/) From be11d493bfd987384c7e7be842eebce1105ca627 Mon Sep 17 00:00:00 2001 From: Randy Fay Date: Fri, 19 Sep 2025 09:56:09 -0600 Subject: [PATCH 03/10] Create AGENTS.md with team communication style and development guidelines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace CLAUDE.md with symlink to AGENTS.md. Added communication style guidelines including banned vague superlatives and team development patterns from main DDEV repo. 🤖 Developed with assistance from [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- AGENTS.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 39b278c8..12b7a69e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -61,13 +61,12 @@ Only commit when explicitly requested by the user. Use descriptive branch names that include: - Date in YYYYMMDD format -- Your GitHub username +- Your GitHub username - Brief description of the work Format: `YYYYMMDD__` Examples: - - `20250919_rfay_update_quickstart` - `20250919_username_fix_blog_styling` - `20250919_contributor_add_sponsor` @@ -200,7 +199,6 @@ Post content here... ### Authors Add new authors to `src/content/authors/` with schema: - - name (must match blog post frontmatter) - firstName - avatarUrl (optional) @@ -257,4 +255,4 @@ Production requires `GITHUB_TOKEN` environment variable in Cloudflare Pages sett - [Astro Documentation](https://docs.astro.build) - [DDEV Documentation](https://ddev.readthedocs.io/) -- [Contributing to ddev.com Training](https://ddev.com/blog/ddev-website-for-contributors/) +- [Contributing to ddev.com Training](https://ddev.com/blog/ddev-website-for-contributors/) \ No newline at end of file From bbbff20a3ad60d2659445c2dabcf0535904d0c4d Mon Sep 17 00:00:00 2001 From: Randy Fay Date: Fri, 19 Sep 2025 10:31:27 -0600 Subject: [PATCH 04/10] simple edit to readme --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index ca7e0c83..e9462623 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ # ddev.com Astro code + Source code for [ddev.com](https://ddev.com)’s static front end, built with [Astro](https://astro.build) to keep things organized, maintainable, and fast. ## Overview From 175cafcba7e634cb3419bd205f2496d0f6ec4207 Mon Sep 17 00:00:00 2001 From: Randy Fay Date: Fri, 19 Sep 2025 10:51:23 -0600 Subject: [PATCH 05/10] dummy commit From 18c1e502a2b858b7e9f4b6fe12f1e3ca2fea3ba4 Mon Sep 17 00:00:00 2001 From: Randy Fay Date: Fri, 19 Sep 2025 10:55:15 -0600 Subject: [PATCH 06/10] Add blog copy --- ...ate-github-actions-contributor-training.md | 159 +----------------- 1 file changed, 5 insertions(+), 154 deletions(-) diff --git a/src/content/blog/tmate-github-actions-contributor-training.md b/src/content/blog/tmate-github-actions-contributor-training.md index 370bb623..2d57b2fb 100644 --- a/src/content/blog/tmate-github-actions-contributor-training.md +++ b/src/content/blog/tmate-github-actions-contributor-training.md @@ -1,8 +1,7 @@ --- -title: "Contributor Training: Tmate for Debugging GitHub Actions Workflows" -pubDate: 2024-10-23 -modifiedDate: 2025-02-26 -summary: Contributor training - Using tmate to debug and experiment with GitHub Actions. +title: "A new blog with stuff in it and forked preview" +pubDate: 2025-10-23 +summary: New experimental blog author: Randy Fay featureImage: src: /img/blog/2024/10/github-actions-tmate-debugging.png @@ -12,154 +11,6 @@ categories: - Guides --- -Here's our October 23, 2024 [Contributor Training](/blog/category/training) on using `ddev debug test` to help other users: - -
- -
- -## What is Tmate? - -[mxschmitt/action-tmate](https://github.com/mxschmitt/action-tmate) provides a way to SSH into actual running GitHub Actions VMs to debug your tests. - -## Why do we need Tmate? - -Often it's hard to understand what has happened with an test because all we see in GitHub's web UI is the output, and we can't interact with it. And trying to recreate the test environment is sometimes fine, but sometimes it's hard to recreate the test. GitHub runners have different memory configuration, disk space, and different packages installed, and they're typically running AMD64 Ubuntu, which may not be something we have easy access to. - -## Alternatives to Tmate - -1. We normally will try to understand a test failure by running it locally. -2. Running in a similar Linux/AMD64 system like GitHub Codespaceds is a pretty easy option. -3. [nektos/act](https://github.com/nektos/act) is another recommended competitor to Tmate. It uses Docker and a Docker image to run an action on your local machine. I haven't had luck with it when I've tried it. See Stas's experience with `act` [below](#how-to-useact). - -## Security Concerns - -If your test has secrets, then anyone who can SSH into it has access to those secrets. - -In addition, the owners of `ssh.tmate.io` clearly have access to the SSH session you're experimenting with, so think carefully about secrets that might be exposed. (In many tests, there are no secrets likely exposed or available. We have a couple of DDEV GitHub Actions that have sensitive secrets, and a few more that have far-less sensitive secrets.) - -I recommend always using `limit-access-to-actor: true` so that only the user that has launched the test can SSH into it. - -## Usage Examples - -These examples are all at [rfay/tmate-demos](https://github.com/rfay/tmate-demos/), which you can fork and experiment with to your heart's delight. - -### Basic on-push example with tmate running after the work is done - -[This on-push example](https://github.com/rfay/tmate-demos/blob/main/.github/workflows/ddev-drupal-setup-on-push.yaml) just does some work (sets up DDEV and a Drupal project) and then right after that the Tmate action starts up and starts telling you how to SSH into the test. - -### Detached example, where Tmate starts at the end - -In the [detached example](https://github.com/rfay/tmate-demos/blob/main/.github/workflows/detached.yaml) Tmate is set up early in the workflow, but is set to `detached: true`, so doesn't become active until everything else is done. However, if there's an error, we won't get to the Tmate step this way. - -### Failure Example - -Often we have a complex step and want to be able to debug it if it fails. For this we can used `if: ${{ failure() }}`, as shown in the [failure example](https://github.com/rfay/tmate-demos/blob/main/.github/workflows/on_fail.yaml). Tmate kicks in automatically if the step _before_ it fails. It would be nicer if it kicked in on any failure, but it just kicks in when the step before fails. - -### Workflow Dispatch Example - -The [Workflow Dispatch](https://github.com/rfay/tmate-demos/blob/main/.github/workflows/workflow_dispatch.yaml) is one of my favorite techniques, because you can easily restart the workflow as many times as you like, and choosing whether to invoke Tmate is just a click of a checkbox. - -## How to Use Act - -[nektos/act](https://github.com/nektos/act) offers a way to locally simulate GitHub Actions workflows. - -In this example `.github/workflows/jekyll-gh-pages.yml`, we deploy Jekyll to GitHub Pages with dynamic addition of JSON data to the website. Our focus is to debug the API call to GitHub using JavaScript: - -```yaml -name: Deploy Jekyll with GitHub Pages - -on: - push: - branches: [main] - workflow_dispatch: - -permissions: - contents: read - pages: write - id-token: write - -concurrency: - group: "pages" - cancel-in-progress: false - -jobs: - build: - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v4 - - name: Setup Pages - uses: actions/configure-pages@v5 - - name: Build with Jekyll - uses: actions/jekyll-build-pages@v1 - with: - source: ./ - destination: ./_site - - name: Get GitHub repositories - uses: actions/github-script@v7 - with: - github-token: ${{ secrets.GITHUB_TOKEN }} - script: | - const { data } = await github.rest.search.repos({q: 'user:stasadev'}) - console.log(data) - const fs = require('fs'); - fs.writeFileSync('data.json', JSON.stringify(data, null, 2)); - - name: Add JSON files to the site - run: | - cat data.json | sudo tee ./_site/data.json - - name: Upload artifact - uses: actions/upload-pages-artifact@v3 - deploy: - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - runs-on: ubuntu-latest - needs: build - steps: - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 -``` - -1. Simplify the workflow file `.github/workflows/jekyll-gh-pages.yml` by removing unrelated code to focus on testing the API call: - - ```yaml - jobs: - build: - runs-on: ubuntu-latest - steps: - - name: Get my GitHub repositories - uses: actions/github-script@v7 - with: - github-token: ${{ secrets.GITHUB_TOKEN }} - script: | - const { data } = await github.rest.search.repos({q: 'user:stasadev'}) - console.log(data) - const fs = require('fs'); - fs.writeFileSync('data.json', JSON.stringify(data, null, 2)); - ``` - - This workflow retrieves repositories for a specified user, writes them to `data.json`, and outputs the result with `console.log()`. - -2. Run the workflow locally with `act` in your project's root directory: - - ```bash - act -P ubuntu-latest=catthehacker/ubuntu:act-latest \ - --bind \ - --job build \ - -s GITHUB_TOKEN=my_token - ``` - - - `-P ubuntu-latest=catthehacker/ubuntu:act-latest`: Specifies the Docker image to use for the `ubuntu-latest` environment. If not specified, `act` uses the default image from its `.actrc` file (see [GitHub issue](https://github.com/nektos/act/issues/2219) for more details). - - `--bind`: Mounts the current working directory into the container, allowing files generated in the container (like `data.json`) to be accessible in the host file system. - - `--job build`: Tells `act` to run only the `build` job from the workflow. - - `-s GITHUB_TOKEN=my_token`: Sets a secret (`GITHUB_TOKEN`) for the workflow, where `my_token` should be replaced with a valid GitHub token for authentication. - -The primary advantage of using `act` in this context is the ability to efficiently debug API calls locally in just a few seconds, without the need to commit changes, push them to GitHub, and wait for the workflow to complete, which typically takes several minutes. - -## Contributions welcome! - -Your suggestions to improve this blog are welcome. You can do a PR to this blog adding your techniques. Info and a training session on how to do a PR to anything in ddev.com is at [DDEV Website For Contributors](ddev-website-for-contributors.md). - Join us for the next [DDEV Live Contributor Training](/blog/contributor-training/). Use the [contact](/contact) link to ask for a calendar invitation. +:w +: From 29f9f755726a762ee2ecf5c7d4df2f813449a1cc Mon Sep 17 00:00:00 2001 From: Randy Fay Date: Fri, 19 Sep 2025 11:01:16 -0600 Subject: [PATCH 07/10] pacify prettier --- .ddev/config.yaml | 1 - AGENTS.md | 6 ++++-- README.md | 1 - 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.ddev/config.yaml b/.ddev/config.yaml index 0462ca68..95a84979 100644 --- a/.ddev/config.yaml +++ b/.ddev/config.yaml @@ -1,4 +1,3 @@ -name: ddev.com type: php docroot: dist php_version: "8.1" diff --git a/AGENTS.md b/AGENTS.md index 12b7a69e..39b278c8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -61,12 +61,13 @@ Only commit when explicitly requested by the user. Use descriptive branch names that include: - Date in YYYYMMDD format -- Your GitHub username +- Your GitHub username - Brief description of the work Format: `YYYYMMDD__` Examples: + - `20250919_rfay_update_quickstart` - `20250919_username_fix_blog_styling` - `20250919_contributor_add_sponsor` @@ -199,6 +200,7 @@ Post content here... ### Authors Add new authors to `src/content/authors/` with schema: + - name (must match blog post frontmatter) - firstName - avatarUrl (optional) @@ -255,4 +257,4 @@ Production requires `GITHUB_TOKEN` environment variable in Cloudflare Pages sett - [Astro Documentation](https://docs.astro.build) - [DDEV Documentation](https://ddev.readthedocs.io/) -- [Contributing to ddev.com Training](https://ddev.com/blog/ddev-website-for-contributors/) \ No newline at end of file +- [Contributing to ddev.com Training](https://ddev.com/blog/ddev-website-for-contributors/) diff --git a/README.md b/README.md index e9462623..ca7e0c83 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,5 @@ # ddev.com Astro code - Source code for [ddev.com](https://ddev.com)’s static front end, built with [Astro](https://astro.build) to keep things organized, maintainable, and fast. ## Overview From 50d44da10a70c4ae28528b89f44798911436e92d Mon Sep 17 00:00:00 2001 From: Randy Fay Date: Fri, 19 Sep 2025 12:32:43 -0600 Subject: [PATCH 08/10] dummy commit From 70eeaf21000f6680ff0b80cbf1cc0ad8f44aa134 Mon Sep 17 00:00:00 2001 From: Randy Fay Date: Fri, 19 Sep 2025 12:39:04 -0600 Subject: [PATCH 09/10] The previous one was 2e1 From cd8d340585767b90612f3f9bf81514f8e5a84a95 Mon Sep 17 00:00:00 2001 From: Randy Fay Date: Fri, 19 Sep 2025 12:47:37 -0600 Subject: [PATCH 10/10] fpr3 first try