.github/workflows/test.yml

@@ -1,32 +1,41 @@
 on:
-  - repository_dispatch
-  - workflow_dispatch
-  - push
-  - pull_request
+  push:
+    branches:
+      - master
+  pull_request:
+  workflow_dispatch:
+  repository_dispatch:
 
 env:
   CUSTOM_OUTPUT_RELATIVE_PATH: lychee/custom_output.md
   CUSTOM_OUTPUT_ABSOLUTE_PATH: /tmp/report.md
   CUSTOM_OUTPUT_DUMP_PATH: /tmp/dump.md
-    
+
 jobs:
   lychee-action:
     runs-on: ubuntu-latest
-    continue-on-error: true
     name: Test the lychee link checker action
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
       - name: test defaults
         uses: ./
-        with:
-          fail: true
 
       - name: test explicit lychee version
         uses: ./
         with:
-          lycheeVersion: 0.9.0
+          lycheeVersion: v0.15.1
+
+      - name: test nightly lychee version
+        uses: ./
+        with:
+          lycheeVersion: nightly
+
+      - name: test latest lychee version
+        uses: ./
+        with:
+          lycheeVersion: latest
 
       - name: test globs
         uses: ./
@@ -38,7 +47,6 @@ jobs:
             './**/*.md'
             './**/*.html'
             './**/*.rst'
-          fail: true
 
       - name: test --base argument
         uses: ./
@@ -50,14 +58,13 @@ jobs:
             './**/*.md'
             './**/*.html'
             './**/*.rst'
-          fail: true
 
       - name: test custom output relative path - creation
         uses: ./
         with:
           output: "${{ env.CUSTOM_OUTPUT_RELATIVE_PATH }}"
           debug: true
-          
+
       - name: test custom output relative path - validation
         run: |
           echo "Checking custom output file at ${{ env.CUSTOM_OUTPUT_RELATIVE_PATH }}"
@@ -68,13 +75,13 @@ jobs:
             echo "Found. Contents:"
             cat "${{ env.CUSTOM_OUTPUT_RELATIVE_PATH }}"
           fi
-         
+
       - name: test custom output absolute path - creation
         uses: ./
         with:
           output: "${{ env.CUSTOM_OUTPUT_ABSOLUTE_PATH }}"
           debug: true
-          
+
       - name: test custom output absolute path - validation
         run: |
           echo "Checking custom output file at ${{ env.CUSTOM_OUTPUT_ABSOLUTE_PATH }}"
@@ -92,7 +99,7 @@ jobs:
           args: --dump './**/*.md' './**/*.html' './**/*.rst'
           output: "${{ env.CUSTOM_OUTPUT_DUMP_PATH }}"
           debug: true
-          
+
       - name: test dump with custom output path - validation
         run: |
           echo "Checking dump output file at ${{ env.CUSTOM_OUTPUT_DUMP_PATH }}"
@@ -104,6 +111,42 @@ jobs:
             cat "${{ env.CUSTOM_OUTPUT_DUMP_PATH }}"
           fi
 
+      - name: test output set in args and action input
+        id: output_set_in_args_and_action_input
+        uses: ./
+        with:
+          args: --output foo -
+          output: bar
+        continue-on-error: true
+
+      - name: test output set in args and action input should fail - validation
+        if: steps.output_set_in_args_and_action_input.outcome != 'failure'
+        run: |
+          echo "Output set in args and action input should have failed."
+          exit 1
+
+      - name: test failIfEmpty - no links in input should fail the pipeline
+        id: fail_if_empty_test
+        uses: ./
+        with:
+          args: --verbose --no-progress fixtures/empty.md
+          debug: true
+        continue-on-error: true
+
+      # Explictly check the exit code of the previous step
+      # as it's expected to fail
+      - name: Check failIfEmpty
+        if: steps.fail_if_empty_test.outcome != 'failure'
+        run: |
+          echo "FailIfEmpty should have failed because no links were found."
+          exit 1
+
+      - name: test disable failIfEmpty - it's okay if no links are found
+        uses: ./
+        with:
+          args: --no-progress fixtures/empty.md
+          failIfEmpty: false
+
       - name: Install jq
         run: sudo apt-get install jq
 
@@ -113,7 +156,6 @@ jobs:
           args: -v fixtures/TEST.md
           format: json
           output: ${{ github.workspace }}/foo_md.json
-          fail: true
 
       - name: Validate JSON - Markdown
         run: |
@@ -128,7 +170,6 @@ jobs:
           args: -v fixtures/TEST.rst
           format: json
           output: ${{ github.workspace }}/foo_rst.json
-          fail: true
 
       - name: Validate JSON - rST
         run: |
@@ -141,15 +182,13 @@ jobs:
         uses: ./
         with:
           args: --exclude-mail .
-          fail: true
 
       - name: test format override
         uses: ./
         with:
           args: --format markdown -v fixtures/TEST.md
           format: doesnotexist # gets ignored if format set in args
           output: ${{ github.workspace }}/foo.txt
-          fail: true
 
       - name: test debug
         uses: ./
@@ -160,3 +199,21 @@ jobs:
         uses: ./
         with:
           token: ${{ secrets.CUSTOM_TOKEN }}
+
+      - name: Test exit code set in steps-output
+        id: lychee_exit_code_test
+        uses: ./
+        with:
+          args: -- inputdoesnotexist
+        continue-on-error: true
+
+      - name: Check exit code in steps.outputs
+        run: |
+          echo "Lychee exit code: ${{ steps.lychee_exit_code_test.outputs.exit_code }}"
+          if [[ "${{ steps.lychee_exit_code_test.outputs.exit_code }}" == "1" ]]; then
+            echo "Lychee correctly failed with exit code 1"
+          else
+            echo "Unexpected exit code: ${{ steps.lychee_exit_code_test.outputs.exit_code }}"
+            echo "Expected exit code 1"
+            exit 1
+          fi

README.md

@@ -32,57 +32,17 @@ jobs:
 
       - name: Link Checker
         id: lychee
-        uses: lycheeverse/lychee-action@v1.9.0
+        uses: lycheeverse/lychee-action@v1
 
       - name: Create Issue From File
         if: env.lychee_exit_code != 0
-        uses: peter-evans/create-issue-from-file@v4
+        uses: peter-evans/create-issue-from-file@v5
         with:
           title: Link Checker Report
           content-filepath: ./lychee/out.md
           labels: report, automated issue
 ```
 
-If you always want to use the latest features but avoid breaking changes, you can replace the version with
-`lycheeverse/lychee-action@v1`.
-
-### Alternative approach:
-
-This will check all repository links during any git push event and for all pull
-requests. If there's an error, it will fail the action. This has the benefit of
-ensuring that during a Pull Request, no link is added that is broken and any
-existing link will be caught if they become broken. Save this under
-`.github/workflows/links-fail-fast.yml`:
-
-```yaml
-name: Links (Fail Fast)
-
-on:
-  push:
-  pull_request:
-
-jobs:
-  linkChecker:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Link Checker
-        uses: lycheeverse/lychee-action@v1.9.0
-        with:
-          fail: true
-```
-
-You may want to add additional arguments to the above. In particular, if you're testing a site directly from the file system (as in the above), you'll likely want to set the argument `--base .` to ensure that **all links** (including root-relative paths) in the files are tested. You don't need to do this if you're testing a hosted site.
-
-```yaml
-      - name: Link Checker
-        uses: lycheeverse/lychee-action@v1.9.0
-        with:
-          fail: true
-          args: --base . --verbose --no-progress './**/*.md' './**/*.html' './**/*.rst'
-```
-
 ## Passing arguments
 
 This action uses [lychee] for link checking.
@@ -92,14 +52,14 @@ On top of that, the action also supports some additional arguments.
 
 | Argument      | Examples                | Description                                                                      |
 | ------------- | ----------------------- | -------------------------------------------------------------------------------- |
-| args          | `--cache`, `--insecure` | See [lychee's documentation][lychee-args] for all arguments and values.          |
-| debug         | `false`                 | Enable debug output in action (set -x). Helpful for troubleshooting.             |
-| fail          | `false`                 | Fail workflow run on error (i.e. when [lychee exit code][lychee-exit] is not 0). |
-| format        | `markdown`, `json`      | Summary output format.                                                           |
-| jobSummary    | `false`                 | Write GitHub job summary (on Markdown output only).                              |
-| lycheeVersion | `0.13.0`                | Overwrite the lychee version to be used.                                         |
-| output        | `lychee/results.md`     | Summary output file path.                                                        |
-| token         | `""`                    | Custom GitHub token to use for API calls.                                               |
+| args          | `--cache`, `--insecure` | See [lychee's documentation][lychee-args] for all arguments and values          |
+| debug         | `false`                 | Enable debug output in action (set -x). Helpful for troubleshooting             |
+| fail          | `false`                 | Fail workflow run on error (i.e. when [lychee exit code][lychee-exit] is not 0) |
+| format        | `markdown`, `json`      | Summary output format                                                           |
+| jobSummary    | `false`                 | Write GitHub job summary (on Markdown output only)                              |
+| lycheeVersion | `v0.15.0`, `nightly`    | Overwrite the lychee version to be used                                         |
+| output        | `lychee/results.md`     | Summary output file path                                                        |
+| token         | `""`                    | Custom GitHub token to use for API calls                                               |
 
 See [action.yml](./action.yml) for a full list of supported arguments and their default values.
 
@@ -109,18 +69,18 @@ Here is how to pass the arguments.
 
 ```yml
 - name: Link Checker
-  uses: lycheeverse/lychee-action@v1.9.0
+  uses: lycheeverse/lychee-action@v1
   with:
-    # Check all markdown and html files in repo (default)
+    # Check all markdown, html and reStructuredText files in repo (default)
     args: --base . --verbose --no-progress './**/*.md' './**/*.html' './**/*.rst'
     # Use json as output format (instead of markdown)
     format: json
     # Use different output file path
     output: /tmp/foo.txt
     # Use a custom GitHub token, which 
     token: ${{ secrets.CUSTOM_TOKEN }}
-    # Fail action on broken links
-    fail: true
+    # Don't fail action on broken links
+    fail: false
 ```
 
 (If you need a token that requires permissions that aren't available in the
@@ -134,14 +94,14 @@ In order to mitigate issues regarding rate limiting or to reduce stress on exter
 
 ```yml
 - name: Restore lychee cache
-  uses: actions/cache@v3
+  uses: actions/cache@v4
   with:
     path: .lycheecache
     key: cache-lychee-${{ github.sha }}
     restore-keys: cache-lychee-
 
 - name: Run lychee
-  uses: lycheeverse/lychee-action@v1.9.0
+  uses: lycheeverse/lychee-action@v1
   with:
     args: "--base . --cache --max-cache-age 1d ."
 ```
@@ -154,19 +114,19 @@ If you need more control over when caches are restored and saved, you can split
 ```yml
 - name: Restore lychee cache
   id: restore-cache
-  uses: actions/cache/restore@v3
+  uses: actions/cache/restore@v4
   with:
     path: .lycheecache
     key: cache-lychee-${{ github.sha }}
     restore-keys: cache-lychee-
 
 - name: Run lychee
-  uses: lycheeverse/lychee-action@v1.9.0
+  uses: lycheeverse/lychee-action@v1
   with:
     args: "--base . --cache --max-cache-age 1d ."
 
 - name: Save lychee cache
-  uses: actions/cache/save@v3
+  uses: actions/cache/save@v4
   if: always()
   with:
     path: .lycheecache
@@ -234,7 +194,7 @@ For example:
 
 ```yml
 - name: Link Checker
-  uses: lycheeverse/lychee-action@22134d37a1fff6c2974df9c92a7c7e1e86a08f9c # for v1.9.0
+  uses: lycheeverse/lychee-action@2b973e86fc7b1f6b36a93795fe2c9c6ae1118621 # for v1.10.0
 ```
 
 ## Credits

action.yml

@@ -1,5 +1,6 @@
 name: "Lychee Broken Link Checker"
 description: "Quickly check links in Markdown, HTML, and text files"
+
 inputs:
   args:
     description: "Lychee arguments (https://github.com/lycheeverse/lychee#commandline-parameters)"
@@ -11,7 +12,11 @@ inputs:
     required: false
   fail:
     description: "Fail entire pipeline on error (i.e. when lychee exit code is not 0)"
-    default: false
+    default: true
+    required: false
+  failIfEmpty:
+    description: "Fail entire pipeline if no links were found"
+    default: true
     required: false
   format:
     description: "Summary output format (e.g. json)"
@@ -23,43 +28,103 @@ inputs:
     required: false
   lycheeVersion:
     description: "Use custom version of lychee link checker"
-    default: 0.15.0
+    default: v0.16.1
     required: false
   output:
     description: "Summary output file path"
     default: "lychee/out.md"
     required: false
   token:
-    description: 'Your GitHub Access Token, defaults to: {{ github.token }}'
+    description: "Your GitHub Access Token, defaults to: {{ github.token }}"
     default: ${{ github.token }}
     required: false
+
 outputs:
   exit_code:
     description: "The exit code returned from Lychee"
-    value: ${{ steps.lychee.outputs.exit_code }}
+    value: ${{ steps.run-lychee.outputs.exit_code }}
+
 runs:
   using: "composite"
   steps:
-    - name: Install lychee
+    - name: Set up environment
       run: |
-        # Cleanup artifacts from previous run in case it crashed
-        rm -rf "lychee-v${{ inputs.LYCHEEVERSION }}-x86_64-unknown-linux-gnu.tar.gz" lychee
-        curl -sLO "https://github.com/lycheeverse/lychee/releases/download/v${{ inputs.LYCHEEVERSION }}/lychee-v${{ inputs.LYCHEEVERSION }}-x86_64-unknown-linux-gnu.tar.gz"
-        tar -xvzf "lychee-v${{ inputs.LYCHEEVERSION }}-x86_64-unknown-linux-gnu.tar.gz"
-        rm "lychee-v${{ inputs.LYCHEEVERSION }}-x86_64-unknown-linux-gnu.tar.gz"
-        install -t "$HOME/.local/bin" -D lychee 
-        rm lychee
         echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+        mkdir -p "$HOME/.local/bin"
+      shell: bash
+
+    - name: Clean up existing lychee files
+      run: |
+        # Remove any existing lychee binaries or archives to prevent conflicts
+        rm -f "$HOME/.local/bin/lychee"
+        rm -rf lychee
+        rm -f "${{ steps.lychee-filename.outputs.filename }}"
       shell: bash
-    - name: Run lychee
-      run: ${{ github.action_path }}/entrypoint.sh
-      id: lychee
+
+    - name: Download and extract lychee
+      id: lychee-setup
+      run: |
+        # Determine filename and download URL based on version
+        if [[ '${{ inputs.lycheeVersion }}' =~ ^v0\.0|^v0\.1[0-5]\. ]]; then
+          FILENAME="lychee-${{ inputs.lycheeVersion }}-x86_64-unknown-linux-gnu.tar.gz"
+          DOWNLOAD_URL="https://github.com/lycheeverse/lychee/releases/download/${{ inputs.lycheeVersion }}/${FILENAME}"
+        else
+          FILENAME="lychee-x86_64-unknown-linux-gnu.tar.gz"
+          if [[ '${{ inputs.lycheeVersion }}' == 'nightly' ]]; then
+            DOWNLOAD_URL="https://github.com/lycheeverse/lychee/releases/download/nightly/${FILENAME}"
+          elif [[ '${{ inputs.lycheeVersion }}' == 'latest' ]]; then
+            DOWNLOAD_URL="https://github.com/lycheeverse/lychee/releases/latest/download/${FILENAME}"
+          else
+            DOWNLOAD_URL="https://github.com/lycheeverse/lychee/releases/download/lychee-${{ inputs.lycheeVersion }}/${FILENAME}"
+          fi
+        fi
+
+        echo "Downloading from: ${DOWNLOAD_URL}"
+        curl -sfLO "${DOWNLOAD_URL}"
+
+        echo "Extracting ${FILENAME}"
+        tar -xvzf "${FILENAME}"
+
+        # Output filename for use in later steps
+        echo "filename=${FILENAME}" >> $GITHUB_OUTPUT
+      shell: bash
+
+    - name: Install lychee
+      run: |
+        install -t "$HOME/.local/bin" -D lychee
+      shell: bash
+
+    - name: Clean up installation files
+      run: |
+        # Remove the downloaded archive and any unnecessary files after installation
+        rm -f "${{ steps.lychee-setup.outputs.filename }}"
+        shopt -s extglob
+        rm -f lychee*!(lychee-bin|lychee-lib)
+      shell: bash
+
+    - name: Run Lychee
+      id: run-lychee
+      run: |
+        # This step runs lychee and captures its exit code.
+        # We use 'set +e' to prevent the script from exiting immediately if lychee fails.
+        # This allows us to capture the exit code and pass it both to GitHub Actions (via GITHUB_OUTPUT)
+        # and to the shell (via the final 'exit $EXIT_CODE').
+        # This ensures that:
+        # 1. The step fails if lychee fails
+        # 2. The exit code is available as an output for subsequent steps
+        # 3. The exit code is properly propagated to the workflow
+        set +e
+        ${{ github.action_path }}/entrypoint.sh
+        EXIT_CODE=$?
+        echo "exit_code=$EXIT_CODE" >> $GITHUB_OUTPUT
+        exit $EXIT_CODE
       env:
         # https://github.com/actions/runner/issues/665
         INPUT_TOKEN: ${{ inputs.TOKEN }}
         INPUT_ARGS: ${{ inputs.ARGS }}
         INPUT_DEBUG: ${{ inputs.DEBUG }}
         INPUT_FAIL: ${{ inputs.FAIL }}
+        INPUT_FAILIFEMPTY: ${{ inputs.FAILIFEMPTY }}
         INPUT_FORMAT: ${{ inputs.FORMAT }}
         INPUT_JOBSUMMARY: ${{ inputs.JOBSUMMARY }}
         INPUT_OUTPUT: ${{ inputs.OUTPUT }}

entrypoint.sh

@@ -21,10 +21,30 @@ FORMAT=""
 # If `format` occurs in args, ignore the value from `INPUT_FORMAT`
 [[ "$ARGS" =~ "--format " ]] || FORMAT="--format ${INPUT_FORMAT}"
 
+# If `output` occurs in args and `INPUT_OUTPUT` is set, exit with an error 
+if [[ "$ARGS" =~ "--output " ]] && [ -n "${INPUT_OUTPUT:-}" ]; then
+    echo "Error: 'output' is set in args as well as in the action configuration. Please remove one of them."
+    exit 1
+fi
+
 # Execute lychee
 eval lychee ${FORMAT} --output ${LYCHEE_TMP} ${ARGS} 
 exit_code=$?
 
+# Overwrite the exit code in case no links were found
+# and `fail-if-empty` is set to `true` (and it is by default)
+if [ "${INPUT_FAILIFEMPTY}" = "true" ]; then
+    # Explicitly set INPUT_FAIL to true to ensure the script fails
+    # if no links are found
+    INPUT_FAIL=true
+    # This is a somewhat crude way to check the Markdown output of lychee
+    if grep -E 'Total\s+\|\s+0' "${LYCHEE_TMP}"; then
+        echo "No links were found. This usually indicates a configuration error." >> "${LYCHEE_TMP}"
+        echo "If this was expected, set 'fail-if-empty: false' in the args." >> "${LYCHEE_TMP}"
+        exit_code=1
+    fi
+fi
+
 if [ ! -f "${LYCHEE_TMP}" ]; then
     echo "No output. Check pipeline run to see if lychee panicked." > "${LYCHEE_TMP}"
 else
@@ -48,10 +68,11 @@ if [ "${INPUT_FORMAT}" == "markdown" ]; then
 fi
 
 # Pass lychee exit code to next step
-echo "lychee_exit_code=$exit_code" >> $GITHUB_ENV
+echo "exit_code=$exit_code" >> $GITHUB_OUTPUT
 
-# If `fail` is set to `true`, propagate the real exit code to the workflow
-# runner. This will cause the pipeline to fail on `exit != 0`.
+# If `fail` is set to `true` (and it is by default), propagate the real exit
+# value to the workflow runner. This will cause the pipeline to fail on 
+# `exit != # 0`.
 if [ "$INPUT_FAIL" = true ] ; then
     exit ${exit_code}
 fi

fixtures/empty.md

@@ -0,0 +1 @@
+This file contains no links. Used for checking `failIfEmpty` flag.