Triggering pipelines through the API · Gitlab 中文文檔

# Triggering pipelines through the API > 原文：[https://docs.gitlab.com/ee/ci/triggers/README.html](https://docs.gitlab.com/ee/ci/triggers/README.html) * [Authentication tokens](#authentication-tokens) * [Trigger token](#trigger-token) * [CI job token](#ci-job-token) * [When used with multi-project pipelines](#when-used-with-multi-project-pipelines) * [When a pipeline depends on the artifacts of another pipeline](#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline-premium) * [Adding a new trigger](#adding-a-new-trigger) * [Revoking a trigger](#revoking-a-trigger) * [Triggering a pipeline](#triggering-a-pipeline) * [Triggering a pipeline from a webhook](#triggering-a-pipeline-from-a-webhook) * [Making use of trigger variables](#making-use-of-trigger-variables) * [Using cron to trigger nightly pipelines](#using-cron-to-trigger-nightly-pipelines) * [Legacy triggers](#legacy-triggers) # Triggering pipelines through the API[](#triggering-pipelines-through-the-api "Permalink") 版本歷史 **注意事項** ： * 在 GitLab 7.14 中[引入](https://about.gitlab.com/releases/2015/08/22/gitlab-7-14-released/) . * GitLab 8.12 具有完全重新設計的工作權限系統. 閱讀有關[新模型及其含義的](../../user/project/new_ci_build_permissions_model.html#pipeline-triggers)所有信息. 觸發器可用于通過 API 調用強制重新運行特定`ref` （分支或標簽）的管道. ## Authentication tokens[](#authentication-tokens "Permalink") 支持以下身份驗證方法： * [Trigger token](#trigger-token) * [CI job token](#ci-job-token) 如果使用`$CI_PIPELINE_SOURCE` [預定義環境變量](../variables/predefined_variables.html)來限制在管道中運行的作業，則值可以是`pipeline`或`trigger` ，具體取決于所使用的觸發器方法. | `$CI_PIPELINE_SOURCE` value | 觸發方式 | | --- | --- | | `pipeline` | 使用 CI / CD 配置文件中的`trigger:`關鍵字，或將觸發器 API 與`$CI_JOB_TOKEN` . | | `trigger` | 使用生成的觸發令牌使用觸發 API | 當使用`pipelines`或使用[`only/except`](../yaml/README.html#onlyexcept-basic)傳統[`only/except`基本語法`only/except`](../yaml/README.html#onlyexcept-basic) `triggers`關鍵字時，這也適用. ### Trigger token[](#trigger-token "Permalink") A unique trigger token can be obtained when [adding a new trigger](#adding-a-new-trigger). **危險：**在公共項目中傳遞純文本令牌是一個安全問題. 潛在的攻擊者可以在`.gitlab-ci.yml`文件中假冒公開暴露其觸發令牌的用戶. 使用[變量](../variables/README.html#gitlab-cicd-environment-variables)來保護觸發令牌. ### CI job token[](#ci-job-token "Permalink") You can use the `CI_JOB_TOKEN` [variable](../variables/README.html#predefined-environment-variables) (used to authenticate with the [GitLab Container Registry](../../user/packages/container_registry/index.html)) in the following cases. #### When used with multi-project pipelines[](#when-used-with-multi-project-pipelines "Permalink") 版本歷史 * 在[GitLab Premium](https://about.gitlab.com/pricing/) 9.3 中[引入](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2017)了`CI_JOB_TOKEN`在多項目管道中的使用. * 在 GitLab 12.4 的所有層中都[可以](https://gitlab.com/gitlab-org/gitlab/-/issues/31573)將`CI_JOB_TOKEN`用于多項目管道. 這種觸發方式只能在`.gitlab-ci.yml`內部調用時使用，并且會在[管道圖](../multi_project_pipelines.html#overview)上創建可見的依賴管道關系. 例如： ``` build_docs: stage: deploy script: - curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/pipeline only: - tags ``` 以這種方式觸發的管道還公開了一個特殊變量： `CI_PIPELINE_SOURCE=pipeline` . 閱讀有關[管道觸發器 API 的](../../api/pipeline_triggers.html)更多信息. #### When a pipeline depends on the artifacts of another pipeline[](#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline-premium "Permalink") 在[GitLab Premium](https://about.gitlab.com/pricing/) 9.5 中[引入了](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2346)在工件下載 API 中使用`CI_JOB_TOKEN` . 隨著不同項目之間的依賴關系的引入，其中一個項目可能需要訪問由前一個項目創建的工件. 必須為授權訪問授予此過程，并且可以使用標識特定作業的`CI_JOB_TOKEN`變量完成此過程. 例如： ``` build_submodule: image: debian stage: test script: - apt update && apt install -y unzip - curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test&job_token=$CI_JOB_TOKEN" - unzip artifacts.zip only: - tags ``` 這使您可以將其用于多項目管道，并從您有權訪問的任何項目下載工件，因為這遵循與[權限模型](../../user/permissions.html#job-permissions)相同的原則. 了解有關[Jobs API 的](../../api/jobs.html#download-the-artifacts-archive)更多信息. ## Adding a new trigger[](#adding-a-new-trigger "Permalink") 您可以通過在"觸發器"下轉到項目的**"設置"?CI / CD**來添加新**觸發器** . **添加觸發器**按鈕將創建一個新令牌，然后您可以使用該令牌來觸發此特定項目管道的重新運行. 您創建的每個新觸發器都會被分配一個不同的令牌，然后您可以在腳本或`.gitlab-ci.yml`使用該令牌. 您還可以很好地了解上一次使用觸發器的時間. [![Triggers page overview](https://img.kancloud.cn/37/23/372364d2ca3e91efdc19e99081b7477a_1000x411.png)](img/triggers_page.png) ## Revoking a trigger[](#revoking-a-trigger "Permalink") 您可以隨時通過單擊" **觸發器"**下項目的**"設置"?CI / CD**并單擊" **撤消"**按鈕來**撤消** **觸發器** . 動作是不可逆的. ## Triggering a pipeline[](#triggering-a-pipeline "Permalink") > **Notes**: > > * 有效的引用只是分支和標簽. 如果通過提交 SHA 作為參考，它將不會觸發作業. 要觸發作業，您需要向 gitLab 的 API 端點發送`POST`請求： ``` POST /projects/:id/trigger/pipeline ``` 必需的參數是[觸發器的`token`](#authentication-tokens)和將在其上執行觸發器的 Git `ref` . 有效的引用是分支和標簽. 可以通過[查詢 API](../../api/projects.html)或訪問**CI / CD**設置頁面（提供不言自明的示例）來找到項目的`:id` . 觸發管道的重新運行時，該信息會在 GitLab 的 UI 中顯示在**Jobs**頁面下，并且作業被標記為"由 API 觸發". [![Marked rebuilds as on jobs page](https://img.kancloud.cn/57/30/5730d73739ecba560ef28709c074782d_1279x381.png)](img/builds_page.png) * * * 您可以通過訪問單個作業頁面查看是哪個觸發器導致了重建. 從下圖中可以看到，觸發器的令牌的一部分顯示在 UI 中. [![Marked rebuilds as triggered on a single job page](https://img.kancloud.cn/6a/08/6a08e4e3e98d610883a6c3a44be19a9a_287x336.png)](img/trigger_single_build.png) * * * 通過使用 cURL，您可以以最小的努力觸發管道重新運行，例如： ``` curl --request POST \ --form token=TOKEN \ --form ref=master \ https://gitlab.example.com/api/v4/projects/9/trigger/pipeline ``` 在這種情況下，ID `9`的項目將在`master`分支上重建. 或者，您可以在查詢字符串中傳遞`token`和`ref`參數： ``` curl --request POST \ "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline?token=TOKEN&ref=master" ``` 您還可以在`.gitlab-ci.yml`使用觸發器來`.gitlab-ci.yml` . 假設您有兩個項目 A 和 B，并且每當在項目 A 上創建標簽時，您都希望在項目 B 的`master`分支上觸發重建. 這是您需要在項目 A 的`.gitlab-ci.yml`添加的工作： ``` build_docs: stage: deploy script: - "curl --request POST --form token=TOKEN --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" only: - tags ``` 這意味著每當在項目 A 上添加新標簽時，該作業就會運行，并且`build_docs`作業將被執行，從而觸發項目 B 的重建`build_docs` `stage: deploy`確保該作業僅在所有帶有`stage: test`作業之后運行成功完成. ## Triggering a pipeline from a webhook[](#triggering-a-pipeline-from-a-webhook "Permalink") 版本歷史 **注意事項** ： * 在 GitLab 8.14 中引入. * `ref`應該作為 URL 的一部分傳遞，以便優先于來自 Webhook 主體的`ref` ，該 Webhook 主體指定了觸發源存儲庫中的觸發器的分支 ref. * `ref`包含斜杠，則應進行 URL 編碼. 要從另一個項目的 Webhook 觸發作業，您需要為 Push 和 Tag 事件添加以下 Webhook URL（更改項目 ID，ref 和 token）： ``` https://gitlab.example.com/api/v4/projects/9/ref/master/trigger/pipeline?token=TOKEN ``` ## Making use of trigger variables[](#making-use-of-trigger-variables "Permalink") 您可以在觸發器 API 調用中傳遞任意數量的任意變量，這些變量將在 GitLab CI / CD 中可用，以便可以在您的`.gitlab-ci.yml`文件中使用. 參數的形式為： ``` variables[key]=value ``` 此信息也顯示在 UI 中. 請注意，只有所有者和維護者才能看到這些*值* . [![Job variables in UI](https://img.kancloud.cn/d5/81/d581d9662dfb20ec0b1a8014f1ec61e2_432x286.png)](img/trigger_variables.png) 出于多種原因，使用觸發器變量可能被證明是有用的： * 可識別的工作. 由于該變量在 UI 中公開，因此您可以通過傳遞解釋目的的變量來知道為什么觸發了重建. * 有條件的作業處理. 您可以讓有條件的作業在存在某個變量時運行. 考慮以下`.gitlab-ci.yml` ，我們在其中設置了三個[階段](../yaml/README.html#stages) ，僅當測試和構建階段中的所有作業都通過時， `upload_package`作業才運行. 當`UPLOAD_TO_S3`變量不為零時，運行`make upload` . ``` stages: - test - build - package run_tests: stage: test script: - make test build_package: stage: build script: - make build upload_package: stage: package script: - if [ -n "${UPLOAD_TO_S3}" ]; then make upload; fi ``` 然后，您可以在傳遞`UPLOAD_TO_S3`變量時觸發重建，并且`upload_package`作業的腳本將運行： ``` curl --request POST \ --form token=TOKEN \ --form ref=master \ --form "variables[UPLOAD_TO_S3]=true" \ https://gitlab.example.com/api/v4/projects/9/trigger/pipeline ``` 觸發變量在所有類型的變量中具有[最高優先級](../variables/README.html#priority-of-environment-variables) . ## Using cron to trigger nightly pipelines[](#using-cron-to-trigger-nightly-pipelines "Permalink") > **注意：**以下行為也可以通過 GitLab 的 UI 與[管道計劃一起實現](../pipelines/schedules.html) . 無論您編寫腳本還是直接運行 cURL，都可以與 cron 一起觸發作業. 以下示例每晚`00:30`在 ID 為`9`的項目的`master`分支上觸發一個作業： ``` 30 0 * * * curl --request POST --form token=TOKEN --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/pipeline ``` ## Legacy triggers[](#legacy-triggers "Permalink") 在 GitLab 9.0 之前創建的舊觸發器將被標記為舊觸發器. 具有舊標簽的觸發器沒有關聯的用戶，只能訪問當前項目. 它們被認為已棄用，并將在將來的 GitLab 版本中刪除.