From a52960f5a1aa039a57c17a577aeb9fb82e238f4a Mon Sep 17 00:00:00 2001 From: Grzegorz Bizon Date: Tue, 2 Oct 2018 16:13:49 +0200 Subject: Add basic documentation for only: changes feature --- doc/ci/yaml/README.md | 37 ++++++++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index e38628b288b..d1ae7326852 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -387,6 +387,8 @@ except master. > `refs` and `kubernetes` policies introduced in GitLab 10.0 > > `variables` policy introduced in 10.7 +> +> `changes` policy introduced in 11.4 CAUTION: **Warning:** This an _alpha_ feature, and it it subject to change at any time without @@ -398,10 +400,15 @@ policy configuration. GitLab now supports both, simple and complex strategies, so it is possible to use an array and a hash configuration scheme. -Three keys are now available: `refs`, `kubernetes` and `variables`. +Four keys are now available: `refs`, `kubernetes` and `variables` and `changes`. + +### `refs` and `kubernetes` + Refs strategy equals to simplified only/except configuration, whereas kubernetes strategy accepts only `active` keyword. +### `variables` + `variables` keyword is used to define variables expressions. In other words you can use predefined variables / project / group or environment-scoped variables to define an expression GitLab is going to @@ -445,6 +452,34 @@ end-to-end: Learn more about variables expressions on [a separate page][variables-expressions]. +### `changes` + +Using `changes` keyword with `only` or `except` makes it possible to define if +a job should be created, based on files modified by a git push event. + +```yaml +docker build: + script: docker build -t my-image:$CI_COMMIT_REF_SLUG . + only: + changes: + - Dockerfile + - docker/scripts/* +``` + +In the scenario above, if you are pushing multiple commits to GitLab, to an +exising branch, GitLab is going to create and trigger `docker build` if one of +the commits contains changes to the `Dockerfile` file or any of the files +inside `docker/scripts/` directory. + +CAUTION: **Warning:** +If you are pushing a **new** branch or a tag to GitLab, only/changes is going +to always evaluate to truth and GitLab will create a job. This feature is not +connected with merge requests yet, GitLab is creating pipelines before an user +creates a merge requests and specifies a target branch. Without a target branch +it is not possible to know what the common ancestor is in case of pushing a new +branch, thus we always create a job in that case. This feature works best for +stable branches like `master`. + ## `tags` `tags` is used to select specific Runners from the list of all Runners that are -- cgit v1.2.1 From 09075759a428220ddfb5dacf6a6974c11956e391 Mon Sep 17 00:00:00 2001 From: Grzegorz Bizon Date: Tue, 2 Oct 2018 16:21:53 +0200 Subject: Copy-edit docs for only: changes feature --- doc/ci/yaml/README.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) (limited to 'doc') diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index d1ae7326852..ef9a00266e1 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -467,18 +467,19 @@ docker build: ``` In the scenario above, if you are pushing multiple commits to GitLab, to an -exising branch, GitLab is going to create and trigger `docker build` if one of -the commits contains changes to the `Dockerfile` file or any of the files -inside `docker/scripts/` directory. +exising branch, GitLab is going to create and trigger `docker build` job, +provided that one of the commits contains changes to the `Dockerfile` file or +changes to any of the files inside `docker/scripts/` directory. CAUTION: **Warning:** -If you are pushing a **new** branch or a tag to GitLab, only/changes is going -to always evaluate to truth and GitLab will create a job. This feature is not -connected with merge requests yet, GitLab is creating pipelines before an user -creates a merge requests and specifies a target branch. Without a target branch -it is not possible to know what the common ancestor is in case of pushing a new -branch, thus we always create a job in that case. This feature works best for -stable branches like `master`. +If you are pushing a **new** branch or a new tag to GitLab, only/changes is +going to always evaluate to truth and GitLab will create a job. This feature is +not combined with merge requests yet, and because GitLab is creating pipelines +before an user can create a merge request we don't know a target branch at +this point. Without a target branchit is not possible to know what the common +ancestor is, thus we always create a job in that case. This feature works best for +stable branches like `master` because in that case GitLab uses previous commit, +that is present in a branch, to compare against a newly pushed latest SHA. ## `tags` -- cgit v1.2.1 From 4000358531668e07021160e436f3cdc1b873e9d7 Mon Sep 17 00:00:00 2001 From: Grzegorz Bizon Date: Wed, 3 Oct 2018 12:21:41 +0200 Subject: Few minor fixed in code and docs for only: changes --- doc/ci/yaml/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index ef9a00266e1..0d07b63a2dc 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -476,7 +476,7 @@ If you are pushing a **new** branch or a new tag to GitLab, only/changes is going to always evaluate to truth and GitLab will create a job. This feature is not combined with merge requests yet, and because GitLab is creating pipelines before an user can create a merge request we don't know a target branch at -this point. Without a target branchit is not possible to know what the common +this point. Without a target branch it is not possible to know what the common ancestor is, thus we always create a job in that case. This feature works best for stable branches like `master` because in that case GitLab uses previous commit, that is present in a branch, to compare against a newly pushed latest SHA. -- cgit v1.2.1 From bfdac6324c717d014b7271a83c2bf883814f93d7 Mon Sep 17 00:00:00 2001 From: Grzegorz Bizon Date: Thu, 4 Oct 2018 11:50:06 +0200 Subject: Copy-edit documentation for only/except changes feature --- doc/ci/yaml/README.md | 38 +++++++++++++++++++++++++------------- 1 file changed, 25 insertions(+), 13 deletions(-) (limited to 'doc') diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 0d07b63a2dc..442a8ba643b 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -388,7 +388,7 @@ except master. > > `variables` policy introduced in 10.7 > -> `changes` policy introduced in 11.4 +> `changes` policy [introduced in 11.4][changes-policy-issue] CAUTION: **Warning:** This an _alpha_ feature, and it it subject to change at any time without @@ -455,7 +455,9 @@ Learn more about variables expressions on [a separate page][variables-expression ### `changes` Using `changes` keyword with `only` or `except` makes it possible to define if -a job should be created, based on files modified by a git push event. +a job should be created based on files modified by a git push event. + +For example: ```yaml docker build: @@ -466,20 +468,29 @@ docker build: - docker/scripts/* ``` -In the scenario above, if you are pushing multiple commits to GitLab, to an -exising branch, GitLab is going to create and trigger `docker build` job, -provided that one of the commits contains changes to the `Dockerfile` file or -changes to any of the files inside `docker/scripts/` directory. +In the scenario above, if you are pushing multiple commits to GitLab to an +existing branch, GitLab creates and triggers `docker build` job, provided that +one of the commits contains changes to either: + +- The `Dockerfile` file. +- Any of the files inside `docker/scripts/` directory. CAUTION: **Warning:** -If you are pushing a **new** branch or a new tag to GitLab, only/changes is -going to always evaluate to truth and GitLab will create a job. This feature is -not combined with merge requests yet, and because GitLab is creating pipelines +There are some caveats when using this feature with new branches and tags. See +the section below. + +#### Using `changes` with new branches and tags + +If you are pushing a **new** branch or a **new** tag to GitLab, the policy +always evaluates to truth and GitLab will create a job. This feature is not +connected with merge requests yet, and because GitLab is creating pipelines before an user can create a merge request we don't know a target branch at -this point. Without a target branch it is not possible to know what the common -ancestor is, thus we always create a job in that case. This feature works best for -stable branches like `master` because in that case GitLab uses previous commit, -that is present in a branch, to compare against a newly pushed latest SHA. +this point. + +Without a target branch, it is not possible to know what the common ancestor is, +thus we always create a job in that case. This feature works best for stable +branches like `master` because in that case GitLab uses the previous commit +that is present in a branch to compare against the latest SHA that was pushed. ## `tags` @@ -1976,3 +1987,4 @@ CI with various languages. [ce-12909]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12909 [schedules]: ../../user/project/pipelines/schedules.md [variables-expressions]: ../variables/README.md#variables-expressions +[changes-policy-issue]: https://gitlab.com/gitlab-org/gitlab-ce/issues/19232 -- cgit v1.2.1 From a545703e739fea0b7d79cc8f0d59e0a64c0eb15b Mon Sep 17 00:00:00 2001 From: Grzegorz Bizon Date: Fri, 5 Oct 2018 10:28:42 +0200 Subject: Improve only: changes feature documentation Align with current technical writing style-guides. --- doc/ci/yaml/README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 442a8ba643b..15dde36cca8 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -388,7 +388,7 @@ except master. > > `variables` policy introduced in 10.7 > -> `changes` policy [introduced in 11.4][changes-policy-issue] +> `changes` policy [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/19232) in 11.4 CAUTION: **Warning:** This an _alpha_ feature, and it it subject to change at any time without @@ -482,7 +482,7 @@ the section below. #### Using `changes` with new branches and tags If you are pushing a **new** branch or a **new** tag to GitLab, the policy -always evaluates to truth and GitLab will create a job. This feature is not +always evaluates to true and GitLab will create a job. This feature is not connected with merge requests yet, and because GitLab is creating pipelines before an user can create a merge request we don't know a target branch at this point. @@ -1987,4 +1987,3 @@ CI with various languages. [ce-12909]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12909 [schedules]: ../../user/project/pipelines/schedules.md [variables-expressions]: ../variables/README.md#variables-expressions -[changes-policy-issue]: https://gitlab.com/gitlab-org/gitlab-ce/issues/19232 -- cgit v1.2.1