From 33ef13c641a63c4c82c5867a6f01a90c57f3aa04 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 21 Dec 2015 15:53:08 +0200 Subject: Init documentation on Triggers [ci skip] --- doc/ci/README.md | 39 ++++++++++++++++++++------------------- doc/ci/triggers/README.md | 11 +++++++++++ 2 files changed, 31 insertions(+), 19 deletions(-) create mode 100644 doc/ci/triggers/README.md diff --git a/doc/ci/README.md b/doc/ci/README.md index 5d9d7a81db3..aef6e69b7a6 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -2,34 +2,35 @@ ### User documentation -+ [Quick Start](quick_start/README.md) -+ [Configuring project (.gitlab-ci.yml)](yaml/README.md) -+ [Configuring runner](runners/README.md) -+ [Configuring deployment](deployment/README.md) -+ [Using Docker Images](docker/using_docker_images.md) -+ [Using Docker Build](docker/using_docker_build.md) -+ [Using Variables](variables/README.md) -+ [Using SSH keys](ssh_keys/README.md) +* [Quick Start](quick_start/README.md) +* [Configuring project (.gitlab-ci.yml)](yaml/README.md) +* [Configuring runner](runners/README.md) +* [Configuring deployment](deployment/README.md) +* [Using Docker Images](docker/using_docker_images.md) +* [Using Docker Build](docker/using_docker_build.md) +* [Using Variables](variables/README.md) +* [Using SSH keys](ssh_keys/README.md) +* [Triggering builds through the API](triggers/README.md) ### Languages -+ [Testing PHP](languages/php.md) +* [Testing PHP](languages/php.md) ### Services -+ [Using MySQL](services/mysql.md) -+ [Using PostgreSQL](services/postgres.md) -+ [Using Redis](services/redis.md) -+ [Using Other Services](docker/using_docker_images.md#how-to-use-other-images-as-services) +* [Using MySQL](services/mysql.md) +* [Using PostgreSQL](services/postgres.md) +* [Using Redis](services/redis.md) +* [Using Other Services](docker/using_docker_images.md#how-to-use-other-images-as-services) ### Examples -+ [Test and deploy Ruby applications to Heroku](examples/test-and-deploy-ruby-application-to-heroku.md) -+ [Test and deploy Python applications to Heroku](examples/test-and-deploy-python-application-to-heroku.md) -+ [Test Clojure applications](examples/test-clojure-application.md) -+ Help your favorite programming language and GitLab by sending a merge request with a guide for that language. +* [Test and deploy Ruby applications to Heroku](examples/test-and-deploy-ruby-application-to-heroku.md) +* [Test and deploy Python applications to Heroku](examples/test-and-deploy-python-application-to-heroku.md) +* [Test Clojure applications](examples/test-clojure-application.md) +* Help your favorite programming language and GitLab by sending a merge request with a guide for that language. ### Administrator documentation -+ [User permissions](permissions/README.md) -+ [API](api/README.md) +* [User permissions](permissions/README.md) +* [API](api/README.md) diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md new file mode 100644 index 00000000000..5990d74fda1 --- /dev/null +++ b/doc/ci/triggers/README.md @@ -0,0 +1,11 @@ +# Triggering Builds through the API + +_**Note:** This feature was [introduced][ci-229] in GitLab CE 7.14_ + +Triggers can be used to force a rebuild of a specific branch or tag with an API +call. + +## Add a trigger + + +[ci-229]: https://gitlab.com/gitlab-org/gitlab-ci/merge_requests/229 -- cgit v1.2.1 From d5e9436033d75da74c40ced450e060c8a5c307f9 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 21 Dec 2015 20:41:51 +0200 Subject: Document triggers in yaml/README.md [ci skip] --- doc/ci/yaml/README.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index fd0d49de4e4..6862116cc5b 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -66,6 +66,7 @@ There are a few reserved `keywords` that **cannot** be used as job names: | before_script | no | Define commands that run before each job's script | | variables | no | Define build variables | | cache | no | Define list of files that should be cached between subsequent runs | +| trigger | no | Force a rebuild of a specific branch or tag with an API call | ### image and services @@ -152,6 +153,32 @@ cache: - binaries/ ``` +### trigger + +Triggers can be used to force a rebuild of a specific branch or tag with an API +call. You can add a trigger by visiting the project's **Settings > Triggers**. + +Every new trigger you create, gets assigned a different token which you can +then use inside your `.gitlab-ci.yml`: + +```yaml +trigger: + stage: deploy + script: + - "curl -X POST -F token=TOKEN -F ref=master https://gitlab.com/api/v3/projects/9/trigger/builds" +``` + +In the example above, a rebuild on master branch will be triggered after all +previous stages build successfully (denoted by `stage: deploy`). + +You can find the endpoint containing the ID of the project on the **Triggers** +page. + +_**Warning:** Be careful how you set up your triggers, because you could end up +in an infinite loop._ + +Read more in the dedicated [triggers documentation](../triggers/README.md). + ## Jobs `.gitlab-ci.yml` allows you to specify an unlimited number of jobs. Each job -- cgit v1.2.1 From 6fce8b6f5cfee1fe17ef7cdb5508b66da93f1f14 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Thu, 24 Dec 2015 21:48:24 +0200 Subject: Add triggers doc in top level readme [ci skip] --- doc/README.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/doc/README.md b/doc/README.md index 8bac00f2f23..f40a257b42f 100644 --- a/doc/README.md +++ b/doc/README.md @@ -28,17 +28,18 @@ - [Using SSH keys](ci/ssh_keys/README.md) - [User permissions](ci/permissions/README.md) - [API](ci/api/README.md) +- [Triggering builds through the API](ci/triggers/README.md) ### CI Languages -+ [Testing PHP](ci/languages/php.md) +- [Testing PHP](ci/languages/php.md) ### CI Services -+ [Using MySQL](ci/services/mysql.md) -+ [Using PostgreSQL](ci/services/postgres.md) -+ [Using Redis](ci/services/redis.md) -+ [Using Other Services](ci/docker/using_docker_images.md#how-to-use-other-images-as-services) +- [Using MySQL](ci/services/mysql.md) +- [Using PostgreSQL](ci/services/postgres.md) +- [Using Redis](ci/services/redis.md) +- [Using Other Services](ci/docker/using_docker_images.md#how-to-use-other-images-as-services) ### CI Examples -- cgit v1.2.1 From aafd7ce83bf1f6c1074b93ad489caa03e5b20786 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Thu, 24 Dec 2015 21:50:03 +0200 Subject: Remove triggers from yaml doc [ci skip] --- doc/ci/yaml/README.md | 27 --------------------------- 1 file changed, 27 deletions(-) diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 6862116cc5b..fd0d49de4e4 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -66,7 +66,6 @@ There are a few reserved `keywords` that **cannot** be used as job names: | before_script | no | Define commands that run before each job's script | | variables | no | Define build variables | | cache | no | Define list of files that should be cached between subsequent runs | -| trigger | no | Force a rebuild of a specific branch or tag with an API call | ### image and services @@ -153,32 +152,6 @@ cache: - binaries/ ``` -### trigger - -Triggers can be used to force a rebuild of a specific branch or tag with an API -call. You can add a trigger by visiting the project's **Settings > Triggers**. - -Every new trigger you create, gets assigned a different token which you can -then use inside your `.gitlab-ci.yml`: - -```yaml -trigger: - stage: deploy - script: - - "curl -X POST -F token=TOKEN -F ref=master https://gitlab.com/api/v3/projects/9/trigger/builds" -``` - -In the example above, a rebuild on master branch will be triggered after all -previous stages build successfully (denoted by `stage: deploy`). - -You can find the endpoint containing the ID of the project on the **Triggers** -page. - -_**Warning:** Be careful how you set up your triggers, because you could end up -in an infinite loop._ - -Read more in the dedicated [triggers documentation](../triggers/README.md). - ## Jobs `.gitlab-ci.yml` allows you to specify an unlimited number of jobs. Each job -- cgit v1.2.1 From e74affcfa84acaddc236d6dfed7be1a61470dc0e Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Fri, 25 Dec 2015 01:29:27 +0200 Subject: Add images and examples --- doc/ci/triggers/README.md | 97 ++++++++++++++++++++++++++- doc/ci/triggers/img/builds_page.png | Bin 0 -> 39713 bytes doc/ci/triggers/img/trigger_single_build.png | Bin 0 -> 2895 bytes doc/ci/triggers/img/trigger_variables.png | Bin 0 -> 5418 bytes doc/ci/triggers/img/triggers_page.png | Bin 0 -> 15889 bytes 5 files changed, 95 insertions(+), 2 deletions(-) create mode 100644 doc/ci/triggers/img/builds_page.png create mode 100644 doc/ci/triggers/img/trigger_single_build.png create mode 100644 doc/ci/triggers/img/trigger_variables.png create mode 100644 doc/ci/triggers/img/triggers_page.png diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index 5990d74fda1..63661ee4858 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -2,10 +2,103 @@ _**Note:** This feature was [introduced][ci-229] in GitLab CE 7.14_ -Triggers can be used to force a rebuild of a specific branch or tag with an API -call. +Triggers can be used to force a rebuild of a specific branch, tag or commit, +with an API call. ## Add a trigger +You can add a new trigger by going to your project's **Settings > Triggers**. +The **Add trigger** button will create a new token which you can then use to +trigger a rebuild of this particular project. + +Once at least one trigger is created, on the **Triggers** page you will find +some descriptive information on how you can + +Every new trigger you create, gets assigned a different token which you can +then use inside your scripts or `.gitlab-ci.yml`. You also have a nice +overview of the time the triggers were last used. + +![Triggers page overview](img/triggers_page.png) + +## Revoke a trigger + +You can revoke a trigger any time by going at your project's +**Settings > Triggers** and hitting the **Revoke** button. The action is +irreversible. + +## Trigger a build + +To trigger a build you need to send a `POST` request to GitLab's API endpoint: + +``` +POST /projects/:id/trigger/builds +``` + +The required parameters are the trigger's `token` and the Git `ref` on which +the trigger will be performed. Valid refs are the branch, the tag or the commit +SHA. The `:id` of a project can be found by [querying the API](../api/projects.md) +or by visiting the **Triggers** page which provides self-explanatory examples. + +When a rebuild is triggered, the information is exposed in GitLab's UI under +the **Builds** page and the builds are marked as `triggered`. + +![Marked rebuilds as triggered on builds page](img/builds_page.png) + +--- + +You can see which trigger caused the rebuild by visiting the single build page. +The token of the trigger is exposed in the UI as you can see from the image +below. + +![Marked rebuilds as triggered on a single build page](img/trigger_single_build.png) + +--- + +See the [Examples](#examples) section for more details on how to actually +trigger a rebuild. + +## Pass build variables to a trigger + +You can pass any number of arbitrary variables in the trigger API call and they +will be available in GitLab CI so that they can be used in your `.gitlab-ci.yml` +file. The parameter is of the form: + +``` +variables[key]=value +``` + +This information is also exposed in the UI. + +![Build variables in UI](img/trigger_variables.png) + +--- + +See the [Examples](#examples) section below for more details. + +## Examples + +Using cURL you can trigger a rebuild with minimal effort, for example: + +```bash +curl -X POST \ + -F token=TOKEN \ + -F ref=master \ + https://gitlab.com/api/v3/projects/9/trigger/builds +``` + +In this case, the project with ID `9` will get rebuilt on `master` branch. + +You can also use triggers in your `.gitlab-ci.yml`. Let's say that you have +two projects, A and B, and you want to trigger a rebuild on the `master` +branch of project B whenever a tag on project A is created. + +```yaml +build_docs: + stage: deploy + script: + - "curl -X POST -F token=TOKEN -F ref=master https://gitlab.com/api/v3/projects/9/trigger/builds" + only: + - tags +``` [ci-229]: https://gitlab.com/gitlab-org/gitlab-ci/merge_requests/229 diff --git a/doc/ci/triggers/img/builds_page.png b/doc/ci/triggers/img/builds_page.png new file mode 100644 index 00000000000..e78794fbee7 Binary files /dev/null and b/doc/ci/triggers/img/builds_page.png differ diff --git a/doc/ci/triggers/img/trigger_single_build.png b/doc/ci/triggers/img/trigger_single_build.png new file mode 100644 index 00000000000..c25f27409d6 Binary files /dev/null and b/doc/ci/triggers/img/trigger_single_build.png differ diff --git a/doc/ci/triggers/img/trigger_variables.png b/doc/ci/triggers/img/trigger_variables.png new file mode 100644 index 00000000000..2207e8b34cb Binary files /dev/null and b/doc/ci/triggers/img/trigger_variables.png differ diff --git a/doc/ci/triggers/img/triggers_page.png b/doc/ci/triggers/img/triggers_page.png new file mode 100644 index 00000000000..268368dc3c5 Binary files /dev/null and b/doc/ci/triggers/img/triggers_page.png differ -- cgit v1.2.1 From 662e9cffe1dc278bad06c8b44c527cac1d0e913d Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Fri, 25 Dec 2015 13:37:46 +0200 Subject: Add examples for triggers [ci skip] --- doc/ci/triggers/README.md | 81 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 76 insertions(+), 5 deletions(-) diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index 63661ee4858..2c1de5859f8 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -83,22 +83,93 @@ Using cURL you can trigger a rebuild with minimal effort, for example: curl -X POST \ -F token=TOKEN \ -F ref=master \ - https://gitlab.com/api/v3/projects/9/trigger/builds + https://gitlab.example.com/api/v3/projects/9/trigger/builds ``` In this case, the project with ID `9` will get rebuilt on `master` branch. -You can also use triggers in your `.gitlab-ci.yml`. Let's say that you have -two projects, A and B, and you want to trigger a rebuild on the `master` -branch of project B whenever a tag on project A is created. + +### Triggering a build within `.gitlab-ci.yml` + +You can also benefit by using triggers in your `.gitlab-ci.yml`. Let's say that +you have two projects, A and B, and you want to trigger a rebuild on the `master` +branch of project B whenever a tag on project A is created. This is the job you +need to add in project's A `.gitlab-ci.yml`: ```yaml build_docs: stage: deploy script: - - "curl -X POST -F token=TOKEN -F ref=master https://gitlab.com/api/v3/projects/9/trigger/builds" + - "curl -X POST -F token=TOKEN -F ref=master https://gitlab.example.com/api/v3/projects/9/trigger/builds" only: - tags ``` +Now, whenever a new tag is pushed on project A, the build will run and the +`build_docs` job will be executed, triggering a rebuild of project B. The +`stage: deploy` ensures that this job will run only after all jobs with +`stage: test` complete successfully. + +_**Note:** If your project is public, passing the token in plain text is +probably not the wiser idea, so you might want to use a +[secure variable](../variables/README.md#user-defined-variables-secure-variables) +for that purpose._ + +### Making use of trigger variables + +Using trigger variables can be proven useful for a variety of reasons. + +* Identifiable jobs. Since the variable is exposed in the UI you can know + why the rebuild was triggered if you pass a variable that explains the + purpose. +* Conditional job processing. You can have conditional jobs that run whenever + a certain variable is present. + +Consider the following `.gitlab-ci.yml` where we set three +[stages](../yaml/README.md#stages) and the `upload_package` job is run only +when all jobs from the test and build stages pass. When the `UPLOAD_TO_S3` +variable is non-zero, `make upload` is run. + +```yaml +stages: +- test +- build +- package + +run_tests: + script: + - make test + +build_package: + stage: build + script: + - make build + +upload_package: + stage: package + script: + - if [ -n "${UPLOAD_TO_S3}" ]; then make upload; fi +``` + +You can then trigger a rebuild while you pass the `UPLOAD_TO_S3` variable +and the script of the `upload_package` job will run: + +```bash +curl -X POST \ + -F token=TOKEN \ + -F ref=master \ + -F "variables[UPLOAD_TO_S3]=true" \ + https://gitlab.example.com/api/v3/projects/9/trigger/builds +``` + +### Using cron to trigger nightly builds + +Whether you craft a script or just run cURL directly, you can trigger builds +in conjunction with cron. The example below triggers a build on the `master` +branch of project with ID `9` every night at `00:30`: + +```bash +30 0 * * * curl -X POST -F token=TOKEN -F ref=master https://gitlab.example.com/api/v3/projects/9/trigger/builds +``` + [ci-229]: https://gitlab.com/gitlab-org/gitlab-ci/merge_requests/229 -- cgit v1.2.1