Add Markdown Linter agentic workflow#581
Conversation
Adds a new agentic workflow (.github/workflows/markdown-linter.md) that runs Super Linter on weekdays at 2 PM UTC and on manual dispatch. The agent analyzes linter output and creates GitHub issues with categorized findings, severity breakdown, and fix recommendations. Adapted from https://github.com/githubnext/agentics/blob/main/workflows/markdown-linter.md with repo-specific conventions: PAT pool rotation, fork protection, pinned action SHAs, scoped bash tools, and safe-outputs.
|
Note This PR is from a fork and modifies infrastructure files ( Changes to infrastructure typically need to be submitted from a branch in Please consider recreating this PR from an upstream branch. If you don't have push access to |
There was a problem hiding this comment.
Pull request overview
Adds a new agentic workflow intended to run Super Linter’s Markdown validation on a schedule (weekdays) and on manual dispatch, then have a Copilot agent summarize results and open a categorized GitHub issue.
Changes:
- Introduces
.github/workflows/markdown-linter.mddefining the scheduled Super Linter run and an agent prompt to create a Markdown quality report issue. - Adds PAT pool rotation + fork protection + safe-outputs constraints for issue creation/noop.
Show a summary per file
| File | Description |
|---|---|
.github/workflows/markdown-linter.md |
New agentic workflow definition: run Super Linter for Markdown, upload log artifact, then have Copilot analyze it and (optionally) create a report issue. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comments suppressed due to low confidence (2)
.github/workflows/markdown-linter.md:98
actions/upload-artifactis referenced as@v7instead of a pinned commit SHA. Please pin it to the same SHA used elsewhere in.github/workflows/*to avoid unexpected upstream changes.
- name: Upload super-linter log
if: always()
uses: actions/upload-artifact@v7
with:
name: super-linter-log
path: super-linter.log
retention-days: 7
.github/workflows/markdown-linter.md:145
actions/download-artifactis referenced as@v8instead of a pinned commit SHA. Please pin it to a specific SHA (consistent with other workflows) to reduce supply-chain risk.
- name: Download super-linter log
uses: actions/download-artifact@v8
with:
name: super-linter-log
path: /tmp/gh-aw/
- Files reviewed: 1/1 changed files
- Comments generated: 5
| - name: Super-linter | ||
| uses: super-linter/super-linter@v8.5.0 | ||
| id: super-linter | ||
| env: | ||
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | ||
| CREATE_LOG_FILE: "true" | ||
| LOG_FILE: super-linter.log |
There was a problem hiding this comment.
The Super Linter step will typically exit non-zero when it finds lint violations, which would fail the super_linter job. Since the intent here is to always produce a report/issue from the log, consider making this step non-fatal (e.g., continue-on-error: true) and rely on the log parsing to drive whether an issue is created.
| DEFAULT_BRANCH: main | ||
| ENABLE_GITHUB_ACTIONS_STEP_SUMMARY: "true" | ||
| VALIDATE_MARKDOWN: "true" | ||
| VALIDATE_ALL_CODEBASE: "false" | ||
|
|
There was a problem hiding this comment.
This workflow description says it reports violations found “across the repository”, but Super Linter is configured with VALIDATE_ALL_CODEBASE: "false". If the goal is a full repo scan on the scheduled run, this setting likely conflicts with that intent; consider enabling full-codebase validation (or adjust the description to match the intended scope).
| - name: Check for linting issues | ||
| id: check-results | ||
| run: | | ||
| if [ -f "super-linter.log" ] && [ -s "super-linter.log" ]; then | ||
| if grep -qE "ERROR|WARN|FAIL" super-linter.log; then | ||
| echo "needs-linting=true" >> "$GITHUB_OUTPUT" | ||
| else | ||
| echo "needs-linting=false" >> "$GITHUB_OUTPUT" | ||
| fi | ||
| else | ||
| echo "needs-linting=false" >> "$GITHUB_OUTPUT" | ||
| fi | ||
|
|
There was a problem hiding this comment.
The check-results step computes a needs-linting output, but nothing in this workflow consumes it. Either wire this output into the agent run (to skip analysis when clean) or remove the step/output to avoid dead code and confusion.
| - name: Check for linting issues | |
| id: check-results | |
| run: | | |
| if [ -f "super-linter.log" ] && [ -s "super-linter.log" ]; then | |
| if grep -qE "ERROR|WARN|FAIL" super-linter.log; then | |
| echo "needs-linting=true" >> "$GITHUB_OUTPUT" | |
| else | |
| echo "needs-linting=false" >> "$GITHUB_OUTPUT" | |
| fi | |
| else | |
| echo "needs-linting=false" >> "$GITHUB_OUTPUT" | |
| fi |
| --- | ||
| name: "Markdown Linter" | ||
| description: > | ||
| Runs Markdown quality checks using Super Linter and creates issues | ||
| for violations found across the repository. | ||
|
|
There was a problem hiding this comment.
This PR adds a new agentic workflow source file, but there is no corresponding compiled .lock.yml workflow. Since GitHub only executes YAML workflows, this workflow won’t run on schedule/dispatch until the repo also includes the compiled markdown-linter.lock.yml generated via gh aw compile (and committed under .github/workflows/).
| persist-credentials: false | ||
|
|
||
| - name: Super-linter | ||
| uses: super-linter/super-linter@v8.5.0 |
There was a problem hiding this comment.
super-linter/super-linter is referenced by a version tag (v8.5.0) rather than a pinned commit SHA. This repo’s workflows generally pin actions to SHAs for supply-chain integrity; please pin Super Linter to a specific SHA (and keep the version in a comment if desired).
This issue also appears in the following locations of the same file:
- line 92
- line 141
| uses: super-linter/super-linter@v8.5.0 | |
| uses: super-linter/super-linter@<FULL_LENGTH_COMMIT_SHA_FOR_V8_5_0> # v8.5.0 |
Summary
Adds a new agentic workflow that runs Super Linter Markdown checks on weekdays at 2 PM UTC (and on manual dispatch), then has a Copilot agent analyze the output and create a GitHub issue with categorized findings, severity breakdown, and fix recommendations.
Adapted from githubnext/agentics
markdown-linter.mdwith repo-specific conventions:select-copilot-patactioncreate-issue(max 1, 2-day expiry,[linter]prefix,automation/code-qualitylabels) andnoopThe existing
markdownlint.ymlPR-gate workflow is unchanged — these serve different purposes (PR check vs. periodic repo-wide quality report).