@kitschpatrol/repo-config

Repository configuration and GitHub workflows for @kitschpatrol/shared-config.

Overview

It's a pnpm-flavored shared config with some essential files for a fresh repo, plus automated linting for things like copyright notice dates, all accessible via a bundled command like tool named ksc-repo.

This includes the following:

• .npmrc with publish branch guards and support for an NPM authentication environment variable for local publishing to NPM
• pnpm-workspace.yaml with hoisting patterns for ksc tool access and trusted dependency installation scripts.
• .gitignore with typical patterns
• .vscode extension recommendations (additional settings and recommendations come from other @kitschpatrol/shared-config packages)
• .github folder with workflows:
  • github-release.yml Automates turning turning vX.X.X tags on main into GitHub releases with changelogs
  • set-github-metadata.yml Populates GitHub repo metadata from package.json

In order to work around some hoisting issues related to plugin resolution in the other @kitschpatrol/shared-config packages, it's critical that it is applied before any other @kitschpatrol/shared-config packages are installed.

[!IMPORTANT]

You can use this package on its own, but it's recommended to use @kitschpatrol/shared-config instead for a single-dependency and single-package approach to linting and fixing your project.

This package is included as a dependency in @kitschpatrol/shared-config, which also automatically invokes the command line functionality in this package via its ksc command

Setup

Run-once approach

If you just need to set up your basic repository configuration files in anticipation of installing another @kitschpatrol shared configuration dependency, you can run the script via dlx to copy them to your project's root:

pnpm --package=@kitschpatrol/repo-config dlx ksc-repo init

Installation approach

Optionally, you can install the package if you think you'll ever want to regenerate the repo config files.

1. Add the package:

   pnpm add -D @kitschpatrol/repo-config

2. If / when you need to regenerate the repo config files, you can run the bundled script:

   pnpm exec ksc-repo init

GitHub Configuration

There are two options for authenticating the release workflow action:

GitHub Token

1. Ensure that read / write permissions are set for actions on the repository under Settings → Actions → General → Workflow permissions.

Personal Access token

If you want releases to come from your account instead of github_actions, then:

1. Create a fine-grained personal access token in your GitHub account with the following permissions:

   | Permission | Access | | -------------- | -------------- | | Administration | Read and write | | Contents | Read and write | | Metadata | Read-only |

2. Add the token as a secret to your new GitHub repository.

   You can do this through the GitHub website under the Settings → Secrets and variables → Actions page under the key PERSONAL_ACCESS_TOKEN.

   Alternately, you can do this locally with the GitHub CLI and a credential manager like 1Password CLI:

   gh secret set PERSONAL_ACCESS_TOKEN --app actions --body $(op read 'op://Personal/GitHub Mika/PERSONAL_ACCESS_TOKEN')

GitHub Actions

Note: Action dependencies have been forked.

| Original | Fork | Modifications | | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------- | | bullrich/generate-release-changelog | kitschpatrol/github-action-release-changelog | ❌ | | softprops/action-gh-release | kitschpatrol/github-action-release | ❌ | | kbrashears5/github-action-repo-sync | kitschpatrol/github-action-repo-sync | ✅ |

Usage

CLI

Command: ksc-repo

Kitschpatrol's repository-related shared configuration tools.

This section lists top-level commands for ksc-repo.

Usage:

ksc-repo <command>

| Command | Description | | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | init | Initialize by copying starter config files to your project root. | | lint | Check the repo for common issues. Package-scoped. In a monorepo, it will also run in all packages below the current working directory. | | fix | Fix common issues like outdated copyright years in license files. Package-scoped. In a monorepo, it will also run in all packages below the current working directory. |

| Option | Description | Type | | ------------------- | ------------------- | --------- | | --help-h | Show help | boolean | | --version-v | Show version number | boolean |

See the sections below for more information on each subcommand.

Subcommand: ksc-repo init

Initialize by copying starter config files to your project root.

Usage:

ksc-repo init

| Option | Description | Type | | ------------------- | ------------------- | --------- | | --help-h | Show help | boolean | | --version-v | Show version number | boolean |

Subcommand: ksc-repo lint

Check the repo for common issues. Package-scoped. In a monorepo, it will also run in all packages below the current working directory.

Usage:

ksc-repo lint

| Option | Description | Type | | ------------------- | ------------------- | --------- | | --help-h | Show help | boolean | | --version-v | Show version number | boolean |

Subcommand: ksc-repo fix

Fix common issues like outdated copyright years in license files. Package-scoped. In a monorepo, it will also run in all packages below the current working directory.

Usage:

ksc-repo fix

| Option | Description | Type | | ------------------- | ------------------- | --------- | | --help-h | Show help | boolean | | --version-v | Show version number | boolean |

License

MIT © Eric Mika