awslabs / awslabs/agent-plugins

pre-commit: check-vcs-permalinks fails on non-permalink GitHub URLs in docs

Open Beginner friendly
#217 1 comment 0 reactions 0 assignees View on GitHub
bug documentation needs-triage stale
Dominant language
Python
Stars
893
Forks
155
Avg merge
5d 20h
Merged PRs (30d)
7

Description

Part of #213.

## Problem

`check-vcs-permalinks` fails because docs link to mutable `.../blob/main/...` GitHub URLs instead of commit-pinned permalinks. These links rot when the target repo's `main` moves.

## Affected lines

```
plugins/databases-on-aws/skills/dsql/mcp/tools/input-validation.md:56
plugins/databases-on-aws/skills/dsql/mcp/tools/input-validation.md:61
plugins/databases-on-aws/skills/dsql/mcp/tools/database-tools.md:125
```

All point at `https://github.com/awslabs/mcp/blob/main/src/aurora-dsql-mcp-server/...`.

## Reproduce

```bash
mise exec -- pre-commit run check-vcs-permalinks --all-files
```

## Proposed fix

Replace `blob/main/` with a commit SHA permalink (on GitHub, press `y` on the file view to get one), or if a moving reference is intentional, exclude these specific docs from the hook.

Filed with assistance from Claude Code while implementing #211.

Contributor guide

Open the contributing guide

Research direction

Inspect the three listed lines in plugins/databases-on-aws/skills/dsql/mcp/tools/input-validation.md and database-tools.md, then run `mise exec -- pre-commit run check-vcs-permalinks --all-files`. Replace the mutable GitHub links with commit-pinned permalinks, or apply the documented exclusion option if the moving references are intentional; the hook should pass afterward.

Written by the indexing model from the issue text.

Assessment

Tech stack
git, github, markdown
Domain
documentation, tooling
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
82/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.