Add caching support for Lychee with --cache flag detection

[mre]

This adds GitHub Actions caching for the .lycheecache file when the --cache flag is present.

Important Notes

1. The cache is only for the .lycheecache file, not the lychee binary
2. Caching is only enabled when --cache is present in the lychee arguments
3. The cache is saved even if the lychee run fails (using !cancelled() condition)
4. The cache key uses github.sha for uniqueness with fallback to previous caches
5. The cache path respects the workingDirectory input

Usage Example

When users include --cache in their arguments:

- uses: lycheeverse/lychee-action@main
  with:
    args: "--cache --verbose --no-progress './**/*.md'"

The action will:

1. Detect the --cache flag
2. Restore any existing .lycheecache file before running
3. Save the updated .lycheecache file after running

Without --cache, no GitHub Actions caching occurs, preventing any issues in restricted environments.

Fixes #291.

[mre]

The question is what will happen with existing workflows that might have a manual cache setup.
I think the behavior depends a bit on the setup:

• If the cache key is identical, it might be a no-op? (I hope so at least)
• If the cache key is different, we store/restore the cache twice, which might be a problem.

(Correct me if I'm wrong here.)

I wonder how to detect if there's an existing cache setup. There probably is no way.
The easiest "fix" I can think of is to mention it in the release notes and release the change under a new major version v3.

[Arteiii]

One thought: using a dedicated action input like cache: true (defaulting to false) might be cleaner than checking for --cache in the args. That way, it avoids changing the behavior of --cache and keeps things more explicit for users with custom caching setups

[thomaseizinger]

Thank you for working on this!

One thought: using a dedicated action input like cache: true (defaulting to false) might be cleaner than checking for --cache in the args. That way, it avoids changing the behavior of --cache and keeps things more explicit for users with custom caching setups

As someone setting the action up from scratch, you might be wondering then "How many times do I need to tell this action that it should use a cache? :)"

In my experience, many actions enable a cache by default these days because it is basically always what you want and the action maintainers likely know best how the cache should be managed.

My vote would go down for a new major version of the action, with an on-by-default cache and perhaps with --cache also being passed by default.

[Arteiii]

Yeee, this works as well and is probably clearer and easier for people using the action. I actually thought about it too, but wasn’t sure if it was worth pushing another release just for this change, especially since there aren't any other updates lined up right now.

[mre]

Fair point. I think we could wait a bit before we merge this. People interested could already use it (and remove the existing cache if any):

- name: Link Checker
  id: lychee
  uses: lycheeverse/lychee-action@cache
  with:
    fail: false

In fact, I believe it would be best if someone could test it for a while to fix any edge-cases. @thomaseizinger wanna volunteer? 😬

[thomaseizinger]

@thomaseizinger wanna volunteer? 😬

Definitely! We are facing 429s on our daily cron suddenly and I am planning to see if the cache mitigates that.

[mre]

Maybe another case of #289?

[thomaseizinger]

Is this branch safe to depend on? We are hash-pinning all actions in our CI so if you'd like me to test this, I'd ask to please not force-push to this branch :)

[mre]

To be on the safe side, you can also use the commit sha:

lycheeverse/lychee-action@e203314714efe5700a013ace5248a697313082b2

This won't change.

[mre]

@thomaseizinger, did you run into any issues so far? If not, I guess this is safe to merge (and release 3.0). 😄

[Arteiii]

still think adding an explicit action argument (cache: true) would make things cleaner (see: #292 (comment)).

It could default to true, but still check for --cache to avoid conflicts.

That said, --cache shouldn't automatically enable GitHub caching

keeping that opt-in gives users more flexibility for custom setups.

Otherwise, looks good to me!

[thomaseizinger]

@thomaseizinger, did you run into any issues so far? If not, I guess this is safe to merge (and release 3.0). 😄

No issue related to the cache!

[mre]

Thanks for the feedback @thomaseizinger.

@Arteiii, I think it's a great idea to have a dedicated action argument for it. +1 for that. We should add it before the merge.

--cache shouldn't automatically enable GitHub caching
keeping that opt-in gives users more flexibility for custom setups.

Can you give me an example of a custom setup where --cache shouldn't automatically enable GitHub caching? In my mind, it could be quite misleading if a user sets --cache but it "doesn't work", because the cache is not stored anywhere.
I value explicitness, but this behavior could be confusing. In my mind, it's better to have a sane default unless there are any showstoppers (and there might be some which I'm overlooking).

[Arteiii]

I can't think of a setup where the built-in cache wouldn't be enough, but custom setups might exist. To avoid breaking anything, I’d suggest:

• If --cache is set alone, just use default Lychee behavior.

• If --cache (or a custom location) and cache: true in the config are set, raise an error to avoid confusion.

This keeps things explicit without changing behavior for existing setups.

[Arteiii]

• If --cache is set alone, just use default Lychee behavior.

this also makes things more explicit, since we shouldn't modify the Action's behavior based on arguments passed to Lychee via args: ....

[thomas-zahner]

In general im in favour of the proposal of @mre since it's just easier for the vast majority of users. In my opinion it boils down to the following: is it still possible to manually override the caching behaviour introduced in this PR?

If so, I think we should go with the approach suggested by @mre. When bumping the major version of the action we are allowed to introduce breaking changes. Users with custom caching logic could stay on the current version or adapt and update.

[jonatan-ivanov]

fyi: v5 was recently released