bitbucket-pipelines.yml reference?

Question

I'm getting started with bitbucket-pipelines.yml and getting frustrated because I can't find any "full reference" of what the bitbucket-pipelines.yml syntax is?

Yes I can use validator, but that is shooting to the dark, because there isn't any descriptions available to all the YAML attributes that could be used.

For example in this documentation I can collect information that the top level `image` supports for example keys: `aws` (Pipeline custom implementation?), `username` and `password`  for docker login, `run-as-user` etc..

The most I'm struggling is that I'm trying to understand how the Pipelines runs the "Docker build environment" when entering the "steps" phase. If I can pass `-e` variables in image declaration like this:

image: my-image
variables:
  var1: $SECRET
  var2: TEST

At the moment I have a feeling that:

a) variables seem not to be set to the container

b) the Pipeline provides it's own entrypoint for the image. This is fine but where are the details of this behavior documented?

I'm feeling I'm wasting time trying to shoot commits in and see how the pipeline behaves with different configurations. Thus a reference would be really really helpful and also detailed description what happens when entering the `steps` phase.

Thanks.

Tyler Kelly · Answer

Hi!

We recently replaced the old configuration options page with a new section with a lot more detail: https://support.atlassian.com/bitbucket-cloud/docs/bitbucket-pipelines-configuration-reference/

I hope everyone finds it more helpful!

Tyler

Caroline R · Answer

Hi, @Snurppa.

First of all, we do understand that the Pipelines documentation can be improved, so I have created a feature request to improve that, please feel free to add any relevant information in the comments:

* https://jira.atlassian.com/browse/BCLOUD-21400

I would suggest that you add your vote there (by selecting the Vote for this issue link) as the number of votes helps the development team and product managers better understand the demand for new features.

You can add yourself as a watcher (by selecting the Start watching this issue link) if you'd like to get notified via email on updates.

Implementation of new features is done as per our policy here and any updates will be posted in the feature request.

Also, just to be sure we are on the same page about variables, you don’t need to specify them in the YAML file, you can directly create the variables at the repository level by following these steps:

* Open the repository > Repository settings

* Select Repository variables

* Add your variables as secured or unsecured and click Add

Please, feel free to share any additional questions or concerns regarding this case.

Kind regards,
Caroline

Snurppa · Answer

Thank you for your responses.

As @Taylor Gregory said, I believe the following documentation will be useful to you:

* Configure bitbucket-pipelines.yml

Yes I've found the provided docs and they are helpful to some extent.

I feel that it's not a "full reference" I was after. For example the `image.aws` key is not documented in that bitbucket-pipelines.yml page. It is mentioned in one of the pages I already mentioned (Use Docker images as build environment). The problem in that case was that the information is not clearly structured, but you need to go through the whole page and "gather the bits and pieces" of the YAML syntax from the examples.

And we also have specific documentation about variables:

* Variables and secrets

I think I didn't really have problems with variables per se, rather trying to figure out how the pipeline behaves with the declared `image`. Eg. if I can use something like `-e` in docker somehow in the YAML or not. The full reference would most likely tell me that NO, I can't use it or I could see from the reference that "oh it's not `variables` it's actualy `environment` I'm after" (hypothetically). Now I need to go through all the examples in different pages to gather this information piece by piece (and the information might or might not be available). For example GitLabs documentation is up to speed with this to assist "power users" to find available bits and pieces in one place. I think if Pipelines would have something that goes that deep into details, I wouldn't have had to write here in the first place.

For my wonder a), it seems that "variables", according to the doc, is only used for "custom" pipelines. In that case eventually the documentation answers that.

The wonder b), regarding how the build container is actually executed by Pipelines isn't documented anywhere. Searching the forums here, I can see some answers that the Pipelines overwrites image entrypoint with custom entrypoint. This would be really good information in the documentation, so without "shooting blindly" I could see how to build and design my image structure to work with pipelines.