Merge branch 'ci_triggers_docs' into 'master'
Documentation on CI triggers Closes #3432 ## Notes * Implement build trigger API - https://gitlab.com/gitlab-org/gitlab-ci/merge_requests/229 * Build trigger API - https://gitlab.com/gitlab-org/gitlab-ci/issues/257 * Build pipeline - https://dev.gitlab.org/gitlab/gitlab-ci/issues/282 and https://gitlab.com/gitlab-org/gitlab-ce/issues/3743 * Dependent builds - https://dev.gitlab.org/gitlab/gitlab-ci/issues/328 * Travis docs - https://docs.travis-ci.com/user/triggering-builds/ * Custom variables Circle CI example - https://circleci.com/docs/nightly-builds * Triggers API (CI) will be done in a separate MR * Notify https://gitlab.com/gitlab-org/gitlab-ci/issues/368 once done ## Docs needed to change - [x] `doc/ci/README.md` - [x] `doc/README.md` See merge request !2161
This commit is contained in:
commit
ed777c7bcc
|
@ -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
|
||||
|
||||
|
|
|
@ -2,25 +2,26 @@
|
|||
|
||||
### 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
|
||||
|
||||
|
@ -32,5 +33,5 @@
|
|||
|
||||
### Administrator documentation
|
||||
|
||||
+ [User permissions](permissions/README.md)
|
||||
+ [API](api/README.md)
|
||||
* [User permissions](permissions/README.md)
|
||||
* [API](api/README.md)
|
||||
|
|
|
@ -0,0 +1,175 @@
|
|||
# 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, 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.example.com/api/v3/projects/9/trigger/builds
|
||||
```
|
||||
|
||||
In this case, the project with ID `9` will get rebuilt on `master` branch.
|
||||
|
||||
|
||||
### 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.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
|
Binary file not shown.
After Width: | Height: | Size: 39 KiB |
Binary file not shown.
After Width: | Height: | Size: 2.8 KiB |
Binary file not shown.
After Width: | Height: | Size: 5.3 KiB |
Binary file not shown.
After Width: | Height: | Size: 16 KiB |
Loading…
Reference in New Issue