From 869aedb3dea8ba555d5009eb7e2df358f934ae7a Mon Sep 17 00:00:00 2001 From: Konstantin Semenov Date: Wed, 10 Jan 2024 14:44:30 +0000 Subject: [PATCH] docs: Explain the reasoning behind and workaround for read/write resource separation Signed-off-by: Konstantin Semenov --- README.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 423f9d7..cfa4311 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ Tracks the commits in a [git](http://git-scm.com/) repository. * `uri`: *Required.* The location of the repository. * `branch`: The branch to track. This is *optional* if the resource is - only used in `get` steps; however, it is *required* when used in a `put` step. If unset for `get`, the repository's default branch is used; usually `master` but [could be different](https://help.github.com/articles/setting-the-default-branch/). + only used in `get` steps; however, it is *required* either here, or in the `put` step, when used in a `put` step. If unset for `get`, the repository's default branch is used; usually `master` but [could be different](https://help.github.com/articles/setting-the-default-branch/). * `private_key`: *Optional.* Private key to use when pulling/pushing. Example: @@ -302,6 +302,19 @@ Push the checked-out reference to the source's URI and branch. All tags are also pushed to the source. If a fast-forward for the branch is not possible and the `rebase` parameter is not provided, the push will fail. +#### Important note + +Due to the way [resources are cached in Concourse](https://medium.com/concourse-ci/concourse-resource-volume-caching-7f4eb73be1a6), +any commits produced by the `put` step will appear in _ALL_ git resources with the +_exact_ same `source` configuration across _ALL_ pipelines, across _ALL_ teams in the +Concourse instance, even if the branch name in `put` step is different from the one +specified `source.branch`. + +Therefore, it is recommended to use a separate git resource to use in the `put` +steps, such that its configuration is different from all the git resources used +in `get` steps. E.g. set `source.commit_filter.exclude` to something like +`[ "this resource is used for pushing new changes" ]`. + #### Parameters * `repository`: *Required.* The path of the repository to push to the source. @@ -342,7 +355,8 @@ pushed regardless of the upstream state. Note that the version produced by the `put` step will be picked up by subsequent `get` steps even if the `branch` differs from the `branch` specified in the source. - To avoid this, you should use two resources of read-only and write-only. + To avoid this, you should use two resources of read-only and write-only with differing `source` + configurations. See [this note](#important-note) for further details. * `refs_prefix`: *Optional.* Allows pushing to refs other than heads. Defaults to `refs/heads`.