Skip to content

Add Bitbucket cache configuration doc#14113

Open
billypoke wants to merge 5 commits intophpstan:2.2.xfrom
billypoke:patch-1
Open

Add Bitbucket cache configuration doc#14113
billypoke wants to merge 5 commits intophpstan:2.2.xfrom
billypoke:patch-1

Conversation

@billypoke
Copy link
Copy Markdown

No description provided.

key:
files:
- composer.lock
- "**/*.php"
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"**/*.php" this doesn't make sense to me, it'd mean that when any .php file changes, the cache is invalidated?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is correct. That makes no sense. I probably misconfigured our pipeline then 🤦 Let me remove that portion and re-run a pipeline.

Copy link
Copy Markdown
Author

@billypoke billypoke Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They also offer the ability to bypass the cache invalidation logic and just always cache the directory, it's possible to do that too.

definitions:
  caches:
    bundler: vendor/bundle
    
pipelines:
  default:
    - step:
  caches:
    - bundler #cache is defined above in the definitions section
  script:
    - bundle install --path vendor/bundle

Copy link
Copy Markdown
Author

@billypoke billypoke Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only invalidating on composer.lock seems to work. The static analysis step dropped to basically they time it takes to clone and setup the env
image
image

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm happy to try any other configurations if you want to check anything else.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

image image

Running across branches works

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can simulate a failure in the phpstan step and in another step and see what the behavior is.

The teardown step is where the cache(s) get uploaded, here's a sample:

You already have a 'composer' cache so we won't create it again
You already have a 'phpstan' cache so we won't create it again
musl libc (x86_64)
Version 1.2.5
Dynamic Program Loader
Usage: /lib/ld-musl-x86_64.so.1 [options] [--] pathname
Cache "composer: ~/.composer/cache": Skipping upload for existing cache
Cache "phpstan: /tmp/phpstan": Skipping upload for existing cache
Searching for test report files in directories named [test-reports, surefire-reports, failsafe-reports, test-results, TestResults] down to a depth of 4
Finished scanning for test reports. Found 0 test report files in 0 seconds.
Merged test suites, total number tests is 0, with 0 failures and 0 errors in 0 seconds.
Compressed step metrics file to 430 B in 0 seconds
Uploading step metrics of 430 B.
Successfully uploaded step metrics in 0 seconds.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It will skip caching if the step using the cache fails. Let me check next if a step not using the cache fails.
image

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When another step not using the cache fails:

If the phpstan cache already exists it will skip
image

If the phpstan cache doesn't exist but the step using the cache passes, it will upload
image

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the step exits with a success code the cache is still uploaded, but that would mask the phpstan failure in the UI

image

@billypoke
Copy link
Copy Markdown
Author

@ondrejmirtes I ran some more tests and attached screenshots. Here's a summary of what I've found:

  • The cache can be used across branches, and multiple versions of the cache can exist based on the files specified, currently composer.lock.
  • If Bitbucket's cache invalidation logic is not desired, it can be configured to always cache a given directory. This is not recommended.
  • If the step using the cache fails (exit code != 0), the cache generation/upload will be skipped, but it will not invalidate any existing caches.
  • If another step not using the cache fails but the step using the cache succeeds, the cache will be uploaded if it does not exist, or skipped if it does.
  • The exit code of the step is used to determine the state of the UI and overall state of the pipeline. If the exit code of the step is coerced to 0, then the cache can still be uploaded but the UI will incorrectly show a passed step.

@ondrejmirtes
Copy link
Copy Markdown
Member

We want the cache to be updated even when PHPStan fails.

Let's say PHPStan has to run fully because you changed config and it finds 5 errors.

If you persist the cache and then run it again after modifying 1 file, it will run much faster.

If you don't persist the cache and modify 1 file, it will have to run full analysis again.

@billypoke
Copy link
Copy Markdown
Author

I don't know if that's possible. According to the cache documentation :

Caches are saved on successful builds when the cache is empty.

If the phpstan process exits with a non-0 code when there are issues, then it seems like the caching step will be skipped. I've opened a community post on Atlassian's website to see if there is a way around that.

@billypoke
Copy link
Copy Markdown
Author

billypoke commented Feb 17, 2026

@ondrejmirtes an Atlassian team member confirmed the limitation:

Unfortunately, Bitbucket Cloud Pipelines don't cache when a build is failed. It will only cache when the build is succeeded.

I can update the PR further to indicate the limitation, or if you don't want the potential additional maintenance overhead with issues that might result from this limitation, I can close this. I think it can still provide some value to configure the cache, even it isn't as flexible or usable as GH or GL.

Thanks for the time and consideration either way!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants