From agent-almanac
Sets up GitHub Actions CI/CD to automatically regenerate putior workflow diagrams on push. Covers workflow YAML creation, R script for diagram generation with sentinel markers, auto-commit, and README sentinel integration.
How this skill is triggered — by the user, by Claude, or both
Slash command
/agent-almanac:setup-putior-ciThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Configure GitHub Actions to automatically regenerate workflow diagrams when source code changes, keeping documentation in sync with code.
Configure GitHub Actions to automatically regenerate workflow diagrams when source code changes, keeping documentation in sync with code.
README.md, docs/workflow.md)"github")"./R/" or "./src/")main)Create the workflow YAML file for automated diagram generation.
# .github/workflows/update-workflow-diagram.yml
name: Update Workflow Diagram
on:
push:
branches: [main]
paths:
- 'R/**'
- 'src/**'
- 'scripts/**'
permissions:
contents: write
jobs:
update-diagram:
if: github.actor != 'github-actions[bot]'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: r-lib/actions/setup-r@v2
with:
use-public-rspm: true
- name: Install putior
run: |
install.packages("putior")
shell: Rscript {0}
- name: Generate workflow diagram
run: |
Rscript scripts/generate-workflow-diagram.R
- name: Commit updated diagram
run: |
git config --local user.name "github-actions[bot]"
git config --local user.email "github-actions[bot]@users.noreply.github.com"
git add README.md docs/workflow.md # Adjust to match your target files
git diff --staged --quiet || git commit -m "docs: update workflow diagram [skip ci]"
git push
Expected: File created at .github/workflows/update-workflow-diagram.yml.
On failure: Ensure the .github/workflows/ directory exists. Adjust the paths filter to match where annotated source files live in the repository.
Create the R script that generates the diagram and updates target files using sentinel markers.
# scripts/generate-workflow-diagram.R
library(putior)
# Scan source files for annotations (exclude build scripts to avoid circular refs)
workflow <- put_merge("./R/", merge_strategy = "supplement",
exclude = c("generate-workflow-diagram\\.R$"),
log_level = NULL) # Set to "DEBUG" to troubleshoot CI diagram generation
# Generate Mermaid code
mermaid_code <- put_diagram(workflow, output = "raw", theme = "github")
# Read target file (e.g., README.md)
readme <- readLines("README.md")
# Find sentinel markers
start_marker <- "<!-- PUTIOR-WORKFLOW-START -->"
end_marker <- "<!-- PUTIOR-WORKFLOW-END -->"
start_idx <- which(readme == start_marker)
end_idx <- which(readme == end_marker)
if (length(start_idx) == 1 && length(end_idx) == 1 && end_idx > start_idx) {
# Replace content between sentinels
new_content <- c(
readme[1:start_idx],
"",
"```mermaid",
mermaid_code,
"```",
"",
readme[end_idx:length(readme)]
)
writeLines(new_content, "README.md")
cat("Updated README.md workflow diagram\n")
} else {
warning("Sentinel markers not found in README.md. Add them manually:\n",
start_marker, "\n", end_marker)
}
# Also write standalone diagram file
writeLines(
c("# Workflow Diagram", "",
"```mermaid", mermaid_code, "```"),
"docs/workflow.md"
)
cat("Updated docs/workflow.md\n")
Expected: Script at scripts/generate-workflow-diagram.R that reads annotations, generates Mermaid code, and replaces content between sentinel markers.
On failure: If put_merge() returns empty, check that source paths match the repository layout. Adjust "./R/" to the actual source directory.
The workflow must avoid infinite loops where an auto-commit re-triggers the same workflow. Pushes made with the default GITHUB_TOKEN typically do not trigger new workflow runs, but the workflow also includes an explicit if: guard on the job as a safety net.
Key configuration points:
permissions: contents: write grants push accessif: github.actor != 'github-actions[bot]' skips the job when the push came from the bot itselfgit diff --staged --quiet || git commit only commits if there are changes[skip ci] in the commit message is a convention some CI systems honor (not built into GitHub Actions, but useful as a signal)github-actions[bot]Expected: The workflow only commits when diagrams actually change. No empty commits, no infinite loops.
On failure: If push fails with permission denied, check repository settings: Settings > Actions > General > Workflow permissions must be set to "Read and write permissions".
Insert sentinel markers in the target file where the diagram should appear.
## Workflow
<!-- PUTIOR-WORKFLOW-START -->
<!-- This section is auto-generated by putior CI. Do not edit manually. -->
```mermaid
flowchart TD
A["Placeholder — will be replaced on next CI run"]
**Expected:** Sentinel markers in README.md (or other target file). The content between them will be replaced on each CI run.
**On failure:** Ensure markers are on their own lines with no leading/trailing whitespace. The script matches exact line content.
### Step 5: Test the Pipeline
Trigger the workflow and verify the diagram updates.
```bash
# Make a small change to trigger the workflow
echo "# test" >> R/some-file.R
git add R/some-file.R
git commit -m "test: trigger workflow diagram update"
git push
# Monitor the GitHub Actions run
gh run watch
# Verify the diagram was updated
git pull
cat README.md | grep -A 5 "PUTIOR-WORKFLOW-START"
Expected: GitHub Actions run completes successfully. The diagram between sentinel markers in README.md is updated with current workflow data.
On failure: Check the Actions log for errors. Common issues:
putior package not available: add to DESCRIPTION Suggests or install explicitly in the workflowput_merge() path must be relative to the repo root.github/workflows/update-workflow-diagram.yml exists and is valid YAMLscripts/generate-workflow-diagram.R runs without errors locally<!-- PUTIOR-WORKFLOW-START --> and <!-- PUTIOR-WORKFLOW-END --> sentinelsif: guard prevents infinite commit loops from bot pushesGITHUB_TOKEN typically don't trigger new runs, but always add an explicit if: github.actor != 'github-actions[bot]' guard on the job. The [skip ci] tag in the commit message is a useful convention but is not a built-in GitHub Actions mechanism.permissions: contents: write in the workflow file, or configure it in repository settings."./R/" or "./src/" must match the actual directory structure.renv::restore() before putior is available. Alternatively, install putior explicitly in the workflow.paths trigger filter to directories that contain PUT annotations, not the entire repo.generate-workflow-diagram — the manual version of what this CI automatessetup-github-actions-ci — general GitHub Actions CI/CD setup for R packagesbuild-ci-cd-pipeline — broader CI/CD pipeline designannotate-source-files — annotations must exist before CI can generate diagramscommit-changes — understanding auto-commit patternsnpx claudepluginhub pjt222/agent-almanacGenerates themed Mermaid flowchart diagrams from putior workflow data with 9 themes (4 colorblind-safe), multiple output modes, and interactive features. Use after annotating source files or when regenerating diagrams after workflow changes.
Generates Mermaid flowcharts visualizing workflows, CI/CD pipelines, deployment processes, and state machines from code or docs. Maps steps, decisions, and transitions.
Designs and implements CI/CD pipelines and GitHub Actions workflows to automate builds, tests, deployments, improving consistency, speed, and security.