From 710e32207f31ce7216f69e0eb31562327a528545 Mon Sep 17 00:00:00 2001 From: Girges Scandar <25529286+scandar@users.noreply.github.com> Date: Tue, 12 Nov 2024 01:15:34 +0100 Subject: [PATCH] Update docs (#5) * Update docs * fix formatting --- .github/workflows/ci.yml | 4 +- README.md | 178 ++++++++++++++++++++++++++++++++++++++- action.yml | 4 +- 3 files changed, 180 insertions(+), 6 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 02ba4e5..ff83515 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -9,7 +9,9 @@ on: - main permissions: + id-token: write contents: read + pull-requests: write # we need this to write comments in PRs jobs: test-typescript: @@ -64,7 +66,7 @@ jobs: uses: ./ with: github_token: ${{ secrets.GITHUB_TOKEN }} - pr-number: ${{ github.event.number }} + pr_number: ${{ github.event.number }} - name: Print Output id: output diff --git a/README.md b/README.md index 638db82..edd28a4 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,176 @@ -# OwnYourCode - WIP +# 📂 OwnYourCode -A GitHub Action to scan your repository for orphan files. It can be used to scan -files modified in a PR or globally checking all files in a branch. +> A GitHub Action to scan your repository for orphan files. It can be used to +> scan files modified in a PR or globally checking all files in a branch. + +## Table of Contents + +- [What is OwnYourCode?](#what-is-ownyourcode) +- [How does it work?](#how-does-it-work) +- [Features](#features) + - [Example comment](#example-comment) +- [API](#api) + - [Inputs](#inputs) + - [Outputs](#outputs) +- [Usage](#usage) + - [Using on a branch](#using-on-a-branch) + - [Printing the output](#printing-the-output) +- [CODEOWNERS file](#codeowners-file) + +## What is OwnYourCode? + +OwnYourCode is a GitHub Action that scans your repository for orphan files, +i.e., files that do not have a CODEOWNER assigned to them. + +## How does it work? + +OwnYourCode uses the CODEOWNERS file in your repository to check if the files +modified in a PR have an owner assigned to them. If a file does not have an +owner, a comment is added to the PR with the list of orphan files. + +## Features + +- Scan files modified in a PR and post a comment with orphan files +- Update the comment in each PR synchronization +- Scan all files in a branch +- Fail the CI if orphan files are found + +### Example comment + +image + +## API + +### Inputs + +- `github_token`: String - Github Token (required) +- `fail-on-missing-codeowners`: Boolean - Fail CI if there are files without + owners (default: true) +- `codeowners_path`: String - Path to the codeowners file (default: CODEOWNERS) +- `pr_number`: Number - Scan only the files modified in the PR (optional if + `branch` is set) +- `branch`: String - Scan all files in the specified branch (optional if + `pr_number` is set) + +### Outputs + +- `total_orphan_files`: Number - Total number of orphaned files +- `total_scanned_files`: Number - Total files scanned +- `failed`: Boolean - If the action failed + +## Usage + +Create a new workflow file in your repository + +```sh +touch .github/workflows/own-your-code.yml +``` + +Add the following content to the file + +```yaml +name: Check CODEOWNERS + +on: + # To check the files modified in a PR + pull_request: + types: [opened, synchronize] + +permissions: + id-token: write + contents: read + pull-requests: write # needed to write comments in PRs + +jobs: + check-codeowners: + name: Check CODEOWNERS + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Check CODEOWNERS + uses: getyourguide/ownyourcode@v1 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + pr_number: ${{ github.event.number }} +``` + +### Using on a branch + +```yaml +name: Check CODEOWNERS + +on: + push: + branches: + - main +permissions: + id-token: write + contents: read + pull-requests: write # we need this to write comments in PRs +jobs: + check-codeowners: + name: Check CODEOWNERS + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Test Local Action + uses: getyourguide/ownyourcode@v1 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + branch: ${{ github.ref_name }} +``` + +### Printing the output + +```yaml +--- +jobs: + check-codeowners: + name: Check CODEOWNERS + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Check CODEOWNERS + id: ownyourcode + uses: getyourguide/ownyourcode@v1 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + pr_number: ${{ github.event.number }} + + - name: Print Output + id: output + run: | + echo "${{ steps.ownyourcode.outputs.total_orphan_files }}" + echo "${{ steps.ownyourcode.outputs.total_scanned_files }}" + echo "${{ steps.ownyourcode.outputs.failed }}" +``` + +## CODEOWNERS file + +The CODEOWNERS file should be in the root of your repository and should have the +following format: + +```sh +path/to/file @optional-owner @another-optional-owner +``` + +Root wildcard owners are ignored: + +```sh +* @owner # this line will be ignored +path/to/*/file @owner # this line will be considered +``` + +Files with no owner will **NOT** be considered orphan files. + +```sh +path/to/file/without/owner # this is not an orphan file, it has no owner +``` diff --git a/action.yml b/action.yml index e63d02b..ebf53ec 100644 --- a/action.yml +++ b/action.yml @@ -15,7 +15,7 @@ inputs: github_token: description: "Github Token" required: true - pr-number: + pr_number: description: "Scan only the files modified in the PR" required: false branch: @@ -62,7 +62,7 @@ runs: env: INPUT_GITHUB_TOKEN: ${{ inputs.github_token }} INPUT_CODEOWNERS_PATH: ${{ inputs.codeowners_path }} - INPUT_PR_NUMBER: ${{ inputs.pr-number }} + INPUT_PR_NUMBER: ${{ inputs.pr_number }} INPUT_FAIL_ON_MISSING_CODEOWNERS: ${{ inputs.fail-on-missing-codeowners }} INPUT_BRANCH: ${{ inputs.branch }}