[Discuss]:discuss preventing redundant website documentation update PRs

[SHUBHANSHU602]

Description

While reviewing update-docs-in-website.yml, I noticed that the workflow automatically creates a PR in the asyncapi/website repository whenever generator documentation changes on master.

The workflow currently:

Checks out the Generator repository.
Checks out the Website repository.
Creates a new branch using the Generator commit SHA.
Copies the latest Generator documentation into the Website repository.
Pushes the branch.
Creates a PR in the Website repository.

This raises a potential issue when multiple documentation changes are pushed to master in a short period of time.

For example:

Generator commit A
↓
Workflow A starts

Generator commit B
↓
Workflow B starts

Both workflows can potentially create
separate Website PRs

The PR created from commit A could become outdated once commit B is available.

Discussion

Would it make sense to add a mechanism to prevent redundant or outdated documentation update runs/PRs?

Possible approaches could include:

workflow-level concurrency to cancel outdated runs;
detecting and updating an existing documentation PR instead of creating a new one;
another mechanism for ensuring that only the latest Generator documentation update is proposed to the Website repository.

I haven't implemented a solution yet because this workflow performs changes in another repository, so I think the expected behavior should be agreed upon before choosing the implementation.

I'd appreciate feedback on the preferred approach.

[SHUBHANSHU602]

@dosu ,what do u think?

[dosubot]

Great discussion — this is a real concern worth addressing. Looking at the current update-docs-in-website.yml, I'd lean toward workflow-level concurrency as the simplest first step, combined with a fixed branch name to prevent redundant PRs.

Here's my take on each option:

1. Workflow-level concurrency (recommended starting point)

You've already applied this pattern successfully to other workflows in this repo [1]. Adding a concurrency block to update-docs-in-website.yml is low-risk:

concurrency:
  group: update-generator-docs-website
  cancel-in-progress: true

This ensures only one run proceeds at a time and the latest commit "wins." The downside is that a cancelled run won't clean up any already-pushed branch or PR — but since this only triggers on master, stale branches are a manageable edge case.

2. Detect and update an existing PR

More elegant but more complex — you'd use gh pr list to check for an open PR with a predictable title, then either update the existing branch or close the stale one. This avoids multiple open PRs entirely but requires more scripting and has more failure modes (e.g., the existing PR has already been merged or changed).

3. Use a fixed branch name instead of github.sha

A simpler middle ground: the workflow currently creates branches named update-generator-docs-${{ github.sha }} [2]. Instead, use a fixed name like update-generator-docs, then force-push to that branch on each run. If a PR already exists against that branch, it auto-updates in place.

My recommendation: Combine concurrency control (prevents redundant runs) with a fixed branch name (prevents redundant PRs). The gh pr create command would fail if a PR already exists, so you'd need a guard like:

gh pr list --head update-generator-docs --state open | grep -q . || \
  gh pr create --title "docs(generator): update latest generator documentation" \
               --body "Updated generator documentation" \
               --head "update-generator-docs"

That way, the first run creates the PR and subsequent runs just force-push new commits to the same branch, keeping the PR current without creating duplicates.

Since this touches a cross-repo workflow, I agree it's worth aligning with maintainers on the preferred pattern before implementing.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[SHUBHANSHU602]

@derberg Please have a look .