Skip to content

[SDCI-2079] Document automatic job retries (Preview) - dedicated-only approach#36150

Closed
afontan wants to merge 3 commits intomasterfrom
alejandro.fontan/SDCI-2079-auto-retries-dedicated
Closed

[SDCI-2079] Document automatic job retries (Preview) - dedicated-only approach#36150
afontan wants to merge 3 commits intomasterfrom
alejandro.fontan/SDCI-2079-auto-retries-dedicated

Conversation

@afontan
Copy link
Copy Markdown
Contributor

@afontan afontan commented Apr 20, 2026

What does this PR do? What is the motivation?

Fixes SDCI-2079

Adds customer-facing documentation for the automatic job retries feature on GitHub Actions and GitLab. The feature is in Preview.

Approach C — Dedicated page only, no changes to provider pages. This is one of three variant PRs opened to compare documentation structures.

Changes:

  • New page: content/en/continuous_integration/pipelines/automatic_retries.md — single source of truth with provider tabs.
  • pipelines/_index.md — new row in the Supported features matrix with a "More info" link to the dedicated page.
  • github.md and gitlab.md are not modified — discovery is via the pipelines index only.

Other approaches in review:

  • Approach A — dedicated page plus a row in each provider's compatibility table.
  • Approach B — inline sections on each provider page.

Merge instructions

Merge readiness:

  • Ready for merge

Additional notes

Tone is Preview / private beta; access is gated via Datadog account team. Internal implementation details are intentionally excluded.

@afontan
[SDCI-2079] Document automatic job retries (Preview)
7c85104 
Adds customer-facing documentation for the automatic job retries
feature on GitHub Actions and GitLab. The feature is documented on a
dedicated page and surfaced in the supported features matrix on the
pipelines index. Provider setup pages are not modified.
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Apr 20, 2026

Preview links (active after the build_preview check completes)

New or renamed files

Modified Files

@afontan
[SDCI-2079] Apply editorial fixes from PR review
b2560c7 
- Replace "hiccups" colloquialism with "failures".
- Split long em-dashed sentence in Overview into two sentences.
- Replace passive "the retry outcome is reflected" with active.
- Replace "configurable maximum" with "maximum number of attempts" since
  the limit is not customer-tunable today.
- Replace "when the failure is determined retriable" with "when the failure
  is identified as retriable".
- Replace quoted "rerun failed jobs" with plain prose (GitHub API call).
- Replace awkward "compute minutes consumed by your pipelines" with
  "GitHub Actions compute usage".
- Add missing "as" in "aren't classified retriable" (GitLab tab).
- Make GitLab provider list items structurally consistent (all full
  sentences).
- Rename "Provider support" heading to "Provider-specific behavior" for
  stronger AI retrieval.
- Add GitHub Actions and GitLab setup pages to further_reading.
- Replace em dash with period in access-gating sentence.
@afontan
Copy link
Copy Markdown
Contributor Author

afontan commented Apr 21, 2026

Editorial review (post-fix round)

The automatic_retries.md prose is identical to approach A (#36147). Same editorial findings apply, plus one structural concern specific to this approach.

Higher-level

  • Requirements list — inconsistent item structure + banner redundancy. Bullets 1-2 are fragments; bullet 3 tacks on two sentences about Preview access that duplicate the top banner.
  • Discoverability (approach-specific). Users on github.md or gitlab.md have no signal that automatic retries exist for their provider. The only entry point is the pipelines index matrix. If this approach wins, consider at minimum adding a further_reading entry to the two provider pages pointing at automatic_retries.md.
  • "Preview." cell prefix in the matrix row still worth aligning with team convention — no other row uses a status prefix.

Must fix

content/en/continuous_integration/pipelines/automatic_retries.md — Requirements list inconsistent + redundant with banner

- CI Visibility enabled for your [GitHub Actions][1] or [GitLab][2] integration.
- [Datadog Source Code Integration][3] configured for the repositories where you want automatic retries.
- Automatic job retries enabled for your organization (see banner above for how to request access).

Suggestions

automatic_retries.md — "Genuine code defects are left alone." is idiomatic. Prefer Genuine code defects are not retried.

automatic_retries.md — "This reduces the number of pipelines developers manually re-run..." — "This" across a paragraph boundary plus awkward reduced-relative. Prefer:

Automatic retries reduce the number of pipelines that developers re-run by hand, shorten feedback loops, and keep pipeline success metrics focused on non-transient failures.

automatic_retries.md (GitLab tab) — "as soon as the job finishes failing" reads oddly. Prefer as soon as the job fails.

automatic_retries.md (GitLab tab) — Slight preposition redundancy; either reading is fine:

Smart retries work with GitLab.com (SaaS) and self-hosted GitLab instances reachable by the Datadog Source Code Integration.

automatic_retries.md — Structural AI-readability (optional). ## How it works → ## How automatic job retries work for stronger retrieval.

Link verification

  • [1]: /continuous_integration/pipelines/github/ — ✓
  • [2]: /continuous_integration/pipelines/gitlab/ — ✓
  • [3]: /integrations/guide/source-code-integration/ — ✓
  • Matrix-row "More info" link — resolves on merge.

Verdict

Comment — one must-fix (Requirements list), one structural concern (discoverability) specific to the dedicated-only approach, plus polish.

@afontan
[SDCI-2079] Apply second round of editorial fixes
d947c10 
- Collapse Requirements bullet 3 into a single fragment; redirect readers
  to the banner instead of repeating access-request instructions.
- Replace "Genuine code defects are left alone" with "not retried" to
  avoid the idiom.
- Replace ambiguous "This reduces the number of pipelines developers
  manually re-run" with "Automatic retries reduce the number of pipelines
  that developers re-run by hand".
- GitLab tab: replace awkward "as soon as the job finishes failing" with
  "as soon as the job fails", and drop the redundant second "with" in the
  Smart retries bullet.
@afontan
Copy link
Copy Markdown
Contributor Author

afontan commented Apr 21, 2026

Closing in favor of approach A (hybrid) — #36147. Thanks to everyone who weighed in.

@afontan afontan closed this Apr 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@afontan