Documentation on CI triggers

Closes #3432 (closed)

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

• doc/ci/README.md
• doc/README.md

I'm wondering whether this should go in its own doc or just reference it somewhere in yaml/README.md like all the others (image, services, cache, etc).

Ideally, each reserved keyword should have its own doc file like we have for docker images. I also want to add some pictures so having it in a separate doc makes more sense.

The only drawback is that the user is driven away from the yaml-all-in-one file where our current docs reside. In the end I might do both, some minor details in the yaml doc and then expand on triggers/README.md.

I'm in for a more modular approach if you ask me. Thoughts, @sytses @ayufan ?

@ayufan I tried adding the trigger in .gitlb-ci.yml like so (REBUILD_TOKEN is a secret variable):

readme:
  script: cat README.md

variables:
  REF_NAME: master

trigger:
  stage: deploy
  script:
    - "curl -X POST -F token=$REBUILD_TOKEN -F ref=$REF_NAME https://gitlab.com/api/v3/projects/41269/trigger/builds"

And then it got in an infinite loop. What is a case scenario one could use?

Added 1 commit:

• d5e94360 - Document triggers in yaml/README.md [ci skip]

Marked the task yaml/README.md as completed

Title changed from Init documentation on Triggers to Documentation on CI triggers

mentioned in issue #4218 (closed)

Title changed from Documentation on CI triggers to [WIP] Documentation on CI triggers

@ayufan what is the reasoning behind the fact that you can create multiple trigger tokens in a specific project? Isn't one enough?

I'm also trying to understand how the trigger keyword fits in (probably in the pipeline stuff). Since we call a script function with curl, couldn't this be a regular job?

@axil The triggering is done to allow external entity to start build. Usually it is script from other project, or some external service executing web hook, usually you should never use triggers to trigger self (it doesn't make sense).

what is the reasoning behind the fact that you can create multiple trigger tokens in a specific project? Isn't one enough?

Yes it is, but as a good security design is better to have revokable triggers. We can think that in future each of the added triggers could have a name that you would specify during creation.

Usually it is script from other project, or some external service executing web hook, usually you should never use triggers to trigger self (it doesn't make sense).

lol yeah brainfart, I thought of that later. Thanks.

Marked the task yaml/README.md as incomplete

Ok, had a call with Kamil and it turned out I had misunderstood that trigger is a special word like image or services, which is not the case. That made everything clear.

Marked the task doc/ci/README.md as completed

Marked the task doc/README.md as completed

Added 1 commit:

• 6fce8b6f - Add triggers doc in top level readme [ci skip]

Added 204 commits:

• 6fce8b6f...350d6550 - 201 commits from branch master
• aafd7ce8 - Remove triggers from yaml doc [ci skip]
• e74affcf - Add images and examples
• d18fd3f6 - Merge branch 'master' into ci_triggers_docs

Added 1 commit:

• 662e9cff - Add examples for triggers [ci skip]

Title changed from [WIP] Documentation on CI triggers to Documentation on CI triggers

Status changed to merged

mentioned in commit ed777c7b