Agent-almanac setup-putior-ci

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/ja/skills/setup-putior-ci" ~/.claude/skills/pjt222-agent-almanac-setup-putior-ci-6aa18d && rm -rf "$T"

manifest: i18n/ja/skills/setup-putior-ci/SKILL.md

source content

Putior CIの構築

Configure GitHub Actions to automatically regenerate workflow diagrams when source code changes, keeping documentation in sync with code.

使用タイミング

Workflow diagrams should always reflect the current state of the code
The project has CI/CD and wants automated documentation updates
Multiple contributors may change workflow-affecting code
Replacing manual diagram regeneration with automated pipeline

入力

必須: GitHub repository with putior annotations in source files
必須: Target file for diagram output (e.g.,
```
README.md
```
,
```
docs/workflow.md
```
)
任意: putior theme (default:
```
"github"
```
)
任意: Source directories to scan (default:
```
"./R/"
```
or
```
"./src/"
```
)
任意: Branch to trigger on (default:
```
main
```
)

手順

ステップ1: Create GitHub Actions Workflow

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

期待結果: File created at

.github/workflows/update-workflow-diagram.yml

失敗時: Ensure the

.github/workflows/

directory exists. Adjust the

paths

filter to match where annotated source files live in the repository.

ステップ2: Write Generation Script

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")

期待結果: Script at

scripts/generate-workflow-diagram.R

that reads annotations, generates Mermaid code, and replaces content between sentinel markers.

失敗時: If

put_merge()

returns empty, check that source paths match the repository layout. Adjust

"./R/"

to the actual source directory.

ステップ3: Configure Auto-Commit

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 access
```
if: github.actor != 'github-actions[bot]'
```
skips the job when the push came from the bot itself
```
git 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)
Bot identity used for commits:
```
github-actions[bot]
```

期待結果: The workflow only commits when diagrams actually change. No empty commits, no infinite loops.

失敗時: If push fails with permission denied, check repository settings: Settings > Actions > General > Workflow permissions must be set to "Read and write permissions".

ステップ4: Add Sentinel Markers to README

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"]


**期待結果:** Sentinel markers in README.md (or other target file). The content between them will be replaced on each CI run.

**失敗時:** Ensure markers are on their own lines with no leading/trailing whitespace. The script matches exact line content.

### ステップ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"

期待結果: GitHub Actions run completes successfully. The diagram between sentinel markers in README.md is updated with current workflow data.

失敗時: Check the Actions log for errors. Common issues:

```
putior
```
package not available: add to
```
DESCRIPTION
```
Suggests or install explicitly in the workflow
Source path wrong: the R script's
```
put_merge()
```
path must be relative to the repo root
No sentinel markers: the script warns but doesn't crash; add markers to README.md

バリデーション

.github/workflows/update-workflow-diagram.yml

exists and is valid YAML

```
scripts/generate-workflow-diagram.R
```
runs without errors locally

README.md contains

<!-- PUTIOR-WORKFLOW-START -->

and

<!-- PUTIOR-WORKFLOW-END -->

sentinels

GitHub Actions workflow triggers on push to the correct branch and paths
Diagram content between sentinels is updated after a workflow run
Job-level
```
if:
```
guard prevents infinite commit loops from bot pushes
No changes = no commit (idempotent)

よくある落とし穴

Infinite CI loops: Pushes with the default
```
GITHUB_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.
Permission denied on push: GitHub Actions needs write permission. Set
```
permissions: contents: write
```
in the workflow file, or configure it in repository settings.
Sentinel marker mismatch: If markers have trailing spaces, leading tabs, or are on the same line as other content, the script won't find them. Keep markers on their own clean lines.
Source path mismatch: The R script runs from the repo root. Paths like
```
"./R/"
```
or
```
"./src/"
```
must match the actual directory structure.
Package installation in CI: If the project uses renv, the CI workflow needs
```
renv::restore()
```
before putior is available. Alternatively, install putior explicitly in the workflow.
Large repos slowing CI: For repos with many source files, limit the
```
paths
```
trigger filter to directories that contain PUT annotations, not the entire repo.