├── .gitignore ├── .nojekyll ├── CHANGELOG.md ├── LICENSE ├── README.md ├── _images ├── agent_add_click.png ├── agent_copy_token.png ├── agent_save_new.png ├── agents │ ├── create_agent.gif │ ├── create_host.gif │ ├── k8s_host_create.gif │ ├── k8s_host_structure.png │ ├── ssh_host_structure.png │ └── test_host.gif ├── architecture.png ├── config │ ├── create_smtp.gif │ ├── create_text.gif │ ├── gmail_setting_1.png │ └── gmail_setting_2.png ├── config_server_url.png ├── create_flow.gif ├── create_flow_and_build.gif ├── demo.gif ├── flow.ci.png ├── flow │ ├── sample.png │ └── structure.png ├── git │ ├── add_token.png │ ├── create_ssh-rsa_credential.png │ ├── gerrit_add_link.png │ ├── gerrit_commit_status.png │ ├── gerrit_create_access_pw.png │ ├── gerrit_setup_ssh_key.png │ ├── gerrit_test_config.gif │ ├── gerrit_webhook_plugin.png │ ├── git_settings.png │ ├── gitee_setup_deploy_key.png │ ├── gitee_setup_webhook.png │ ├── gitee_test_config.gif │ ├── github_add_link.png │ ├── github_check_updated.png │ ├── github_create_access_token.png │ ├── github_select_events.png │ ├── github_setup_deploy_key.png │ ├── github_setup_payload_and_content.png │ ├── github_test_config.gif │ ├── gitlab_add_link.png │ ├── gitlab_create_access_token.png │ ├── gitlab_setup_deploy_key.png │ ├── gitlab_setup_webhook.png │ ├── gitlab_stage_updated.png │ ├── gitlab_test_config.gif │ ├── gogs_setup_deploy_key.png │ ├── gogs_setup_webhook.png │ ├── gogs_test_config.gif │ ├── select_webhook_url.gif │ └── structure.png ├── job │ ├── cache_demo.png │ ├── cache_run_example.png │ ├── cron_job.gif │ ├── multiple_docker.png │ ├── parallel.png │ └── terminal.gif ├── logo.png ├── plugins.png ├── secret │ ├── android_signed.png │ ├── auth_create.png │ ├── create_android_sign.gif │ ├── create_auth_pair.gif │ ├── create_kubeconfig.gif │ ├── create_ssh_key.gif │ └── create_token.gif ├── start_agent.gif ├── start_job.gif ├── start_server.gif ├── statistic.gif ├── trigger │ ├── create_job_finish_email.gif │ ├── create_job_finish_webhook.gif │ ├── email_sample.png │ └── send_job_finish_webhook.gif └── trigger_from_github.gif ├── cf_docker.md ├── cf_linux.md ├── cf_osx.md ├── cn ├── README.md ├── _sidebar.md ├── agents │ ├── index.md │ ├── k8s_host.md │ ├── manual.md │ ├── ssh_host.md │ └── vars.md ├── config │ ├── freetext.md │ └── smtp.md ├── flow │ └── structure.md ├── git │ ├── gerrit.md │ ├── gitee.md │ ├── github.md │ ├── gitlab.md │ ├── gogs.md │ └── index.md ├── job │ ├── cache.md │ ├── condition.md │ ├── docker.md │ ├── parallel.md │ ├── schedule.md │ ├── start.md │ ├── web_terminal.md │ └── workspace.md ├── secret │ ├── android_sign.md │ ├── auth.md │ ├── kubeconfig.md │ ├── ssh-rsa.md │ └── token.md ├── start │ └── index.md ├── trigger │ └── on_job_finish.md ├── upgrade │ └── index.md └── yml │ ├── plugins.md │ └── reference_v1.md ├── en ├── README.md ├── _sidebar.md ├── agents │ ├── index.md │ ├── k8s_host.md │ ├── manual.md │ ├── ssh_host.md │ └── vars.md ├── config │ ├── freetext.md │ └── smtp.md ├── flow │ └── structure.md ├── git │ ├── gerrit.md │ ├── gitee.md │ ├── github.md │ ├── gitlab.md │ ├── gogs.md │ └── index.md ├── job │ ├── cache.md │ ├── condition.md │ ├── docker.md │ ├── parallel.md │ ├── schedule.md │ ├── start.md │ ├── web_terminal.md │ └── workspace.md ├── secret │ ├── android_sign.md │ ├── auth.md │ ├── kubeconfig.md │ ├── ssh-rsa.md │ └── token.md ├── start │ └── index.md ├── trigger │ └── on_job_finish.md ├── upgrade │ └── index.md ├── user │ └── .placeholder └── yml │ ├── plugins.md │ └── reference_v1.md ├── index.html └── intro_base.md /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules/ 2 | .DS_Store 3 | -------------------------------------------------------------------------------- /.nojekyll: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/.nojekyll -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | - v1.21.50 2021-12-16 2 | * 新增触发器，可配置出发 webhook 及 邮件 3 | * 支持显示同一个 Git 事件的相关任务 4 | * 优化了模版选择界面 5 | * 修复了 Log4j2 安全问题 6 | * 升级 flow-core-x 服务到 Java 11 7 | * Bugfix 8 | 9 | - v1.21.50 2021-12-16 10 | * Introduced trigger system 11 | * Enable to list related jobs from the same git event 12 | * Improved template selection UI 13 | * Fix Log4j2 vulnerability issue 14 | * Upgrade flow-core-x to Java 11 15 | * Bugfix 16 | 17 | - v1.21.40 2021-10-05 18 | * 系统设置中可现实插件信息和同步状态 19 | * flow.ci python 包的问题修复 20 | * Bugfix 21 | 22 | - v1.21.40 2021-10-05 23 | * Enable to show plugin and sync status from settings 24 | * Bugfix on flow.ci python lib 25 | * Bugfix on Agent 26 | 27 | - v1.21.33 2021-08-18 28 | * 提升产品稳定性 29 | * Job 页面优化 30 | * 支持从变量中获取 Config 内容 31 | * Bugfix 32 | 33 | - v1.21.33 2021-08-18 34 | * Stability improvement 35 | * Job page improvement 36 | * Enable to load config content from the environment variable 37 | * Bugfix 38 | 39 | - v0.21.21 2021-05-06 40 | * 新增 post step，在任务结束、失败或取消时执行 41 | * 可从失败的 step 从新开始任务 42 | * 支持从变量中获取 Secret 43 | * 改进 Agent 及任务的用户界面 44 | * BUG 修复 45 | 46 | - v0.21.21 2021-05-06 47 | * Support post step that will be executed anyway 48 | * Enable to restart the job from failure step 49 | * Enable to get secret from the environment variable 50 | * UI improvement 51 | * Bugfix 52 | 53 | - v0.21.05 2021-02-10 54 | * 支持并行任务 55 | * 支持任务缓存 56 | * 手动构建支持参数设置 57 | * 改进用户界面 58 | * BUG 修复 59 | 60 | - v0.21.05 2021-02-10 61 | * Support parallel build 62 | * Support step level cache 63 | * Enable to modify parameters on manual build 64 | * UI improvement 65 | * Bugfix 66 | 67 | 68 | - v0.20.45 2020-10-29 69 | * Agent 支持 Windows 环境 70 | * 支持 `bash` `pwsh`， 在任务中可自定义 Bash 或 PowerShell 71 | * 支持 `retry`, 可设置任务重试次数 72 | * 支持 `timeout`, 可以设置任务过期时间 73 | * 支持工作流级别的 condition，可以通过 Groovy 脚本自定义工作流启动规则 74 | * 新增 .Net Core 项目模板 75 | * BUG 修复 76 | 77 | - v0.20.45 2020-10-29 78 | * Support Agent in Windows 79 | * Introduce `bash` `pwsh` in step level to define Bash and/or Powershell script 80 | * Introduce `retry` to defined retry times 81 | * Introduce `timeout` to defined timeout in seconds 82 | * Introduce `condition` in flow level to customize flow start condition with Groovy script 83 | * New template for .Net Core project 84 | * Bugfix 85 | 86 | - v0.20.40 2020-10-01 87 | * 支持 k8s 中运行, 并动态扩展 Agent 88 | * PHP 构建模板 89 | * 支持定义子任务(sub-steps) 90 | * 新增管理员功能 - 系统配置 91 | * BUG 修复 92 | 93 | - v0.20.40 2020-10-01 94 | * Support dynamic agents in a Kubernetes cluster. 95 | * PHP template 96 | * Support sub-steps in a step 97 | * New system configuration in the admin panel 98 | * Bugfix 99 | 100 | - v0.20.32 2020-08-03 101 | * Web 用户界面优化 102 | * 可编辑 SSH 主机的端口 103 | * Web页面设置默认用户 104 | * 支持 `condition` YAML，可使用 Groovy 脚本来定义 Step 是否运行 105 | 106 | - v0.20.32 2020-08-03 107 | * Improvement of UI 108 | * Enable to edit the port number on SSH host 109 | * Default user can be created from web 110 | * Support condition in the YAML to setup step start condition in Groovy 111 | 112 | - v0.20.30 2020-07-27 113 | * Web 用户界面优化 114 | * 提升 Agent 的稳定性 115 | * 支持 flow 定时任务 116 | * 多容器的支持 117 | * 支持工作流级别的 `docker/dockers` YAML 118 | * 支持 `android` 秘钥类型，可以配置安卓签名 119 | * 新增安卓构建模板 120 | 121 | - v0.20.30 2020-07-27 122 | * Improvement of UI 123 | * Improvement of Agent stability 124 | * Support crontab task for flow 125 | * Support multiple docker containers 126 | * Introduce `docker/dockers` YAML section on flow level 127 | * Introduce `android` secret type to config android certificate 128 | * New android flow template 129 | 130 | - v0.20.26 2020-06-20 131 | * 支持在运行中的 Step 使用 Terminal 调试 132 | * 新增 'notification' YAML 配置通知插件 133 | * 新增 'token' 类型的 Secret 134 | * 可以在 Flow 设置页面配置 Job 过期时间 135 | * 支持显示 SSH RSA 公钥的 MD5 指纹 136 | * 新增 Sonarqube 插件 137 | * BUG 修复 138 | 139 | - v0.20.26 2020-06-20 140 | * Support TTY on running step to debug 141 | * Introduce 'notification' YAML section to config flow notification task 142 | * Introduce 'token' secret type 143 | * Enable to config job timeout in flow settings 144 | * Support MD5 fingerprint on SSH RSA public key 145 | * New Sonarqube plugin 146 | * Important bugfix 147 | 148 | - v0.20.20 2020-05-14 149 | * 支持任务 '重新开始' 150 | * 新增 ‘配置’ 功能 151 | * 添加了 npm 模板 152 | * 重要 BUG 修复 153 | 154 | - v0.20.20 2020-05-14 155 | * Support 'rerun' for job 156 | * New configuration feature 157 | * Introduce an 'npm' build template 158 | * Important bugfix 159 | 160 | - v0.20.16 2020-04-12 161 | * 支持 Gitee webhook 162 | * 可以从 Git 仓库中定义 YAML 配置 (.flowci.yaml) 163 | * 可以运行在 Docker 容器中运行 Step 和插件 164 | * 实时日志性能改进 165 | * Bugfix 166 | 167 | - v0.20.16 2020-04-12 168 | * Support webhook for Gitee 169 | * Enable to load YAML configuration in Git repository (.flowci.yaml) 170 | * Enable to execute step and plugin in docker container 171 | * Impore performance on logging 172 | * Bugfix 173 | 174 | - v0.20.09 2020-02-13 175 | * Job 详情页面支持图形显示，优化了 Log 终端的格式 176 | * 支持 Agent 通过 docker socket 的方式弹性伸缩 177 | * 支持 Agent 通过 ssh host 的方式弹性伸缩 178 | 179 | - v0.20.09 2020-02-13 180 | * Optimize job detail page with step graphic view and log terminal layout 181 | * Support agent auto scaling via docker socket 182 | * Support agent auto scaling via ssh remote host 183 | 184 | - v0.19.42 2019-12-06 185 | * 支持工作流统计 186 | * 支持 GitLab & Gogs webhook 187 | * 支持 HTML 报告页面 (Jacoco, Junit) 188 | * 支持 Agent 资源 (CPU, Memory) 显示 189 | * 优化 Job 页面 190 | * Bug fix 191 | 192 | - v0.19.42 2019-12-06 193 | * Support flow job statistic view 194 | * Support GitLab & Gogs webhook 195 | * Enable to show HTML report from plugin (Jacoco, Junit) 196 | * Enable to show Agent resource detail (CPU, Memory) 197 | * Optimize job detail page 198 | * Bug fix 199 | 200 | - v0.1.4-alpha 2017-12-29 201 | * 支持 Web 定义工作流 202 | * 支持插件系统，以及插件-Agent同步 203 | * 支持 ‘final’ 节点，该节点为必执行节点 204 | * 支持 flow.ci 的 Windows 安装 205 | * 支持 Agent 通过 Cygwin 在 Windows 环境运行 206 | * bug fix 207 | 208 | - v0.1.3-alpha 2017-12-08 209 | * 创建项目支持 oschina 仓库 210 | * yaml 工作流支持设置 condition，基于 Groovy 语法 211 | * bug fixed...https://github.com/orgs/FlowCI/projects/1（参见Done） 212 | 213 | - v0.1.2-alpha 2017-12-01 214 | * yml 工作流支持设置工作目录 215 | * yml 编辑器更新为 Monaco Editor 216 | * 轻松发布到 fir.im（基于 Docker） 217 | * 修复 bitbucket 无法正常克隆代码问题 218 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "{}" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright {yyyy} {name of copyright owner} 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # flow.ci document 2 | 3 | The document repository for https://flowci.github.io 4 | 5 | - [English](https://flowci.github.io/#/en/) 6 | - [中文文档](https://flowci.github.io/#/cn/) 7 | 8 | -------------------------------------------------------------------------------- /_images/agent_add_click.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/agent_add_click.png -------------------------------------------------------------------------------- /_images/agent_copy_token.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/agent_copy_token.png -------------------------------------------------------------------------------- /_images/agent_save_new.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/agent_save_new.png -------------------------------------------------------------------------------- /_images/agents/create_agent.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/agents/create_agent.gif -------------------------------------------------------------------------------- /_images/agents/create_host.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/agents/create_host.gif -------------------------------------------------------------------------------- /_images/agents/k8s_host_create.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/agents/k8s_host_create.gif -------------------------------------------------------------------------------- /_images/agents/k8s_host_structure.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/agents/k8s_host_structure.png -------------------------------------------------------------------------------- /_images/agents/ssh_host_structure.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/agents/ssh_host_structure.png -------------------------------------------------------------------------------- /_images/agents/test_host.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/agents/test_host.gif -------------------------------------------------------------------------------- /_images/architecture.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/architecture.png -------------------------------------------------------------------------------- /_images/config/create_smtp.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/config/create_smtp.gif -------------------------------------------------------------------------------- /_images/config/create_text.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/config/create_text.gif -------------------------------------------------------------------------------- /_images/config/gmail_setting_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/config/gmail_setting_1.png -------------------------------------------------------------------------------- /_images/config/gmail_setting_2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/config/gmail_setting_2.png -------------------------------------------------------------------------------- /_images/config_server_url.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/config_server_url.png -------------------------------------------------------------------------------- /_images/create_flow.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/create_flow.gif -------------------------------------------------------------------------------- /_images/create_flow_and_build.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/create_flow_and_build.gif -------------------------------------------------------------------------------- /_images/demo.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/demo.gif -------------------------------------------------------------------------------- /_images/flow.ci.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/flow.ci.png -------------------------------------------------------------------------------- /_images/flow/sample.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/flow/sample.png -------------------------------------------------------------------------------- /_images/flow/structure.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/flow/structure.png -------------------------------------------------------------------------------- /_images/git/add_token.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/add_token.png -------------------------------------------------------------------------------- /_images/git/create_ssh-rsa_credential.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/create_ssh-rsa_credential.png -------------------------------------------------------------------------------- /_images/git/gerrit_add_link.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/gerrit_add_link.png -------------------------------------------------------------------------------- /_images/git/gerrit_commit_status.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/gerrit_commit_status.png -------------------------------------------------------------------------------- /_images/git/gerrit_create_access_pw.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/gerrit_create_access_pw.png -------------------------------------------------------------------------------- /_images/git/gerrit_setup_ssh_key.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/gerrit_setup_ssh_key.png -------------------------------------------------------------------------------- /_images/git/gerrit_test_config.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/gerrit_test_config.gif -------------------------------------------------------------------------------- /_images/git/gerrit_webhook_plugin.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/gerrit_webhook_plugin.png -------------------------------------------------------------------------------- /_images/git/git_settings.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/git_settings.png -------------------------------------------------------------------------------- /_images/git/gitee_setup_deploy_key.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/gitee_setup_deploy_key.png -------------------------------------------------------------------------------- /_images/git/gitee_setup_webhook.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/gitee_setup_webhook.png -------------------------------------------------------------------------------- /_images/git/gitee_test_config.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/gitee_test_config.gif -------------------------------------------------------------------------------- /_images/git/github_add_link.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/github_add_link.png -------------------------------------------------------------------------------- /_images/git/github_check_updated.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/github_check_updated.png -------------------------------------------------------------------------------- /_images/git/github_create_access_token.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/github_create_access_token.png -------------------------------------------------------------------------------- /_images/git/github_select_events.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/github_select_events.png -------------------------------------------------------------------------------- /_images/git/github_setup_deploy_key.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/github_setup_deploy_key.png -------------------------------------------------------------------------------- /_images/git/github_setup_payload_and_content.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/github_setup_payload_and_content.png -------------------------------------------------------------------------------- /_images/git/github_test_config.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/github_test_config.gif -------------------------------------------------------------------------------- /_images/git/gitlab_add_link.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/gitlab_add_link.png -------------------------------------------------------------------------------- /_images/git/gitlab_create_access_token.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/gitlab_create_access_token.png -------------------------------------------------------------------------------- /_images/git/gitlab_setup_deploy_key.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/gitlab_setup_deploy_key.png -------------------------------------------------------------------------------- /_images/git/gitlab_setup_webhook.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/gitlab_setup_webhook.png -------------------------------------------------------------------------------- /_images/git/gitlab_stage_updated.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/gitlab_stage_updated.png -------------------------------------------------------------------------------- /_images/git/gitlab_test_config.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/gitlab_test_config.gif -------------------------------------------------------------------------------- /_images/git/gogs_setup_deploy_key.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/gogs_setup_deploy_key.png -------------------------------------------------------------------------------- /_images/git/gogs_setup_webhook.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/gogs_setup_webhook.png -------------------------------------------------------------------------------- /_images/git/gogs_test_config.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/gogs_test_config.gif -------------------------------------------------------------------------------- /_images/git/select_webhook_url.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/select_webhook_url.gif -------------------------------------------------------------------------------- /_images/git/structure.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/git/structure.png -------------------------------------------------------------------------------- /_images/job/cache_demo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/job/cache_demo.png -------------------------------------------------------------------------------- /_images/job/cache_run_example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/job/cache_run_example.png -------------------------------------------------------------------------------- /_images/job/cron_job.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/job/cron_job.gif -------------------------------------------------------------------------------- /_images/job/multiple_docker.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/job/multiple_docker.png -------------------------------------------------------------------------------- /_images/job/parallel.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/job/parallel.png -------------------------------------------------------------------------------- /_images/job/terminal.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/job/terminal.gif -------------------------------------------------------------------------------- /_images/logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/logo.png -------------------------------------------------------------------------------- /_images/plugins.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/plugins.png -------------------------------------------------------------------------------- /_images/secret/android_signed.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/secret/android_signed.png -------------------------------------------------------------------------------- /_images/secret/auth_create.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/secret/auth_create.png -------------------------------------------------------------------------------- /_images/secret/create_android_sign.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/secret/create_android_sign.gif -------------------------------------------------------------------------------- /_images/secret/create_auth_pair.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/secret/create_auth_pair.gif -------------------------------------------------------------------------------- /_images/secret/create_kubeconfig.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/secret/create_kubeconfig.gif -------------------------------------------------------------------------------- /_images/secret/create_ssh_key.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/secret/create_ssh_key.gif -------------------------------------------------------------------------------- /_images/secret/create_token.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/secret/create_token.gif -------------------------------------------------------------------------------- /_images/start_agent.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/start_agent.gif -------------------------------------------------------------------------------- /_images/start_job.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/start_job.gif -------------------------------------------------------------------------------- /_images/start_server.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/start_server.gif -------------------------------------------------------------------------------- /_images/statistic.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/statistic.gif -------------------------------------------------------------------------------- /_images/trigger/create_job_finish_email.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/trigger/create_job_finish_email.gif -------------------------------------------------------------------------------- /_images/trigger/create_job_finish_webhook.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/trigger/create_job_finish_webhook.gif -------------------------------------------------------------------------------- /_images/trigger/email_sample.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/trigger/email_sample.png -------------------------------------------------------------------------------- /_images/trigger/send_job_finish_webhook.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/trigger/send_job_finish_webhook.gif -------------------------------------------------------------------------------- /_images/trigger_from_github.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/_images/trigger_from_github.gif -------------------------------------------------------------------------------- /cf_docker.md: -------------------------------------------------------------------------------- 1 | 更多信息，请访问 [flow.ci](https://flowci.github.io) -------------------------------------------------------------------------------- /cf_linux.md: -------------------------------------------------------------------------------- 1 | 更多信息，请访问 [flow.ci](https://flowci.github.io) -------------------------------------------------------------------------------- /cf_osx.md: -------------------------------------------------------------------------------- 1 | 更多信息，请访问 [flow.ci](https://flowci.github.io) -------------------------------------------------------------------------------- /cn/README.md: -------------------------------------------------------------------------------- 1 |

2 | 3 | Logo 4 | 5 |

6 | 7 |

A Simple & Powerful CI/CD Server

8 | 9 |

10 | 11 | 12 | GitHub Org's stars 13 | Docker Pulls 14 |

15 | 16 |
17 | 18 | **[English](en/README.md) | 简体中文** 19 | 20 |
21 | 22 | ## 什么是 flow.ci 23 | 24 | flow.ci 是一款开源的持续集成服务，与其他的持续集成服务相比，能够开箱即用，简化了繁琐的配置，并增加了用户体验。 25 | 26 | - __高可用__ 27 | 28 | flow.ci 采用前后端分离架构，可工作在任何环境中，支持多个前后端事例部署，保证在节点宕机情况下任务不会丢失。 29 | 30 | - __构建速度__ 31 | 32 | - __自动伸缩__: 在 k8s 或者 linux 中运行的 Agent 可以根据需要自动伸缩 33 | - __并行任务__: 任务中的每个步骤都可以在不同的 Agent 上并行执行，可极大的提高构建速度 34 | - __缓存__: 支持任务缓存，省去下载时间 35 | 36 | - __开箱即用__ 37 | 38 | 只需一行命令即可安装 flow.ci 服务，可根据提供的模版创建工作流，修改仓库后即可开始任务。 39 | 40 | - __在线调试__ 41 | 42 | flow.ci 可以在任务运行时在线进入终端，进行调试 43 | 44 | - __灵活的插件__ 45 | 46 | flow.ci 的插件可以用任意语言编写。使用插件也非常简单，只需要在 `YAML` 中配置插件名称即可 47 | 48 | - __灵活的环境支持__ 49 | 50 | 任务中的每个步骤都可以指定 docker 镜像，在任意的环境中执行 51 | 52 | ## 快速开始 53 | 54 | > 需要安装 [Docker](https://docs.docker.com/install/) & [Docker-Compose](https://docs.docker.com/compose/install/) 55 | 56 | ```bash 57 | git clone https://github.com/FlowCI/docker.git flow-docker 58 | cd flow-docker 59 | ./server.sh start 60 | ``` 61 | 62 | ## 帮助 63 | 64 | 如果需要帮助? 从[这里](https://github.com/FlowCI/docs/issues) 提交问题 或发送邮件至 `flowci@foxmail.com` 65 | 66 | 67 | ## 构建模板 68 | 69 | [maven, npm, golang, ruby, android 和更多...](https://github.com/FlowCI/templates) 70 | 71 | 72 | ## 基本架构 73 | 74 | ![architecture](https://github.com/FlowCI/docs/raw/master/_images/architecture.png) 75 | 76 | ## 预览 77 | 78 | ![demo](https://github.com/FlowCI/docs/raw/master/_images/demo.gif) 79 | -------------------------------------------------------------------------------- /cn/_sidebar.md: -------------------------------------------------------------------------------- 1 | 2 | * 快速开始 3 | * [安装](cn/start/index.md#安装) 4 | * [配置 URL](cn/start/index.md#配置服务器URL) 5 | * [创建工作流](cn/start/index.md#创建工作流) 6 | * [开始任务](cn/start/index.md#开始任务) 7 | 8 | * 工作流 (flow) 9 | * [结构](cn/flow/structure.md) 10 | 11 | * 任务 (job) 12 | * [开始](cn/job/start.md) 13 | * [工作区](cn/job/workspace.md) 14 | * [运行条件](cn/job/condition.md) 15 | * [通过 Docker 配置运行环境](cn/job/docker.md) 16 | * [并行执行](cn/job/parallel.md) 17 | * [缓存](cn/job/cache.md) 18 | * [定时任务](cn/job/schedule.md) 19 | * [网页终端](cn/job/web_terminal.md) 20 | 21 | * Git 集成 22 | * [配置 Git](cn/git/index.md) 23 | * [Github](cn/git/github.md) 24 | * [Gitlab](cn/git/gitlab.md) 25 | * [Gogs](cn/git/gogs.md) 26 | * [Gitee](cn/git/gitee.md) 27 | * [Gerrit](cn/git/gerrit.md) 28 | 29 | * Agent 30 | * [什么是 Agent](cn/agents/index.md) 31 | * [添加 Agent](cn/agents/manual.md) 32 | * 弹性伸缩 33 | * [Kubernates](cn/agents/k8s_host.md) 34 | * [SSH 主机](cn/agents/ssh_host.md) 35 | 36 | * 密钥 (Secret) 37 | * [SSH-RSA](cn/secret/ssh-rsa.md) 38 | * [用户名密码](cn/secret/auth.md) 39 | * [Token](cn/secret/token.md) 40 | * [安卓签名](cn/secret/android_sign.md) 41 | * [K8s kubeconfig](cn/secret/kubeconfig.md) 42 | 43 | 44 | * 通用配置 (Config) 45 | * [SMTP](cn/config/smtp.md) 46 | * [任意配置(text)](cn/config/freetext.md) 47 | 48 | * 触发器 (Trigger) 49 | * [任务结束事件](cn/trigger/on_job_finish.md) 50 | - [发送邮件](cn/trigger/on_job_finish.md#发送邮件) 51 | - [发送 HTTP 请求](cn/trigger/on_job_finish.md#发送-http-请求) 52 | 53 | * 插件 (Plugins) 54 | 55 | * 参考 56 | * [YAML](cn/yml/reference_v1.md) 57 | * [环境变量](cn/agents/vars.md) 58 | * [Upgrade](cn/upgrade/index.md) -------------------------------------------------------------------------------- /cn/agents/index.md: -------------------------------------------------------------------------------- 1 | # Agent 2 | 3 | Agent 是实际运行任务的地方。 4 | 5 | 它可以是一个 `可执行程序`、 `Docker` 6 | 7 | 自动伸缩的 Agent 可以配置在 Kubernates or SSH 主机中。 8 | 9 | * [手动配置 Agent](cn/agents/manual) 10 | 11 | * 弹性伸缩 Agent 12 | - [配置 k8s](cn/agents/k8s_host) 13 | - [配置 SSH 主机](cn/agents/ssh_host) -------------------------------------------------------------------------------- /cn/agents/k8s_host.md: -------------------------------------------------------------------------------- 1 | # 可伸缩 Agent: 配置 k8s 2 | 3 | 配置 k8s 集群后，flow.ci 会自动创建，并管理 Agent Pod 4 | 5 | ![ssh host structure](../../_images/agents/k8s_host_structure.png) 6 | 7 | ## 从管理员界面配置 k8s 8 | 9 | * 创建 `Settings` -> `Agents` -> `+` 10 | * 选择 `Dynamic agent` 11 | * 输入一个名称 12 | * 输入标签 (可选) 13 | 14 | Agent 标签用于 YAML `selector` 配置，可以让工作流运行在指定的 Agent 中。例如在 Agent 中配置了 `ios` 标签，并且在 YAML 中定义了如下的 `selector`， 则该工作流只会运行在带有 `ios` 标签的 Agent 中. 15 | 16 | ```yaml 17 | selector: 18 | label: 19 | - ios 20 | ``` 21 | 22 | * 填入集群信息 23 | * Namespace: k8s namespace 用于创建 Agent Pod 24 | 25 | * Secret: kube config 秘钥，用于访问和创建 Agent Pod. (如果没有此类型的密钥，请先创建，参考[如何创建 Kubeconfig 密钥](cn/secret/kubeconfig.md#k8s-kubeconfig-类型的密钥)) 26 | 27 | * Max Pool Size: 最大可运行 Agent 的数量 28 | 29 | * 点击 `Save` 30 | 31 | 创建的 k8s 主机将会显示在列表中 32 | 33 | ![how to create host](../../_images/agents/k8s_host_create.gif) -------------------------------------------------------------------------------- /cn/agents/manual.md: -------------------------------------------------------------------------------- 1 | # 手动配置 Agent 2 | 3 | 任务是运行在 Agent 上的，所以在任务开始之前，需要创建并启动至少一个 Agent。 4 | 5 | > 如果从 [docker-install](https://github.com/FlowCI/docker-install.git) 安装 flow.ci, 默认会配置一个自动 Agent 启动器，所以可以不用配置 Agent，直接运行任务即可 6 | 7 | ## 1. 从管理员页面创建 Agent 8 | 9 | * 点击 `Settings` -> `Agents` -> `+` 10 | * 选择 `Manual agent` 11 | * 输入一个名称 12 | * 定义标签 (可选) 13 | 14 | Agent 标签用于 YAML `selector` 配置，可以让工作流运行在指定的 Agent 中。例如在 Agent 中配置了 `ios` 标签，并且在 YAML 中定义了如下的 `selector`， 则该工作流只会运行在带有 `ios` 标签的 Agent 中. 15 | 16 | ```yaml 17 | selector: 18 | label: 19 | - ios 20 | ``` 21 | 22 | * 保存 `Save` 23 | 24 | 新创建的 Agent 会在列表中显示，可以从列表中拷贝 token 25 | 26 | ![how to create agent](../../_images/agents/create_agent.gif) 27 | 28 | ## 2. 启动 Agent 29 | 30 | 31 | #### 2.1 从 Docker 启动 32 | 33 | 最简单的方式为 Git 克隆 [docker-install](https://github.com/flowci/docker-install) 仓库，之后运行 `./agent.sh -t -u start`，填入 token 和 server url 即可。 34 | 35 | 或者可以使用以下 Bash 脚本，填入 `FLOWCI_SERVER_URL` 和 `FLOWCI_AGENT_TOKEN` 36 | 37 | ```bash 38 | docker run -it \ 39 | -e FLOWCI_SERVER_URL={ci_server_url} \ 40 | -e FLOWCI_AGENT_TOKEN={agent_token} \ 41 | -e FLOWCI_AGENT_VOLUMES="name=pyenv,dest=/ci/python,script=init.sh,image=flowci/pyenv,init=init-pyenv-volume.sh" \ 42 | -v /var/run/docker.sock:/var/run/docker.sock \ 43 | flowci/agent 44 | ``` 45 | 46 | #### 2.2 从 Binary 启动 47 | 48 | 您可以从 [这里](https://github.com/FlowCI/flow-agent-x/releases) 找到最新的 Agent 版本. 49 | 50 | 需要的环境 （如果要获得 flow.ci 所有功能): 51 | - Python >= 3.6 52 | - required pip libs: `pip install requests==2.22.0 python-lib-flow.ci` 53 | - Docker 54 | 55 | 56 | ##### Linux 57 | 58 | 替换 `{version}`, `{ci_server_url}`, `{agent_token}` 后运行以下 Bash 脚本 59 | 60 | ```bash 61 | wget https://github.com/FlowCI/flow-agent-x/releases/download/{version}/flow-agent-x-linux 62 | chmod +x flow-agent-x-linux 63 | ./flow-agent-x-linux -u {ci_server_url} -t {agent_token} -m name=pyenv,dest=/ci/python,script=init.sh,image=flowci/pyenv,init=init-pyenv-volume.sh 64 | ``` 65 | 66 | ##### MacOS (intel) 67 | 68 | 替换 `{version}`, `{ci_server_url}`, `{agent_token}` 后运行以下 Bash 脚本 69 | 70 | ```bash 71 | wget https://github.com/FlowCI/flow-agent-x/releases/download/{version}/flow-agent-x-mac 72 | chmod +x flow-agent-x-mac 73 | ./flow-agent-x-mac -u {ci_server_url} -t {agent_token} -m name=pyenv,dest=/ci/python,script=init.sh,image=flowci/pyenv,init=init-pyenv-volume.sh 74 | ``` 75 | 76 | ##### Windows (x64) 77 | 78 | 替换 `{version}`, `{ci_server_url}`, `{agent_token}` 后运行以下 PowerShell 脚本 79 | 80 | ```powershell 81 | Invoke-WebRequest https://github.com/FlowCI/flow-agent-x/releases/download/{version}/flow-agent-x-win -OutFile flow-agent-x-win.exe 82 | .\flow-agent-x-linux -u {ci_server_url} -t {agent_token} -m name=pyenv,dest=/ci/python,script=init.sh,image=flowci/pyenv,init=init-pyenv-volume.sh 83 | ``` 84 | -------------------------------------------------------------------------------- /cn/agents/ssh_host.md: -------------------------------------------------------------------------------- 1 | # 可伸缩 Agent: 配置 SSH 主机 2 | 3 | 配置 SSH 主机后，flow.ci 会自动通过 SSH 的方式创建并管理 Docker Agent。 4 | 5 | ![ssh host structure](../../_images/agents/ssh_host_structure.png) 6 | 7 | ## 1. 从管理员界面创建 SSH 主机 8 | 9 | * 创建 `Settings` -> `Agents` -> `+` 10 | * 选择 `Dynamic agent` 11 | * 输入一个名称 12 | * 输入标签 (可选) 13 | 14 | Agent 标签用于 YAML `selector` 配置，可以让工作流运行在指定的 Agent 中。例如在 Agent 中配置了 `ios` 标签，并且在 YAML 中定义了如下的 `selector`， 则该工作流只会运行在带有 `ios` 标签的 Agent 中. 15 | 16 | ```yaml 17 | selector: 18 | label: 19 | - ios 20 | ``` 21 | 22 | * 填入 SSH 信息 23 | * Secret: 选择一个 SSH key 类型的秘钥（如果没有此类型的密钥，请先创建，参考[如何创建 SSH-RSA 密钥](cn/secret/ssh-rsa.md#ssh-rsa-类型的秘钥)） 24 | 25 | * User: SSH 登录的用户名 26 | 27 | * IP: 主机的 IP 地址 28 | 29 | * Max Pool Size: 最大可运行 Docker Agent 的数量 30 | 31 | * 点击 `Save` 32 | 33 | 创建的 SSH 主机将会显示在列表中 34 | 35 | ![how to create host](../../_images/agents/create_host.gif) 36 | 37 | ## 2. 配置 SSH 主机的环境 38 | 39 | * 拷贝该公钥到 __目标主机__ 中的 `.ssh/authorzied_keys` 目录，已获得访问权限 40 | 41 | * 在主机中运行 [初始化脚本](https://github.com/FlowCI/docker-install/blob/master/host-init.sh)，配置 Docker Agent 的运行环境 42 | 43 | * 测试连接 44 | 45 | ![test host](../../_images/agents/test_host.gif) -------------------------------------------------------------------------------- /cn/agents/vars.md: -------------------------------------------------------------------------------- 1 | # 任务运行时可使用的环境变量 2 | 3 | ## 通用的 4 | 5 | - `FLOWCI_SERVER_URL` 6 | 7 | - `FLOWCI_FLOW_NAME` 8 | 9 | - `FLOWCI_FLOW_WEBHOOK` 10 | 11 | ## 任务 (Job) 相关 12 | 13 | - `FLOWCI_JOB_BUILD_NUM` 14 | 15 | - `FLOWCI_JOB_STATUS` 16 | 17 | - `FLOWCI_JOB_TRIGGER` 18 | 19 | - `FLOWCI_JOB_URL` 20 | 21 | - `FLOWCI_JOB_START_AT` 22 | 23 | - `FLOWCI_JOB_FINISH_AT` 24 | 25 | - `FLOWCI_JOB_DURATION` 26 | 27 | ## Agent 相关 28 | 29 | - `FLOWCI_AGENT_TOKEN` 30 | 31 | - `FLOWCI_AGENT_PORT` 32 | 33 | - `FLOWCI_AGENT_WORKSPACE` 34 | 35 | - `FLOWCI_AGENT_JOB_DIR` 36 | 37 | - `FLOWCI_AGENT_PLUGIN_DIR` 38 | 39 | - `FLOWCI_AGENT_IP_{interface name}`: interface name for example: en0, en1 40 | 41 | ## Docker 容器相关 (当 step 中定义了 docker 内容时有效) 42 | 43 | - `FLOWCI_AGENT_DOCKER_NETWORK`: 当前 Docker network 名称 44 | 45 | - `CONTAINER_ID_{container index}`: container index start from 0 46 | 47 | - `CONTAINER_IP_{container index}` 48 | 49 | ## Git 相关 50 | 51 | - `FLOWCI_GIT_REPO` 52 | 53 | - `FLOWCI_GIT_SOURCE`: `GITHUB` | `GITLAB` | `GOGS` | `GITEE` 54 | 55 | - `FLOWCI_GIT_EVENT`: `PUSH` | `TAG` | `PR_OPENED` | `PR_MERGED` 56 | 57 | #### Push / Tag 事件 58 | 59 | - `FLOWCI_GIT_BRANCH` 60 | 61 | - `FLOWCI_GIT_AUTHOR` 62 | 63 | - `FLOWCI_GIT_COMMIT_MESSAGE`: 最后一个 Commit 的描述 64 | 65 | - `FLOWCI_GIT_COMMIT_TOTAL`: 66 | 67 | - `FLOWCI_GIT_COMMIT_LIST`: commit 列表, base64格式. 例如: `base64([{id:xx, message: xxx, time:xxx, url: xxx, author: {name: xx, email: xx}}, {xxx}, ...])` 68 | 69 | #### Pull Request 事件 70 | 71 | - `FLOWCI_GIT_PR_TITLE` 72 | 73 | - `FLOWCI_GIT_PR_MESSAGE` 74 | 75 | - `FLOWCI_GIT_PR_URL` 76 | 77 | - `FLOWCI_GIT_PR_TIME` 78 | 79 | - `FLOWCI_GIT_PR_NUMBER` 80 | 81 | - `FLOWCI_GIT_PR_HEAD_REPO_NAME` 82 | 83 | - `FLOWCI_GIT_PR_HEAD_REPO_BRANCH` 84 | 85 | - `FLOWCI_GIT_PR_HEAD_REPO_COMMIT` 86 | 87 | - `FLOWCI_GIT_PR_BASE_REPO_NAME` 88 | 89 | - `FLOWCI_GIT_PR_BASE_REPO_BRANCH` 90 | 91 | - `FLOWCI_GIT_PR_BASE_REPO_COMMIT` 92 | -------------------------------------------------------------------------------- /cn/config/freetext.md: -------------------------------------------------------------------------------- 1 | # 任意配置 (Free Text) 2 | 3 | ## 创建配置 4 | 5 | 1. 点击 `Settings` -> `Config` -> `+` 6 | 2. 输入一个名称 7 | 3. 选择 `Text` 类型 8 | 4. 填入配置信息，可以为任意格式 9 | 5. 保存 `Save` 10 | 11 | ![create smtp](../../_images/config/create_text.gif) 12 | 13 | 14 | ## 如何使用 15 | 16 | - 从 Step 中获取 `Free Text` 配置 17 | 18 | 例如: 需要自定义 Maven .m2 中的 `settings.xml`, 可以输入所需要的 `xml` 配置 19 | ```xml 20 | 21 | 22 | 23 | ... 24 | 25 | 26 | 27 | ``` 28 | 29 | 之后在 YAML 配置中，通过 `configs` 引入 30 | 31 | ```yaml 32 | steps: 33 | - name: set maven settings 34 | configs: 35 | - my_xml_config 36 | bash: | 37 | echo ${my_xml_config} 38 | echo ${my_xml_config} > ~/.m2/settings.xml 39 | ``` -------------------------------------------------------------------------------- /cn/config/smtp.md: -------------------------------------------------------------------------------- 1 | # SMTP 配置 2 | 3 | ## 创建配置 4 | 5 | 1. 点击 `Settings` -> `Config` -> `+` 6 | 2. 输入一个名称 7 | 3. 选择 `SMTP` 类型 8 | 4. 填入所需的信息 9 | - `Server` 10 | - `Port` 11 | - `Username` 12 | - `Password` 13 | - 选择加密类型 `None`, `SSL` or `TLS` 14 | 5. 保存 `Save` 15 | 16 | ![create smtp](../../_images/config/create_smtp.gif) 17 | 18 | ## 如何使用 19 | 20 | - 从 Step 中获取 `SMTP` 配置 21 | 22 | 例如: 创建了一个名为 `default_smtp` 的 `SMTP` 类型的配置，可以在 YAML 配置中，通过 `configs` 引入 23 | 24 | ```yaml 25 | steps: 26 | - name: smtp config demo 27 | configs: 28 | - default_smtp 29 | bash: | 30 | echo ${default_smtp_SERVER} 31 | echo ${default_smtp_PORT} 32 | echo ${default_smtp_SECURE_TYPE} 33 | echo ${default_smtp_AUTH_USERNAME} 34 | echo ${default_smtp_AUTH_PASSWORD} 35 | ``` 36 | 37 | - 在 `触发器 (Trigger)` 中使用 38 | 39 | 例如配置 gmail 发送 任务结束通知 邮件: 40 | - `Server`: stmp.gmail.com 41 | - `Port`: 587 42 | - `Username`: gmail 的用户名 43 | - `Password`: gmail 的密码 44 | - 选择 `TLS` 45 | 46 | 此外还需要登陆 Gmail 47 | 找到 `Security > Less secure app access` 48 | 点击 `Click Turn on access` 49 | ![gmail_1](../../_images/config/gmail_setting_1.png) 50 | ![gmail_2](../../_images/config/gmail_setting_2.png) 51 | 52 | 配置好后，设置邮件触发器，[请参见](cn/trigger/on_job_finish.md#发送邮件) 53 | -------------------------------------------------------------------------------- /cn/flow/structure.md: -------------------------------------------------------------------------------- 1 | # 工作流结构 2 | 3 | 工作流(flow) 是 flow.ci 的最基本的组成。 4 | 5 | 构成工作流 (flow) 的基本元素有: 6 | - 步骤列表 (steps) 7 | - 执行步骤 (step) 8 | - 并行步骤 (parallel) 9 | 10 | ![structure](../../_images/flow/structure.png) 11 | 12 | 13 | ### 举个例子 14 | 15 | 从 Git 仓库克隆代码，在 Java 8 和 11 的环境下同时运行测试，之后部署到不同的环境中 16 | 17 | ![sample](../../_images/flow/sample.png) 18 | 19 | 20 | 使用 YAML 配置来表示以上结构: 21 | 22 | ```yaml 23 | 24 | steps: 25 | - name: git clone 26 | bash: | 27 | echo "run git clone" 28 | 29 | - name: steps for build 30 | docker: 31 | image: "my build image" 32 | steps: 33 | - name: build_a 34 | bash: | 35 | echo "run build step a" 36 | - name: build_b 37 | bash: | 38 | echo "run build step b" 39 | 40 | - parallel: 41 | java_8_test: 42 | docker: 43 | image: "java 8 image" 44 | steps: 45 | - name: test a 46 | bash: | 47 | echo "run test a for java 8" 48 | - name: test b 49 | bash: | 50 | echo "run test b for java 8" 51 | 52 | java_11_test: 53 | docker: 54 | image: "java 11 image" 55 | steps: 56 | - name: test a 57 | bash: | 58 | echo "run test a for java 11" 59 | - name: test b 60 | bash: | 61 | echo "run test b for java 11" 62 | 63 | 64 | - parallel: 65 | deploy_to_a: 66 | steps: 67 | - name: deploy 68 | bash: | 69 | echo "deploy to environment a" 70 | 71 | deploy_to_b: 72 | steps: 73 | - name: deploy 74 | bash: | 75 | echo "deploy to environment b" 76 | 77 | ``` 78 | 79 | 更详细的 YAML 配置，请查看 [YAML 配置参考](/cn/yml/reference_v1) -------------------------------------------------------------------------------- /cn/git/gerrit.md: -------------------------------------------------------------------------------- 1 | # Gerrit 集成 2 | 3 | ## 添加访问权限 4 | 5 | - 从 `Settings -> Secret` 中 copy 相应的公钥 6 | - 打开 Gerrit 页面 `{your_gerrit_host}/settings/#SSHKeys` 7 | - 黏贴公钥，保存后，flow.ci 就可获得该 GitLab 项目的访问权限 8 | 9 | ![setup_deploy_key](../../_images/git/gerrit_setup_ssh_key.png) 10 | 11 | ## 配置 Git 触发事件 (Webhook) 12 | 13 | 1. 确定 [webhook 插件](https://gerrit.googlesource.com/plugins/webhooks/) 已经在 Gerrit 上安装, 或也可以从 Gerrit plugin manager 中安装 14 | 15 | ![webhook plugin](../../_images/git/gerrit_webhook_plugin.png) 16 | 17 | 18 | 2. 进入已经从 Gerrit 上 clone 到本地项目仓库, 进入 `meta/config` 分之 19 | 20 | ```bash 21 | git fetch origin refs/meta/config:refs/remotes/origin/meta/config 22 | git checkout meta/config 23 | ``` 24 | 25 | 3. 从工作流设置中复制 webhook 链接 26 | 27 | > 提示: 当前 CI 的主机需要有公网能访问的 IP 或者 域名，否则无法收到触发事件。如果无法配置公网访问，可以使用 [ngrok](https://ngrok.com/) 等工具来获取公网 -> 内网映射。 28 | 29 | ![webhook settings](../../_images/git/select_webhook_url.gif) 30 | 31 | 32 | 4. 添加一下配置到 `webhooks.config` 文件 (如果文件不存在可创建) 33 | 34 | > flow.ci 目前仅支持 `patchset-created` Gerrit 事件 35 | 36 | ``` 37 | [remote "flowci_pathset_created"] 38 | url = {从第3步拷贝的 URL 地址} 39 | maxTries = 1 40 | sslVerify = false 41 | event = patchset-created 42 | ``` 43 | 44 | 5. 保存更改到 `meta/config` 分支 45 | 46 | ``` 47 | git push origin meta/config:meta/config 48 | ``` 49 | 50 | 51 | ## 验证 Gerrit 配置 52 | 53 | - Verify permission for repo: 54 | 55 | 可以点击 `Test` 按钮验证访问权限是否配置正确. 56 | 57 | ![test](../../_images/git/gerrit_test_config.gif) 58 | 59 | ## 配置 CI 任务状态写入到 Gerrit 的权限 60 | 61 | 1. 在 Gerrit 中创建 Http Credential 62 | 63 | 我们须创建一个 `HTTP Credentials (GENERATE NEW PASSWORD)` 以便让 flow.ci 获得任务状态的写入权限，可以在 Gerrit `{your_gerrit_host}/settings/#HTTPCredentials` 页面创建。 64 | 65 | ![token](../../_images/git/gerrit_create_access_pw.png) 66 | 67 | 2. 添加密码到 flow.ci 密钥 68 | 69 | 在 flow.ci 中打开添加密钥页面 `Settings -> Secret -> +`，黏贴从 Gerrit 中拷贝的密码，并保存。 70 | 71 | ![add token](../../_images/git/add_token.png) 72 | 73 | 3. flow.ci 中配置 Gerrit 74 | 75 | 在 flow.ci 中打开 Git 集成页面 `Settings -> Git -> +`, 选择 `Gerrit`, 输入 Gerrit 地址, 之后选择上一步所添加的密钥 76 | 77 | ![link](../../_images/git/gerrit_add_link.png) 78 | 79 | 4. 任务状态显示 80 | 81 | 如果一切配置正确，当 CI 任务完成后，Gerrit PatchSet 中即可显示任务状态。 82 | 83 | ![commit status](../../_images/git/gerrit_commit_status.png) -------------------------------------------------------------------------------- /cn/git/gitee.md: -------------------------------------------------------------------------------- 1 | # Gitee 集成 2 | 3 | ## 添加访问权限 4 | 5 | - 从 `Settings -> Secret` 中 copy 相应的公钥 6 | - 打开 Gitee 页面，在项目设置 `Settings > Deploy keys -> Add key` 7 | - Paste 公钥，保存后，flow.ci 就可获得该 Gitee 项目的访问权限 8 | 9 | > Gitee 不可以在多个项目中使用同一个公钥， 如果需要用同一个公钥访问多个仓库，建议在 Gitee 中创建一个特殊的用户比如 `CI User`，之后再该用户中添加 SSH 公钥。 10 | 11 | ![setup_deploy_key](../../_images/git/gitee_setup_deploy_key.png) 12 | 13 | ## 配置 Git 触发事件 (Webhook) 14 | 15 | 触发事件（Webhook）是用于当有 Push，Tag 或者 Pull Request 等操作时时，触发 CI 任务。 16 | 17 | 1. 从工作流设置中复制 webhook 链接 18 | > 提示: 当前 CI 的主机需要有公网能访问的 IP 或者 域名，否则无法收到触发事件。如果无法配置公网访问，可以使用 [ngrok](https://ngrok.com/) 等工具来获取公网 -> 内网映射。 19 | 20 | ![webhook settings](../../_images/git/select_webhook_url.gif) 21 | 22 | 2. 设置 Gitee webhook 23 | 24 | - Payload URL: 粘贴 webhook 链接 25 | 26 | > 如果使用 `ngrok`, 请手动替换地址的第一部分, 例如: `http://172.20.10.4/webhooks/spring-sample` to `http://7e9ea9dc.ngrok.io/webhooks/spring-sample` 27 | 28 | - 选择触发事件 29 | 30 | - 选择 `Push`, `Tag Push` and `Pull Request` 31 | 32 | ![events](../../_images/git/gitee_setup_webhook.png) 33 | 34 | 35 | ## 验证 Gitee 配置 36 | 37 | - 触发事件 Webhook: 38 | 39 | Gitee 会自动发送一个验证事件 ping 到 webhook 的地址，当 flow.ci 接收到这个事件后，会出现一个绿色的标识。 40 | 41 | - 验证权限: 42 | 43 | 可以点击 `Test` 按钮验证访问权限是否配置正确. 44 | 45 | ![test](../../_images/git/gitee_test_config.gif) -------------------------------------------------------------------------------- /cn/git/github.md: -------------------------------------------------------------------------------- 1 | # GitHub 集成 2 | 3 | ## 添加访问权限 4 | 5 | - 从 `Settings -> Secret` 中 copy 相应的公钥 6 | - 打开 GitHub 页面，在项目设置 `Settings > Deploy key` 选择 `Add deploy key` 7 | - Paste 公钥，保存后，flow.ci 就可获得该 GitHub 项目的访问权限 8 | 9 | > GitHub 不可以在多个项目中使用同一个公钥， 如果需要用同一个公钥访问多个仓库，建议在 GitHub 中创建一个特殊的用户比如 `CI User`，之后再该用户中添加 SSH 公钥，可参考 [adding new ssh key to your GitHub account](https://help.github.com/en/articles/adding-a-new-ssh-key-to-your-github-account). 10 | 11 | ![github_setup_deploy_key](../../_images/git/github_setup_deploy_key.png) 12 | 13 | ## 配置 Git 触发事件 (Webhook) 14 | 15 | 触发事件（Webhook）是用于当有 Push，Tag 或者 Pull Request 等操作时时，触发 CI 任务。 16 | 17 | 1. 从工作流设置中复制 webhook 链接 18 | > 提示: 当前 CI 的主机需要有公网能访问的 IP 或者 域名，否则无法收到触发事件。如果无法配置公网访问，可以使用 [ngrok](https://ngrok.com/) 等工具来获取公网 -> 内网映射。 19 | 20 | ![webhook settings](../../_images/git/select_webhook_url.gif) 21 | 22 | 2. 设置 GitHub webhook 23 | 24 | - Payload URL: 粘贴 webhook 链接 25 | 26 | > 如果使用 `ngrok`, 请手动替换地址的第一部分, 例如: `http://172.20.10.4/webhooks/spring-sample` to `http://7e9ea9dc.ngrok.io/webhooks/spring-sample` 27 | 28 | - Content type: `application/json` 29 | 30 | ![payload and content](../../_images/git/github_setup_payload_and_content.png) 31 | 32 | - 选择触发事件 33 | 34 | - 选择 `Let me select individual events` 35 | - 选择 `push` and `pull request` 36 | 37 | ![events](../../_images/git/github_select_events.png) 38 | 39 | ## 验证 GitHub 配置 40 | 41 | - 触发事件 Webhook: 42 | 43 | 当配置完成后，GitHub 会自动发送一个验证事件 ping 到 webhook 的地址，当 flow.ci 接收到这个事件后，会出现一个绿色的标识。 44 | 45 | - 验证权限: 46 | 47 | 可以点击 `Test` 按钮验证访问权限是否配置正确. 48 | 49 | ![github_test](../../_images/git/github_test_config.gif) 50 | 51 | 52 | ## 配置 CI 任务状态写入到 GitHub 的权限 53 | 54 | 1. 在 GitHub 中创建 Token 55 | 56 | 我们须创建一个拥有 `repo:status` 权限的 Token，以便让 flow.ci 获得任务状态的写入权限，可以在 GitHub `https://github.com/settings/tokens` 页面中创建。 57 | 58 | ![create token](../../_images/git/github_create_access_token.png) 59 | 60 | 2. 添加 Token 到 flow.ci 密钥 61 | 62 | 在 flow.ci 中打开添加密钥页面 `Settings -> Secret -> +`，黏贴从 GitHub 中拷贝的 Token，并保存。 63 | 64 | ![add token](../../_images/git/add_token.png) 65 | 66 | 3. flow.ci 中配置 GitHub 67 | 68 | 在 flow.ci 中打开 Git 集成页面 `Settings -> Git -> +`, 选择 `GitHub`, 之后选择上一步所添加的密钥 69 | 70 | ![link](../../_images/git/github_add_link.png) 71 | 72 | 4. 任务状态显示 73 | 74 | 如果一切配置正确，当 CI 任务完成后，GitHub 的提交中即可显示任务状态。 75 | 76 | ![demo](../../_images/git/github_check_updated.png) -------------------------------------------------------------------------------- /cn/git/gitlab.md: -------------------------------------------------------------------------------- 1 | # GitLab 集成 2 | 3 | ## 添加访问权限 4 | 5 | - 从 `Settings -> Secret` 中 copy 相应的公钥 6 | - 打开 GitLab 页面，在项目设置 `Settings > Repository -> Deploy Keys` 7 | - Paste 公钥，保存后，flow.ci 就可获得该 GitLab 项目的访问权限 8 | 9 | > GitLab 不可以在多个项目中使用同一个公钥， 如果需要用同一个公钥访问多个仓库，建议在 GitLab 中创建一个特殊的用户比如 `CI User`，之后再该用户中添加 SSH 公钥。 10 | 11 | ![gitlab_setup_deploy_key](../../_images/git/gitlab_setup_deploy_key.png) 12 | 13 | ## 配置 Git 触发事件 (Webhook) 14 | 15 | 触发事件（Webhook）是用于当有 Push，Tag 或者 Pull Request 等操作时时，触发 CI 任务。 16 | 17 | 1. 从工作流设置中复制 webhook 链接 18 | > 提示: 当前 CI 的主机需要有公网能访问的 IP 或者 域名，否则无法收到触发事件。如果无法配置公网访问，可以使用 [ngrok](https://ngrok.com/) 等工具来获取公网 -> 内网映射。 19 | 20 | ![webhook settings](../../_images/git/select_webhook_url.gif) 21 | 22 | 2. 设置 GitLab webhook 23 | 24 | - URL: 粘贴 webhook 链接 25 | 26 | > 如果使用 `ngrok`, 请手动替换地址的第一部分, 例如: `http://172.20.10.4/webhooks/spring-sample` to `http://7e9ea9dc.ngrok.io/webhooks/spring-sample` 27 | 28 | - 选择触发事件 29 | 30 | 选择事件 `Push events`, `Tag push events` 和 `Merge request events` 31 | 32 | ![events](../../_images/git/gitlab_setup_webhook.png) 33 | 34 | ## 验证 GitLab 配置 35 | 36 | - 验证权限: 37 | 38 | 可以点击 `Test` 按钮验证访问权限是否配置正确. 39 | 40 | ![gitlab_test](../../_images/git/gitlab_test_config.gif) 41 | 42 | 43 | ## 配置 CI 任务状态写入到 GitLab 的权限 44 | 45 | 1. 在 GitLab 中创建 Token 46 | 47 | In order to have permission for writing job status back to GitLab, we need to create a token with `api` permission from https://gitlab.com/-/profile/personal_access_tokens (replace `https://gitlab.com` to your own GitLab host when access private gitlab) 48 | 49 | 我们须创建一个拥有 `api` 权限的 Token，以便让 flow.ci 获得任务状态的写入权限，可以在 GitLab `https://gitlab.com/-/profile/personal_access_tokens` 页面中创建 (如私有 GitLab 仓库，请替换 `https//gitlab.com`)。 50 | 51 | ![create token](../../_images/git/gitlab_create_access_token.png) 52 | 53 | 2. 添加 Token 到 flow.ci 密钥 54 | 55 | 在 flow.ci 中打开添加密钥页面 `Settings -> Secret -> +`，黏贴从 GitLab 中拷贝的 Token，并保存。 56 | 57 | ![add token](../../_images/git/add_token.png) 58 | 59 | 3. flow.ci 中配置 GitLab 60 | 61 | 在 flow.ci 中打开 Git 集成页面 `Settings -> Git -> +`, 选择 `GitLab`, 输入 GitLab 地址, 之后选择上一步所添加的密钥 62 | 63 | ![link](../../_images/git/gitlab_add_link.png) 64 | 65 | 4. 任务状态显示 66 | 67 | 如果一切配置正确，当 CI 任务完成后，GitLab 的提交中即可显示任务状态。 68 | 69 | ![demo](../../_images/git/gitlab_stage_updated.png) -------------------------------------------------------------------------------- /cn/git/gogs.md: -------------------------------------------------------------------------------- 1 | # Gogs 集成 2 | 3 | ## 添加访问权限 4 | 5 | - 从 `Settings -> Secret` 中 copy 相应的公钥 6 | - 打开 Gogs 页面，在项目设置 `Settings > Deploy Keys` 选择 `Add deploy key` 7 | - Paste 公钥，保存后，flow.ci 就可获得该 Gogs 项目的访问权限 8 | 9 | > Gogs 不可以在多个项目中使用同一个公钥， 如果需要用同一个公钥访问多个仓库，建议在 Gogs 中创建一个特殊的用户比如 `CI User`，之后再该用户中添加 SSH 公钥。 10 | 11 | ![setup_deploy_key](../../_images/git/gogs_setup_deploy_key.png) 12 | 13 | ## 配置 Git 触发事件 (Webhook) 14 | 15 | 触发事件（Webhook）是用于当有 Push，Tag 或者 Pull Request 等操作时时，触发 CI 任务。 16 | 17 | 1. 从工作流设置中复制 webhook 链接 18 | > 提示: 当前 CI 的主机需要有公网能访问的 IP 或者 域名，否则无法收到触发事件。如果无法配置公网访问，可以使用 [ngrok](https://ngrok.com/) 等工具来获取公网 -> 内网映射。 19 | 20 | ![webhook settings](../../_images/git/select_webhook_url.gif) 21 | 22 | 2. 设置 Gogs webhook 23 | 24 | - Payload URL: 粘贴 webhook 链接 25 | 26 | > 如果使用 `ngrok`, 请手动替换地址的第一部分, 例如: `http://172.20.10.4/webhooks/spring-sample` to `http://7e9ea9dc.ngrok.io/webhooks/spring-sample` 27 | 28 | - 选择触发事件 29 | 30 | - 选择 `Let me choose what I need` 31 | - 选择 `push` and `pull request` 32 | 33 | ![events](../../_images/git/gogs_setup_webhook.png) 34 | 35 | ## 验证 Gogs 配置 36 | 37 | - 验证权限: 38 | 39 | 可以点击 `Test` 按钮验证访问权限是否配置正确. 40 | 41 | ![test](../../src/git/gogs_test_config.gif) -------------------------------------------------------------------------------- /cn/git/index.md: -------------------------------------------------------------------------------- 1 | # 工作流中配置 Git 2 | 3 | ## 克隆 Git 仓库 4 | 5 | flow.ci 通过 [git clone](https://github.com/flowci-plugins/gitclone) 插件来实现 clone 代码. 6 | 7 | ```yaml 8 | envs: 9 | FLOWCI_GIT_URL: "https://github.com/FlowCI/spring-petclinic-sample.git" ## 替换对应的仓库地址, 支持 https 或 ssh 10 | 11 | steps: 12 | - name: clone 13 | docker: 14 | image: flowci/debian-git ## 也可使用带有 git 命令的其他 image。如果 Agent 运行环境带有 Git 命令，也可以不使用 docker 定义 15 | plugin: 'gitclone' 16 | ``` 17 | 18 | 19 | ## 配置仓库访问权限 20 | 21 | 如果 Git 链接为 __SSH__ 协议，例如 `git@github.com:FlowCI/docs.git`, 则需要配置 __SSH-RSA__ 秘钥已获得代码的访问权限. 22 | 23 | 1. 创建 SSH-RSA 秘钥 24 | 25 | - 进入管理员界面 `Settings -> Secret -> +` 26 | - 输入一个秘钥名称， 例如 `ras-test` 27 | - 选择 `SSH key` 类型 28 | - 点击生创建新的秘钥，或者 copy 已有的公钥私钥 29 | - 保存 30 | 31 | > 如果使用已有的 SSH KEY，请复制 公钥 和 私钥 32 | 33 | ![how to create ssh-rsa secret](../../_images/secret/create_ssh_key.gif) 34 | 35 | 2. 配置秘钥到工作流 36 | 37 | `FLOWCI_GIT_CREDENTIAL` 用于 [Git clone 插件](https://github.com/flowci-plugins/gitclone) 使用哪个秘钥访问，可在 YAML 中设置该变量为秘钥名称。 38 | 39 | ```yaml 40 | envs: 41 | FLOWCI_GIT_CREDENTIAL: "rsa-test" 42 | 43 | steps: 44 | - name: clone 45 | docker: 46 | image: flowci/debian-git 47 | plugin: 'gitclone' 48 | ``` 49 | 50 | ## Git 仓库中添加访问权限，及触发事件 51 | 52 | 不同 Git 仓库的访问权限，和触发事件的配置有略微差异，目前 flow.ci 支持的仓库有 53 | 54 | - [GitHub](/cn/git/github.md) 55 | - [GitLab](/cn/git/gitlab.md) 56 | - [Gogs](/cn/git/gogs.md) 57 | - [Gitee](/cn/git/gitee.md) 58 | - [Gerrit](/cn/git/gerrit.md) 59 | 60 | 请点击相关 Git 仓库查看详细配置方法 61 | -------------------------------------------------------------------------------- /cn/job/cache.md: -------------------------------------------------------------------------------- 1 | # 任务缓存 (cache) 2 | 3 | 当并行执行时, 任务会运行在不同的 Agent 中。如果这时想访问同一数据，这时就需要配置缓存。 4 | 5 | ![cache demo](../../_images/job/cache_demo.png) 6 | 7 | ## 如何使用缓存 8 | 9 | 可以在 步骤 (step) 中使用 `cache`。配置缓存需要使用 `key` 来定义缓存名称，如果该步骤为 写入缓存，则需要配置 `paths` 指定那个路径或文件需要写入。 10 | 11 | ```yaml 12 | steps: 13 | - name: write 14 | cache: 15 | key: mycache 16 | paths: 17 | - "./my_demo_cache" 18 | bash: | 19 | mkdir -p ./my_demo_cache 20 | echo "cache_content" > ./my_demo_cache/my_file 21 | 22 | - name: clean 23 | bash: | 24 | # 从本地工作区(workspace) 删除该目录, 确保之后的缓存从正确的位置读取 25 | rm -rf ./my_demo_cache 26 | 27 | - parallel: 28 | flow_1: 29 | docker: 30 | image: "ubuntu:21.04" 31 | steps: 32 | - name: read 33 | cache: 34 | key: mycache 35 | bash: | 36 | cat ./my_demo_cache/my_file 37 | 38 | flow_2: 39 | docker: 40 | image: "ubuntu:18.04" 41 | steps: 42 | - name: read 43 | cache: 44 | key: mycache 45 | bash: | 46 | cat ./my_demo_cache/my_file 47 | 48 | ``` 49 | 50 | 运行结果如下: 51 | 52 | ![cache_run](../../_images/job/cache_run_example.png) -------------------------------------------------------------------------------- /cn/job/condition.md: -------------------------------------------------------------------------------- 1 | # 运行条件 2 | 3 | 每一个任务(job) 或 执行步骤(step) 都可以使用 `Groovy` 脚步自定义执行条件。 4 | 5 | 6 | 在 `Groovy` 脚本中，可以使用 [flow.ci 的环境变量](cn/agents/vars.md), 要求返回值为 `boolean`, 例如: 7 | 8 | ```yaml 9 | - condition: | 10 | println("hello world") 11 | true 12 | ``` 13 | 14 | 15 | ## 任务的运行条件 16 | 17 | 在工作流 YAML 配置中，根节点添加 `condition`。 18 | 19 | __例如__: 指定任务只能在 "develop" 或 "master" 分支改变时运行 20 | 21 | ```yaml 22 | condition: | 23 | return $FLOWCI_GIT_BRANCH == "develop" || $FLOWCI_GIT_BRANCH == "master"; 24 | 25 | steps: 26 | - name: step1 27 | bash: | 28 | echo "this is the step one" 29 | 30 | ``` 31 | 32 | 33 | ## 步骤 (step) 的运行条件 34 | 35 | 每个步骤 (step) 都可以定义对应的运行条件，如果条件不满足时，会 __跳过__ 该步骤。 36 | 37 | __例如__: `step1` 中返回值为 `false`, 运行时则会跳过该步骤，直接执行 `step2` 38 | 39 | ```yaml 40 | steps: 41 | - name: step1 42 | condition: | 43 | return false 44 | bash: | 45 | echo "this is the step one" 46 | 47 | - name: step2 48 | condition: | 49 | return true 50 | bash: | 51 | echo "this is the step two" 52 | ``` -------------------------------------------------------------------------------- /cn/job/docker.md: -------------------------------------------------------------------------------- 1 | # 通过 Docker 配置运行环境 2 | 3 | 可通过在 YAML 中配置 `docker` / `dockers`, 来配置每个步骤所需要的运行环境 4 | 5 | > 此功能需要 Agent 运行环境中安装 docker 6 | 7 | ## 配置 Docker image 8 | 9 | 工作流(flow) 和 执行步骤(step) 中，均支持 `docker` 定义。 10 | 11 | 在 YAML 定义了 `docker` 之后，步骤中的 `bash` 脚本会在 Docker 容器中执行。 12 | 13 | ### 在执行步骤(step) 使用 `docker` 14 | 15 | 当定义了 `docker.image` 后，步骤即会在 `openjdk:11` 或 `openjdk:8` 中的环境运行 16 | 17 | ```yaml 18 | steps: 19 | - name: step_1 20 | docker: 21 | image: "openjdk:11" 22 | bash: "Run from openjdk 11" 23 | 24 | - name: step_2 25 | docker: 26 | image: "openjdk:8" 27 | bash: "Run from openjdk 8" 28 | ``` 29 | 30 | ### 在工作流(flow) 使用 `docker` 31 | 32 | 当在 工作流 范围中定义了 `docker` 后，所有的步骤会使用该 `docker` 配置。 33 | 34 | 在 步骤 中有 `docker` 定义时，会使用此步骤中的配置。 35 | 36 | ```yaml 37 | docker: 38 | image: "openjdk:11" 39 | 40 | steps: 41 | - name: step_1 42 | bash: "Run from openjdk 11" 43 | 44 | - name: step_2 45 | docker: 46 | image: "openjdk:8" 47 | bash: "Run from openjdk 8" 48 | 49 | ``` 50 | 51 | ## 配置 __多个__ Docker image 52 | 53 | 步骤中同时需要多个服务时, 比如需要 `redis`, `mongodb` 等，则可通过配置 `dockers` 来实现，同时必须定义 `is_runtime` 来确定脚本的执行环境。 54 | 55 | Agent 中内置了 `wait-for-it.sh` 等待脚本, 可使用该脚本来等待某个服务启动。 56 | 57 | __例如__: 运行时需要 `mysql` 的服务, 可以添加 `mysql` 的镜像来获得该服务 58 | 59 | ```yaml 60 | steps: 61 | - name: run mutiple dockers 62 | dockers: 63 | - image: ubuntu:21.04 64 | is_runtime: true # 步骤脚本在此环境中执行 65 | 66 | - image: mysql:5.6 67 | environment: 68 | MYSQL_ROOT_PASSWORD: 12345 69 | bash: | 70 | ## 通过环境变量获取 container id 71 | echo "ubuntu:21.04 id = $CONTAINER_ID_0" 72 | echo "mysql:5.6 id = $CONTAINER_ID_1" 73 | 74 | ## 通过环境变量获取 container IP 地址, 网络默认模式为 'bridge' 75 | echo "ubuntu:21.04 ip = $CONTAINER_IP_0" 76 | echo "mysql:5.6 ip = $CONTAINER_IP_1" 77 | 78 | ## 内置 wait-for-it.sh 脚本，可以等待 'mysql' 服务启动 79 | wait-for-it.sh ${CONTAINER_IP_1}:3306 -t 30 80 | if [ $? == 0 ];then 81 | docker run --network ${FLOWCI_AGENT_DOCKER_NETWORK} --rm mysql:5.6 mysql -h${CONTAINER_IP_1} -uroot -p12345 mysql -e "select * from user" 82 | fi 83 | ``` 84 | 85 | ![multiple docker](../../_images/job/multiple_docker.png) -------------------------------------------------------------------------------- /cn/job/parallel.md: -------------------------------------------------------------------------------- 1 | # 并行执行 2 | 3 | 并行执行可以大幅提升任务的运行效率。 4 | 5 | YAML 中可以通过 `parallel` 来配置并行执行, 在 `parallel` 节点下，可配置多个并行工作流。 6 | 7 | 当并行执行时，需要多个空闲 Agent。如果当前环境只有一个空闲的 Agent，即使配置了 `parallel` 也会顺序执行。 8 | 9 | ```yaml 10 | steps: 11 | - parallel: 12 | flow_1: ## 定义并行执行的工作流名称 13 | steps: 14 | - name: step_1 15 | bash: | 16 | echo "step 1 from flow 1" 17 | 18 | flow_2: ## 定义并行执行的工作流名称 19 | steps: 20 | - name: step_1 21 | bash: | 22 | echo "step 1 from flow 2" 23 | 24 | ``` 25 | 26 | ![parallel](../../_images/job/parallel.png) 27 | 28 | 例如：需要 系统测试 运行在 `java 8` 和 `java 11` 环境下 29 | 30 | ```yaml 31 | steps: 32 | - name: git clone 33 | bash: | 34 | echo "run git clone" 35 | 36 | - parallel: 37 | java_8_test: 38 | docker: 39 | image: "java 8 image" 40 | steps: 41 | - name: test a 42 | bash: | 43 | echo "run test a for java 8" 44 | - name: test b 45 | bash: | 46 | echo "run test b for java 8" 47 | 48 | java_11_test: 49 | docker: 50 | image: "java 11 image" 51 | steps: 52 | - name: test a 53 | bash: | 54 | echo "run test a for java 11" 55 | - name: test b 56 | bash: | 57 | echo "run test b for java 11" 58 | ``` -------------------------------------------------------------------------------- /cn/job/schedule.md: -------------------------------------------------------------------------------- 1 | # 定时任务 2 | 3 | 一个工作流(flow)可以配置 __任务时间表（crontab)__ 按一定的时间间隔执行。 4 | 5 | 定时任务可以从 工作流设置页面 `http://{your_host}/#/flows/{your_flow_name}/settings` 配置。 6 | 7 | ![cron](../../_images/job/cron_job.gif) -------------------------------------------------------------------------------- /cn/job/start.md: -------------------------------------------------------------------------------- 1 | # 开始任务 2 | 3 | 当配置好工作流 (flow) 后，即可开始一个任务 (job). 4 | 5 | 开始一个任务，至少需要一个可用的 Agent。 关于如何配置 Agent，请参考[Agent 章节](/cn/agents/index) 6 | 7 | ## 手动触发 8 | 9 | 从页面 `http://{your host}/#/flows/{your flow name}/jobs`，点击 `开始` 来执行一个任务 10 | 11 | ## Git 事件触发 12 | 13 | 支持的仓库有: [GitHub](https://github.com), [GitLab](https://gitlab.com), [Gogs](https://gogs.io/) 和 [Gitee](https://gitee.com/) 14 | 15 | 支持的事件有: `Push`, `Tag` 和 `Pull Request` 16 | 17 | 如何配置 Git 仓库，请参见 [Git 仓库](cn/git/index.md) -------------------------------------------------------------------------------- /cn/job/web_terminal.md: -------------------------------------------------------------------------------- 1 | # 网页终端 (Web Terminals) 2 | 3 | 在任务运行时，如果有 __管理员权限__ 则用户可以在线访问终端环境，输入命令行进行在线调试. 4 | 5 | 当进入终端环境调试时，系统会等待终端退出后，才会执行下一步。 6 | 7 | > 如果任务运行时间较短，没有时间从页面进入终端，则可以使用 `sleep xxx` 让任务飞一会儿 8 | 9 | ```yaml 10 | steps: 11 | - name: step1 12 | bash: | 13 | echo "try web terminal" 14 | sleep 10 15 | ``` 16 | 17 | ![web terminal](../../_images/job/terminal.gif) -------------------------------------------------------------------------------- /cn/job/workspace.md: -------------------------------------------------------------------------------- 1 | # 工作区 (workspace) 2 | 3 | __工作区__ 是一个在 Agent 中的文件路径，每个工作流下的任务，都 __共享__ 同一个工作区。 4 | 5 | 该工作区为脚本的默认路径，也可以通过变量 `FLOWCI_AGENT_JOB_DIR` 访问。 6 | 7 | - Agent 从 `Docker` 启动: `/ws/{flow id}` 8 | - Agent 从 `可执行程序` 启动: 默认路径为 `${HOME}/.flow.ci.agent/{flow id}` 9 | 10 | 如果需要存储 任务(job) 特有的数据，可以创建该任务所对应的目录: 11 | 12 | ```yaml 13 | steps: 14 | - name: job_own_dir 15 | bash: | 16 | # 根据 任务编号 创建文件夹 17 | mkdir -p "${FLOWCI_AGENT_JOB_DIR}/${FLOWCI_JOB_BUILD_NUM}" 18 | 19 | - name: access_job_dir 20 | bash: | 21 | # 访问该文件夹 22 | cd "${FLOWCI_AGENT_JOB_DIR}/${FLOWCI_JOB_BUILD_NUM}" 23 | ``` -------------------------------------------------------------------------------- /cn/secret/android_sign.md: -------------------------------------------------------------------------------- 1 | # "安卓签名" 密钥 2 | 3 | ## 创建密钥 4 | 5 | 1. 点击 `Settings` -> `Secret` -> `+` 6 | 2. 输入一个名称 7 | 3. 选择 `Android sign` 类型 8 | 4. 填入所需的信息 9 | - `Key store file` 10 | - `key store password` 11 | - `Key alias` 12 | - `Key password` 13 | 5. 保存 `Save` 14 | 15 | ![create android sign](../../_images/secret/create_android_sign.gif) 16 | 17 | ## 如何使用 18 | 19 | - 在 [android-signing](https://github.com/flowci-plugins/android-signing) 插件中使用: 20 | 21 | 在变量 `SIGN_SECRET` 中填入所对应的 `安卓签名` 类型的密钥名称。 22 | 23 | ```yaml 24 | - name: sign apk 25 | envs: 26 | SIGN_FILE_PATTERN: '*-unsigned.apk' 27 | SIGN_SECRET: my_android_sign 28 | plugin: android-signing 29 | ``` 30 | 31 | 如果签名成功，会在此步骤中显示 `'./xx/xx/xx/you_package.apk' signed`，例如： 32 | 33 | ![show android signed](../../_images/secret/android_signed.png) -------------------------------------------------------------------------------- /cn/secret/auth.md: -------------------------------------------------------------------------------- 1 | # "用户名密码" 类型的秘钥 2 | 3 | ## 创建密钥 4 | 5 | 1. 点击 `Settings` -> `Secret` -> `+` 6 | 2. 输入一个名称 7 | 3. 选择 `Auth pair` 类型 8 | 4. 输入用户名，密码 9 | 5. 保存 10 | 11 | ![create auth](../../_images/secret/create_auth_pair.gif) 12 | 13 | ## 如何使用 14 | 15 | - 从 `Step` 中获取 `用户名密码` 密钥 16 | 17 | 例如: 创建了一个名为 `my_auth_key` 的 `用户名密码` 类型的密钥，可以在 YAML 配置中，通过 `secrets` 引入 18 | 19 | ```yaml 20 | steps: 21 | - name: get auth demo 22 | secrets: 23 | - my_auth_key 24 | bash: | 25 | echo ${my_auth_key_USERNAME} 26 | echo ${my_auth_key_PASSWORD} 27 | ``` 28 | 29 | 30 | -------------------------------------------------------------------------------- /cn/secret/kubeconfig.md: -------------------------------------------------------------------------------- 1 | # K8s "kubeconfig" 类型的密钥 2 | 3 | ## 创建密钥 4 | 5 | 1. 点击 `Settings` -> `Secret` -> `+` 6 | 2. 输入一个名称 7 | 3. 选择 `Kubeconfig` 类型 8 | 4. 拷贝对应的配置到文本框 9 | 5. 保存 `Save` 10 | 11 | ![create ssh rsa](../../_images/secret/create_kubeconfig.gif) 12 | 13 | ## 如何使用 14 | 15 | 此类型密钥主要用于配置 K8s 可伸缩 Agent，如何配置[请参考](cn/agents/k8s_host.md) -------------------------------------------------------------------------------- /cn/secret/ssh-rsa.md: -------------------------------------------------------------------------------- 1 | # "SSH-RSA" 类型的秘钥 2 | 3 | ## 创建密钥 4 | 5 | 1. 点击 `Settings` -> `Secret` -> `+` 6 | 2. 输入一个名称 7 | 3. 选择 `SSH Key` 类型 8 | 4. 编辑 SSH 公私钥 9 | - 可以点击 `CREATE NEW SSH KEY` 按钮来创建新的 SSH-RSA 公私钥 10 | - 或者拷贝已有的公私钥 11 | 5. 保存 `Save` 12 | 13 | ![create ssh rsa](../../_images/secret/create_ssh_key.gif) 14 | 15 | ## 如何使用 16 | 17 | - `gitclone` 插件中使用: 只需要在 `FLOWCI_GIT_CREDENTIAL` 变量中输入所创建的秘钥名称即可 18 | 19 | ```yaml 20 | envs: 21 | FLOWCI_GIT_URL: "https://github.com/FlowCI/spring-petclinic-sample.git" 22 | FLOWCI_GIT_BRANCH: "master" 23 | FLOWCI_GIT_REPO: "spring-petclinic" 24 | 25 | steps: 26 | - name: clone 27 | envs: 28 | FLOWCI_GIT_CREDENTIAL: "rsa-test" 29 | plugin: 'gitclone' 30 | ``` 31 | 32 | - 配置 SSH 类型的可伸缩 Agent 中使用，[请参考](cn/agents/ssh_host.md#可伸缩-agent-配置-ssh-主机) 33 | 34 | - 从 `Step` 中获取 `SSH-RSA` 密钥 35 | 36 | 例如: 创建了一个名为 `my_ssh_key` 的 `SSH-RSA` 类型的密钥，可以在 YAML 配置中，通过 `secrets` 引入 37 | 38 | ```yaml 39 | steps: 40 | - name: get sshrsa demo 41 | secrets: 42 | - my_ssh_key 43 | bash: | 44 | echo ${my_ssh_key_PUBLIC_KEY} 45 | echo ${my_ssh_key_PRIVATE_KEY} 46 | ``` 47 | -------------------------------------------------------------------------------- /cn/secret/token.md: -------------------------------------------------------------------------------- 1 | # "Token" 类型的秘钥 2 | 3 | ## 创建密钥 4 | 5 | 1. 点击 `Settings` -> `Secret` -> `+` 6 | 2. 输入一个名称 7 | 3. 选择 `Token` 类型 8 | 4. 输入 token 数据 9 | 5. 保存 10 | 11 | ![create token](../../_images/secret/create_token.gif) 12 | 13 | ## 如何使用 14 | 15 | - 从 `Step` 中获取 `Token` 密钥 16 | 17 | 例如: 创建了一个名为 `my_token` 的 `Token` 类型的密钥，可以在 YAML 配置中，通过 `secrets` 引入 18 | 19 | ```yaml 20 | steps: 21 | - name: get token demo 22 | secrets: 23 | - my_token 24 | bash: | 25 | echo ${my_token} 26 | ``` -------------------------------------------------------------------------------- /cn/start/index.md: -------------------------------------------------------------------------------- 1 | # 开始使用 flow.ci 2 | 3 | ## 安装 4 | 5 | > 需要预先安装 [Docker](https://docs.docker.com/install/) & [Docker-Compose](https://docs.docker.com/compose/install/) 6 | 7 | 安装 flow.ci 只需要运行如下脚本: 8 | 9 | ```bash 10 | git clone https://github.com/FlowCI/docker.git flow-docker 11 | cd flow-docker 12 | ./server.sh start 13 | ``` 14 | 15 | 等待完成后，可通过浏览器访问 `http://localhost:2015`. 16 | 17 | > - 默认端口：服务端 `8080`，前端 `2015`。可以从 `server.sh` 及 `server.yml` 配置文件中修改 18 | > - 默认IP地址: `./server.sh start` 命令会自动检测 IP 地址，如果没有找到对应的 IP 地址，可以使用 `./server.sh -h your_ip start` 来启动 19 | 20 | ![start_server](../../_images/start_server.gif) 21 | 22 | 23 | ## 配置 Host URL 24 | 25 | 确定服务端及前端的 URL 正确并可访问，已确保 flow.ci 正常工作。 26 | 27 | 可以在 `Settings -> System` `(http://{页面地址}/#/settings/system}` 中配置: 28 | 29 | ![config_url](../../_images/config_server_url.png) 30 | 31 | 32 | ## 创建工作流 33 | 34 | - 输入工作流名称 35 | - 点击 '创建工作流' 36 | - 按提示输入工作流名称 37 | 38 | - 选择 YAML 配置模板 39 | 40 | ![create_flow](../../_images/create_flow.gif) 41 | 42 | ## 开始任务 43 | 44 | 点击 `运行` 开始任务 45 | 46 | > - 如果选择空模板，则需要配置 YAML 后才可以开始任务 47 | 48 | ![start_job](../../_images/start_job.gif) 49 | 50 | - Git: 如何配置 Git 仓库，请参考 [Git 仓库配置](/cn/git/index.md) 51 | 52 | - Agent: 从 Docker 安装，会在服务器主机自动创建 Agent， 如果添加更多的 Agent，请[参考 Agent 章节](cn/agents/index.md) 53 | 54 | - 触发器(Trigger): 任务结束后，会触发 `OnJobFinish` 事件，如果需要邮件及其他类型的通知，[请参见](cn/trigger/on_job_finish.md) -------------------------------------------------------------------------------- /cn/trigger/on_job_finish.md: -------------------------------------------------------------------------------- 1 | # 任务结束 "OnJobFinish" 事件 2 | 3 | 此类事件可以定义 __当任务结束时__ 的行为 4 | 5 | ## 发送邮件 6 | 7 | 可以 __发送邮件__ 通知给相应的用户 8 | 9 | 1. 点击 `Settings` -> `Triggers` -> `+` 10 | 2. 输入一个名称 11 | 3. 选择 `On Job Finish` 事件 12 | 4. 选择 `Email` 类型的触发器 13 | 5. 设置邮件相关参数 14 | - 选择 `SMTP` 配置 15 | - 输入邮件标题, 标题可以使用环境变量 `[[${变量名称}]]` 16 | * 例如: 在标题中使用 工作流名称 及 任务编号 `工作流 [[${FLOWCI_FLOW_NAME}]] 任务 [[${FLOWCI_JOB_BUILD_NUM}]] 报告` 17 | * 可以参考 [环境变量列表](cn/agents/vars.md) 来定义邮件标题 18 | - 输入发件人地址 (如果为空，发件人为 `SMTP` 配置的地址) 19 | - 输入收件人地址 / 或选择 `To all flow users` 则收件人为所有工作流的用户地址 20 | 6. 保存 `Save` 21 | 22 | ![create_email_trigger](../../_images/trigger/create_job_finish_email.gif) 23 | 24 | 配置成功后，当任务结束时会发送如下邮件: 25 | 26 | ![email_sample](../../_images/trigger/email_sample.png) 27 | 28 | 29 | ## 发送 HTTP 请求 30 | 31 | 可以根据配置发送 __HTTP 请求__ 32 | 33 | 1. 点击 `Settings` -> `Triggers` -> `+` 34 | 2. 输入一个名称 35 | 3. 选择 `On Job Finish` 事件 36 | 4. 选择 `Webhook` 类型的触发器 37 | 5. 设置相关参数 38 | - 输入 `URL` 39 | - 选择 `HTTP 方法` 40 | - 请求参数 41 | * `Params` 42 | * `Headers` 43 | * `Body`: 可以使用[环境变量](cn/agents/vars.md)，例如 44 | ```json 45 | { 46 | "channel": "ID", 47 | "text": "[[${FLOWCI_FLOW_NAME}]] #[[${FLOWCI_JOB_BUILD_NUM}]] is [[${FLOWCI_JOB_STATUS}]] at [[${FLOWCI_JOB_URL}]]" 48 | } 49 | ``` 50 | 6. 保存 `Save` 51 | 52 | ![create_webhook_trigger](../../_images/trigger/create_job_finish_webhook.gif) 53 | 54 | 例如: 如果正确配置了 Slack 发送消息的请求，当任务完成后，会发送所对应的消息到 Slack 频道中 55 | 56 | ![send_webhook_trigger](../../_images/trigger/send_job_finish_webhook.gif) -------------------------------------------------------------------------------- /cn/upgrade/index.md: -------------------------------------------------------------------------------- 1 | # 版本升级 2 | 3 | ### 从版本 1.22.xx 升级至 1.23.xx 4 | 5 | 由于数据库的改动，需要在 `mongodb` 中执行以下脚本，否则会服务启动失败 6 | 7 | ```bash 8 | db.job.dropIndex('index_flow_id') 9 | db.flow_yml.dropIndex('index_flow_id') 10 | db.flow_yml.dropIndex('index_flow_id_and_yaml_name') 11 | ``` 12 | -------------------------------------------------------------------------------- /cn/yml/plugins.md: -------------------------------------------------------------------------------- 1 | # 插件 2 | 3 | 在 flow.ci 中配置插件非常简单，只需要在工作流 YAML 中配置插件名称即可, 例如: `gitclone` 插件 4 | 5 | ```yml 6 | envs: 7 | FLOWCI_GIT_URL: "https://github.com/gin-gonic/gin.git" 8 | 9 | steps: 10 | - name: clone 11 | plugin: 'gitclone' 12 | ``` 13 | 14 | 插件列表，以及插件说明可以在工作流设置 `settings` -> `YAML` -> `plugins` 找到。 15 | 16 | ![list](../../src/plugins.png) 17 | -------------------------------------------------------------------------------- /cn/yml/reference_v1.md: -------------------------------------------------------------------------------- 1 | # YAML 参考 2 | 3 | * [`envs`](#envs) 4 | * [`condition`](#condition) 5 | * [`selector`](#selector) 6 | * [`docker` / `dockers`](#docker/dockers) 7 | * `image` 8 | * `auth` 9 | * `name` 10 | * `ports` 11 | * `user` 12 | * `entrypoint` 13 | * `command` 14 | * `environment` 15 | * `network` 16 | * `is_runtime` 17 | * `stop_on_finish` 18 | * `delete_on_finish` 19 | * [`notifications`](#notifications) 20 | * `plugin` 21 | * `envs` 22 | * [`steps`](#steps) 23 | - 并行任务 24 | * [`parallel`](#parallel) 25 | - 普通任务 26 | * [`name`](#name) 27 | * [`condition`](#condition) 28 | * [`allow_failure`](#allow_failure) 29 | * [`retry`](#retry) 30 | * [`timeout`](#timeout) 31 | * [`envs`](#envs) 32 | * [`secrets`](#secrets) 33 | * [`bash`](#bash) 34 | * [`pwsh`](#pwsh) 35 | * [`docker` / `dockers`](#docker/dockers) 36 | * `image` 37 | * `auth` 38 | * `name` 39 | * `ports` 40 | * `user` 41 | * `entrypoint` 42 | * `command` 43 | * `environment` 44 | * `network` 45 | * `is_runtime` 46 | * `stop_on_finish` 47 | * `delete_on_finish` 48 | * [`plugin`](#plugin) 49 | * [`exports`](#exports) 50 | 51 | ----------- 52 | 53 | ## __envs__ 54 | 55 | 全局环境变量，可以在所有的 Step 中使用 56 | 57 | ```yaml 58 | envs: 59 | FIRST_ENV: "first var" 60 | SECOND_ENV: "hello world" 61 | ``` 62 | 63 | ## __condition__ 64 | 65 | Groovy 脚本定义工作流启动的条件，在脚本中可用的环境变量在[这里 (仅在 Git 章节中)](../agents/vars.md)。 66 | 67 | > 手动启动时该定义无效。 68 | 69 | 例如以下代码，定义了工作流只能在 分支为 `master` 并且才 GitHub 推送时才会启动 70 | 71 | ```yaml 72 | condition: | 73 | return FLOWCI_GIT_BRANCH == "master" && FLOWCI_GIT_SOURCE == "GITHUB" 74 | ``` 75 | 76 | ## __selector__ 77 | 78 | `selector` 可以根据 Agent 的 Tag 来决定当前工作流运行在哪个 Agent 上运行，如果该配置为空，则当前工作流可以运行在所有的 Agent 上。 79 | 80 | ```yaml 81 | selector: 82 | label: 83 | - ios 84 | - local 85 | ``` 86 | 87 | ## __docker/dockers__ 88 | 89 | 当配置 `docker` 或者 `dockers` 时，说明当前工作流的所有 Step 将运行在容器中。 90 | 91 | ### 配置 Docker (`docker`) 92 | 93 | ```yml 94 | docker: 95 | image: ubuntu:18.04 # 必填项 96 | auth: secret_name # 可选, 如果 docker 镜像为私有，则输入 secret 名称，secret 从管理员 -> 添加 -> secret 类型为 'Auth pair' 97 | name: your_container_name # 可选，容器名称 98 | ports: # 可选 99 | - "8080:8080" 100 | - "9090:9090" 101 | user: root # 可选, 默认为 root 102 | entrypoint: # 可选, 默认为 "/bin/bash" 103 | - "/bin/bash" 104 | stop_on_finish: 'true' # 可选, 默认为 true 105 | delete_on_finish: 'ture' # 可选, 默认为 true 106 | 107 | steps: 108 | - name: step name 109 | allow_failure: true 110 | envs: 111 | MY_ENV: "hello" 112 | script: | 113 | echo $MY_ENV 114 | ``` 115 | 116 | ### 配置多个 Docker (`dockers`) 117 | 118 | 例如下面的配置，每个 Step 运行时启动 3 个容器 (Image 分别为 ubuntu:18.04, mysql:5.6, rabbitmq:3)， 其中 ubuntu:18.04 为 Step 的运行环境. 119 | 120 | ```yml 121 | dockers: 122 | - image: ubuntu:18.04 123 | entrypoint: ["/bin/bash"] # 可选, 默认为 /bin/bash 124 | is_runtime: true # # 可选, 默认为列表中的第一个为 Step 的运行环境 125 | 126 | - image: mysql:5.6 127 | environment: # 可选, 可以配置容器的环境变量 128 | MYSQL_ROOT_PASSWORD: my_password 129 | ports: # 可选 130 | - "3306:3306" 131 | user: root # 可选, 默认为 root 132 | entrypoint: [] # 可选, 默认为空 133 | command: [] # 可选, 默认为空 134 | network_mode: "bridge" # 可选, 默认为 bridge 135 | stop_on_finish: 'true' # 可选, 默认为 true 136 | delete_on_finish: 'ture' # 可选, 默认为 true 137 | 138 | - image: rabbitmq:3 139 | 140 | steps: 141 | - name: step name 142 | allow_failure: true 143 | envs: 144 | MY_ENV: "hello" 145 | script: | 146 | echo $MY_ENV 147 | ``` 148 | 149 | ## __notifications__ 150 | 151 | 消息通知配置，可以使用消息通知类型的插件，当任务结束后发送通知。 152 | 153 | ```yaml 154 | notifications: 155 | - plugin: 'email-notify' 156 | envs: 157 | FLOWCI_SMTP_CONFIG: 'test-config' 158 | ``` 159 | 160 | ## __steps__ 161 | 162 | 事例: 163 | 164 | ```yml 165 | envs: 166 | # Git config 167 | FLOWCI_GIT_URL: "https://github.com/FlowCI/gin.git" 168 | 169 | steps: 170 | - name: clone # 普通任务 171 | docker: 172 | image: flowci/debian-git 173 | plugin: 'gitclone' 174 | cache: 175 | key: repo 176 | paths: 177 | - "./${FLOWCI_GIT_REPO}" 178 | 179 | - parallel: # 并行任务 180 | lint-flow: 181 | steps: 182 | - name: lint 183 | plugin: 'go-lint' 184 | allow_failure: true 185 | cache: 186 | key: repo 187 | 188 | test-flow: 189 | steps: 190 | - name: test 191 | docker: 192 | image: golang:1.12 193 | plugin: 'go-test' 194 | cache: 195 | key: repo 196 | 197 | ``` 198 | 199 | ### __并行任务__ 200 | 201 | #### __parallel__ 202 | 203 | 并行任务定义在 `parallel` 中，可以定义并行执行的子工作流，其会并行执行在所需要的 Agent 中 204 | 205 | ```yml 206 | - parallel: 207 | lint-flow: # 并行任务中子工作流的名称, 例如 'lint-flow' 208 | selector: # Agent 选择器，该子工作流会在具有 local 标签的 Agent 中执行 209 | label: 210 | - local 211 | steps: 212 | - name: lint # 子工作流的任务 213 | plugin: 'go-lint' 214 | allow_failure: true 215 | cache: 216 | key: repo 217 | 218 | test-flow: # 并行任务中子工作流的名称, 例如 'test-flow' 219 | selector: # Agent 选择器，该子工作流会在具有 remote 标签的 Agent 中执行 220 | label: 221 | - remote 222 | steps: 223 | - name: test # 子工作流的任务 224 | docker: 225 | image: golang:1.12 226 | plugin: 'go-test' 227 | cache: 228 | key: repo 229 | ``` 230 | 231 | ### __普通任务__ 232 | 233 | #### __name__ 234 | 235 | 可以自定义 Step 的名称，默认值为 step-1, step-2, step-xx 236 | 237 | ```yml 238 | steps: 239 | - name: step name 240 | ``` 241 | 242 | #### __condition__ 243 | 244 | 可以定义一个返回值为布尔的 Groovy 脚本，确定该 Step 可否运行 245 | 246 | ```yml 247 | steps: 248 | - name: step name 249 | envs: 250 | my_var: "hello" 251 | conditon: | 252 | ## groovy script that return boolean value 253 | return "$my_var" == "hello"; 254 | ``` 255 | 256 | #### __allow_failure__ 257 | 258 | 允许失败，如果该值为 `true`，则表示 Step 失败后可继续运行后面的 Step。默认值为 `false` 259 | 260 | ```yml 261 | steps: 262 | - name: step name 263 | allow_failure: true 264 | ``` 265 | 266 | 267 | #### __retry__ 268 | 269 | 定义当任务失败时，重试的次数。 270 | 271 | ```yml 272 | steps: 273 | - name: step name 274 | allow_failure: true 275 | retry: 5 276 | bash: 277 | echo "start" 278 | fail_here. 279 | ``` 280 | 281 | #### __timeout__ 282 | 283 | 定义任务的过期时间，单位为秒。 284 | 285 | ```yml 286 | steps: 287 | - name: step name 288 | allow_failure: true 289 | timeout: 3600 290 | bash: 291 | echo "start" 292 | sleep 1000 293 | ``` 294 | 295 | #### __envs__ 296 | 297 | Step 级别的环境变量 （优先级高于工作流级别） 298 | 299 | ```yml 300 | steps: 301 | - name: step name 302 | allow_failure: true 303 | envs: 304 | MY_ENV: "hello" 305 | ``` 306 | 307 | #### __secrets__ 308 | 309 | 引入 `secret` 作为可使用的环境变量 310 | 311 | ```yml 312 | steps: 313 | - name: step name 314 | allow_failure: true 315 | envs: 316 | MY_ENV: "hello" 317 | secrets: 318 | - my_auth_secret 319 | - my_token_secret 320 | - my_rsa_key 321 | bash: | 322 | echo "--- HOW TO use auth secret ---" 323 | echo '{secret name}_USERNAME' 324 | echo "{secret name}_PASSWORD" 325 | 326 | echo "${my_auth_secret_USERNAME}" 327 | echo "${my_auth_secret_PASSWORD}" 328 | echo "------------------------------" 329 | 330 | echo "--- HOW TO use token secret ---" 331 | echo '{secret name}' 332 | 333 | echo "${my_token_secret}" 334 | echo "------------------------------" 335 | 336 | echo "--- HOW TO use rsa (SSH) secret ---" 337 | echo '{secret name}_PUBLIC_KEY' 338 | 339 | echo "${my_rsa_secret_PUBLIC_KEY}" 340 | echo "------------------------------" 341 | 342 | ``` 343 | 344 | #### __cache__ 345 | 346 | 在 `paths` 中定义的路径为任务路径 `FLOWCI_AGENT_JOB_DIR` 的相对路径 347 | 348 | ```yml 349 | cache: 350 | key: mycache # 缓存名称 351 | paths: 352 | - "./" # 任务根目录，缓存在任务路径 FLOWCI_AGENT_JOB_DIR 下的所有文件 353 | - "vendor" # 缓存任务路径 FLOWCI_AGENT_JOB_DIR 下的 vendor 目录 354 | ``` 355 | 356 | 如果 `paths` 没有定义，此时为只读缓存，只会下载对应的缓存到本地 357 | 358 | ```yml 359 | cache: 360 | key: mycache 361 | ``` 362 | 363 | 事例: 364 | 365 | ```yml 366 | steps: 367 | - name: step name 368 | allow_failure: true 369 | envs: 370 | MY_ENV: "hello" 371 | bash: | 372 | echo 'apply cache' 373 | cache: 374 | key: mycache 375 | paths: 376 | - "./${FLOWCI_GIT_REPO}" # 缓存 git 目录 377 | ``` 378 | 379 | #### __bash__ 380 | 381 | 要执行的 Bash 脚本 382 | 383 | ```yml 384 | steps: 385 | - name: step name 386 | allow_failure: true 387 | envs: 388 | MY_ENV: "hello" 389 | script: | 390 | echo $MY_ENV 391 | ``` 392 | 393 | #### __pwsh__ 394 | 395 | 定义需要执行的 PowerShell 脚本，仅在 Windows Agent 中运行 396 | 397 | ```yml 398 | steps: 399 | - name: step name 400 | allow_failure: true 401 | envs: 402 | MY_ENV: "hello" 403 | pwsh: | 404 | echo $Env:MY_ENV 405 | ``` 406 | 407 | #### __docker/dockers__ 408 | 409 | Step 级别的设置（优先级高于工作流级别），具体配置请参考工作流的 [`docker` / `dockers`](#docker/dockers) 配置 410 | 411 | #### __plugin__ 412 | 413 | 在 Step 中应用插件， 414 | 415 | > 当插件应用后， `script` 为可选项, 如果 `script` 定义了脚本，则会在插件执行前执行。 416 | 417 | ```yml 418 | steps: 419 | - name: run unit test 420 | envs: 421 | ENV_FOR_PLUGIN: "xxx" 422 | plugin: 'maven-test' # the plugin name 423 | ``` 424 | 425 | #### __exports__ 426 | 427 | 输出环境变量，所输出的环境变量可以在之后的 Step 中使用。 428 | 429 | ```yml 430 | steps: 431 | - name: step name 432 | script: | 433 | echo $MY_ENV 434 | export ENV_FOR_NEXT_STEP="hello" 435 | exports: 436 | - "ENV_FOR_NEXT_STEP" 437 | ``` 438 | -------------------------------------------------------------------------------- /en/README.md: -------------------------------------------------------------------------------- 1 |

2 | 3 | Logo 4 | 5 |

6 | 7 |

A Simple & Powerful CI/CD Server

8 | 9 |

10 | 11 | 12 | GitHub Org's stars 13 | Docker Pulls 14 |

15 | 16 |
17 | 18 | **English | [简体中文](cn/README.md)** 19 | 20 |
21 | 22 | ## What is flow.ci? 23 | 24 | flow.ci is an open-source CI/CD automation server that designed for setting up a self-hosted CI/CD service with the easiest, fastest and most painless way. It supports high availability, multiple building environment, and scalability with dynamic agents. 25 | 26 | 27 | - __High Availability__ 28 | 29 | flow.ci is designed to work in the cloud -- public, private, or hybrid, it could be deployed with multiple instances, the configuration/jobs data on the node may not be lost when the instance fails. 30 | 31 | - __High Performance__ 32 | 33 | - __scaling__: auto scaling agents either on K8s cluster or Linux host 34 | - __parallel__: job steps can be executed in parallel on multiple agents 35 | - __cache__: cache anything to speed up the build 36 | 37 | - __Zero Configuration__ 38 | 39 | flow.ci tries to minimize the complexity of any configuration, the server could be started with three command lines. It also provides build templates of many programming languages, a job could be started just using it. 40 | 41 | - __Online Debugging__ 42 | 43 | flow.ci supports the online TTY terminal so that you could find out the problems in the running job from runtime terminal. 44 | 45 | - __Flexible Plugins__ 46 | 47 | Using plugins on flow.ci is quite simple, you just need type the plugin name in the step. Developing a plugin is also quite easy, you could use any language on your own plugin development. 48 | 49 | - __Flexible Runtime__ 50 | 51 | Each step or step group can be run either on any docker images or native os. 52 | 53 | ## Quick start 54 | 55 | > [Docker](https://docs.docker.com/install/) & [Docker-Compose](https://docs.docker.com/compose/install/) are required 56 | 57 | ```bash 58 | git clone https://github.com/FlowCI/docker.git flow-docker 59 | cd flow-docker 60 | ./server.sh start 61 | ``` 62 | 63 | ## Help 64 | 65 | Need Help? submit issue from [here](https://github.com/FlowCI/docs/issues) or send email to `flowci@foxmail.com` 66 | 67 | 68 | ## Templates 69 | 70 | [maven, npm, golang, ruby, android and more](https://github.com/FlowCI/templates) 71 | 72 | 73 | ## Architecture 74 | 75 | ![architecture](https://github.com/FlowCI/docs/raw/master/_images/architecture.png) 76 | 77 | ## Preview 78 | ![demo](https://github.com/FlowCI/docs/raw/master/_images/demo.gif) 79 | -------------------------------------------------------------------------------- /en/_sidebar.md: -------------------------------------------------------------------------------- 1 | 2 | * Quick Start 3 | * [Install](en/start/index.md#Install) 4 | * [Set URL](en/start/index.md#set-server-url) 5 | * [Create a flow](en/start/index.md#create-a-flow) 6 | * [Run](en/start/index.md#run) 7 | 8 | * Flow 9 | * [Structure](en/flow/structure.md#flow-structure) 10 | 11 | * Job 12 | * [Start](en/job/start.md) 13 | * [Workspace](en/job/workspace.md) 14 | * [Conditions](en/job/condition.md) 15 | * [Environment with Docker](en/job/docker.md) 16 | * [Parallel](en/job/parallel.md) 17 | * [Cache](en/job/cache.md) 18 | * [Crontab](en/job/schedule.md) 19 | * [Web Terminal](en/job/web_terminal.md) 20 | 21 | * Git Integration 22 | * [Git setup](en/git/index.md) 23 | * [Github](en/git/github.md) 24 | * [Gitlab](en/git/gitlab.md) 25 | * [Gogs](en/git/gogs.md) 26 | * [Gitee](en/git/gitee.md) 27 | * [Gerrit](en/git/gerrit.md) 28 | 29 | * Agent 30 | * [What is Agent](en/agents/index.md) 31 | * [Add Agent](en/agents/manual.md) 32 | * Auto Scaling 33 | * [Kubernates](en/agents/k8s_host.md) 34 | * [SSH Host](en/agents/ssh_host.md) 35 | 36 | * Secret 37 | * [SSH-RSA](en/secret/ssh-rsa.md) 38 | * [Auth](en/secret/auth.md) 39 | * [Token](en/secret/token.md) 40 | * [Android Sign](en/secret/android_sign.md) 41 | * [K8s kubeconfig](en/secret/kubeconfig.md) 42 | 43 | 44 | * Config 45 | * [SMTP](en/config/smtp.md) 46 | * [Free Text](en/config/freetext.md) 47 | 48 | * Trigger 49 | * [`OnJobFinish` Event](en/trigger/on_job_finish.md) 50 | - [Email Trigger](en/trigger/on_job_finish.md#send-email) 51 | - [Webhook Trigger](en/trigger/on_job_finish.md#send-http-request) 52 | 53 | * Plugins 54 | 55 | * Reference 56 | * [YAML](en/yml/reference_v1.md) 57 | * [Variables](en/agents/vars.md) 58 | * [Upgrade](en/upgrade/index.md) -------------------------------------------------------------------------------- /en/agents/index.md: -------------------------------------------------------------------------------- 1 | # Agent 2 | 3 | Jobs are executed by Agents. 4 | 5 | Agent coulde be started from `binary` or `Docker`. 6 | 7 | Auto scaling agents are available from Kubernates or on SSH host. 8 | 9 | * [Add Agent](en/agents/manual) 10 | 11 | * Auto scaling 12 | - [Kubernates](en/agents/k8s_host) 13 | - [SSH host](en/agents/ssh_host) -------------------------------------------------------------------------------- /en/agents/k8s_host.md: -------------------------------------------------------------------------------- 1 | # Auto scalling on K8s Cluster 2 | 3 | Another way to setup agent is config hosts on ci server, and then flow.ci will create and manage agent by k8s pod automatically. 4 | 5 | ![ssh host structure](../../_images/agents/k8s_host_structure.png) 6 | 7 | ## Config Cluster 8 | 9 | * Click `Settings` -> `Agents` -> `+` 10 | * Select `Dynmaic agent` 11 | * Specify unique host name 12 | * Specify tag (optional) 13 | 14 | Agent tag is used for flow which has `selector` configuration in YAML, that means the flow job runs only on the agent with matched tags. 15 | 16 | For example, if YAML specified `selector` like the following, so that job will runs only on Agents with tag `ios`. 17 | 18 | ```yaml 19 | selector: 20 | label: 21 | - ios 22 | ``` 23 | 24 | * Fill in cluster detail 25 | * Namespace: namespace for dynmaic agents 26 | * Secret: kube config secret to gain access permission for cluster. you have to create secret first and then select it here. 27 | * Max Pool Size: max docker agents will be run in the cluster 28 | 29 | * Click `Save` 30 | 31 | The host will be shown on the list 32 | 33 | ![how to create host](../../_images/agents/k8s_host_create.gif) -------------------------------------------------------------------------------- /en/agents/manual.md: -------------------------------------------------------------------------------- 1 | # Add Agent 2 | 3 | Agent is an application to run real jobs, you have to create an Agent and start it before job started. 4 | 5 | > if installed from [docker-install](https://github.com/FlowCI/docker-install.git) repo, there are default dynamic Agent configuread locally, which means you can start build without agent setup. 6 | 7 | ## Add an Agent from admin page 8 | 9 | * Click `Settings` -> `Agents` -> `+` 10 | * Select `Manual agent` 11 | * Specify unique agent name 12 | * Specify tag (optional) 13 | 14 | Agent tag is used for flow which has `selector` configuration in YAML, that means the flow job runs only on the agent with matched tags. 15 | 16 | For example, if YAML specified `selector` like the following, so that job will runs only on Agents with tag `ios`. 17 | 18 | ```yaml 19 | selector: 20 | label: 21 | - ios 22 | ``` 23 | 24 | * Click `Save` 25 | 26 | The created agent will be shown on the list 27 | 28 | ![how to create agent](../../_images/agents/create_agent.gif) 29 | 30 | ## Start an Agent 31 | 32 | ### Start from Docker 33 | 34 | The most easiest way is start agent from [docker-install](https://github.com/flowci/docker-install) repo by run `./agent.sh` script. 35 | 36 | Or start from the following script, and replace the value of `FLOWCI_SERVER_URL` and `FLOWCI_AGENT_TOKEN` 37 | 38 | ```bash 39 | docker run -it \ 40 | -e FLOWCI_SERVER_URL= \ 41 | -e FLOWCI_AGENT_TOKEN= \ 42 | -e FLOWCI_AGENT_VOLUMES="name=pyenv,dest=/ci/python,script=init.sh,image=flowci/pyenv,init=init-pyenv-volume.sh" \ 43 | -v /var/run/docker.sock:/var/run/docker.sock \ 44 | flowci/agent 45 | ``` 46 | 47 | ### Start from Binary 48 | 49 | The latest agent binary file can be found from [here](https://github.com/FlowCI/flow-agent-x/releases) 50 | 51 | Environments (optional, for full functionality): 52 | - Python >= 3.6 53 | - required pip libs: `pip install requests==2.22.0 python-lib-flow.ci` 54 | - Docker 55 | 56 | __Linux__ 57 | 58 | Replace `{version}`, `{ci_server_url}`, `{agent_token}` and run the following Bash in terminal 59 | 60 | ```bash 61 | wget https://github.com/FlowCI/flow-agent-x/releases/download/{version}/flow-agent-x-linux 62 | chmod +x flow-agent-x-linux 63 | ./flow-agent-x-linux -u {ci_server_url} -t {agent_token} -m name=pyenv,dest=/ci/python,script=init.sh,image=flowci/pyenv,init=init-pyenv-volume.sh 64 | ``` 65 | 66 | __MacOS__ 67 | 68 | Replace `{version}`, `{ci_server_url}`, `{agent_token}` and run the following Bash in terminal 69 | 70 | ```bash 71 | wget https://github.com/FlowCI/flow-agent-x/releases/download/{version}/flow-agent-x-mac 72 | chmod +x flow-agent-x-mac 73 | ./flow-agent-x-mac -u {ci_server_url} -t {agent_token} -m name=pyenv,dest=/ci/python,script=init.sh,image=flowci/pyenv,init=init-pyenv-volume.sh 74 | ``` 75 | 76 | __Windows (x64)__ 77 | 78 | Replace `{version}`, `{ci_server_url}`, `{agent_token}` and run the following PowerShell in terminal 79 | 80 | ```powershell 81 | Invoke-WebRequest https://github.com/FlowCI/flow-agent-x/releases/download/{version}/flow-agent-x-win -OutFile flow-agent-x-win.exe 82 | .\flow-agent-x-linux -u {ci_server_url} -t {agent_token} -m name=pyenv,dest=/ci/python,script=init.sh,image=flowci/pyenv,init=init-pyenv-volume.sh 83 | ``` 84 | 85 | -------------------------------------------------------------------------------- /en/agents/ssh_host.md: -------------------------------------------------------------------------------- 1 | # Auto scalling on a host via SSH 2 | 3 | Another way to setup agent is config hosts on ci server, and then flow.ci will create and manage agent by docker on the host via ssh automatically. 4 | 5 | ![ssh host structure](../../_images/agents/ssh_host_structure.png) 6 | 7 | ## 1. Create a host 8 | 9 | * Click `Settings` -> `Agents` -> `+` 10 | * Select `Dynamic agent` 11 | * Specify unique host name 12 | * Specify tag (optional) 13 | 14 | Agent tag is used for flow which has `selector` configuration in YAML, that means the flow job runs only on the agent with matched tags. 15 | 16 | For example, if YAML specified `selector` like the following, so that job will runs only on Agents with tag `ios`. 17 | 18 | ```yaml 19 | selector: 20 | label: 21 | - ios 22 | ``` 23 | 24 | * Fill in host detail 25 | * Secret: to gain access permission in the host (you have to create `ssh key` secret, and copy the public key to `.ssh/authorized_keys` in the host) 26 | 27 | * User: username for ssh login 28 | 29 | * IP: host ip address 30 | 31 | * Max Pool Size: max docker agents will be run in the host 32 | 33 | * Click `Save` 34 | 35 | The host will be shown on the list 36 | 37 | ![how to create host](../../_images/agents/create_host.gif) 38 | 39 | ## 2. Setup the host 40 | 41 | * Copy public key into `.ssh/authorzied_keys` 42 | 43 | * Run [init script](https://github.com/FlowCI/docker-install/blob/master/host-init.sh) in the host, to steup required docker environment 44 | 45 | * Test connection 46 | 47 | ![test host](../../_images/agents/test_host.gif) -------------------------------------------------------------------------------- /en/agents/vars.md: -------------------------------------------------------------------------------- 1 | # Variables which available in Agent 2 | 3 | ## Common 4 | 5 | - `FLOWCI_SERVER_URL` 6 | 7 | - `FLOWCI_FLOW_NAME` 8 | 9 | - `FLOWCI_FLOW_WEBHOOK` 10 | 11 | ## Job 12 | 13 | - `FLOWCI_JOB_BUILD_NUM` 14 | 15 | - `FLOWCI_JOB_STATUS` 16 | 17 | - `FLOWCI_JOB_TRIGGER` 18 | 19 | - `FLOWCI_JOB_URL` 20 | 21 | - `FLOWCI_JOB_START_AT` 22 | 23 | - `FLOWCI_JOB_FINISH_AT` 24 | 25 | - `FLOWCI_JOB_DURATION` 26 | 27 | ## Agent 28 | 29 | - `FLOWCI_AGENT_TOKEN` 30 | 31 | - `FLOWCI_AGENT_PORT` 32 | 33 | - `FLOWCI_AGENT_WORKSPACE` 34 | 35 | - `FLOWCI_AGENT_JOB_DIR` 36 | 37 | - `FLOWCI_AGENT_PLUGIN_DIR` 38 | 39 | - `FLOWCI_AGENT_IP_{interface name}`: interface name for example: en0, en1 40 | 41 | ## Docker Container (if step with docker section) 42 | 43 | - `FLOWCI_AGENT_DOCKER_NETWORK`: current docker network name 44 | 45 | - `CONTAINER_ID_{container index}`: container index start from 0 46 | 47 | - `CONTAINER_IP_{container index}` 48 | 49 | ## Git 50 | 51 | - `FLOWCI_GIT_REPO`: the git repo name, you could access repo by '${FLOWCI_AGENT_JOB_DIR}/${FLOWCI_GIT_REPO}' 52 | 53 | - `FLOWCI_GIT_SOURCE`: `GITHUB` | `GITLAB` | `GOGS` | `GITEE` 54 | 55 | - `FLOWCI_GIT_EVENT`: `PUSH` | `TAG` | `PR_OPENED` | `PR_MERGED` 56 | 57 | 58 | #### Push / Tag 59 | 60 | - `FLOWCI_GIT_BRANCH` 61 | 62 | - `FLOWCI_GIT_AUTHOR` 63 | 64 | - `FLOWCI_GIT_COMMIT_MESSAGE`: Commit message of latest commit 65 | 66 | - `FLOWCI_GIT_COMMIT_TOTAL`: 67 | 68 | - `FLOWCI_GIT_COMMIT_LIST`: commit list, base64 format. example: `base64([{id:xx, message: xxx, time:xxx, url: xxx, author: {name: xx, email: xx}}, {xxx}, ...])` 69 | 70 | #### PR 71 | 72 | - `FLOWCI_GIT_PR_TITLE` 73 | - `FLOWCI_GIT_PR_MESSAGE` 74 | - `FLOWCI_GIT_PR_URL` 75 | - `FLOWCI_GIT_PR_TIME` 76 | - `FLOWCI_GIT_PR_NUMBER` 77 | 78 | - `FLOWCI_GIT_PR_HEAD_REPO_NAME` 79 | - `FLOWCI_GIT_PR_HEAD_REPO_BRANCH` 80 | - `FLOWCI_GIT_PR_HEAD_REPO_COMMIT` 81 | 82 | - `FLOWCI_GIT_PR_BASE_REPO_NAME` 83 | - `FLOWCI_GIT_PR_BASE_REPO_BRANCH` 84 | - `FLOWCI_GIT_PR_BASE_REPO_COMMIT` 85 | -------------------------------------------------------------------------------- /en/config/freetext.md: -------------------------------------------------------------------------------- 1 | # Free text Config 2 | 3 | ## Create 4 | 5 | 1. Click `Settings` -> `Config` -> `+` 6 | 2. Enter a Config name 7 | 3. Select `Text` in category field 8 | 4. Type configuration data 9 | 5. Save 10 | 11 | ![create smtp](../../_images/config/create_text.gif) 12 | 13 | 14 | ## How to 15 | 16 | - Access `Free Text` Config from script 17 | 18 | For example: customize Maven `settings.xml` in .m2 directory, you can type XML configuration from text field 19 | 20 | ```xml 21 | 22 | 23 | 24 | ... 25 | 26 | 27 | 28 | ``` 29 | 30 | Apply `configs` and type Config name from step YAML 31 | 32 | ```yaml 33 | steps: 34 | - name: set maven settings 35 | configs: 36 | - my_xml_config 37 | bash: | 38 | echo ${my_xml_config} 39 | echo ${my_xml_config} > ~/.m2/settings.xml 40 | ``` 41 | -------------------------------------------------------------------------------- /en/config/smtp.md: -------------------------------------------------------------------------------- 1 | # SMTP Config 2 | 3 | ## Create 4 | 5 | 1. Click `Settings` -> `Config` -> `+` 6 | 2. Enter Config name 7 | 2. Select `SMTP` in category field 8 | 3. Type required data: 9 | - `Server` 10 | - `Port` 11 | - `Username` 12 | - `Password` 13 | - Select encryption type: `None`, `SSL` or `TLS` 14 | 4. Save 15 | 16 | ![create smtp](../../_images/config/create_smtp.gif) 17 | 18 | ## How to 19 | 20 | - Access `SMTP` Config from script 21 | 22 | It can be accessed from script if the `configs` has beed defined in `step` YAML 23 | 24 | ```yaml 25 | steps: 26 | - name: smtp config demo 27 | configs: 28 | - default_smtp 29 | bash: | 30 | echo ${default_smtp_SERVER} 31 | echo ${default_smtp_PORT} 32 | echo ${default_smtp_SECURE_TYPE} 33 | echo ${default_smtp_AUTH_USERNAME} 34 | echo ${default_smtp_AUTH_PASSWORD} 35 | ``` 36 | 37 | - Apply `SMTP` Config in Trigger 38 | 39 | For example, send job notification email with Gmail: 40 | 41 | - `Server`: stmp.gmail.com 42 | - `Port`: 587 43 | - `Username`: Gmail username 44 | - `Password`: Gmail password 45 | - Select `TLS` 46 | 47 | Also need to modify Gmail security setting: 48 | 49 | - Login to Gmail 50 | - Find `Security > Less secure app access` 51 | - Click `Turn on access` 52 | 53 | ![gmail_1](../../_images/config/gmail_setting_1.png) 54 | ![gmail_2](../../_images/config/gmail_setting_2.png) 55 | 56 | About how to setup email trigger, please refer [Email Trigger](en/trigger/on_job_finish.md#send-email) 57 | -------------------------------------------------------------------------------- /en/flow/structure.md: -------------------------------------------------------------------------------- 1 | # Flow Structure 2 | 3 | Flow is the top-level component of flow.ci for CI/CD or other kinds of job 4 | 5 | The basic elements of flow include: 6 | - steps 7 | - step 8 | - parallel 9 | 10 | ![structure](../../_images/flow/structure.png) 11 | 12 | ### Let's make an example! 13 | 14 | 15 | Clone the code from git repo, run test for both Java 8 and 11, and then deploy to two environments. 16 | 17 | 18 | ![sample](../../_images/flow/sample.png) 19 | 20 | 21 | Repersent the above diagram by YAML 22 | 23 | ```yaml 24 | 25 | steps: 26 | - name: git clone 27 | bash: | 28 | echo "run git clone" 29 | 30 | - name: steps for build 31 | docker: 32 | image: "my build image" 33 | steps: 34 | - name: build_a 35 | bash: | 36 | echo "run build step a" 37 | - name: build_b 38 | bash: | 39 | echo "run build step b" 40 | 41 | - parallel: 42 | java_8_test: 43 | docker: 44 | image: "java 8 image" 45 | steps: 46 | - name: test a 47 | bash: | 48 | echo "run test a for java 8" 49 | - name: test b 50 | bash: | 51 | echo "run test b for java 8" 52 | 53 | java_11_test: 54 | docker: 55 | image: "java 11 image" 56 | steps: 57 | - name: test a 58 | bash: | 59 | echo "run test a for java 11" 60 | - name: test b 61 | bash: | 62 | echo "run test b for java 11" 63 | 64 | 65 | - parallel: 66 | deploy_to_a: 67 | steps: 68 | - name: deploy 69 | bash: | 70 | echo "deploy to environment a" 71 | 72 | deploy_to_b: 73 | steps: 74 | - name: deploy 75 | bash: | 76 | echo "deploy to environment b" 77 | 78 | ``` 79 | 80 | For more YAML configuration, please refer [YAML Reference](/en/yml/reference_v1) -------------------------------------------------------------------------------- /en/git/gerrit.md: -------------------------------------------------------------------------------- 1 | # Gerrit Integration 2 | 3 | ## Setup Access Permission for Private Repo 4 | 5 | Copy `public key` from flow.ci secret page 6 | 7 | Open Gerrit and add it from `{your_gerrit_host}/settings/#SSHKeys` to your account. (make sure the accout has access right to git repo) 8 | 9 | ![setup_deploy_key](../../_images/git/gerrit_setup_ssh_key.png) 10 | 11 | ## Setup Webhook 12 | 13 | Webhook is a way of how to trigger CI job from Gerrit. 14 | 15 | 1. Make sure the [webhook plugin](https://gerrit.googlesource.com/plugins/webhooks/) is installed in the Gerrit, you could install it from Gerrit plugin manager. 16 | 17 | ![webhook plugin](../../_images/git/gerrit_webhook_plugin.png) 18 | 19 | 20 | 2. Go into the local git repo folder which is cloned from Gerrit, and checkout `meta/config` branch 21 | 22 | ```bash 23 | git fetch origin refs/meta/config:refs/remotes/origin/meta/config 24 | git checkout meta/config 25 | ``` 26 | 27 | 3. Copy webhook url from flow settings 28 | > Hint: Your host must be exposed to internet (public ip or domain), otherwide the GitHub events can not be received. 29 | > If pulbic ip or domain not availble in your environments, please use the tools like [ngrok](https://ngrok.com/). 30 | 31 | ![webhook settings](../../_images/git/select_webhook_url.gif) 32 | 33 | 34 | 35 | 4. Add the following to `webhooks.config` file (create the file if not existed) 36 | 37 | > flow.ci only support `patchset-created` gerrit event currently 38 | 39 | ``` 40 | [remote "flowci_pathset_created"] 41 | url = {the url copied from step 3} 42 | maxTries = 1 43 | sslVerify = false 44 | event = patchset-created 45 | ``` 46 | 47 | 5. Push the change to `meta/config` branch 48 | 49 | ``` 50 | git push origin meta/config:meta/config 51 | ``` 52 | 53 | 54 | ## Verify Gerrit Settings 55 | 56 | - Verify permission for repo: 57 | 58 | Test the access right from flow settings by click 'test' button, the green will be shown if everything correct. 59 | 60 | ![test](../../_images/git/gerrit_test_config.gif) 61 | 62 | 63 | ## Setup Access permission to Write Job Status to Gerrit 64 | 65 | 1. Create Http Credential in Gerrit 66 | 67 | In order to have permission for writing job status back to Gerrit, we need to create a `HTTP Credentials (GENERATE NEW PASSWORD) ` in Gerrit `{your_gerrit_host}/settings/#HTTPCredentials` 68 | 69 | ![token](../../_images/git/gerrit_create_access_pw.png) 70 | 71 | 2. Add password to flow.ci Secret 72 | 73 | Open the secret settings page `Settings -> Secret -> +` , paste the password copied from Gerrit and save 74 | 75 | ![add token](../../_images/git/add_token.png) 76 | 77 | 3. Setup Gerrit in flow.ci 78 | 79 | Open the git integration page `Settings -> Git -> +`, select `Gerrit` on git source, input your Gerrit host address, and then select a secret created on the last step 80 | 81 | ![link](../../_images/git/gerrit_add_link.png) 82 | 83 | 4. Gerrit Commit Status 84 | 85 | After the configuration, the correspond commit status will be updated after job finished. 86 | 87 | ![commit status](../../_images/git/gerrit_commit_status.png) 88 | -------------------------------------------------------------------------------- /en/git/gitee.md: -------------------------------------------------------------------------------- 1 | # Gitee Integration 2 | 3 | ## Setup Access Permission for Private Repo 4 | 5 | Copy `public key` from admin page, open Gitee repo web and add it from `Settings > Deploy keys -> Add key` for single repo access. Gitee not allowed to add same public key for muliple repositories, we recommend to have a special 'CI user' to manage single public key access. 6 | 7 | ![setup_deploy_key](../../_images/git/gitee_setup_deploy_key.png) 8 | 9 | ## Setup Webhook 10 | 11 | The webhook used for receive git notification such as push, tag, pull request and so on. 12 | 13 | 1. Copy webhook url from flow settings 14 | > Hint: Your host must be exposed to internet (public ip or domain), otherwide the GitHub events can not be received. 15 | > If pulbic ip or domain not availble in your environments, please use the tools like [ngrok](https://ngrok.com/). 16 | 17 | ![webhook settings](../../_images/git/select_webhook_url.gif) 18 | 19 | 2. Setup webhook 20 | 21 | - Payload URL 22 | 23 | Paste webhook url copied from flow settings (step 1) 24 | 25 | > If using `ngrok`, please replace wehbook url by ngrok, ex: `http://172.20.10.4/webhooks/spring-sample` to `http://7e9ea9dc.ngrok.io/webhooks/spring-sample` 26 | 27 | - Select events 28 | 29 | Check events `Push`, `Tag Push` and `Pull Request` 30 | 31 | ![events](../../_images/git/gitee_setup_webhook.png) 32 | 33 | ## Verify Gitee Settings 34 | 35 | - Webhook: 36 | 37 | The green check box will be shown on 'webhook' field if the flow receive the 'ping' request by click 'Test' button on Gitee webhook page. 38 | 39 | - Permission for repo: 40 | 41 | Test the access right from flow settings by click 'test' button, the green will be shown if everything correct. 42 | 43 | ![gitlab_test](../../_images/git/gitee_test_config.gif) -------------------------------------------------------------------------------- /en/git/github.md: -------------------------------------------------------------------------------- 1 | # GitHub Integration 2 | 3 | ## Setup Access Permission for Private Repo 4 | 5 | Copy `public key` from admin page, open GitHub repo web and add it from `Settings > Deploy key` for single repo access. GitHub not allowed to add same public key for muliple repositories, we recommend to have a special 'CI user' to manage single public key access: [adding new ssh key to your GitHub account](https://help.github.com/en/articles/adding-a-new-ssh-key-to-your-github-account). 6 | 7 | ![github_setup_deploy_key](../../_images/git/github_setup_deploy_key.png) 8 | 9 | ## Setup Webhook 10 | 11 | The webhook used for receive git notification such as push, tag, pull request and so on. 12 | 13 | 1. Copy webhook url from flow settings 14 | > Hint: Your host must be exposed to internet (public ip or domain), otherwide the GitHub events can not be received. 15 | > If pulbic ip or domain not availble in your environments, please use the tools like [ngrok](https://ngrok.com/). 16 | 17 | ![webhook settings](../../_images/git/select_webhook_url.gif) 18 | 19 | 2. Setup webhook 20 | 21 | - Payload URL 22 | 23 | Paste webhook url copied from flow settings (step 1) 24 | 25 | > If using `ngrok`, please replace wehbook url by ngrok, ex: `http://172.20.10.4/webhooks/spring-sample` to `http://7e9ea9dc.ngrok.io/webhooks/spring-sample` 26 | 27 | - Content type 28 | 29 | Select content type to `application/json` 30 | 31 | ![payload and content](../../_images/git/github_setup_payload_and_content.png) 32 | 33 | - Select events 34 | 35 | - Select `Let me select individual events` 36 | - Check events `push` and `pull request` 37 | 38 | ![events](../../_images/git/github_select_events.png) 39 | 40 | ## Verify GitHub Settings 41 | 42 | - Webhook: 43 | 44 | The green check box will be shown after 'webhook' field if the flow receive the 'ping' request after GitHub webhook created. 45 | 46 | - Permission for repo: 47 | 48 | Test the access right from flow settings by click 'test' button, the green will be shown if everything correct. 49 | 50 | ![github_test](../../_images/git/github_test_config.gif) 51 | 52 | 53 | ## Setup Access permission to Write Job Status to GitHub 54 | 55 | 1. Create a Token 56 | 57 | In order to have permission for writing job status back to GitHub, we need to create a token with `repo:status` scope from https://github.com/settings/tokens 58 | 59 | ![create token](../../_images/git/github_create_access_token.png) 60 | 61 | 2. Add GitHub Token to flow.ci Secret 62 | 63 | Open the secret settings page `Settings -> Secret -> +` , paste the token copied from Github and save 64 | 65 | ![add token](../../_images/git/add_token.png) 66 | 67 | 3. Setup GitHub 68 | 69 | Open the git integration page `Settings -> Git -> +`, select `GitHub` on git source, and select a secret created on the last step 70 | 71 | ![link](../../_images/git/github_add_link.png) 72 | 73 | 4. GitHub Commit Status 74 | 75 | After the configuration, the correspond commit status will be updated after job finished. 76 | 77 | ![demo](../../_images/git/github_check_updated.png) -------------------------------------------------------------------------------- /en/git/gitlab.md: -------------------------------------------------------------------------------- 1 | # GitLab Integration 2 | 3 | ## Setup Access Permission for Private Repo 4 | 5 | Copy `public key` from admin page, open GitLab repo web and add it from `Settings > Repository -> Deploy Keys` for single repo access. GitLab not allowed to add same public key for muliple repositories, we recommend to have a special 'CI user' to manage single public key access 6 | 7 | ![gitlab_setup_deploy_key](../../_images/git/gitlab_setup_deploy_key.png) 8 | 9 | ## Setup Webhook 10 | 11 | The webhook used for receive git notification such as push, tag, pull request and so on. 12 | 13 | 1. Copy webhook url from flow settings 14 | > Hint: Your host must be exposed to internet (public ip or domain), otherwide the gitlab events can not be received. 15 | > If pulbic ip or domain not availble in your environments, please use the tools like [ngrok](https://ngrok.com/). 16 | 17 | ![webhook settings](../../_images/git/select_webhook_url.gif) 18 | 19 | 2. Setup webhook 20 | 21 | - URL 22 | 23 | Paste webhook url copied from flow settings (step 1) 24 | 25 | > If using `ngrok`, please replace wehbook url by ngrok, ex: `http://172.20.10.4/webhooks/spring-sample` to `http://7e9ea9dc.ngrok.io/webhooks/spring-sample` 26 | 27 | - Select events 28 | 29 | Check events `Push events`, `Tag push events` and `Merge request events` 30 | 31 | ![events](../../_images/git/gitlab_setup_webhook.png) 32 | 33 | ## Verify GitLab Settings 34 | 35 | - Permission for repo: 36 | 37 | Test the access right from flow settings by click 'test' button, the green will be shown if everything correct. 38 | 39 | ![gitlab_test](../../_images/git/gitlab_test_config.gif) 40 | 41 | 42 | ## Setup Access permission to Write Job Status to GitHub 43 | 44 | 1. Create a Token 45 | 46 | In order to have permission for writing job status back to GitLab, we need to create a token with `api` permission from https://gitlab.com/-/profile/personal_access_tokens (replace `https://gitlab.com` to your own GitLab host when access private gitlab) 47 | 48 | ![create token](../../_images/git/gitlab_create_access_token.png) 49 | 50 | 2. Add GitLab Token to flow.ci Secret 51 | 52 | Open the secret settings page `Settings -> Secret -> +` , paste the token copied from GitLab and save 53 | 54 | ![add token](../../_images/git/add_token.png) 55 | 56 | 3. Link to GitLab 57 | 58 | Open the git connection page `Settings -> Git -> +`, select `GitLab` on git source, input your GitLab host address, and then select a secret created on the last step 59 | 60 | ![link](../../_images/git/gitlab_add_link.png) 61 | 62 | 4. GitLab commit status 63 | 64 | After the configuration, the correspond commit status will be updated after job finished. 65 | 66 | ![demo](../../_images/git/gitlab_stage_updated.png) -------------------------------------------------------------------------------- /en/git/gogs.md: -------------------------------------------------------------------------------- 1 | # Gogs Integration 2 | 3 | ## Setup Access Permission for Private Repo 4 | 5 | Copy `public key` from admin page, open Gogs repo web and add it from `Settings > Deploy Keys` for single repo access. Gogs not allowed to add same public key for muliple repositories, we recommend to have a special 'CI user' to manage single public key access 6 | 7 | ![gogs_setup_deploy_key](../../_images/git/gogs_setup_deploy_key.png) 8 | 9 | ## Setup Webhook 10 | 11 | The webhook used for receive git notification such as push, tag, pull request and so on. 12 | 13 | 1. Copy webhook url from flow settings 14 | > Hint: Your host must be exposed to internet (public ip or domain), otherwide the gogs events can not be received. 15 | > If pulbic ip or domain not availble in your environments, please use the tools like [ngrok](https://ngrok.com/). 16 | 17 | ![webhook settings](../../_images/git/select_webhook_url.gif) 18 | 19 | 2. Setup webhook 20 | 21 | - Playload URL 22 | 23 | Paste webhook url copied from flow settings (step 1), and select `application/json` as content type 24 | 25 | > If using `ngrok`, please replace wehbook url by ngrok, ex: `http://172.20.10.5/webhooks/spring-sample` to `http://7e9ea9dc.ngrok.io/webhooks/spring-sample` 26 | 27 | - Select events 28 | 29 | Check events `Push` and `Pull Request` 30 | 31 | ![events](../../_images/git/gogs_setup_webhook.png) 32 | 33 | ## Verify Gogs Settings 34 | 35 | - Permission for repo: 36 | 37 | Test the access right from flow settings by click 'test' button, the green will be shown if everything correct. 38 | 39 | ![gogs_test](../../_images/git/gogs_test_config.gif) -------------------------------------------------------------------------------- /en/git/index.md: -------------------------------------------------------------------------------- 1 | # Git setup 2 | 3 | What you need to config? 4 | 5 | - Git repo URL to clone 6 | - Access permission for private Git repo 7 | - Webhook that can trigger CI job 8 | - Git provider host 9 | - Access permission to write job status back 10 | 11 | ![structure](../../_images/git/structure.png) 12 | 13 | 14 | ## Clone Git repo 15 | 16 | flow.ci clones git repo via [git clone](https://github.com/flowci-plugins/gitclone) plugin 17 | 18 | ```yaml 19 | envs: 20 | FLOWCI_GIT_URL: "https://github.com/FlowCI/spring-petclinic-sample.git" ## Git repo address, support https or ssh 21 | 22 | steps: 23 | - name: clone 24 | docker: 25 | image: flowci/debian-git ## other images with git command can be applied here as well! 26 | plugin: 'gitclone' 27 | ``` 28 | 29 | 30 | ## Access permission for private Git repo 31 | 32 | The __SSH-RSA__ `secret` is required if git url is __SSH__ based, for example `git@github.com:FlowCI/docs.git` 33 | 34 | 1. Create SSH-RSA secret 35 | 36 | - Go to `Settings -> Secret -> +` from Admin page 37 | - Input a secret name, for example `ras-test` 38 | - Select `SSH key` category 39 | - Click `create a new` ssh key pair or paste exsiting public and private key 40 | - Save 41 | 42 | ![how to create ssh-rsa secret](../../_images/secret/create_ssh_key.gif) 43 | 44 | 2. Config secret in the flow 45 | 46 | `FLOWCI_GIT_CREDENTIAL` variable is applied for git access permisison in [Git clone plugin](https://github.com/flowci-plugins/gitclone). 47 | 48 | For example: 49 | 50 | ```yaml 51 | envs: 52 | FLOWCI_GIT_CREDENTIAL: "rsa-test" 53 | 54 | steps: 55 | - name: clone 56 | docker: 57 | image: flowci/debian-git 58 | plugin: 'gitclone' 59 | ``` 60 | 61 | ## Setup Git provider 62 | 63 | Different Git provider has different way to setup access permission and webhook 64 | 65 | flow.ci currenlty supports: 66 | 67 | - [GitHub](en/git/github.md) 68 | - [GitLab](en/git/gitlab.md) 69 | - [Gogs](en/git/gogs.md) 70 | - [Gitee](en/git/gitee.md) 71 | - [Gerrit](en/git/gerrit.md) 72 | 73 | please click around the links for more detail 74 | -------------------------------------------------------------------------------- /en/job/cache.md: -------------------------------------------------------------------------------- 1 | # Cache 2 | 3 | The job cache is needed when steps run on different Agents and steps want to access the data from previous steps. 4 | 5 | ![cache demo](../../_images/job/cache_demo.png) 6 | 7 | ## How to use Cache 8 | 9 | The `cache` could be used in a `step`. The `key` is required to define cache name, `paths` is needed to write data. 10 | 11 | ```yaml 12 | steps: 13 | - name: write 14 | cache: 15 | key: mycache 16 | paths: 17 | - "./my_demo_cache" 18 | bash: | 19 | mkdir -p ./my_demo_cache 20 | echo "cache_content" > ./my_demo_cache/my_file 21 | 22 | - name: clean 23 | bash: | 24 | # Delete dir from worksapce, to make sure cache is loaded not from locally. 25 | rm -rf ./my_demo_cache 26 | 27 | - parallel: 28 | flow_1: 29 | docker: 30 | image: "ubuntu:21.04" 31 | steps: 32 | - name: read 33 | cache: 34 | key: mycache 35 | bash: | 36 | cat ./my_demo_cache/my_file 37 | 38 | flow_2: 39 | docker: 40 | image: "ubuntu:18.04" 41 | steps: 42 | - name: read 43 | cache: 44 | key: mycache 45 | bash: | 46 | cat ./my_demo_cache/my_file 47 | 48 | ``` 49 | 50 | The executed result like: 51 | 52 | ![cache_run](../../_images/job/cache_run_example.png) -------------------------------------------------------------------------------- /en/job/condition.md: -------------------------------------------------------------------------------- 1 | # Conditions 2 | 3 | Every jobs or steps could apply a starting condition with `Groovy` script. 4 | 5 | The [variables](en/agents/vars.md) could be used in the `Groovy` script, the return value of `Groovy` should be `boolean`, for example: 6 | 7 | ```yaml 8 | - condition: | 9 | println("hello world") 10 | true 11 | ``` 12 | 13 | ## Jobs Condition 14 | 15 | Set `condition` in the YAML root 16 | 17 | __Example__: Job only can be started at branch `master` or `develop` 18 | 19 | ```yaml 20 | condition: | 21 | return $FLOWCI_GIT_BRANCH == "develop" || $FLOWCI_GIT_BRANCH == "master"; 22 | 23 | steps: 24 | - name: step1 25 | bash: | 26 | echo "this is the step one" 27 | ``` 28 | 29 | ## Steps Condition 30 | 31 | Set `condition` in the step YAML, the step will be __skipped__ when the condtion script return `false` 32 | 33 | __Example__: `step2` will be executed directly since `step1` return `false` 34 | 35 | ```yaml 36 | steps: 37 | - name: step1 38 | condition: | 39 | return false 40 | bash: | 41 | echo "this is the step one" 42 | 43 | - name: step2 44 | condition: | 45 | return true 46 | bash: | 47 | echo "this is the step two" 48 | ``` -------------------------------------------------------------------------------- /en/job/docker.md: -------------------------------------------------------------------------------- 1 | # Environment with Docker 2 | 3 | Agent could use Docker to support any runtime environments, it could be set from `docker` or `dockers` in the YAML configuration. 4 | 5 | > Docker installation is needed from Agent 6 | 7 | ## Use Docker 8 | 9 | To use Docker environment, the only thing you need to do is apply `docker` from YAML. 10 | 11 | After this kind of setup, the script defined in `bash` will be run within the docker container. 12 | 13 | 14 | - `docker` within `step` 15 | 16 | Example: the bash script will be executed within `openjdk:11` or `openjdk:8` 17 | 18 | ```yaml 19 | steps: 20 | - name: step_1 21 | docker: 22 | image: "openjdk:11" 23 | bash: "Run from openjdk 11" 24 | 25 | - name: step_2 26 | docker: 27 | image: "openjdk:8" 28 | bash: "Run from openjdk 8" 29 | ``` 30 | 31 | ### Apply `docker` from Flow 32 | 33 | All the steps will apply the `docker` defined from Flow level. 34 | 35 | The step level `docker` will be applied as top priority. 36 | 37 | ```yaml 38 | docker: 39 | image: "openjdk:11" 40 | 41 | steps: 42 | - name: step_1 43 | bash: "Run from openjdk 11" 44 | 45 | - name: step_2 46 | docker: 47 | image: "openjdk:8" 48 | bash: "Run from openjdk 8" 49 | 50 | ``` 51 | 52 | ## Use multiple Docker images 53 | 54 | The `dockers` could be used for when multiple services like `redis`, `mongodb` and others are need in a step. 55 | 56 | The `is_runtime` must be defined for bash script environment. 57 | 58 | The `wait-for-it.sh` is built-in script in Agent, you could use it to wait for service until it's running. 59 | 60 | __Example__: Use `mysql` service in the step 61 | 62 | ```yaml 63 | steps: 64 | - name: run mutiple dockers 65 | dockers: 66 | - image: ubuntu:21.04 67 | is_runtime: true # the bash script runs in this image 68 | 69 | - image: mysql:5.6 70 | environment: 71 | MYSQL_ROOT_PASSWORD: 12345 72 | bash: | 73 | ## Get container id 74 | echo "ubuntu:21.04 id = $CONTAINER_ID_0" 75 | echo "mysql:5.6 id = $CONTAINER_ID_1" 76 | 77 | ## Get container IP address, the default network mode is 'bridge' 78 | echo "ubuntu:21.04 ip = $CONTAINER_IP_0" 79 | echo "mysql:5.6 ip = $CONTAINER_IP_1" 80 | 81 | ## Built-in wait-for-it.sh, wait 'mysql' service 82 | wait-for-it.sh ${CONTAINER_IP_1}:3306 -t 30 83 | if [ $? == 0 ];then 84 | docker run --network ${FLOWCI_AGENT_DOCKER_NETWORK} --rm mysql:5.6 mysql -h${CONTAINER_IP_1} -uroot -p12345 mysql -e "select * from user" 85 | fi 86 | ``` 87 | 88 | ![multiple docker](../../_images/job/multiple_docker.png) -------------------------------------------------------------------------------- /en/job/parallel.md: -------------------------------------------------------------------------------- 1 | # Parallel 2 | 3 | Running steps parallelly could speed up the performance of the job. 4 | 5 | The multiple flows are supported in the `parallel`. 6 | 7 | Multiple idle Agents are required for parallel steps, the steps will run sequentially if only ONE idle agent available. 8 | 9 | ```yaml 10 | steps: 11 | - parallel: 12 | flow_1: ## parallel flow name 13 | steps: 14 | - name: step_1 15 | bash: | 16 | echo "step 1 from flow 1" 17 | 18 | flow_2: ## parallel flow name 19 | steps: 20 | - name: step_1 21 | bash: | 22 | echo "step 1 from flow 2" 23 | 24 | ``` 25 | 26 | ![parallel](../../_images/job/parallel.png) 27 | 28 | Example: to run system test on both `java 8` and `java 11` environment. 29 | 30 | ```yaml 31 | steps: 32 | - name: git clone 33 | bash: | 34 | echo "run git clone" 35 | 36 | - parallel: 37 | java_8_test: 38 | docker: 39 | image: "java 8 image" 40 | steps: 41 | - name: test a 42 | bash: | 43 | echo "run test a for java 8" 44 | - name: test b 45 | bash: | 46 | echo "run test b for java 8" 47 | 48 | java_11_test: 49 | docker: 50 | image: "java 11 image" 51 | steps: 52 | - name: test a 53 | bash: | 54 | echo "run test a for java 11" 55 | - name: test b 56 | bash: | 57 | echo "run test b for java 11" 58 | ``` -------------------------------------------------------------------------------- /en/job/schedule.md: -------------------------------------------------------------------------------- 1 | # Crontab Job 2 | 3 | The __crontab__ schedule can be defined from Flow settings web UI `http://{your_host}/#/flows/{your_flow_name}/settings` 4 | 5 | ![cron](../../_images/job/cron_job.gif) -------------------------------------------------------------------------------- /en/job/start.md: -------------------------------------------------------------------------------- 1 | # Start a job 2 | 3 | A job could be started after the YAML configuraiton of flow is ready. 4 | 5 | At least one Agent is required for starting a job, please refer [Agent](/en/agents/index) for how to setup agent 6 | 7 | ## Run manually 8 | 9 | Click 'RUN' button from the web page `http://{your host}/#/flows/{your flow name}/jobs` 10 | 11 | ## Run from Git events 12 | 13 | Supported Git provider: [GitHub](https://github.com), [GitLab](https://gitlab.com), [Gogs](https://gogs.io/) 和 [Gitee](https://gitee.com/) 14 | 15 | Supported Git events: `Push`, `Tag` 和 `Pull Request` 16 | 17 | For how to config Git, please refer [Setup Git](en/git/index.md) -------------------------------------------------------------------------------- /en/job/web_terminal.md: -------------------------------------------------------------------------------- 1 | # Interactive Web Terminals 2 | 3 | Interactive web terminals give the user access to a terminal in step for running commands, it's only available for __admin user__. 4 | 5 | The step will be holded unit the web terminal session exit. 6 | 7 | ```yaml 8 | steps: 9 | - name: step1 10 | bash: | 11 | echo "try web terminal" 12 | sleep 10 13 | ``` 14 | 15 | ![web terminal](../../_images/job/terminal.gif) -------------------------------------------------------------------------------- /en/job/workspace.md: -------------------------------------------------------------------------------- 1 | # Workspace 2 | 3 | __Workspace__ is a directory on Agent, every jobs of flow shares the same workspace. 4 | 5 | The default directory of step script is workspace, you could use variable `FLOWCI_AGENT_JOB_DIR` 6 | 7 | - Agent from `docker`: `/ws/{flow id}` 8 | - Agent from `binary`: default path is `${HOME}/.flow.ci.agent/{flow id}` 9 | 10 | The job specific directory could be created by `FLOWCI_JOB_BUILD_NUM` in the step 11 | 12 | ```yaml 13 | steps: 14 | - name: job_own_dir 15 | bash: | 16 | # Create job directory according to build number 17 | mkdir -p "${FLOWCI_AGENT_JOB_DIR}/${FLOWCI_JOB_BUILD_NUM}" 18 | 19 | - name: access_job_dir 20 | bash: | 21 | cd "${FLOWCI_AGENT_JOB_DIR}/${FLOWCI_JOB_BUILD_NUM}" 22 | ``` -------------------------------------------------------------------------------- /en/secret/android_sign.md: -------------------------------------------------------------------------------- 1 | # Android Sign Secret 2 | 3 | ## Create 4 | 5 | 1. Click `Settings` -> `Secret` -> `+` 6 | 2. Enter a secret name 7 | 3. Select `Android sign` in category field 8 | 4. Input required data 9 | - `Key store file` 10 | - `key store password` 11 | - `Key alias` 12 | - `Key password` 13 | 5. Save 14 | 15 | ![create android sign](../../_images/secret/create_android_sign.gif) 16 | 17 | ## How to 18 | 19 | - [android-signing](https://github.com/flowci-plugins/android-signing) plugin: 20 | 21 | Type secret name in the variable `SIGN_SECRET` 22 | 23 | ```yaml 24 | - name: sign apk 25 | envs: 26 | SIGN_FILE_PATTERN: '*-unsigned.apk' 27 | SIGN_SECRET: my_android_sign 28 | plugin: android-signing 29 | ``` 30 | 31 | The output will be like `'./xx/xx/xx/you_package.apk' signed` if apk is signed 32 | 33 | ![show android signed](../../_images/secret/android_signed.png) -------------------------------------------------------------------------------- /en/secret/auth.md: -------------------------------------------------------------------------------- 1 | # Auth (username & password) Secret 2 | 3 | Auth Secret repersent username and password pair. 4 | 5 | ## Create 6 | 7 | 1. Click `Settings` -> `Secret` -> `+` 8 | 2. Enter a secret name 9 | 3. Select `AUTH` in category field 10 | 4. Type username and password 11 | 5. Save 12 | 13 | ![create auth](../../_images/secret/create_auth_pair.gif) 14 | 15 | ## How to 16 | 17 | - Access `Auth` secret from script 18 | 19 | It can be accessed from script if the `secrets` has beed defined in `step` YAML 20 | 21 | ```yaml 22 | steps: 23 | - name: get auth demo 24 | secrets: 25 | - my_auth_key 26 | bash: | 27 | echo ${my_auth_key_USERNAME} 28 | echo ${my_auth_key_PASSWORD} 29 | ``` 30 | -------------------------------------------------------------------------------- /en/secret/kubeconfig.md: -------------------------------------------------------------------------------- 1 | # K8s "kubeconfig" Secret 2 | 3 | ## Create 4 | 5 | 1. Click `Settings` -> `Secret` -> `+` 6 | 2. Enter a secret name 7 | 3. Select `Kubeconfig` in category field 8 | 4. Copy kubeconfig to the text field 9 | 5. Save 10 | 11 | ![create ssh rsa](../../_images/secret/create_kubeconfig.gif) 12 | 13 | ## How to 14 | 15 | - Auto scaling Agent: please refer [Kubernates](en/agents/k8s_host.md#auto-scalling-on-k8s-cluster) -------------------------------------------------------------------------------- /en/secret/ssh-rsa.md: -------------------------------------------------------------------------------- 1 | # SSH-RSA Secret 2 | 3 | ## Create 4 | 5 | 1. Click `Settings` -> `Secret` -> `+` 6 | 2. Enter a secret name 7 | 3. Select `SSH_RSA` in category field 8 | 4. Edit key pair 9 | 10 | - create new key pair by click `CREATE NEW SSH KEY` button, it will generate new ssh-rsa key pair from current user email 11 | - or copy-paste key pair to text box 12 | 5. save 13 | 14 | ![create ssh rsa](../../_images/secret/create_ssh_key.gif) 15 | 16 | ## How to 17 | 18 | - `git-clone` plugin: just need to type the secret name as value for variable `FLOWCI_GIT_CREDENTIAL` 19 | 20 | ```yml 21 | envs: 22 | FLOWCI_GIT_URL: "https://github.com/FlowCI/spring-petclinic-sample.git" 23 | FLOWCI_GIT_BRANCH: "master" 24 | FLOWCI_GIT_REPO: "spring-petclinic" 25 | 26 | steps: 27 | - name: clone 28 | envs: 29 | FLOWCI_GIT_CREDENTIAL: "rsa-test" 30 | plugin: 'gitclone' 31 | ``` 32 | 33 | - Auto scaling Agent: please refer [SSH Host](en/agents/ssh_host.md#auto-scalling-on-a-host-via-SSH) 34 | 35 | - Access `SSH-RSA` secret from script 36 | 37 | It can be accessed from script if the `secrets` has beed defined from step YAML 38 | 39 | ```yaml 40 | steps: 41 | - name: get sshrsa demo 42 | secrets: 43 | - my_ssh_key 44 | bash: | 45 | echo ${my_ssh_key_PUBLIC_KEY} 46 | echo ${my_ssh_key_PRIVATE_KEY} 47 | ``` -------------------------------------------------------------------------------- /en/secret/token.md: -------------------------------------------------------------------------------- 1 | # Token Secret 2 | 3 | ## Create 4 | 5 | 1. Click `Settings` -> `Secret` -> `+` 6 | 2. Enter a secret name 7 | 3. Select `Token` in category field 8 | 4. Type token data 9 | 5. save 10 | 11 | ![create token](../../_images/secret/create_token.gif) 12 | 13 | ## How to 14 | 15 | - Access `Token` secret from script 16 | 17 | It can be accessed from script if the `secrets` has beed defined from step YAML 18 | 19 | ```yaml 20 | steps: 21 | - name: get token demo 22 | secrets: 23 | - my_token 24 | bash: | 25 | echo ${my_token} 26 | ``` 27 | -------------------------------------------------------------------------------- /en/start/index.md: -------------------------------------------------------------------------------- 1 | # Getting Started 2 | 3 | ## Install 4 | 5 | > [Docker](https://docs.docker.com/install/) & [Docker-Compose](https://docs.docker.com/compose/install/) are required 6 | 7 | To install flow.ci, just run the following script: 8 | 9 | ```bash 10 | git clone https://github.com/FlowCI/docker.git flow-docker 11 | cd flow-docker 12 | ./server.sh start 13 | ``` 14 | 15 | Open the link `http://localhost:2015` from web browser after installtion is finished. 16 | 17 | > - __Port__: default port for server is `8080`, for web is `2015`. Modify the default ports from `server.sh` 及 `server.yml` 18 | > - __IP__: It will be auto detected from `./server.sh start`, or set your IP from `./server.sh -h your_ip start` if the address cannot be found. 19 | 20 | ![cmd](../../_images/start_server.gif) 21 | 22 | 23 | ## Set Host URL 24 | 25 | Check from `Settings -> System` `(http://{your_web_host}/#/settings/system)` to make sure the URL of server and web are correct. 26 | 27 | ![config_url](../../_images/config_server_url.png) 28 | 29 | ## Create a flow 30 | 31 | - Input flow name 32 | - Click 'create flow' button 33 | - Input name of flow 34 | 35 | - Select YAML template 36 | 37 | ![create_flow](../../_images/create_flow.gif) 38 | 39 | 40 | ## RUN 41 | 42 | Click `Run` button from flow page 43 | 44 | > - Job CANNOT start when the blank template has been selected. 45 | 46 | ![start_job](../../_images/start_job.gif) 47 | 48 | 49 | - Git: How to config Git repo, please refer [Git Connection](en/git/index.md) 50 | 51 | - Agent: There are default agents on server host, to configurate more agetns, please refer [Agent](en/agents/index.md) 52 | 53 | - Trigger: The `OnJobFinish` event will be triggered when a job is done, the __email__ or other notifications could be set up by the trigger. please refer [Trigger](cn/trigger/on_job_finish.md) 54 | -------------------------------------------------------------------------------- /en/trigger/on_job_finish.md: -------------------------------------------------------------------------------- 1 | # "OnJobFinish" Event 2 | 3 | The behavior when __job finished__ can be customized from `OnJobFinish` event 4 | 5 | ## Send email 6 | 7 | A __notification email__ will be sent to related users when job is finished 8 | 9 | 1. Click `Settings` -> `Triggers` -> `+` 10 | 2. Type a trigger name 11 | 3. Select `On Job Finish` event 12 | 4. Select `Email` category 13 | 5. Type email related data 14 | - Select a `SMTP` Config 15 | - Input email title, the variable can be used like `[[${variable name}]]` 16 | * Example show flow name and job build number in the title: `Report of flow [[${FLOWCI_FLOW_NAME}]] on job # [[${FLOWCI_JOB_BUILD_NUM}]]` 17 | * For more variables, please refer [variables](en/agents/vars.md) 18 | - Sender email (optional, `SMTP` username will be applied) 19 | - Receiver email / or select `To all flow users` to all users of related flow 20 | 6. Save 21 | 22 | ![create_email_trigger](../../_images/trigger/create_job_finish_email.gif) 23 | 24 | The notification email will be sent on job is finished 25 | 26 | ![email_sample](../../_images/trigger/email_sample.png) 27 | 28 | 29 | ## Send HTTP request 30 | 31 | A __HTTP request__ will be sent to per-defined URL when job is finished 32 | 33 | 1. Click `Settings` -> `Triggers` -> `+` 34 | 2. Type a trigger name 35 | 3. Select `On Job Finish` event 36 | 4. Select `Webhook` category 37 | 5. Type related data 38 | - `URL` 39 | - `HTTP Method` 40 | - Data of request 41 | * `Params` 42 | * `Headers` 43 | * `Body`: the variable can be used here, please refer [Variables](en/agents/vars.md), for example: 44 | ```json 45 | { 46 | "channel": "ID", 47 | "text": "[[${FLOWCI_FLOW_NAME}]] #[[${FLOWCI_JOB_BUILD_NUM}]] is [[${FLOWCI_JOB_STATUS}]] at [[${FLOWCI_JOB_URL}]]" 48 | } 49 | ``` 50 | 6. Save 51 | 52 | ![create_webhook_trigger](../../_images/trigger/create_job_finish_webhook.gif) 53 | 54 | 55 | Example: send job finish notification to __Slack__ channle. 56 | 57 | ![send_webhook_trigger](../../_images/trigger/send_job_finish_webhook.gif) -------------------------------------------------------------------------------- /en/upgrade/index.md: -------------------------------------------------------------------------------- 1 | # Upgrade 2 | 3 | ### from version 1.22.xx to 1.23.xx 4 | 5 | the database structure has been changed on version `1.23.xx`, need to execute the following script on the mongodb 6 | 7 | ```bash 8 | db.job.dropIndex('index_flow_id') 9 | db.flow_yml.dropIndex('index_flow_id') 10 | db.flow_yml.dropIndex('index_flow_id_and_yaml_name') 11 | ``` -------------------------------------------------------------------------------- /en/user/.placeholder: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FlowCI/docs/356287c6212fef113b410881a956ce37d7ac9543/en/user/.placeholder -------------------------------------------------------------------------------- /en/yml/plugins.md: -------------------------------------------------------------------------------- 1 | # Plugins 2 | 3 | Apply plugin in flow.ci is very simple, it just needs type plugin name in the YAML step, for example apply `gitclone` plugin: 4 | 5 | ```yml 6 | envs: 7 | FLOWCI_GIT_URL: "https://github.com/gin-gonic/gin.git" 8 | 9 | steps: 10 | - name: clone 11 | plugin: 'gitclone' 12 | ``` 13 | 14 | All plugins list at flow `settings` -> `configuration` -> `plugins` 15 | 16 | ![list](../../src/plugins.png) 17 | -------------------------------------------------------------------------------- /en/yml/reference_v1.md: -------------------------------------------------------------------------------- 1 | # YAML References 2 | 3 | * [`envs`](#envs) 4 | * [`condition`](#condition) 5 | * [`selector`](#selector) 6 | * [`docker` / `dockers`](#docker/dockers) 7 | * `image` 8 | * `auth` 9 | * `name` 10 | * `ports` 11 | * `user` 12 | * `entrypoint` 13 | * `command` 14 | * `environment` 15 | * `network` 16 | * `is_runtime` 17 | * `stop_on_finish` 18 | * `delete_on_finish` 19 | * [`notifications`](#notifications) 20 | * `plugin` 21 | * `envs` 22 | * [`steps`](#steps) 23 | - parallel step 24 | * [`parallel`](#parallel) 25 | - regular step 26 | * [`name`](#name) 27 | * [`condition`](#condition) 28 | * [`allow_failure`](#allow_failure) 29 | * [`retry`](#retry) 30 | * [`timeout`](#timeout) 31 | * [`envs`](#envs) 32 | * [`secrets`](#secrets) 33 | * [`cache`](#cache) 34 | * [`bash`](#bash) 35 | * [`pwsh`](#pwsh) 36 | * [`docker` / `dockers`](#docker/dockers) 37 | * `image` 38 | * `auth` 39 | * `name` 40 | * `ports` 41 | * `user` 42 | * `entrypoint` 43 | * `command` 44 | * `environment` 45 | * `network` 46 | * `is_runtime` 47 | * `stop_on_finish` 48 | * `delete_on_finish` 49 | * [`plugin`](#plugin) 50 | * [`exports`](#exports) 51 | 52 | ----------- 53 | 54 | ## __envs__ 55 | 56 | Environment variables that will effected in all steps 57 | 58 | ```yaml 59 | envs: 60 | FIRST_ENV: "first var" 61 | SECOND_ENV: "hello world" 62 | ``` 63 | 64 | ## __condition__ 65 | 66 | The Groovy script return boolean value to define the flow starting condition, the list of environment variables in [here (Git section only)](../agents/vars.md). 67 | 68 | > The conditon will be ignored while start a job from manual 69 | 70 | for example: the following defined the flow can be started when branch is `master` from github. 71 | 72 | ```yaml 73 | condition: | 74 | return FLOWCI_GIT_BRANCH == "master" && FLOWCI_GIT_SOURCE == "GITHUB" 75 | ``` 76 | 77 | ## __selector__ 78 | 79 | Find out matched agents to run flow job by label, or any idle agents if the tag not defined 80 | 81 | ```yaml 82 | selector: 83 | label: 84 | - ios 85 | - local 86 | ``` 87 | 88 | ## __docker/dockers__ 89 | 90 | if `docker` / `dockers` tag applied, all steps will be run within docker container 91 | 92 | > the default network is `flow-ci-agent-default` 93 | 94 | ### single docker 95 | 96 | ```yml 97 | docker: 98 | image: ubuntu:18.04 99 | auth: secret_name # optional, should be defined if image from private registry, defined from admin -> create secret -> secret with 'Auth pair' 100 | name: your_container_name # optional 101 | ports: # optional 102 | - "8080:8080" 103 | - "9090:9090" 104 | user: root # optiona, default is root 105 | entrypoint: # optional, default is "/bin/bash" 106 | - "/bin/bash" 107 | stop_on_finish: 'true' # optional, default is true 108 | delete_on_finish: 'ture' # optiaon, default is true 109 | 110 | steps: 111 | - name: step name 112 | allow_failure: true 113 | envs: 114 | MY_ENV: "hello" 115 | script: | 116 | echo $MY_ENV 117 | ``` 118 | 119 | ### multiple docker 120 | 121 | ```yml 122 | dockers: 123 | - image: ubuntu:18.04 124 | entrypoint: ["/bin/bash"] # optional, default is /bin/bash for runtime image 125 | is_runtime: true # default runtime for steps 126 | 127 | - image: mysql:5.6 128 | environment: # optional: environment for docker only 129 | MYSQL_ROOT_PASSWORD: my_password 130 | ports: # optional 131 | - "3306:3306" 132 | user: root # optiona, default is root 133 | entrypoint: [] # optional, default is empty 134 | command: [] # optional, default is empty 135 | network: "flow-ci-agent-default" # optional, default is flow-ci-agent-default 136 | stop_on_finish: 'true' # optional, default is true 137 | delete_on_finish: 'ture' # optiaon, default is true 138 | 139 | - image: rabbitmq:3 140 | 141 | steps: 142 | - name: step name 143 | allow_failure: true 144 | envs: 145 | MY_ENV: "hello" 146 | script: | 147 | echo $MY_ENV 148 | ``` 149 | 150 | ## __notifications__ 151 | 152 | It will run plugin with tag `notification` in server side, to send notification when job finished 153 | 154 | ```yaml 155 | notifications: 156 | - plugin: 'email-notify' 157 | envs: 158 | FLOWCI_SMTP_CONFIG: 'test-config' 159 | ``` 160 | 161 | ## __steps__ 162 | 163 | Example 164 | 165 | ```yml 166 | envs: 167 | # Git config 168 | FLOWCI_GIT_URL: "https://github.com/FlowCI/gin.git" 169 | 170 | steps: 171 | - name: clone # regular step 172 | docker: 173 | image: flowci/debian-git 174 | plugin: 'gitclone' 175 | cache: 176 | key: repo 177 | paths: 178 | - "./${FLOWCI_GIT_REPO}" 179 | 180 | - parallel: # parallel step 181 | lint-flow: 182 | steps: 183 | - name: lint 184 | plugin: 'go-lint' 185 | allow_failure: true 186 | cache: 187 | key: repo 188 | 189 | test-flow: 190 | steps: 191 | - name: test 192 | docker: 193 | image: golang:1.12 194 | plugin: 'go-test' 195 | cache: 196 | key: repo 197 | 198 | ``` 199 | 200 | ### __Parallel Step__ 201 | 202 | #### __parallel__ 203 | 204 | The subflow can be defined under `parallel` keyword, all subflows will be executed in parallel if has engouth agents. 205 | 206 | ```yml 207 | - parallel: 208 | lint-flow: # subflow name, ex 'lint-flow' 209 | selector: # the subflow will be executed in agent which the tag 'local' 210 | label: 211 | - local 212 | steps: 213 | - name: lint # steps in the subflow 214 | plugin: 'go-lint' 215 | allow_failure: true 216 | cache: 217 | key: repo 218 | 219 | test-flow: # subflow name, ex 'test-flow' 220 | selector: # the subflow will be executed in agent which the tag 'remote' 221 | label: 222 | - remote 223 | steps: 224 | - name: test # steps in the subflow 225 | docker: 226 | image: golang:1.12 227 | plugin: 'go-test' 228 | cache: 229 | key: repo 230 | ``` 231 | 232 | ### __Regular Step__ 233 | 234 | #### __name__ 235 | 236 | Specify a custom step name, rather than a generated default name (ex: step-1) 237 | 238 | ```yml 239 | steps: 240 | - name: step name 241 | ``` 242 | 243 | #### __condition__ 244 | 245 | The Groovy script return boolean value to define the step can be run or not 246 | 247 | ```yml 248 | steps: 249 | - name: step name 250 | envs: 251 | my_var: "hello" 252 | conditon: | 253 | ## groovy script that return boolean value 254 | return "$my_var" == "hello"; 255 | ``` 256 | 257 | #### __allow_failure__ 258 | 259 | the flow will be failed if something wrong in the script while value is `false`. Ignore the error and mark step status to passed if value is `true`, the default value is `false`. 260 | 261 | ```yml 262 | steps: 263 | - name: step name 264 | allow_failure: true 265 | ``` 266 | 267 | #### __retry__ 268 | 269 | define number of times to retry the step when it's fail 270 | 271 | ```yml 272 | steps: 273 | - name: step name 274 | allow_failure: true 275 | retry: 5 276 | bash: 277 | echo "start" 278 | fail_here. 279 | ``` 280 | 281 | #### __timeout__ 282 | 283 | define step timeout in seconds 284 | 285 | ```yml 286 | steps: 287 | - name: step name 288 | allow_failure: true 289 | timeout: 3600 290 | bash: 291 | echo "start" 292 | sleep 1000 293 | ``` 294 | 295 | #### __envs__ 296 | 297 | define environment variables scoped to individual steps. 298 | 299 | ```yml 300 | steps: 301 | - name: step name 302 | allow_failure: true 303 | envs: 304 | MY_ENV: "hello" 305 | ``` 306 | 307 | #### __secrets__ 308 | 309 | reference created secrets in the step 310 | 311 | ```yml 312 | steps: 313 | - name: step name 314 | allow_failure: true 315 | envs: 316 | MY_ENV: "hello" 317 | secrets: 318 | - my_auth_secret 319 | - my_token_secret 320 | - my_rsa_key 321 | bash: | 322 | echo "--- HOW TO use auth secret ---" 323 | echo '{secret name}_USERNAME' 324 | echo "{secret name}_PASSWORD" 325 | 326 | echo "${my_auth_secret_USERNAME}" 327 | echo "${my_auth_secret_PASSWORD}" 328 | echo "------------------------------" 329 | 330 | echo "--- HOW TO use token secret ---" 331 | echo '{secret name}' 332 | 333 | echo "${my_token_secret}" 334 | echo "------------------------------" 335 | 336 | echo "--- HOW TO use rsa (SSH) secret ---" 337 | echo '{secret name}_PUBLIC_KEY' 338 | 339 | echo "${my_rsa_secret_PUBLIC_KEY}" 340 | echo "------------------------------" 341 | 342 | ``` 343 | 344 | #### __cache__ 345 | 346 | the dir or file that defined in `paths` are relative path under `FLOWCI_AGENT_JOB_DIR` 347 | 348 | ```yml 349 | cache: 350 | key: mycache # cache name 351 | paths: 352 | - "./" # to cache everthing under FLOWCI_AGENT_JOB_DIR 353 | - "vendor" # to cache vendor dir under FLOWCI_AGENT_JOB_DIR 354 | ``` 355 | 356 | if the `paths` not defined, it will be read-only cache which means only download the cache by name 357 | 358 | ```yml 359 | cache: 360 | key: mycache 361 | ``` 362 | 363 | example: 364 | 365 | ```yml 366 | steps: 367 | - name: step name 368 | allow_failure: true 369 | envs: 370 | MY_ENV: "hello" 371 | bash: | 372 | echo 'apply cache' 373 | cache: 374 | key: mycache 375 | paths: 376 | - "./${FLOWCI_GIT_REPO}" # it will cache git repo 377 | ``` 378 | 379 | #### __bash__ 380 | 381 | the Bash script will be executed. 382 | 383 | ```yml 384 | steps: 385 | - name: step name 386 | allow_failure: true 387 | envs: 388 | MY_ENV: "hello" 389 | bash: | 390 | echo $MY_ENV 391 | ``` 392 | 393 | #### __pwsh__ 394 | 395 | the PowerShell script will be executed under Windows Agent 396 | 397 | ```yml 398 | steps: 399 | - name: step name 400 | allow_failure: true 401 | envs: 402 | MY_ENV: "hello" 403 | pwsh: | 404 | echo $Env:MY_ENV 405 | ``` 406 | 407 | #### __docker/dockers__ 408 | 409 | higher priority than flow level docker section, for detail please refer to flow level [`docker` / `dockers`](#docker/dockers) 410 | 411 | #### __plugin__ 412 | 413 | Apply plugin in the step 414 | 415 | > the `script` tag will be optional, if script specified, it will be executed before plugin 416 | 417 | ```yml 418 | steps: 419 | - name: run unit test 420 | envs: 421 | ENV_FOR_PLUGIN: "xxx" 422 | plugin: 'maven-test' # the plugin name 423 | ``` 424 | 425 | #### __exports__ 426 | 427 | define environment variables that will passed to job context, and available for flowing steps 428 | 429 | ```yml 430 | steps: 431 | - name: step name 432 | script: | 433 | echo $MY_ENV 434 | export ENV_FOR_NEXT_STEP="hello" 435 | exports: 436 | - "ENV_FOR_NEXT_STEP" 437 | ``` 438 | -------------------------------------------------------------------------------- /index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Document 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 26 |
27 | 42 | 43 | 44 | -------------------------------------------------------------------------------- /intro_base.md: -------------------------------------------------------------------------------- 1 | For more information, please check [flow.ci](https://flowci.github.io) --------------------------------------------------------------------------------