pimp-my-repo

name

pimp-my-repo

description

Bootstrap a full-featured GitHub repository's standard configuration. Use when: setting up a new repository, adding a missing Dependabot or pre-commit config, or standardizing an existing repo. Generates .github/dependabot.yml from the ecosystems the repo actually uses, a baseline .pre-commit-config.yaml, ensures every workflow SHA-pins its third-party actions, ignores .claude in .gitignore, sets up .github/copilot-instructions.md with a thin CLAUDE.md importing it, and hardens workflow secret scoping and permissions.

Pimp My Repo

Bootstrap the standard configuration a full-featured GitHub repository should have. Work through the steps below, tailoring each to what the repo actually contains. Skip anything already configured correctly; merge rather than overwrite.

1. Dependabot — .github/dependabot.yml derived from the ecosystems in use.
2. Pre-commit — a baseline .pre-commit-config.yaml with the standard hooks, wired into CI via this repo's reusable pre-commit action, placed wherever best fits the repo's existing workflows.
3. SHA-pinning — every workflow references third-party actions by commit SHA.
4. Gitignore — common ignores for the repo's stack, plus Claude Code artifacts.
5. AI assistant instructions — .github/copilot-instructions.md with a thin CLAUDE.md.
6. Secrets & permissions — least-privilege secret scoping and workflow permissions.

1. Dependabot config

Generate (or extend) .github/dependabot.yml based on what the repo actually contains. Detect the ecosystems in use from their marker files (package.json, pom.xml, pyproject.toml/uv.lock, go.mod, Dockerfile, *.tf, etc.) and emit one updates block per ecosystem found — never for tooling the repo doesn't use.

Rules for every block:

• github-actions is always included, even when no other ecosystem is detected.
• Grouping is always enabled — at least one catch-all group so Dependabot opens one grouped PR per ecosystem instead of many.
• Weekly schedule, 7-day cooldown, and directories: (plural) pointing at the parent dirs of the marker files (collapse siblings with a glob).
• Label with dependencies plus an ecosystem-specific label.

# Documentation for all configuration options:
# https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference
version: 2
updates:
  - package-ecosystem: "github-actions"
    directories:
      - "/"
    schedule:
      interval: "weekly"
    labels:
      - "dependencies"
      - "github_actions"
    cooldown:
      default-days: 7
    groups:
      github-actions:
        patterns:
          - "*"

Add further blocks in the same shape for each detected ecosystem. Only split into extra named groups when a family of dependencies must always move together. When the file already exists, preserve existing ignore, groups, and custom directories.

2. Pre-commit config

Add a baseline .pre-commit-config.yaml with the standard hooks (pin revs to the latest release of each repo). Include language-specific hooks (black/isort/flake8, shellcheck, …) only for languages the repo actually uses.

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v6.0.0
    hooks:
      - id: check-yaml
        args: [--allow-multiple-documents]
      - id: check-json
      - id: check-xml
      - id: check-merge-conflict
      - id: fix-byte-order-marker
      - id: mixed-line-ending
        args: ['--fix=lf']
      - id: end-of-file-fixer
      - id: trailing-whitespace

  - repo: https://github.com/sirosen/check-jsonschema
    rev: 0.37.1
    hooks:
      - id: check-dependabot
      - id: check-github-actions
      - id: check-github-workflows

  - repo: https://github.com/igorshubovych/markdownlint-cli
    rev: v0.47.0
    hooks:
      - id: markdownlint

  - repo: https://github.com/rhysd/actionlint
    rev: v1.7.12
    hooks:
      - id: actionlint

  - repo: https://github.com/hyland/github-actions-ensure-sha-pinned-actions
    rev: v1.2.0
    hooks:
      - id: gha-sha-convert
        args: [--allowlist, 'Alfresco/alfresco-build-tools/*']

Wire the config into CI by calling this repo's reusable pre-commit action (documented here) instead of hand-rolling the pre-commit invocation. Use the latest released tag (check git tag in this repo, or the releases page for the current version). Unlike other third-party actions (see SHA-pinning below), a version tag is fine here: alfresco-build-tools release tags are immutable, so pinning further has no security benefit (though it's harmless if you prefer it).

Where the job goes depends on the shape of the target repo's existing workflows — check in this order and stop at the first match:

1. A single main workflow drives most CI activity (build, test, publish, …). Add pre-commit as that workflow's first job, and make every other job depend on it via needs: pre-commit so a hook failure blocks the rest of the run.

2. No single main workflow, but one is clearly dedicated to linting/static checks (e.g. named lint.yml, or a job doing actionlint/yamllint/similar). Add pre-commit as a job there instead of creating a new file.

3. Neither applies (several unrelated workflows, none a natural home). Create a new .github/workflows/pre-checks.yml dedicated to it:

   Replace <default-branch> with the repo's actual default branch (e.g. git remote show origin | sed -n 's/HEAD branch: //p').

   # .github/workflows/pre-checks.yml
   name: pre-checks
   
   on:
     pull_request:
       branches: [<default-branch>]
     push:
       branches: [<default-branch>]
   
   jobs:
     pre-commit:
       runs-on: ubuntu-latest
       permissions:
         contents: read # bump to write only if you enable auto-commit below
       steps:
         - uses: Alfresco/alfresco-build-tools/.github/actions/pre-commit@v18.21.0
           with:
             auto-commit: "false" # set to "true" (and permissions.contents above to write) to auto-commit fixups
   

In cases 1 and 2, add the same steps: shown above as a job named pre-commit in the existing workflow, keeping its own on: triggers untouched.

Besides wiring pre-commit into CI, check whether pre-commit is available locally and use it to validate the new hooks before they ever hit CI:

command -v pre-commit

• If it's available, install the hooks, bump the baseline revs to each hook's actual latest release, and run them across the whole repo, then fix anything that fails before moving on:

  pre-commit install
  pre-commit autoupdate
  pre-commit run --all-files
  

  The revs in the baseline config above are a snapshot from when this skill was written — autoupdate is what keeps them current instead of drifting stale from day one.

• If it's missing, tell the user explicitly: running pre-commit locally means you catch (and fix) issues before pushing, instead of waiting on CI to fail. Ask them to install it with one of:

  pip install pre-commit
  # or
  brew install pre-commit
  

  Then re-run the check above and proceed with pre-commit install, pre-commit autoupdate, and pre-commit run --all-files once it's installed. If they decline, continue with the rest of the setup and note that the config is untested locally and the pinned revs may be stale compared to upstream releases; enabling auto-commit on the CI job above still catches and fixes issues without a local install, though the bot's auto-commit push usually does not retrigger CI on its own — the user will need to push an empty commit to kick off another run once the auto-fix commit is in:

  git commit --allow-empty -m "Trigger CI" && git push
  

3. SHA-pin third-party actions

Every workflow and composite action must reference third-party actions by full 40-char commit SHA, with the version as a trailing comment — mutable tags (@v4, @main) are forbidden for security.

- uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0

The gha-sha-convert hook above converts existing tag refs to SHA pins automatically. After wiring up pre-commit, run it across the repo and commit the result:

pre-commit run gha-sha-convert --all-files

Keep your first-party action refs (e.g. <OWNER>/<REPO>/*) on the allowlist only if you intentionally permit version tags for them; otherwise let gha-sha-convert pin them too.

4. Gitignore

Ensure .gitignore covers the common entries for what the repo actually contains — build outputs, dependency directories, caches, editor/OS cruft, and local tooling artifacts for the languages and tools detected in step 1. Derive the set from the repo structure rather than dropping in a fixed list, and always include Claude Code's local artifacts:

# Claude Code local artifacts
.claude

Add missing entries and keep the existing ordering and comment style consistent; don't duplicate or reorder what's already there.

5. AI assistant instructions

Keep repo guidance in a single shared source of truth. The actual instructions live in .github/copilot-instructions.md; CLAUDE.md is a thin file that imports them via Claude's native @ syntax rather than duplicating content.

If .github/copilot-instructions.md is missing, generate it with the agent's /init operation, which documents the codebase (purpose, layout, build/test commands, conventions). Then arrange the result into the single-source layout:

• Put the generated instructions in .github/copilot-instructions.md.

• Make CLAUDE.md at the repo root contain only the import:

  @.github/copilot-instructions.md
  

If CLAUDE.md already holds real content, move it into .github/copilot-instructions.md and replace CLAUDE.md with the single import line.

6. Secrets and permissions in workflows

Harden how workflows handle secrets and permissions.

Never put secrets in a top-level (workflow) env block. A workflow-level env exposes secrets to every job and every step, including any third-party action that runs.

Scope secrets as tightly as possible:

• Prefer step-level env — declare the secret on the specific step that needs it. Duplicating the same env block across several steps is fine and preferred; the narrower exposure is worth the repetition.
• Job-level env is acceptable only when the job runs no third-party actions — GitHub-maintained actions such as actions/checkout don't count against this. As soon as a job uses a third-party action, move secrets back down to the steps that need them.

Prefer a GitHub App over a personal access token (PAT) for authenticated operations: App tokens are short-lived, scoped to the installation, and not tied to an individual. Mint a token at runtime (e.g. actions/create-github-app-token) instead of storing a long-lived PAT.

Always declare a workflow-level permissions block with the minimum needed to check out the repo, then widen per-job only where required:

permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@<sha> # vX.Y.Z

  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write   # widened only for the job that needs it
    steps:
      - uses: actions/checkout@<sha> # vX.Y.Z
      - name: Publish
        env:
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}   # step-level: scoped to where it's used
        run: npm publish