docs: how to create a GitHub Action

docs/FAQs.md

@@ -13,6 +13,108 @@ After you set up a repository, you can substitute in any tools you'd like.
 
 If you think the tool would be broadly useful to most consumers of this template, feel free to [file a feature request](https://github.com/JoshuaKGoldberg/create-typescript-app/issues/new?assignees=&labels=type%3A+feature&projects=&template=03-feature.yml&title=%F0%9F%9A%80+Feature%3A+%3Cshort+description+of+the+feature%3E) to add it in.
 
+## Can I create a GitHub action with CTA?
+
+Yes! If you want to read in detail about GitHub Actions [try this](https://docs.github.com/en/actions/creating-actions). Here we'll outline the steps required to migrate a CTA app to a GitHub Action:
+1. The GitHub Actions does not cater for tabs well, so you will likely want to set your `README.md` to use spaces, not tabs. 
+2. GitHub Actions are _not_ like packages published to npm. The output is expected to live in the `dist` folder of a GitHub repo. As a consequence we should:
+   - delete `.github/workflows/release.yml` and `.github/workflows/post-release.yml`.
+   - update `.github/workflows/build.yml`
+   ```diff
+   -      - run: node ./lib/index.js
+   ```
+   - GitHub Actions have a different build mechanism. So you'll be removing `tsup` in favour of [`ncc`](https://github.com/vercel/ncc) which compiles output into a single JS file. So delete `tsup.config.ts` then:
+   ```bash
+   pnpm remove tsup
+   pnpm add @vercel/ncc -D
+   pnpm add @actions/core -P
+   ```
+   - We also added the [`@actions/core`](https://github.com/actions/toolkit/tree/master/packages/core) package, used for building GitHub Actions. Now we need to update the `build` script in our `package.json`:
+   ```diff
+   -"build": "tsup",
+   +"build": "ncc build src/index.ts -o dist --license licenses.txt",
+   ```
+   - Our build now emits to the `dist` directory; so we'll want to avoid linting that directory by adding the following to `.eslintignore` and our `.prettierignore`:
+   ```diff
+   +dist
+   ```
+   - Rather than having to remember to compile each time, we'll update our precommit hook in `.husky/precommit` to build for us on each commit:
+   ```diff
+   +pnpm run build
+   +git add dist
+   npx lint-staged
+   ``` 
+   - on the off chance someone isn't running husky, we'll add `.github/workflows/check-dist.yml` ([based on this](https://github.com/actions/typescript-action/blob/main/.github/workflows/check-dist.yml)) to ensure `dist` is up to date:
+   ```yml
+   # In TypeScript actions, `dist/` is a special directory. When you reference
+   # an action with the `uses:` property, `dist/index.js` is the code that will be
+   # run. For this project, the `dist/index.js` file is transpiled from other
+   # source files. This workflow ensures the `dist/index.js` file contains the
+   # expected transpiled code.
+   #
+   # If this workflow is run from a feature branch, it will act as an additional CI
+   # check and fail if the checked-in `dist/` directory does not match what is
+   # expected from the build.
+   name: Check transpiled index.js in dist is up to date
+
+   on:
+     push:
+       branches:
+         - main
+     pull_request:
+
+   permissions:
+     contents: read
+
+   jobs:
+     check-dist:
+       name: check dist
+       runs-on: ubuntu-latest
+
+       steps:
+         - uses: actions/checkout@v4
+         - uses: ./.github/actions/prepare
+
+         - name: Build dist directory
+           id: build
+           run: pnpm run build
+
+         # This will fail the workflow if the PR wasn't created by Dependabot.
+         - name: Compare directories
+           id: diff
+           run: |
+             if [ "$(git diff --ignore-space-at-eol --text dist/index.js | wc -l)" -gt "0" ]; then
+               echo "Detected uncommitted changes after build."
+               echo "You may need to run 'pnpm run build' locally and commit the changes."
+               echo ""
+               echo "See diff below:"
+               echo ""
+               git diff --ignore-space-at-eol --text dist/index.js
+               echo ""
+               # say this again in case the diff is long
+               echo "You may need to run 'pnpm run build' locally and commit the changes."
+               echo ""
+               exit 1
+             fi
+
+         # If `dist/` was different than expected, and this was not a Dependabot
+         # PR, upload the expected version as a workflow artifact.
+         - if: ${{ failure() && steps.diff.outcome == 'failure' }}
+           name: Upload artifact
+           id: upload
+           uses: actions/upload-artifact@v4
+           with:
+             name: dist
+             path: dist/
+   ```
+3. We're going to need an [`action.yml`](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions) file - [here's an example](https://docs.github.com/en/actions/creating-actions/creating-a-javascript-action#creating-an-action-metadata-file).
+4. Our GitHub Action needs Node.js 20 so we'll update `.github/actions/prepare/action.yml`:
+```diff
+-node-version: "18"
++node-version: "20"
+```
+5. Change the code in your `src` directory to be a GitHub Action. It's worth reading the official documentation [for an example](https://docs.github.com/en/actions/creating-actions/creating-a-javascript-action#writing-the-action-code).
+
 ## How can I add dual CommonJS / ECMAScript Modules emit?
 
 First, I'd suggest reading [TypeScript Handbook > Modules - Introduction](https://www.typescriptlang.org/docs/handbook/modules/introduction.html) to understand how CommonJS (CJS) and ECMAScript (ESM) came to be.