|
1 |
| -# Create a GitHub Action Using TypeScript |
| 1 | +# CODEOWNERS coverage check |
2 | 2 |
|
3 | 3 | [](https://github.com/super-linter/super-linter)
|
4 | 4 | 
|
5 | 5 | [](https://github.com/actions/typescript-action/actions/workflows/check-dist.yml)
|
6 | 6 | [](https://github.com/actions/typescript-action/actions/workflows/codeql-analysis.yml)
|
7 | 7 | [](./badges/coverage.svg)
|
8 | 8 |
|
9 |
| -Use this template to bootstrap the creation of a TypeScript action. :rocket: |
| 9 | +This action can: |
| 10 | +* Check if all files are covered by a CODEOWNERS Rule |
| 11 | +* Check if all modified files are covered by a CODEOWNERS Rule. (PR) |
| 12 | +* Check if all CODEOWNER rules are used. |
10 | 13 |
|
11 |
| -This template includes compilation support, tests, a validation workflow, |
12 |
| -publishing, and versioning guidance. |
| 14 | +## Examples |
13 | 15 |
|
14 |
| -If you are new, there's also a simpler introduction in the |
15 |
| -[Hello world JavaScript action repository](https://github.com/actions/hello-world-javascript-action). |
16 |
| - |
17 |
| -## Create Your Own Action |
18 |
| - |
19 |
| -To create your own action, you can use this repository as a template! Just |
20 |
| -follow the below instructions: |
21 |
| - |
22 |
| -1. Click the **Use this template** button at the top of the repository |
23 |
| -1. Select **Create a new repository** |
24 |
| -1. Select an owner and name for your new repository |
25 |
| -1. Click **Create repository** |
26 |
| -1. Clone your new repository |
27 |
| - |
28 |
| -> [!IMPORTANT] |
29 |
| -> |
30 |
| -> Make sure to remove or update the [`CODEOWNERS`](./CODEOWNERS) file! For |
31 |
| -> details on how to use this file, see |
32 |
| -> [About code owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners). |
33 |
| -
|
34 |
| -## Initial Setup |
35 |
| - |
36 |
| -After you've cloned the repository to your local machine or codespace, you'll |
37 |
| -need to perform some initial setup steps before you can develop your action. |
38 |
| - |
39 |
| -> [!NOTE] |
40 |
| -> |
41 |
| -> You'll need to have a reasonably modern version of |
42 |
| -> [Node.js](https://nodejs.org) handy (20.x or later should work!). If you are |
43 |
| -> using a version manager like [`nodenv`](https://github.com/nodenv/nodenv) or |
44 |
| -> [`fnm`](https://github.com/Schniz/fnm), this template has a `.node-version` |
45 |
| -> file at the root of the repository that can be used to automatically switch to |
46 |
| -> the correct version when you `cd` into the repository. Additionally, this |
47 |
| -> `.node-version` file is used by GitHub Actions in any `actions/setup-node` |
48 |
| -> actions. |
49 |
| -
|
50 |
| -1. :hammer_and_wrench: Install the dependencies |
51 |
| - |
52 |
| - ```bash |
53 |
| - npm install |
54 |
| - ``` |
55 |
| - |
56 |
| -1. :building_construction: Package the TypeScript for distribution |
57 |
| - |
58 |
| - ```bash |
59 |
| - npm run bundle |
60 |
| - ``` |
61 |
| - |
62 |
| -1. :white_check_mark: Run the tests |
63 |
| - |
64 |
| - ```bash |
65 |
| - $ npm test |
66 |
| - |
67 |
| - PASS ./index.test.js |
68 |
| - ✓ throws invalid number (3ms) |
69 |
| - ✓ wait 500 ms (504ms) |
70 |
| - ✓ test runs (95ms) |
71 |
| - |
72 |
| - ... |
73 |
| - ``` |
74 |
| - |
75 |
| -## Update the Action Metadata |
76 |
| - |
77 |
| -The [`action.yml`](action.yml) file defines metadata about your action, such as |
78 |
| -input(s) and output(s). For details about this file, see |
79 |
| -[Metadata syntax for GitHub Actions](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions). |
80 |
| - |
81 |
| -When you copy this repository, update `action.yml` with the name, description, |
82 |
| -inputs, and outputs for your action. |
83 |
| - |
84 |
| -## Update the Action Code |
85 |
| - |
86 |
| -The [`src/`](./src/) directory is the heart of your action! This contains the |
87 |
| -source code that will be run when your action is invoked. You can replace the |
88 |
| -contents of this directory with your own code. |
89 |
| - |
90 |
| -There are a few things to keep in mind when writing your action code: |
91 |
| - |
92 |
| -- Most GitHub Actions toolkit and CI/CD operations are processed asynchronously. |
93 |
| - In `main.ts`, you will see that the action is run in an `async` function. |
94 |
| - |
95 |
| - ```javascript |
96 |
| - import * as core from '@actions/core'; |
97 |
| - //... |
98 |
| - |
99 |
| - async function run() { |
100 |
| - try { |
101 |
| - //... |
102 |
| - } catch (error) { |
103 |
| - core.setFailed(error.message); |
104 |
| - } |
105 |
| - } |
106 |
| - ``` |
107 |
| - |
108 |
| - For more information about the GitHub Actions toolkit, see the |
109 |
| - [documentation](https://github.com/actions/toolkit/blob/master/README.md). |
110 |
| - |
111 |
| -So, what are you waiting for? Go ahead and start customizing your action! |
112 |
| - |
113 |
| -1. Create a new branch |
114 |
| - |
115 |
| - ```bash |
116 |
| - git checkout -b releases/v1 |
117 |
| - ``` |
118 |
| - |
119 |
| -1. Replace the contents of `src/` with your action code |
120 |
| -1. Add tests to `__tests__/` for your source code |
121 |
| -1. Format, test, and build the action |
122 |
| - |
123 |
| - ```bash |
124 |
| - npm run all |
125 |
| - ``` |
126 |
| - |
127 |
| - > This step is important! It will run [`rollup`](https://rollupjs.org/) to |
128 |
| - > build the final JavaScript action code with all dependencies included. If |
129 |
| - > you do not run this step, your action will not work correctly when it is |
130 |
| - > used in a workflow. |
131 |
| -
|
132 |
| -1. (Optional) Test your action locally |
133 |
| - |
134 |
| - The [`@github/local-action`](https://github.com/github/local-action) utility |
135 |
| - can be used to test your action locally. It is a simple command-line tool |
136 |
| - that "stubs" (or simulates) the GitHub Actions Toolkit. This way, you can run |
137 |
| - your TypeScript action locally without having to commit and push your changes |
138 |
| - to a repository. |
139 |
| - |
140 |
| - The `local-action` utility can be run in the following ways: |
141 |
| - |
142 |
| - - Visual Studio Code Debugger |
143 |
| - |
144 |
| - Make sure to review and, if needed, update |
145 |
| - [`.vscode/launch.json`](./.vscode/launch.json) |
146 |
| - |
147 |
| - - Terminal/Command Prompt |
148 |
| - |
149 |
| - ```bash |
150 |
| - # npx @github/local action <action-yaml-path> <entrypoint> <dotenv-file> |
151 |
| - npx @github/local-action . src/main.ts .env |
152 |
| - ``` |
153 |
| - |
154 |
| - You can provide a `.env` file to the `local-action` CLI to set environment |
155 |
| - variables used by the GitHub Actions Toolkit. For example, setting inputs and |
156 |
| - event payload data used by your action. For more information, see the example |
157 |
| - file, [`.env.example`](./.env.example), and the |
158 |
| - [GitHub Actions Documentation](https://docs.github.com/en/actions/learn-github-actions/variables#default-environment-variables). |
159 |
| - |
160 |
| -1. Commit your changes |
161 |
| - |
162 |
| - ```bash |
163 |
| - git add . |
164 |
| - git commit -m "My first action is ready!" |
165 |
| - ``` |
166 |
| - |
167 |
| -1. Push them to your repository |
168 |
| - |
169 |
| - ```bash |
170 |
| - git push -u origin releases/v1 |
171 |
| - ``` |
172 |
| - |
173 |
| -1. Create a pull request and get feedback on your action |
174 |
| -1. Merge the pull request into the `main` branch |
175 |
| - |
176 |
| -Your action is now published! :rocket: |
177 |
| - |
178 |
| -For information about versioning your action, see |
179 |
| -[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md) |
180 |
| -in the GitHub Actions toolkit. |
181 |
| - |
182 |
| -## Validate the Action |
183 |
| - |
184 |
| -You can now validate the action by referencing it in a workflow file. For |
185 |
| -example, [`ci.yml`](./.github/workflows/ci.yml) demonstrates how to reference an |
186 |
| -action in the same repository. |
| 16 | +### Check all files |
187 | 17 |
|
188 | 18 | ```yaml
|
189 | 19 | steps:
|
190 |
| - - name: Checkout |
191 |
| - id: checkout |
192 |
| - uses: actions/checkout@v4 |
193 |
| -
|
194 |
| - - name: Test Local Action |
| 20 | + - uses: actions/checkout@v4 |
| 21 | + - name: CODEOWNERS Check |
195 | 22 | id: test-action
|
196 |
| - uses: ./ |
| 23 | + uses: joelharkes/gh-action-codeowner-coverage@v1 |
197 | 24 | with:
|
198 |
| - milliseconds: 1000 |
199 |
| -
|
200 |
| - - name: Print Output |
201 |
| - id: output |
202 |
| - run: echo "${{ steps.test-action.outputs.time }}" |
| 25 | + includeGitignore: 'false' |
| 26 | + ignoreDefault: 'false' |
| 27 | + allRulesMustHit: 'true' # Action will fail if there is a rule that is not used. |
203 | 28 | ```
|
204 | 29 |
|
205 |
| -For example workflow runs, check out the |
206 |
| -[Actions tab](https://github.com/actions/typescript-action/actions)! :rocket: |
| 30 | +### PR Check modifield files |
207 | 31 |
|
208 |
| -## Usage |
209 |
| - |
210 |
| -After testing, you can create version tag(s) that developers can use to |
211 |
| -reference different stable versions of your action. For more information, see |
212 |
| -[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md) |
213 |
| -in the GitHub Actions toolkit. |
| 32 | +```yaml |
| 33 | +name: CODEOWNERS Check on modified files |
| 34 | + |
| 35 | +on: |
| 36 | + pull_request: |
| 37 | + branches: |
| 38 | + - main |
| 39 | + push: |
| 40 | + branches: |
| 41 | + - main |
| 42 | + |
| 43 | +permissions: |
| 44 | + contents: read |
| 45 | + |
| 46 | +jobs: |
| 47 | + codeowners: |
| 48 | + runs-on: ubuntu-latest |
| 49 | + name: Test changed-files |
| 50 | + steps: |
| 51 | + - uses: actions/checkout@v4 |
| 52 | + - name: Get changed files |
| 53 | + id: changed-files |
| 54 | + uses: tj-actions/changed-files@v45 |
| 55 | + |
| 56 | + - name: CODEOWNERS Check |
| 57 | + id: test-action |
| 58 | + uses: joelharkes/gh-action-codeowner-coverage@v1 |
| 59 | + with: |
| 60 | + files: ${{ steps.changed-files.outputs.all_changed_files }} |
| 61 | + includeGitignore: 'false' |
| 62 | + ignoreDefault: 'false' |
| 63 | +``` |
214 | 64 |
|
215 |
| -To include the action in a workflow in another repository, you can use the |
216 |
| -`uses` syntax with the `@` symbol to reference a specific branch, tag, or commit |
217 |
| -hash. |
218 | 65 |
|
| 66 | +### Outputs example |
219 | 67 | ```yaml
|
220 | 68 | steps:
|
221 |
| - - name: Checkout |
222 |
| - id: checkout |
223 |
| - uses: actions/checkout@v4 |
224 |
| -
|
225 |
| - - name: Test Local Action |
226 |
| - id: test-action |
227 |
| - uses: actions/typescript-action@v1 # Commit with the `v1` tag |
| 69 | + - uses: actions/checkout@v4 |
| 70 | + - name: CODEOWNERS Check |
| 71 | + id: codeowners |
| 72 | + uses: joelharkes/gh-action-codeowner-coverage@v1 |
228 | 73 | with:
|
229 | 74 | milliseconds: 1000
|
230 | 75 |
|
231 | 76 | - name: Print Output
|
232 | 77 | id: output
|
233 |
| - run: echo "${{ steps.test-action.outputs.time }}" |
| 78 | + run: echo "${{ steps.codeowners.outputs.missedFiles }}" |
234 | 79 | ```
|
235 | 80 |
|
236 |
| -## Publishing a New Release |
237 |
| - |
238 |
| -This project includes a helper script, [`script/release`](./script/release) |
239 |
| -designed to streamline the process of tagging and pushing new releases for |
240 |
| -GitHub Actions. |
241 |
| - |
242 |
| -GitHub Actions allows users to select a specific version of the action to use, |
243 |
| -based on release tags. This script simplifies this process by performing the |
244 |
| -following steps: |
245 |
| - |
246 |
| -1. **Retrieving the latest release tag:** The script starts by fetching the most |
247 |
| - recent SemVer release tag of the current branch, by looking at the local data |
248 |
| - available in your repository. |
249 |
| -1. **Prompting for a new release tag:** The user is then prompted to enter a new |
250 |
| - release tag. To assist with this, the script displays the tag retrieved in |
251 |
| - the previous step, and validates the format of the inputted tag (vX.X.X). The |
252 |
| - user is also reminded to update the version field in package.json. |
253 |
| -1. **Tagging the new release:** The script then tags a new release and syncs the |
254 |
| - separate major tag (e.g. v1, v2) with the new release tag (e.g. v1.0.0, |
255 |
| - v2.1.2). When the user is creating a new major release, the script |
256 |
| - auto-detects this and creates a `releases/v#` branch for the previous major |
257 |
| - version. |
258 |
| -1. **Pushing changes to remote:** Finally, the script pushes the necessary |
259 |
| - commits, tags and branches to the remote repository. From here, you will need |
260 |
| - to create a new release in GitHub so users can easily reference the new tags |
261 |
| - in their workflows. |
262 |
| - |
263 |
| -## Dependency License Management |
264 |
| - |
265 |
| -This template includes a GitHub Actions workflow, |
266 |
| -[`licensed.yml`](./.github/workflows/licensed.yml), that uses |
267 |
| -[Licensed](https://github.com/licensee/licensed) to check for dependencies with |
268 |
| -missing or non-compliant licenses. This workflow is initially disabled. To |
269 |
| -enable the workflow, follow the below steps. |
270 |
| - |
271 |
| -1. Open [`licensed.yml`](./.github/workflows/licensed.yml) |
272 |
| -1. Uncomment the following lines: |
273 | 81 |
|
274 |
| - ```yaml |
275 |
| - # pull_request: |
276 |
| - # branches: |
277 |
| - # - main |
278 |
| - # push: |
279 |
| - # branches: |
280 |
| - # - main |
281 |
| - ``` |
| 82 | +### Contributing |
282 | 83 |
|
283 |
| -1. Save and commit the changes |
284 |
| - |
285 |
| -Once complete, this workflow will run any time a pull request is created or |
286 |
| -changes pushed directly to `main`. If the workflow detects any dependencies with |
287 |
| -missing or non-compliant licenses, it will fail the workflow and provide details |
288 |
| -on the issue(s) found. |
289 |
| - |
290 |
| -### Updating Licenses |
291 |
| - |
292 |
| -Whenever you install or update dependencies, you can use the Licensed CLI to |
293 |
| -update the licenses database. To install Licensed, see the project's |
294 |
| -[Readme](https://github.com/licensee/licensed?tab=readme-ov-file#installation). |
295 |
| -
|
296 |
| -To update the cached licenses, run the following command: |
297 |
| -
|
298 |
| -```bash |
299 |
| -licensed cache |
300 |
| -``` |
301 |
| -
|
302 |
| -To check the status of cached licenses, run the following command: |
303 |
| -
|
304 |
| -```bash |
305 |
| -licensed status |
306 |
| -``` |
| 84 | +See: https://github.com/actions/typescript-action on how to run, test and contribute to github actions. |
0 commit comments