BigW Consortium Gitlab

README.md 6.27 KB
Newer Older
1 2
# Triggering Builds through the API

3
> [Introduced][ci-229] in GitLab CE 7.14.
4

5 6
> **Note**:
GitLab 8.12 has a completely redesigned build permissions system.
7
Read all about the [new model and its implications](../../user/project/new_ci_build_permissions_model.md#build-triggers).
8

9 10
Triggers can be used to force a rebuild of a specific branch, tag or commit,
with an API call.
11 12 13

## Add a trigger

14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39
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.

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
40
SHA. The `:id` of a project can be found by [querying the API](../../api/projects.md)
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60
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.

61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76
## Trigger a build from webhook

> Introduced in GitLab 8.14.

To trigger a build from webhook of another project you need to add the following
webhook url for Push and Tag push events:

```
https://gitlab.example.com/api/v3/projects/:id/ref/:ref/trigger/builds?token=TOKEN
```

> **Note**:
- `ref` should be passed as part of url in order to take precedence over `ref`
  from webhook body that designates the branchref that fired the trigger in the source repository.
- `ref` should be url encoded if contains slashes.

77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99
## 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
100 101 102
curl --request POST \
     --form token=TOKEN \
     --form ref=master \
103
     https://gitlab.example.com/api/v3/projects/9/trigger/builds
104 105 106 107
```

In this case, the project with ID `9` will get rebuilt on `master` branch.

108 109 110
Alternatively, you can pass the `token` and `ref` arguments in the query string:

```bash
111
curl --request POST \
112 113
    "https://gitlab.example.com/api/v3/projects/9/trigger/builds?token=TOKEN&ref=master"
```
114 115 116 117 118 119 120

### 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`:
121 122 123 124 125

```yaml
build_docs:
  stage: deploy
  script:
126
  - "curl --request POST --form token=TOKEN --form ref=master https://gitlab.example.com/api/v3/projects/9/trigger/builds"
127 128 129
  only:
  - tags
```
130

131 132 133 134 135 136
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
137
probably not the wisest idea, so you might want to use a
138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180
[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
181 182 183 184
curl --request POST \
  --form token=TOKEN \
  --form ref=master \
  --form "variables[UPLOAD_TO_S3]=true" \
185 186 187
  https://gitlab.example.com/api/v3/projects/9/trigger/builds
```

188 189 190 191 192 193 194 195
### Using webhook to trigger builds

You can add the following webhook to another project in order to trigger a build:

```
https://gitlab.example.com/api/v3/projects/9/ref/master/trigger/builds?token=TOKEN&variables[UPLOAD_TO_S3]=true
```

196 197 198 199 200 201 202
### 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
203
30 0 * * * curl --request POST --form token=TOKEN --form ref=master https://gitlab.example.com/api/v3/projects/9/trigger/builds
204 205
```

206
[ci-229]: https://gitlab.com/gitlab-org/gitlab-ci/merge_requests/229