From a104c6b62480754d4261713361667edcb9a6419a Mon Sep 17 00:00:00 2001 From: Kell Sanders Date: Tue, 28 Jan 2025 13:05:47 -0600 Subject: [PATCH] fix: corrected versioned doc behavior to remove Next --- docusaurus.config.js | 2 +- .../version-0.26/installation/install-vela.md | 106 -- .../installation/server/docker.md | 157 --- .../installation/server/kubernetes.md | 31 - .../installation/server/server.md | 31 - .../version-0.26/installation/ui/docker.md | 68 -- .../installation/ui/kubernetes.md | 24 - .../version-0.26/installation/ui/ui.md | 34 - .../installation/worker/docker.md | 121 --- .../installation/worker/kubernetes.md | 266 ----- .../installation/worker/worker.md | 33 - .../version-0.26/reference/_index.md | 10 - .../reference/api/_category_.json | 7 - .../version-0.26/reference/api/admin/admin.md | 14 - .../version-0.26/reference/api/admin/build.md | 109 --- .../reference/api/admin/build_queue.md | 101 -- .../version-0.26/reference/api/admin/clean.md | 68 -- .../version-0.26/reference/api/admin/hook.md | 83 -- .../version-0.26/reference/api/admin/repo.md | 101 -- .../reference/api/admin/secret.md | 141 --- .../reference/api/admin/service.md | 81 -- .../reference/api/admin/settings/restore.md | 69 -- .../reference/api/admin/settings/settings.md | 14 - .../reference/api/admin/settings/update.md | 94 -- .../reference/api/admin/settings/view.md | 68 -- .../version-0.26/reference/api/admin/step.md | 87 -- .../version-0.26/reference/api/admin/user.md | 71 -- .../reference/api/admin/worker.md | 49 - .../reference/api/authentication.md | 51 - .../version-0.26/reference/api/build/add.md | 100 -- .../version-0.26/reference/api/build/build.md | 14 - .../reference/api/build/cancel.md | 48 - .../version-0.26/reference/api/build/get.md | 133 --- .../version-0.26/reference/api/build/logs.md | 77 -- .../reference/api/build/remove.md | 56 -- .../reference/api/build/restart.md | 82 -- .../reference/api/build/update.md | 92 -- .../version-0.26/reference/api/build/view.md | 156 --- .../reference/api/dashboard/add.md | 94 -- .../reference/api/dashboard/dashboard.md | 14 - .../reference/api/dashboard/delete.md | 50 - .../reference/api/dashboard/get.md | 130 --- .../reference/api/dashboard/list.md | 112 --- .../reference/api/dashboard/update.md | 106 -- .../reference/api/deployment/add.md | 122 --- .../reference/api/deployment/deployment.md | 14 - .../reference/api/deployment/get.md | 138 --- .../reference/api/deployment/view.md | 66 -- .../version-0.26/reference/api/hook/add.md | 159 --- .../version-0.26/reference/api/hook/get.md | 146 --- .../version-0.26/reference/api/hook/hook.md | 14 - .../version-0.26/reference/api/hook/remove.md | 56 -- .../version-0.26/reference/api/hook/update.md | 155 --- .../version-0.26/reference/api/hook/view.md | 145 --- .../reference/api/metrics/metrics.md | 71 -- .../reference/api/pipeline/add.md | 86 -- .../reference/api/pipeline/compile.md | 212 ---- .../reference/api/pipeline/expand.md | 168 ---- .../reference/api/pipeline/get.md | 93 -- .../reference/api/pipeline/pipeline.md | 14 - .../reference/api/pipeline/remove.md | 56 -- .../reference/api/pipeline/templates.md | 75 -- .../reference/api/pipeline/update.md | 82 -- .../reference/api/pipeline/validate.md | 60 -- .../reference/api/pipeline/view.md | 74 -- .../version-0.26/reference/api/repo/add.md | 107 --- .../version-0.26/reference/api/repo/chown.md | 55 -- .../version-0.26/reference/api/repo/get.md | 313 ------ .../version-0.26/reference/api/repo/remove.md | 55 -- .../version-0.26/reference/api/repo/repair.md | 55 -- .../version-0.26/reference/api/repo/repo.md | 14 - .../version-0.26/reference/api/repo/update.md | 113 --- .../version-0.26/reference/api/repo/view.md | 103 -- .../reference/api/schedule/add.md | 131 --- .../reference/api/schedule/get.md | 189 ---- .../reference/api/schedule/remove.md | 56 -- .../reference/api/schedule/schedule.md | 14 - .../reference/api/schedule/update.md | 130 --- .../reference/api/schedule/view.md | 122 --- .../version-0.26/reference/api/scm/scm.md | 14 - .../version-0.26/reference/api/scm/sync.md | 63 -- .../version-0.26/reference/api/scm/syncAll.md | 62 -- .../version-0.26/reference/api/secret/add.md | 112 --- .../version-0.26/reference/api/secret/get.md | 144 --- .../reference/api/secret/remove.md | 58 -- .../reference/api/secret/secret.md | 14 - .../reference/api/secret/update.md | 110 --- .../version-0.26/reference/api/secret/view.md | 100 -- .../version-0.26/reference/api/service/add.md | 79 -- .../version-0.26/reference/api/service/get.md | 83 -- .../reference/api/service/logs.md | 69 -- .../reference/api/service/remove.md | 57 -- .../reference/api/service/service.md | 14 - .../reference/api/service/update.md | 79 -- .../reference/api/service/view.md | 69 -- .../version-0.26/reference/api/step/add.md | 82 -- .../version-0.26/reference/api/step/get.md | 89 -- .../version-0.26/reference/api/step/logs.md | 69 -- .../version-0.26/reference/api/step/remove.md | 57 -- .../version-0.26/reference/api/step/step.md | 14 - .../version-0.26/reference/api/step/update.md | 82 -- .../version-0.26/reference/api/step/view.md | 72 -- .../version-0.26/reference/api/user/add.md | 66 -- .../reference/api/user/current/current.md | 14 - .../reference/api/user/current/repos.md | 87 -- .../reference/api/user/current/update.md | 63 -- .../reference/api/user/current/view.md | 53 - .../version-0.26/reference/api/user/get.md | 63 -- .../version-0.26/reference/api/user/remove.md | 54 -- .../version-0.26/reference/api/user/update.md | 71 -- .../version-0.26/reference/api/user/user.md | 14 - .../version-0.26/reference/api/user/view.md | 61 -- .../reference/cli/_category_.json | 7 - .../reference/cli/authentication.md | 80 -- .../reference/cli/build/approve.md | 71 -- .../version-0.26/reference/cli/build/build.md | 13 - .../reference/cli/build/cancel.md | 71 -- .../version-0.26/reference/cli/build/get.md | 80 -- .../reference/cli/build/restart.md | 95 -- .../version-0.26/reference/cli/build/view.md | 95 -- .../reference/cli/completion/completion.md | 16 - .../reference/cli/completion/generate.md | 140 --- .../reference/cli/config/config.md | 16 - .../reference/cli/config/generate.md | 66 -- .../reference/cli/config/remove.md | 60 -- .../reference/cli/config/update.md | 69 -- .../version-0.26/reference/cli/config/view.md | 50 - .../reference/cli/dashboard/add.md | 100 -- .../reference/cli/dashboard/dashboard.md | 16 - .../reference/cli/dashboard/get.md | 119 --- .../reference/cli/dashboard/update.md | 108 --- .../reference/cli/dashboard/view.md | 93 -- .../reference/cli/deployment/add.md | 92 -- .../reference/cli/deployment/deployment.md | 16 - .../reference/cli/deployment/get.md | 85 -- .../reference/cli/deployment/view.md | 86 -- .../version-0.26/reference/cli/hook/get.md | 77 -- .../version-0.26/reference/cli/hook/hook.md | 16 - .../version-0.26/reference/cli/hook/view.md | 82 -- .../version-0.26/reference/cli/install.md | 120 --- .../version-0.26/reference/cli/log/get.md | 85 -- .../version-0.26/reference/cli/log/log.md | 16 - .../version-0.26/reference/cli/log/view.md | 84 -- .../reference/cli/pipeline/exec.md | 271 ------ .../reference/cli/pipeline/generate.md | 53 - .../reference/cli/pipeline/get.md | 74 -- .../reference/cli/pipeline/pipeline.md | 16 - .../reference/cli/pipeline/validate.md | 83 -- .../version-0.26/reference/cli/repo/add.md | 103 -- .../version-0.26/reference/cli/repo/chown.md | 72 -- .../version-0.26/reference/cli/repo/get.md | 65 -- .../version-0.26/reference/cli/repo/remove.md | 72 -- .../version-0.26/reference/cli/repo/repair.md | 70 -- .../version-0.26/reference/cli/repo/repo.md | 16 - .../version-0.26/reference/cli/repo/sync.md | 96 -- .../version-0.26/reference/cli/repo/update.md | 113 --- .../version-0.26/reference/cli/repo/view.md | 90 -- .../reference/cli/schedule/add.md | 146 --- .../reference/cli/schedule/get.md | 85 -- .../reference/cli/schedule/remove.md | 85 -- .../reference/cli/schedule/schedule.md | 16 - .../reference/cli/schedule/update.md | 149 --- .../reference/cli/schedule/view.md | 142 --- .../version-0.26/reference/cli/secret/add.md | 177 ---- .../version-0.26/reference/cli/secret/get.md | 76 -- .../reference/cli/secret/remove.md | 78 -- .../reference/cli/secret/secret.md | 16 - .../reference/cli/secret/update.md | 170 ---- .../version-0.26/reference/cli/secret/view.md | 93 -- .../version-0.26/reference/cli/service/get.md | 77 -- .../reference/cli/service/service.md | 16 - .../reference/cli/service/view.md | 85 -- .../reference/cli/settings/settings.md | 16 - .../reference/cli/settings/update.md | 110 --- .../reference/cli/settings/view.md | 58 -- .../version-0.26/reference/cli/step/get.md | 77 -- .../version-0.26/reference/cli/step/step.md | 16 - .../version-0.26/reference/cli/step/view.md | 85 -- .../version-0.26/reference/cli/validate.md | 10 - .../version-0.26/reference/cli/version.md | 44 - .../version-0.26/reference/cli/worker/add.md | 73 -- .../version-0.26/reference/cli/worker/get.md | 75 -- .../reference/cli/worker/update.md | 76 -- .../version-0.26/reference/cli/worker/view.md | 74 -- .../reference/cli/worker/worker.md | 16 - .../reference/environment/environment.md | 13 - .../reference/environment/substitution.md | 54 -- .../reference/environment/variables.md | 203 ---- .../reference/installation/_category_.json | 7 - .../reference/installation/server/compiler.md | 129 --- .../reference/installation/server/database.md | 113 --- .../reference/installation/server/queue.md | 69 -- .../reference/installation/server/scm.md | 75 -- .../reference/installation/server/secret.md | 75 -- .../reference/installation/server/server.md | 907 ------------------ .../reference/installation/server/settings.md | 60 -- .../installation/server/token_manager.md | 33 - .../reference/installation/server/tracing.md | 145 --- .../version-0.26/reference/installation/ui.md | 82 -- .../reference/installation/worker/executor.md | 67 -- .../reference/installation/worker/queue.md | 58 -- .../reference/installation/worker/runtime.md | 93 -- .../reference/installation/worker/worker.md | 304 ------ .../version-0.26/reference/sdk/go.md | 56 -- .../version-0.26/reference/sdk/python.md | 45 - .../version-0.26/reference/sdk/sdk.md | 11 - .../reference/yaml/environment.md | 19 - .../version-0.26/reference/yaml/metadata.md | 111 --- .../version-0.26/reference/yaml/secrets.md | 159 --- .../version-0.26/reference/yaml/services.md | 126 --- .../version-0.26/reference/yaml/stages.md | 90 -- .../version-0.26/reference/yaml/steps.md | 452 --------- .../version-0.26/reference/yaml/templates.md | 89 -- .../version-0.26/reference/yaml/version.md | 16 - .../version-0.26/reference/yaml/worker.md | 56 -- .../version-0.26/reference/yaml/yaml.md | 64 -- .../version-0.26/usage/_category_.json | 7 - .../version-0.26/usage/authenticate.md | 25 - versioned_docs/version-0.26/usage/badge.md | 43 - versioned_docs/version-0.26/usage/docker.md | 65 -- .../version-0.26/usage/enable_repo.md | 25 - .../version-0.26/usage/environment.md | 135 --- .../usage/examples/_category_.json | 7 - .../version-0.26/usage/examples/go_modules.md | 119 --- .../usage/examples/java_gradle.md | 117 --- .../version-0.26/usage/examples/java_maven.md | 105 -- .../version-0.26/usage/examples/mongo.md | 82 -- .../version-0.26/usage/examples/node.md | 99 -- .../version-0.26/usage/examples/postgres.md | 96 -- .../version-0.26/usage/examples/redis.md | 84 -- .../version-0.26/usage/examples/route.md | 83 -- .../version-0.26/usage/examples/rust_cargo.md | 105 -- .../usage/examples/secrets_external.md | 134 --- .../usage/examples/secrets_internal.md | 117 --- .../version-0.26/usage/json-schema-support.md | 8 - .../usage/managing-deployments.md | 88 -- .../version-0.26/usage/open_id_connect.md | 105 -- versioned_docs/version-0.26/usage/outputs.md | 88 -- versioned_docs/version-0.26/usage/plugin.md | 90 -- .../version-0.26/usage/plugins/index.md | 85 -- .../usage/plugins/registry/Ansible.md | 159 --- .../usage/plugins/registry/Artifactory.md | 320 ------ .../usage/plugins/registry/Aws Credentials.md | 205 ---- .../usage/plugins/registry/Build Summary.md | 138 --- .../usage/plugins/registry/Cache.md | 215 ----- .../usage/plugins/registry/Downstream.md | 226 ----- .../usage/plugins/registry/Email.md | 376 -------- .../usage/plugins/registry/Git.md | 185 ---- .../usage/plugins/registry/Github Release.md | 269 ------ .../usage/plugins/registry/Hugo.md | 141 --- .../usage/plugins/registry/Influx.md | 156 --- .../version-0.26/usage/plugins/registry/K6.md | 77 -- .../usage/plugins/registry/Kaniko.md | 302 ------ .../usage/plugins/registry/Kubernetes.md | 387 -------- .../usage/plugins/registry/Manifest Tool.md | 102 -- .../usage/plugins/registry/NPM.md | 207 ---- .../usage/plugins/registry/SCP.md | 167 ---- .../usage/plugins/registry/SSH.md | 166 ---- .../usage/plugins/registry/Slack.md | 195 ---- .../usage/plugins/registry/Terraform.md | 321 ------- .../usage/plugins/registry/_category_.json | 12 - .../usage/plugins/registry/captains_log.md | 104 -- .../usage/plugins/tutorials/_category_.json | 12 - .../usage/plugins/tutorials/bash.md | 111 --- .../version-0.26/usage/pull_policies.md | 80 -- .../version-0.26/usage/quickstart.md | 149 --- .../version-0.26/usage/repo_settings.md | 148 --- versioned_docs/version-0.26/usage/roles.md | 57 -- .../version-0.26/usage/schedule_build.md | 90 -- versioned_docs/version-0.26/usage/secrets.md | 265 ----- .../version-0.26/usage/skipping_build.md | 20 - .../version-0.26/usage/stage_orchestration.md | 267 ------ .../version-0.26/usage/start_build.md | 10 - .../usage/templates/go/_category_.json | 7 - .../usage/templates/go/conditional.md | 106 -- .../usage/templates/go/functions.md | 97 -- .../usage/templates/go/loops_maps.md | 133 --- .../usage/templates/go/loops_slice.md | 126 --- .../usage/templates/go/mulitline.md | 99 -- .../usage/templates/go/vars_platform.md | 75 -- .../usage/templates/go/vars_template.md | 67 -- .../usage/templates/starlark/_category_.json | 7 - .../usage/templates/starlark/anatomy.md | 81 -- .../usage/templates/starlark/conditional.md | 111 --- .../usage/templates/starlark/functions.md | 91 -- .../usage/templates/starlark/loops_map.md | 147 --- .../usage/templates/starlark/loops_slice.md | 141 --- .../usage/templates/starlark/vars_platform.md | 75 -- .../usage/templates/starlark/vars_template.md | 89 -- .../version-0.26/usage/templates/templates.md | 454 --------- .../version-0.26/usage/tour/cloning.md | 59 -- .../version-0.26/usage/tour/environment.md | 62 -- .../version-0.26/usage/tour/image.md | 55 -- .../version-0.26/usage/tour/plugins.md | 51 - .../version-0.26/usage/tour/rulesets.md | 48 - .../version-0.26/usage/tour/secrets.md | 76 -- .../version-0.26/usage/tour/services.md | 76 -- .../version-0.26/usage/tour/stages.md | 82 -- .../version-0.26/usage/tour/status.md | 41 - .../version-0.26/usage/tour/step.md | 43 - .../version-0.26/usage/tour/steps.md | 57 -- .../version-0.26/usage/tour/templates.md | 47 - .../version-0.26/usage/tour/tour.md | 16 - .../version-0.26/usage/troubleshooting.md | 203 ---- .../version-0.26/usage/workspace.md | 66 -- versioned_sidebars/version-0.26-sidebars.json | 20 - versions.json | 3 - 307 files changed, 1 insertion(+), 28657 deletions(-) delete mode 100644 versioned_docs/version-0.26/installation/install-vela.md delete mode 100644 versioned_docs/version-0.26/installation/server/docker.md delete mode 100644 versioned_docs/version-0.26/installation/server/kubernetes.md delete mode 100644 versioned_docs/version-0.26/installation/server/server.md delete mode 100644 versioned_docs/version-0.26/installation/ui/docker.md delete mode 100644 versioned_docs/version-0.26/installation/ui/kubernetes.md delete mode 100644 versioned_docs/version-0.26/installation/ui/ui.md delete mode 100644 versioned_docs/version-0.26/installation/worker/docker.md delete mode 100644 versioned_docs/version-0.26/installation/worker/kubernetes.md delete mode 100644 versioned_docs/version-0.26/installation/worker/worker.md delete mode 100644 versioned_docs/version-0.26/reference/_index.md delete mode 100644 versioned_docs/version-0.26/reference/api/_category_.json delete mode 100644 versioned_docs/version-0.26/reference/api/admin/admin.md delete mode 100644 versioned_docs/version-0.26/reference/api/admin/build.md delete mode 100644 versioned_docs/version-0.26/reference/api/admin/build_queue.md delete mode 100644 versioned_docs/version-0.26/reference/api/admin/clean.md delete mode 100644 versioned_docs/version-0.26/reference/api/admin/hook.md delete mode 100644 versioned_docs/version-0.26/reference/api/admin/repo.md delete mode 100644 versioned_docs/version-0.26/reference/api/admin/secret.md delete mode 100644 versioned_docs/version-0.26/reference/api/admin/service.md delete mode 100644 versioned_docs/version-0.26/reference/api/admin/settings/restore.md delete mode 100644 versioned_docs/version-0.26/reference/api/admin/settings/settings.md delete mode 100644 versioned_docs/version-0.26/reference/api/admin/settings/update.md delete mode 100644 versioned_docs/version-0.26/reference/api/admin/settings/view.md delete mode 100644 versioned_docs/version-0.26/reference/api/admin/step.md delete mode 100644 versioned_docs/version-0.26/reference/api/admin/user.md delete mode 100644 versioned_docs/version-0.26/reference/api/admin/worker.md delete mode 100644 versioned_docs/version-0.26/reference/api/authentication.md delete mode 100644 versioned_docs/version-0.26/reference/api/build/add.md delete mode 100644 versioned_docs/version-0.26/reference/api/build/build.md delete mode 100644 versioned_docs/version-0.26/reference/api/build/cancel.md delete mode 100644 versioned_docs/version-0.26/reference/api/build/get.md delete mode 100644 versioned_docs/version-0.26/reference/api/build/logs.md delete mode 100644 versioned_docs/version-0.26/reference/api/build/remove.md delete mode 100644 versioned_docs/version-0.26/reference/api/build/restart.md delete mode 100644 versioned_docs/version-0.26/reference/api/build/update.md delete mode 100644 versioned_docs/version-0.26/reference/api/build/view.md delete mode 100644 versioned_docs/version-0.26/reference/api/dashboard/add.md delete mode 100644 versioned_docs/version-0.26/reference/api/dashboard/dashboard.md delete mode 100644 versioned_docs/version-0.26/reference/api/dashboard/delete.md delete mode 100644 versioned_docs/version-0.26/reference/api/dashboard/get.md delete mode 100644 versioned_docs/version-0.26/reference/api/dashboard/list.md delete mode 100644 versioned_docs/version-0.26/reference/api/dashboard/update.md delete mode 100644 versioned_docs/version-0.26/reference/api/deployment/add.md delete mode 100644 versioned_docs/version-0.26/reference/api/deployment/deployment.md delete mode 100644 versioned_docs/version-0.26/reference/api/deployment/get.md delete mode 100644 versioned_docs/version-0.26/reference/api/deployment/view.md delete mode 100644 versioned_docs/version-0.26/reference/api/hook/add.md delete mode 100644 versioned_docs/version-0.26/reference/api/hook/get.md delete mode 100644 versioned_docs/version-0.26/reference/api/hook/hook.md delete mode 100644 versioned_docs/version-0.26/reference/api/hook/remove.md delete mode 100644 versioned_docs/version-0.26/reference/api/hook/update.md delete mode 100644 versioned_docs/version-0.26/reference/api/hook/view.md delete mode 100644 versioned_docs/version-0.26/reference/api/metrics/metrics.md delete mode 100644 versioned_docs/version-0.26/reference/api/pipeline/add.md delete mode 100644 versioned_docs/version-0.26/reference/api/pipeline/compile.md delete mode 100644 versioned_docs/version-0.26/reference/api/pipeline/expand.md delete mode 100644 versioned_docs/version-0.26/reference/api/pipeline/get.md delete mode 100644 versioned_docs/version-0.26/reference/api/pipeline/pipeline.md delete mode 100644 versioned_docs/version-0.26/reference/api/pipeline/remove.md delete mode 100644 versioned_docs/version-0.26/reference/api/pipeline/templates.md delete mode 100644 versioned_docs/version-0.26/reference/api/pipeline/update.md delete mode 100644 versioned_docs/version-0.26/reference/api/pipeline/validate.md delete mode 100644 versioned_docs/version-0.26/reference/api/pipeline/view.md delete mode 100644 versioned_docs/version-0.26/reference/api/repo/add.md delete mode 100644 versioned_docs/version-0.26/reference/api/repo/chown.md delete mode 100644 versioned_docs/version-0.26/reference/api/repo/get.md delete mode 100644 versioned_docs/version-0.26/reference/api/repo/remove.md delete mode 100644 versioned_docs/version-0.26/reference/api/repo/repair.md delete mode 100644 versioned_docs/version-0.26/reference/api/repo/repo.md delete mode 100644 versioned_docs/version-0.26/reference/api/repo/update.md delete mode 100644 versioned_docs/version-0.26/reference/api/repo/view.md delete mode 100644 versioned_docs/version-0.26/reference/api/schedule/add.md delete mode 100644 versioned_docs/version-0.26/reference/api/schedule/get.md delete mode 100644 versioned_docs/version-0.26/reference/api/schedule/remove.md delete mode 100644 versioned_docs/version-0.26/reference/api/schedule/schedule.md delete mode 100644 versioned_docs/version-0.26/reference/api/schedule/update.md delete mode 100644 versioned_docs/version-0.26/reference/api/schedule/view.md delete mode 100644 versioned_docs/version-0.26/reference/api/scm/scm.md delete mode 100644 versioned_docs/version-0.26/reference/api/scm/sync.md delete mode 100644 versioned_docs/version-0.26/reference/api/scm/syncAll.md delete mode 100644 versioned_docs/version-0.26/reference/api/secret/add.md delete mode 100644 versioned_docs/version-0.26/reference/api/secret/get.md delete mode 100644 versioned_docs/version-0.26/reference/api/secret/remove.md delete mode 100644 versioned_docs/version-0.26/reference/api/secret/secret.md delete mode 100644 versioned_docs/version-0.26/reference/api/secret/update.md delete mode 100644 versioned_docs/version-0.26/reference/api/secret/view.md delete mode 100644 versioned_docs/version-0.26/reference/api/service/add.md delete mode 100644 versioned_docs/version-0.26/reference/api/service/get.md delete mode 100644 versioned_docs/version-0.26/reference/api/service/logs.md delete mode 100644 versioned_docs/version-0.26/reference/api/service/remove.md delete mode 100644 versioned_docs/version-0.26/reference/api/service/service.md delete mode 100644 versioned_docs/version-0.26/reference/api/service/update.md delete mode 100644 versioned_docs/version-0.26/reference/api/service/view.md delete mode 100644 versioned_docs/version-0.26/reference/api/step/add.md delete mode 100644 versioned_docs/version-0.26/reference/api/step/get.md delete mode 100644 versioned_docs/version-0.26/reference/api/step/logs.md delete mode 100644 versioned_docs/version-0.26/reference/api/step/remove.md delete mode 100644 versioned_docs/version-0.26/reference/api/step/step.md delete mode 100644 versioned_docs/version-0.26/reference/api/step/update.md delete mode 100644 versioned_docs/version-0.26/reference/api/step/view.md delete mode 100644 versioned_docs/version-0.26/reference/api/user/add.md delete mode 100644 versioned_docs/version-0.26/reference/api/user/current/current.md delete mode 100644 versioned_docs/version-0.26/reference/api/user/current/repos.md delete mode 100644 versioned_docs/version-0.26/reference/api/user/current/update.md delete mode 100644 versioned_docs/version-0.26/reference/api/user/current/view.md delete mode 100644 versioned_docs/version-0.26/reference/api/user/get.md delete mode 100644 versioned_docs/version-0.26/reference/api/user/remove.md delete mode 100644 versioned_docs/version-0.26/reference/api/user/update.md delete mode 100644 versioned_docs/version-0.26/reference/api/user/user.md delete mode 100644 versioned_docs/version-0.26/reference/api/user/view.md delete mode 100644 versioned_docs/version-0.26/reference/cli/_category_.json delete mode 100644 versioned_docs/version-0.26/reference/cli/authentication.md delete mode 100644 versioned_docs/version-0.26/reference/cli/build/approve.md delete mode 100644 versioned_docs/version-0.26/reference/cli/build/build.md delete mode 100644 versioned_docs/version-0.26/reference/cli/build/cancel.md delete mode 100644 versioned_docs/version-0.26/reference/cli/build/get.md delete mode 100644 versioned_docs/version-0.26/reference/cli/build/restart.md delete mode 100644 versioned_docs/version-0.26/reference/cli/build/view.md delete mode 100644 versioned_docs/version-0.26/reference/cli/completion/completion.md delete mode 100644 versioned_docs/version-0.26/reference/cli/completion/generate.md delete mode 100644 versioned_docs/version-0.26/reference/cli/config/config.md delete mode 100644 versioned_docs/version-0.26/reference/cli/config/generate.md delete mode 100644 versioned_docs/version-0.26/reference/cli/config/remove.md delete mode 100644 versioned_docs/version-0.26/reference/cli/config/update.md delete mode 100644 versioned_docs/version-0.26/reference/cli/config/view.md delete mode 100644 versioned_docs/version-0.26/reference/cli/dashboard/add.md delete mode 100644 versioned_docs/version-0.26/reference/cli/dashboard/dashboard.md delete mode 100644 versioned_docs/version-0.26/reference/cli/dashboard/get.md delete mode 100644 versioned_docs/version-0.26/reference/cli/dashboard/update.md delete mode 100644 versioned_docs/version-0.26/reference/cli/dashboard/view.md delete mode 100644 versioned_docs/version-0.26/reference/cli/deployment/add.md delete mode 100644 versioned_docs/version-0.26/reference/cli/deployment/deployment.md delete mode 100644 versioned_docs/version-0.26/reference/cli/deployment/get.md delete mode 100644 versioned_docs/version-0.26/reference/cli/deployment/view.md delete mode 100644 versioned_docs/version-0.26/reference/cli/hook/get.md delete mode 100644 versioned_docs/version-0.26/reference/cli/hook/hook.md delete mode 100644 versioned_docs/version-0.26/reference/cli/hook/view.md delete mode 100644 versioned_docs/version-0.26/reference/cli/install.md delete mode 100644 versioned_docs/version-0.26/reference/cli/log/get.md delete mode 100644 versioned_docs/version-0.26/reference/cli/log/log.md delete mode 100644 versioned_docs/version-0.26/reference/cli/log/view.md delete mode 100644 versioned_docs/version-0.26/reference/cli/pipeline/exec.md delete mode 100644 versioned_docs/version-0.26/reference/cli/pipeline/generate.md delete mode 100644 versioned_docs/version-0.26/reference/cli/pipeline/get.md delete mode 100644 versioned_docs/version-0.26/reference/cli/pipeline/pipeline.md delete mode 100644 versioned_docs/version-0.26/reference/cli/pipeline/validate.md delete mode 100644 versioned_docs/version-0.26/reference/cli/repo/add.md delete mode 100644 versioned_docs/version-0.26/reference/cli/repo/chown.md delete mode 100644 versioned_docs/version-0.26/reference/cli/repo/get.md delete mode 100644 versioned_docs/version-0.26/reference/cli/repo/remove.md delete mode 100644 versioned_docs/version-0.26/reference/cli/repo/repair.md delete mode 100644 versioned_docs/version-0.26/reference/cli/repo/repo.md delete mode 100644 versioned_docs/version-0.26/reference/cli/repo/sync.md delete mode 100644 versioned_docs/version-0.26/reference/cli/repo/update.md delete mode 100644 versioned_docs/version-0.26/reference/cli/repo/view.md delete mode 100644 versioned_docs/version-0.26/reference/cli/schedule/add.md delete mode 100644 versioned_docs/version-0.26/reference/cli/schedule/get.md delete mode 100644 versioned_docs/version-0.26/reference/cli/schedule/remove.md delete mode 100644 versioned_docs/version-0.26/reference/cli/schedule/schedule.md delete mode 100644 versioned_docs/version-0.26/reference/cli/schedule/update.md delete mode 100644 versioned_docs/version-0.26/reference/cli/schedule/view.md delete mode 100644 versioned_docs/version-0.26/reference/cli/secret/add.md delete mode 100644 versioned_docs/version-0.26/reference/cli/secret/get.md delete mode 100644 versioned_docs/version-0.26/reference/cli/secret/remove.md delete mode 100644 versioned_docs/version-0.26/reference/cli/secret/secret.md delete mode 100644 versioned_docs/version-0.26/reference/cli/secret/update.md delete mode 100644 versioned_docs/version-0.26/reference/cli/secret/view.md delete mode 100644 versioned_docs/version-0.26/reference/cli/service/get.md delete mode 100644 versioned_docs/version-0.26/reference/cli/service/service.md delete mode 100644 versioned_docs/version-0.26/reference/cli/service/view.md delete mode 100644 versioned_docs/version-0.26/reference/cli/settings/settings.md delete mode 100644 versioned_docs/version-0.26/reference/cli/settings/update.md delete mode 100644 versioned_docs/version-0.26/reference/cli/settings/view.md delete mode 100644 versioned_docs/version-0.26/reference/cli/step/get.md delete mode 100644 versioned_docs/version-0.26/reference/cli/step/step.md delete mode 100644 versioned_docs/version-0.26/reference/cli/step/view.md delete mode 100644 versioned_docs/version-0.26/reference/cli/validate.md delete mode 100644 versioned_docs/version-0.26/reference/cli/version.md delete mode 100644 versioned_docs/version-0.26/reference/cli/worker/add.md delete mode 100644 versioned_docs/version-0.26/reference/cli/worker/get.md delete mode 100644 versioned_docs/version-0.26/reference/cli/worker/update.md delete mode 100644 versioned_docs/version-0.26/reference/cli/worker/view.md delete mode 100644 versioned_docs/version-0.26/reference/cli/worker/worker.md delete mode 100644 versioned_docs/version-0.26/reference/environment/environment.md delete mode 100644 versioned_docs/version-0.26/reference/environment/substitution.md delete mode 100644 versioned_docs/version-0.26/reference/environment/variables.md delete mode 100644 versioned_docs/version-0.26/reference/installation/_category_.json delete mode 100644 versioned_docs/version-0.26/reference/installation/server/compiler.md delete mode 100644 versioned_docs/version-0.26/reference/installation/server/database.md delete mode 100644 versioned_docs/version-0.26/reference/installation/server/queue.md delete mode 100644 versioned_docs/version-0.26/reference/installation/server/scm.md delete mode 100644 versioned_docs/version-0.26/reference/installation/server/secret.md delete mode 100644 versioned_docs/version-0.26/reference/installation/server/server.md delete mode 100644 versioned_docs/version-0.26/reference/installation/server/settings.md delete mode 100644 versioned_docs/version-0.26/reference/installation/server/token_manager.md delete mode 100644 versioned_docs/version-0.26/reference/installation/server/tracing.md delete mode 100644 versioned_docs/version-0.26/reference/installation/ui.md delete mode 100644 versioned_docs/version-0.26/reference/installation/worker/executor.md delete mode 100644 versioned_docs/version-0.26/reference/installation/worker/queue.md delete mode 100644 versioned_docs/version-0.26/reference/installation/worker/runtime.md delete mode 100644 versioned_docs/version-0.26/reference/installation/worker/worker.md delete mode 100644 versioned_docs/version-0.26/reference/sdk/go.md delete mode 100644 versioned_docs/version-0.26/reference/sdk/python.md delete mode 100644 versioned_docs/version-0.26/reference/sdk/sdk.md delete mode 100644 versioned_docs/version-0.26/reference/yaml/environment.md delete mode 100644 versioned_docs/version-0.26/reference/yaml/metadata.md delete mode 100644 versioned_docs/version-0.26/reference/yaml/secrets.md delete mode 100644 versioned_docs/version-0.26/reference/yaml/services.md delete mode 100644 versioned_docs/version-0.26/reference/yaml/stages.md delete mode 100644 versioned_docs/version-0.26/reference/yaml/steps.md delete mode 100644 versioned_docs/version-0.26/reference/yaml/templates.md delete mode 100644 versioned_docs/version-0.26/reference/yaml/version.md delete mode 100644 versioned_docs/version-0.26/reference/yaml/worker.md delete mode 100644 versioned_docs/version-0.26/reference/yaml/yaml.md delete mode 100644 versioned_docs/version-0.26/usage/_category_.json delete mode 100644 versioned_docs/version-0.26/usage/authenticate.md delete mode 100644 versioned_docs/version-0.26/usage/badge.md delete mode 100644 versioned_docs/version-0.26/usage/docker.md delete mode 100644 versioned_docs/version-0.26/usage/enable_repo.md delete mode 100644 versioned_docs/version-0.26/usage/environment.md delete mode 100644 versioned_docs/version-0.26/usage/examples/_category_.json delete mode 100644 versioned_docs/version-0.26/usage/examples/go_modules.md delete mode 100644 versioned_docs/version-0.26/usage/examples/java_gradle.md delete mode 100644 versioned_docs/version-0.26/usage/examples/java_maven.md delete mode 100644 versioned_docs/version-0.26/usage/examples/mongo.md delete mode 100644 versioned_docs/version-0.26/usage/examples/node.md delete mode 100644 versioned_docs/version-0.26/usage/examples/postgres.md delete mode 100644 versioned_docs/version-0.26/usage/examples/redis.md delete mode 100644 versioned_docs/version-0.26/usage/examples/route.md delete mode 100644 versioned_docs/version-0.26/usage/examples/rust_cargo.md delete mode 100644 versioned_docs/version-0.26/usage/examples/secrets_external.md delete mode 100644 versioned_docs/version-0.26/usage/examples/secrets_internal.md delete mode 100644 versioned_docs/version-0.26/usage/json-schema-support.md delete mode 100644 versioned_docs/version-0.26/usage/managing-deployments.md delete mode 100644 versioned_docs/version-0.26/usage/open_id_connect.md delete mode 100644 versioned_docs/version-0.26/usage/outputs.md delete mode 100644 versioned_docs/version-0.26/usage/plugin.md delete mode 100644 versioned_docs/version-0.26/usage/plugins/index.md delete mode 100644 versioned_docs/version-0.26/usage/plugins/registry/Ansible.md delete mode 100644 versioned_docs/version-0.26/usage/plugins/registry/Artifactory.md delete mode 100644 versioned_docs/version-0.26/usage/plugins/registry/Aws Credentials.md delete mode 100644 versioned_docs/version-0.26/usage/plugins/registry/Build Summary.md delete mode 100644 versioned_docs/version-0.26/usage/plugins/registry/Cache.md delete mode 100644 versioned_docs/version-0.26/usage/plugins/registry/Downstream.md delete mode 100644 versioned_docs/version-0.26/usage/plugins/registry/Email.md delete mode 100644 versioned_docs/version-0.26/usage/plugins/registry/Git.md delete mode 100644 versioned_docs/version-0.26/usage/plugins/registry/Github Release.md delete mode 100644 versioned_docs/version-0.26/usage/plugins/registry/Hugo.md delete mode 100644 versioned_docs/version-0.26/usage/plugins/registry/Influx.md delete mode 100644 versioned_docs/version-0.26/usage/plugins/registry/K6.md delete mode 100644 versioned_docs/version-0.26/usage/plugins/registry/Kaniko.md delete mode 100644 versioned_docs/version-0.26/usage/plugins/registry/Kubernetes.md delete mode 100644 versioned_docs/version-0.26/usage/plugins/registry/Manifest Tool.md delete mode 100644 versioned_docs/version-0.26/usage/plugins/registry/NPM.md delete mode 100644 versioned_docs/version-0.26/usage/plugins/registry/SCP.md delete mode 100644 versioned_docs/version-0.26/usage/plugins/registry/SSH.md delete mode 100644 versioned_docs/version-0.26/usage/plugins/registry/Slack.md delete mode 100644 versioned_docs/version-0.26/usage/plugins/registry/Terraform.md delete mode 100644 versioned_docs/version-0.26/usage/plugins/registry/_category_.json delete mode 100644 versioned_docs/version-0.26/usage/plugins/registry/captains_log.md delete mode 100644 versioned_docs/version-0.26/usage/plugins/tutorials/_category_.json delete mode 100644 versioned_docs/version-0.26/usage/plugins/tutorials/bash.md delete mode 100644 versioned_docs/version-0.26/usage/pull_policies.md delete mode 100644 versioned_docs/version-0.26/usage/quickstart.md delete mode 100644 versioned_docs/version-0.26/usage/repo_settings.md delete mode 100644 versioned_docs/version-0.26/usage/roles.md delete mode 100644 versioned_docs/version-0.26/usage/schedule_build.md delete mode 100644 versioned_docs/version-0.26/usage/secrets.md delete mode 100644 versioned_docs/version-0.26/usage/skipping_build.md delete mode 100644 versioned_docs/version-0.26/usage/stage_orchestration.md delete mode 100644 versioned_docs/version-0.26/usage/start_build.md delete mode 100644 versioned_docs/version-0.26/usage/templates/go/_category_.json delete mode 100644 versioned_docs/version-0.26/usage/templates/go/conditional.md delete mode 100644 versioned_docs/version-0.26/usage/templates/go/functions.md delete mode 100644 versioned_docs/version-0.26/usage/templates/go/loops_maps.md delete mode 100644 versioned_docs/version-0.26/usage/templates/go/loops_slice.md delete mode 100644 versioned_docs/version-0.26/usage/templates/go/mulitline.md delete mode 100644 versioned_docs/version-0.26/usage/templates/go/vars_platform.md delete mode 100644 versioned_docs/version-0.26/usage/templates/go/vars_template.md delete mode 100644 versioned_docs/version-0.26/usage/templates/starlark/_category_.json delete mode 100644 versioned_docs/version-0.26/usage/templates/starlark/anatomy.md delete mode 100644 versioned_docs/version-0.26/usage/templates/starlark/conditional.md delete mode 100644 versioned_docs/version-0.26/usage/templates/starlark/functions.md delete mode 100644 versioned_docs/version-0.26/usage/templates/starlark/loops_map.md delete mode 100644 versioned_docs/version-0.26/usage/templates/starlark/loops_slice.md delete mode 100644 versioned_docs/version-0.26/usage/templates/starlark/vars_platform.md delete mode 100644 versioned_docs/version-0.26/usage/templates/starlark/vars_template.md delete mode 100644 versioned_docs/version-0.26/usage/templates/templates.md delete mode 100644 versioned_docs/version-0.26/usage/tour/cloning.md delete mode 100644 versioned_docs/version-0.26/usage/tour/environment.md delete mode 100644 versioned_docs/version-0.26/usage/tour/image.md delete mode 100644 versioned_docs/version-0.26/usage/tour/plugins.md delete mode 100644 versioned_docs/version-0.26/usage/tour/rulesets.md delete mode 100644 versioned_docs/version-0.26/usage/tour/secrets.md delete mode 100644 versioned_docs/version-0.26/usage/tour/services.md delete mode 100644 versioned_docs/version-0.26/usage/tour/stages.md delete mode 100644 versioned_docs/version-0.26/usage/tour/status.md delete mode 100644 versioned_docs/version-0.26/usage/tour/step.md delete mode 100644 versioned_docs/version-0.26/usage/tour/steps.md delete mode 100644 versioned_docs/version-0.26/usage/tour/templates.md delete mode 100644 versioned_docs/version-0.26/usage/tour/tour.md delete mode 100644 versioned_docs/version-0.26/usage/troubleshooting.md delete mode 100644 versioned_docs/version-0.26/usage/workspace.md delete mode 100644 versioned_sidebars/version-0.26-sidebars.json delete mode 100644 versions.json diff --git a/docusaurus.config.js b/docusaurus.config.js index e5ee651..a2552be 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -46,7 +46,7 @@ const config = { 'https://github.com/go-vela/docs/blob/main/', versions: { current: { - label: `Next 🚧`, + label: `v0.26`, }, }, }, diff --git a/versioned_docs/version-0.26/installation/install-vela.md b/versioned_docs/version-0.26/installation/install-vela.md deleted file mode 100644 index f574215..0000000 --- a/versioned_docs/version-0.26/installation/install-vela.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Install Vela - -## macOS - -### Homebrew - -```js -# add Vela tap to your brew configuration -brew tap go-vela/vela - -# update your taps -brew update - -# install Vela CLI -brew install vela -``` - -### cURL - -```js -# download the binary -curl -L https://github.com/go-vela/cli/releases/latest/download/vela_darwin_amd64.tar.gz | tar zx - -# copy binary to $PATH -sudo cp vela /usr/local/bin/ -``` - -## Linux - -### cURL - -```js -# download the binary -curl -L https://github.com/go-vela/cli/releases/latest/download/vela_darwin_amd64.tar.gz | tar zx - -# copy binary to $PATH -sudo cp vela /usr/local/bin/ -``` - -## Windows - -### Command Prompt - -```js -# download the binary -curl -L https://github.com/go-vela/cli/releases/latest/download/vela_windows_amd64.tar.gz --output vela_windows_amd64.tar.gz - -# unzip the tarball -tar xzvf vela_windows_amd64.tar.gz - -# copy binary to $PATH -copy vela C:\Windows\System32/vela.exe -``` - -### Windows PowerShell - -```js -# download the binary -curl https://github.com/go-vela/cli/releases/latest/download/vela_windows_amd64.tar.gz -OutFile vela_windows_amd64.tar.gz - -# unzip the tarball -tar xzvf vela_windows_amd64.tar.gz - -# copy binary to $PATH -cp vela C:\Windows\System32/vela.exe -``` - -### PowerShell 6 (PowerShell Core) - -```js -# download the binary -curl https://github.com/go-vela/cli/releases/latest/download/vela_windows_amd64.tar.gz -OutFile vela_windows_amd64.tar.gz - -# unzip the tarball -tar xzvf vela_windows_amd64.tar.gz - -# copy binary to $PATH -cp vela C:\Windows\System32/vela.exe -``` - -### Source - -:::warning - -This method is intended for developers and advanced users only. - -Golang is required before continuing. To install and setup Golang, please review [installation documentation](https://golang.org/doc/install) -::: - -```js -# download the repo -go get -d github.com/go-vela/cli - -# change to the cli directory -cd ${GOPATH}/src/github.com/go-vela/cli - -# build a release binary with Go -go build -o releases/vela - -# copy binary to $PATH -sudo cp releases/vela /usr/local/bin/ -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/installation/server/docker.md b/versioned_docs/version-0.26/installation/server/docker.md deleted file mode 100644 index 6ba0d2b..0000000 --- a/versioned_docs/version-0.26/installation/server/docker.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Docker - -## Prerequisites - -This section provides all required dependencies to install and start the server with Docker. - -### Dependency 1: Docker - -[Docker](https://docker.com/) will be used for downloading the server and managing the lifecycle of the application. - -You can refer to [Docker's official documentation](https://docs.docker.com/get-docker/) on installing and configuring the service. - -### Dependency 2: Redis - -[Redis](https://redis.io/) will be used for storing workloads, created by the server, that will run on a [worker](/docs/installation/worker/worker.md). - -You can refer to [Redis's official documentation](https://redis.io/topics/quickstart/) on installing and configuring the service. - -## Installation - -This section provides an example of installing the server with Docker. - -:::info -This example only shows a subset of all possible configuration options. -::: - -### Step 1: Download the Image - -Download the [Docker image](https://docs.docker.com/get-started/overview/#images) for the Vela server from [DockerHub](https://hub.docker.com/). - -You can use the [`docker pull` command](https://docs.docker.com/engine/reference/commandline/pull/) to download the image: - -```shell -$ docker pull target/vela-server:latest -``` - -:::info -The `latest` tag will ensure you install the most-recent version of the Vela server. - -To see the full list of available versions, please refer to [the official registry](https://hub.docker.com/r/target/vela-server). -::: - -### Step 2: Create an Encryption Key - -Create an [Advanced Encryption Standard (AES)](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) key used for encrypting sensitive data at rest in the database. - -You can use the [`openssl` command](https://www.openssl.org/) to generate the AES key: - -```shell -$ openssl aes-128-cbc -k secret -P -md sha1 -``` - -:::info -This command will output multiple key/value pairs for the AES key. - -The specific value we need from the output is the line with `key` in it (i.e. `key=`). -::: - -### Step 3: Create a Shared Secret - -:::info -Skip this step if you are utilizing the [worker registration auth flow](/installation/worker/docker/#worker-registration-and-auth-refresh) -::: - -Create a shared secret used for authenticating communication between workers and the server. - -You can use the [`openssl` command](https://www.openssl.org/) to generate the shared secret: - -```shell -$ openssl rand -hex 16 -``` - -### Step 4: Create the private key - -Create a private key used for minting and validating user, worker auth, and build JWT tokens. - -You can also use the [`openssl` command](https://www.openssl.org/) to generate the key. - -```shell -$ openssl rand -hex 16 -``` - -### Step 5: Create the signing key pair - -Create a key pair (ed25519) used for signing queue items. Items are signed via private key and opened via public key in the server and worker, respectively. The key pair must be base64 encoded prior to being supplied to the server. The server distributes the public key to registered workers, therefore both keys must be provided to the server. - -To make it easier, you can use this [Go Playground program](https://go.dev/play/p/-go_7SnJbnP) to generate an encoded key pair that is ready to use. For security we recommend running the program locally. - -:::info -The private key is used to sign items in the server. -The public key is used to open items in the worker. -Both keys are provided to the server. -::: - -### Step 6: Create an OAuth Application - -Vela requires OAuth application credentials from a source control management (SCM) provider. - -These credentials are used to authenticate and authorize actions preformed within the platform. - -Vela has support for many Source Control Management (SCM) providers to enable the preferences of you and your team. - -You can follow the [SCM reference](/docs/reference/installation/server/scm.md) for instructions on creating the OAuth application. - -### Step 7: Start the Server - -Start the Vela server as a [Docker container](https://docs.docker.com/get-started/overview/#containers) that is configured via environment variables. - -You can use the [`docker run` command](https://docs.docker.com/engine/reference/commandline/run/) to start the server: -```shell -$ docker run \ - --detach=true \ - --env=VELA_ADDR=https://vela-server.example.com \ - --env=VELA_DATABASE_ENCRYPTION_KEY= \ - --env=VELA_QUEUE_DRIVER=redis \ - --env=VELA_QUEUE_ADDR=redis://@:/ \ - --env=VELA_QUEUE_PRIVATE_KEY= \ - --env=VELA_QUEUE_PUBLIC_KEY= \ - --env=VELA_PORT=443 \ - --env=VELA_SERVER_PRIVATE_KEY= \ - --env=VELA_SCM_CLIENT= \ - --env=VELA_SCM_SECRET= \ - --env=VELA_WEBUI_ADDR=https://vela.example.com \ - --name=server \ - --publish=80:80 \ - --publish=443:443 \ - --restart=always \ - target/vela-server:latest -``` - -:::info -If using the [server-worker trusted symmetric auth method](/installation/worker/docker/#worker-server-trusted-symmetric-token), be sure to add the `VELA_SECRET` env variable: -```shell - --env=VELA_SECRET= -``` -For a full list of configuration options, please see the [server reference](/docs/reference/installation/server/server.md). -::: - -### Step 8: Verify the Server Logs - -Ensure the server started up successfully and is running as expected by viewing the logs. - -You can use the [`docker logs` command](https://docs.docker.com/engine/reference/commandline/logs/) to inspect the logs: - -```shell -$ docker logs server -``` - -### Step 9: Install Workers - -After the server is up and running, you need to install workers to run workloads. - -Please refer to [the worker installation docs](/docs/installation/worker/worker.md) for more information. \ No newline at end of file diff --git a/versioned_docs/version-0.26/installation/server/kubernetes.md b/versioned_docs/version-0.26/installation/server/kubernetes.md deleted file mode 100644 index 2eac8ff..0000000 --- a/versioned_docs/version-0.26/installation/server/kubernetes.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -sidebar_position: 3 ---- - -# Kubernetes - -## Prerequisites - -This section provides all required dependencies to install and start the server with Kubernetes. - -### Dependency 1: Kubernetes - -[Kubernetes](https://kubernetes.io/) will be used for downloading the server and managing the lifecycle of the application. - -You can refer to [Kubernetes' official documentation](https://kubernetes.io/docs/setup/) on installing and configuring the service. - -### Dependency 2: Redis - -[Redis](https://redis.io/) will be used for storing workloads, created by the server, that will run on a [worker](/docs/installation/worker/worker.md). - -You can refer to [Redis's official documentation](https://redis.io/topics/quickstart/) on installing and configuring the service. - -## Installation - -This section provides an example of installing the server with Kubernetes. - -This example only shows a subset of all possible configuration options. - -### Step 1: TODO - -TODO \ No newline at end of file diff --git a/versioned_docs/version-0.26/installation/server/server.md b/versioned_docs/version-0.26/installation/server/server.md deleted file mode 100644 index f84b38e..0000000 --- a/versioned_docs/version-0.26/installation/server/server.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -sidebar_position: 1 ---- -# Server - -Known as the brains of the Vela application, this service is responsible for managing the state of application resources. - -This includes managing resources in the system (repositories, users etc.) and storing resource data in the database. - -Additionally, the server responds to event-driven requests (webhooks) which creates new builds to run on a [worker](/docs/installation/worker/worker.md). - -After a build is created, it is pushed to the queue which will be retrieved and executed by a worker. - -As a build is run by a worker, it will send requests to the server's API which stores the state of the build in the database. - -![Build Workflow](/img/build_workflow.png) - -## Deployment Guides - -Vela supports a number of deployment strategies to enable the preferences of you and your team. - -This section provides a list of comprehensive guides to install and start the server: - -### Docker - -From the [Docker official website](https://docker.io/): - -> Docker takes away repetitive, mundane configuration tasks and is used throughout the development lifecycle for fast, easy and portable application development - desktop and cloud. Docker’s comprehensive end to end platform includes UIs, CLIs, APIs and security that are engineered to work together across the entire application delivery lifecycle. - -Please refer to [our Docker deployment guide](/docs/installation/server/docker.md) to get started. - diff --git a/versioned_docs/version-0.26/installation/ui/docker.md b/versioned_docs/version-0.26/installation/ui/docker.md deleted file mode 100644 index 5176a9c..0000000 --- a/versioned_docs/version-0.26/installation/ui/docker.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Docker - -## Prerequisites - -This section provides all required dependencies to install and start the UI with Docker. - -### Dependency 1: Docker - -[Docker](https://docs.docker.com/) will be used for downloading the UI and managing the lifecycle of the application. - -You can refer to [Docker's official documentation](https://docs.docker.com/get-docker/) on installing and configuring the service. - -## Installation - -This section provides an example of installing the UI with Docker. - -This example only shows a subset of all possible configuration options. - -### Step 1: Download the Image - -Download the [Docker image](https://docs.docker.com/get-started/overview/#images) for the Vela UI from [DockerHub](https://hub.docker.com/). - -You can use the [`docker pull` command](https://docs.docker.com/engine/reference/commandline/pull/) to download the image: - -```shell -$ docker pull target/vela-ui:latest -``` - -:::info -The `latest` tag will ensure you install the most-recent version of the Vela UI. - -To see the full list of available versions, please refer to [the official registry](https://hub.docker.com/r/target/vela-ui). -::: - -### Step 2: Start the UI - -Start the Vela UI as a [Docker container](https://docs.docker.com/get-started/overview/#containers) that is configured via environment variables. - -You can use the [`docker run` command](https://docs.docker.com/engine/reference/commandline/run/) to start the worker: - -```shell -$ docker run \ - --detach=true \ - --env=VELA_API=https://vela-server.example.com \ - --name=ui \ - --publish=80:80 \ - --publish=443:443 \ - --restart=always \ - target/vela-ui:latest -``` - -:::info -For a full list of configuration options, please see the [UI reference](/docs/reference/installation/ui.md). -::: - -### Step 3: Verify the UI Logs - -Ensure the UI started up successfully and is running as expected by inspecting the logs. - -You can use the [`docker logs` command](https://docs.docker.com/engine/reference/commandline/logs/) to verify the logs: - -```shell -$ docker logs ui -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/installation/ui/kubernetes.md b/versioned_docs/version-0.26/installation/ui/kubernetes.md deleted file mode 100644 index 4758635..0000000 --- a/versioned_docs/version-0.26/installation/ui/kubernetes.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -sidebar_position: 3 ---- -# Kubernetes - -## Prerequisites - -This section provides all required dependencies to install and start the UI with Kubernetes. - -### Dependency 1: Kubernetes - -[Kubernetes](https://kubernetes.io/) will be used for downloading the UI and managing the lifecycle of the application. - -You can refer to [Kubernetes' official documentation](https://kubernetes.io/docs/setup/) on installing and configuring the service. - -## Installation - -This section provides an example of installing the UI with Kubernetes. - -This example only shows a subset of all possible configuration options. - -### Step 1: TODO - -TODO \ No newline at end of file diff --git a/versioned_docs/version-0.26/installation/ui/ui.md b/versioned_docs/version-0.26/installation/ui/ui.md deleted file mode 100644 index e20eaf3..0000000 --- a/versioned_docs/version-0.26/installation/ui/ui.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -sidebar_position: 1 ---- -# UI - -Known as the user interface for the Vela application, often referred to as the Vela UI, this service provides a means for utilizing and interacting with the Vela platform. - -The Vela UI aims to provide users with an easy-to-use toolbox that supplies most of the functionality necessary for managing, investigating, and successfully troubleshooting Vela pipelines. - -This array of functionality includes viewing and managing resources in the system, enabling repositories, compiling pipelines, viewing logs etc. Most of these actions are performed through interacting with the server API on the user's behalf. - -The UI also offers a quick glance into additional pipeline information, including any errors that might be interfering with the success of your pipeline, such as webhook processing issues returned by the SCM or user pipeline syntax mistakes. The purpose of the UI is to make managing and debugging Vela pipelines not only possible, but approachable. - -## Deployment Guides - -Vela supports a number of deployment strategies to enable the preferences of you and your team. - -This section provides a list of comprehensive guides to install and start the UI: - -### Docker - -From the [Docker official website](https://docker.io/): - -> Docker takes away repetitive, mundane configuration tasks and is used throughout the development lifecycle for fast, easy and portable application development - desktop and cloud. Docker’s comprehensive end to end platform includes UIs, CLIs, APIs and security that are engineered to work together across the entire application delivery lifecycle. - -Please refer to [our Docker deployment guide](/docs/installation/ui/docker.md) to get started. - -### Kubernetes - -From the [Kubernetes official website](https://kubernetes.io/): - -> Kubernetes, also known as K8s, is an open-source system for automating deployment, scaling, and management of containerized applications. - -Please refer to [our Kubernetes deployment guide](/docs/installation/ui/kubernetes.md) to get started. \ No newline at end of file diff --git a/versioned_docs/version-0.26/installation/worker/docker.md b/versioned_docs/version-0.26/installation/worker/docker.md deleted file mode 100644 index c72c4f5..0000000 --- a/versioned_docs/version-0.26/installation/worker/docker.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Docker - -## Prerequisites - -This section provides all required dependencies to install and start the worker with Docker. - -### Dependency 1: Docker - -[Docker](https://docs.docker.com/) will be used for downloading the worker and managing the lifecycle of the application. - -You can refer to [Docker's official documentation](https://docs.docker.com/get-docker/) on installing and configuring the service. - -### Dependency 2: Redis - -[Redis](https://redis.io/) will be used for storing workloads, created by the [server](/docs/installation/server/server.md), that will be run by a worker. - -You can refer to [Redis's official documentation](https://redis.io/topics/quickstart/) on installing and configuring the service. - -## Installation - -This section provides an example of installing the worker with Docker. - -This example only shows a subset of all possible configuration options. - -### Step 1: Download the Image - -Download the [Docker image](https://docs.docker.com/get-started/overview/#images) for the Vela worker from [DockerHub](https://hub.docker.com/). - -You can use the [`docker pull` command](https://docs.docker.com/engine/reference/commandline/pull/) to download the image: - -```shell -$ docker pull target/vela-worker:latest -``` - -:::info -The `latest` tag will ensure you install the most-recent version of the Vela worker. - -To see the full list of available versions, please refer to [the official registry](https://hub.docker.com/r/target/vela-worker). -::: - -### Step 2: Determine Worker Authentication and Start Worker - -Currently, Vela supports two methods of maintaining authentication between the worker and the server. - -Take care to read through both options to determine which setup makes the most sense for your installation: - -### Worker-Server Trusted Symmetric Token - -This authentication method involves using the same secret generated as the `VELA_SECRET` during the [server installation](/installation/server/docker/#step-3-create-a-shared-secret) as the bearer token for all API requests related to check-in and build tokens from the worker to the server. - -The token is non-expiring and exists within the container environment. Once the server is running, all that is necessary for a worker to connect to the server and pull builds from the queue is simply starting the worker container: - -```shell -$ docker run \ - --detach=true \ - --env=VELA_QUEUE_DRIVER=redis \ - --env=VELA_SERVER_ADDR=https://vela-server.example.com \ - --env=VELA_SERVER_SECRET= \ - --env=VELA_WORKER_ADDR=https://vela-worker.example.com \ - --name=worker \ - --publish=80:80 \ - --publish=443:443 \ - --restart=always \ - --volume=/var/run/docker.sock:/var/run/docker.sock \ - target/vela-worker:latest -``` - -The worker must still pass its check-in with the server in order to pull builds from the queue. - -### Worker Registration and Auth Refresh - -This authentication method is the more secure of the two options. Rather than using a non-expiring token in the container environment, platform administrators can register workers using their credentials via the Vela CLI. In order to leverage this method, simply do NOT supply the [`VELA_SECRET`](/reference/installation/server#vela_secret) to the server and do NOT supply the [`VELA_SERVER_SECRET`](/reference/installation/worker/#vela_server_secret) to the worker. - -To start, launch the worker container: - -```shell -$ docker run \ - --detach=true \ - --env=VELA_QUEUE_DRIVER=redis \ - --env=VELA_SERVER_ADDR=https://vela-server.example.com \ - --env=VELA_WORKER_ADDR=https://vela-worker.example.com \ - --name=worker \ - --publish=80:80 \ - --publish=443:443 \ - --restart=always \ - --volume=/var/run/docker.sock:/var/run/docker.sock \ - target/vela-worker:latest -``` - -Once the worker has started, it will be in a paused state until a platform admin registers the worker: - -```shell -$ vela login --api.addr https://vela-server.example.com - -$ vela add worker --worker.hostname vela-worker --worker.address https://vela-worker.example.com - -worker registered successfully -``` - -This process involves the generation of a registration token, which can only be done by platform admins. The quickly expiring registration token is then passed to the worker using an http request to the worker's `/register` endpoint. The worker exchanges this registration token with the server for an auth token. - -:::info -IMPORTANT: When using this method, ensure that the [`VELA_WORKER_AUTH_TOKEN_DURATION`](/reference/installation/server#vela_worker_auth_token_duration) configured in the server is _longer_ than the [`VELA_CHECK_IN`](/reference/installation/worker/#vela_check_in) configured in the worker. This ensures that all requests made by the worker are done with a valid token, refreshed at each check-in. -::: - -Once registered, the worker will continue refreshing its authentication token at the specified check in interval. Workers that lose their connection to the server for long enough for their existing auth -token to expire will need to be re-registered. - -### Step 3: Verify the Worker Logs - -Ensure the worker started up successfully and is running as expected by inspecting the logs. - -You can use the [`docker logs` command](https://docs.docker.com/engine/reference/commandline/logs/) to verify the logs: - -```shell -$ docker logs worker -``` diff --git a/versioned_docs/version-0.26/installation/worker/kubernetes.md b/versioned_docs/version-0.26/installation/worker/kubernetes.md deleted file mode 100644 index 4e6964f..0000000 --- a/versioned_docs/version-0.26/installation/worker/kubernetes.md +++ /dev/null @@ -1,266 +0,0 @@ ---- -sidebar_position: 3 ---- -# Kubernetes - -## Prerequisites - -This section provides all required dependencies to install and start the worker with Kubernetes. - -### Dependency 1: Kubernetes - -[Kubernetes](https://kubernetes.io/) will be used for downloading the worker and managing the lifecycle of the application. - -You can refer to [Kubernetes' official documentation](https://kubernetes.io/docs/setup/) on installing and configuring the service. - -### Dependency 2: Redis - -[Redis](https://redis.io/) will be used for storing workloads, created by the [server](/docs/installation/worker/worker.md), that will be run by a worker. - -You can refer to [Redis's official documentation](https://redis.io/topics/quickstart/) on installing and configuring the service. - -## Installation - -This section provides an example of installing the worker with Kubernetes. - -This example only shows a subset of all possible configuration options. - -### Step 1: Create a Worker Secret and ConfigMap - -You will need to store some env vars in a `Secret`, and the rest can go in a `ConfigMap`. - -:::info -Determine which worker auth method to use for worker-server communication before writing the `ConfigMap`. Details of the two offerings can be found [here](/installation/worker/docker/#step-2-determine-worker-authentication-and-start-worker). -::: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: vela-worker - namespace: default -data: - # these values are base64 encoded - - # this value should only be specified if using the server-worker trusted symmetric token auth method. - VELA_SERVER_SECRET: PHNoYXJlZC1zZWNyZXQ+ - # VELA_SERVER_SECRET: -``` - -Do not store any passwords in the `ConfigMap`. The `ConfigMap` is more convenient for everything else. - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: vela-worker - namespace: default -data: - # This might be "http://vela-server:8080" if vela-server is also deployed in k8s. - VELA_SERVER_ADDR: https://vela-server.example.com - - VELA_QUEUE_DRIVER: redis - - VELA_EXECUTOR_DRIVER: linux - - VELA_RUNTIME_DRIVER: kubernetes - VELA_RUNTIME_NAMESPACE: default - VELA_RUNTIME_PODS_TEMPLATE_NAME: pipeline-pods-template - - # do not define VELA_WORKER_ADDR here. See "Create a Worker Deployment" below. - - # VELA_RUNTIME_CONFIG is not needed in-cluster. - # We'll use the auto-mounted ServiceAccount Token. -``` - -And then load them in your cluster. - -```shell -$ kubectl apply -f worker-secret.yaml -$ kubectl apply -f worker-configmap.yaml -``` - -:::info -For a full list of configuration options, please see the [worker reference](/docs/reference/installation/worker/worker.md). -::: - - -### Step 2: Load the Pipeline Pods Template CRD - -Download Vela's "Pipeline Pods Template" Custom Resource Definition (CRD). -Be sure to replace `v0.14.0` with the version you're installing. - -```shell -$ curl https://raw.githubusercontent.com/go-vela/worker/v0.14.0/runtime/kubernetes/generated/go-vela.github.io_pipelinepodstemplates.yaml -o go-vela.github.io_pipelinepodstemplates.yaml -``` - -And then add the CRD to your cluster. - -```shell -$ kubectl apply -f go-vela.github.io_pipelinepodstemplates.yaml -``` - -### Step 3: Create a Pipeline Pods Template - -The Pipeline Pods Template allows you to define `annotations`, `securityContext`, `dnsConfig` -and other settings that the worker should add to every Pipeline's `Pod`. - -```yaml -apiVersion: go-vela.github.io/v1alpha1 -kind: PipelinePodsTemplate -metadata: - name: pipeline-pods-template # this should match VELA_RUNTIME_PODS_TEMPLATE_NAME - namespace: default -spec: - # spec.template is a subset of what is possible to define in a Deployment's "spec.template". - template: - - metadata: - # custom annotations to add to all pipeline pods - annotations: - example.com/owner: devops - #labels: - - #spec: - # dnsConfig: {} - # dnsPolicy: ClusterFirst - - # nodeSelector: {} - # tolerations: [] - # affinity: {} - - # # These gets applied to all containers in the Pipeline Pod. - # container: - # securityContext: - # capabilities: - # drop: ["ALL"] - # add: [] -``` - -And then your `PipelinePodsTemplate` to your cluster. - -```shell -$ kubectl apply -f pipeline-pods-template.yaml -``` - -### Step 5: Create a ServiceAccount, Role, and RoleBinding - -The Worker needs access to Kubernetes APIs. It uses an auto-mounted ServiceAcount token to do this. - -Here is a ServiceAccount: -```yaml -apiVersion: v1 -kind: ServiceAccount -metadata: - name: vela-worker - namespace: default -``` - -Here's the Role you'll need: -```yaml -kind: Role -apiVersion: rbac.authorization.k8s.io/v1 -metadata: - name: vela-worker - namespace: default -rules: - - apiGroups: [""] - resources: [pods/log] - verbs: [get, list, watch] - - apiGroups: [""] - resources: [pods] - verbs: [create, patch, get, list, update, watch, delete] - - apiGroups: ["go-vela.github.io"] - resources: [pipelinepodstemplate] - verbs: [get, list, watch] -``` - -And use this RoleBinding: -```yaml -kind: RoleBinding -apiVersion: rbac.authorization.k8s.io/v1 -metadata: - name: vela-worker - namespace: default -subjects: - - kind: ServiceAccount - name: vela-worker - namespace: default -roleRef: - kind: Role - name: vela-worker - apiGroup: rbac.authorization.k8s.io -``` - -Then apply each of these to your cluster: - -```shell -$ kubectl apply -f worker-serviceaccount.yaml -$ kubectl apply -f worker-role.yaml -$ kubectl apply -f worker-role-binding.yaml -``` - -### Step 5: Create a Worker Deployment - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: vela-worker - namespace: default - labels: - app.kubernetes.io/name: vela-worker -spec: - replicas: 1 # Increase this to deploy more worker pods. - selector: - matchLabels: - app.kubernetes.io/name: vela-worker - serviceAccount: vela-worker - containers: - - name: worker - image: target/vela-worker:v0.13.0 - ports: - - {name: http, port: 8080, protocol: TCP} - livenessProbe: - httpGet: {path: /health, port: 8080, scheme: HTTP} - env: - - {name: VELA_WORKER_ADDR_SCHEME, value: http} - - {name: VELA_WORKER_ADDR_PORT, value: "8080"} - - name: VELA_WORKER_POD_NAME - valueFrom: - fieldRef: {fieldPath: metadata.name} - - name: VELA_WORKER_POD_IP - valueFrom: - fieldRef: {fieldPath: status.podIP} - # using the pod name does not get a dns entry without a lot of unnecessary effort. - # So, here we use status.podIP instead of metadata.name - - name: VELA_WORKER_ADDR - value: $(VELA_WORKER_ADDR_SCHEME)://$(WORKER_POD_IP):$(VELA_WORKER_ADDR_PORT) - envFrom: - - configMapRef: - name: vela-worker - - secretRef: - name: vela-worker -``` - -And then load it in your cluster. - -```shell -$ kubectl apply -f worker-deployment.yaml -``` - -### Step 6: Verify the Worker Deployment - -Ensure the worker started up successfully and is running as expected by inspecting details with `kubectl`. - -```shell -$ kubectl describe deployment vela-worker -$ kubectl get pods -l app.kubernetes.io/name=vela-worker -``` - -You can also check the worker logs with `stern`. The following command will tail all of the logs -for pods that start with `vela-worker-`: - -```shell -$ stern vela-worker- -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/installation/worker/worker.md b/versioned_docs/version-0.26/installation/worker/worker.md deleted file mode 100644 index 9ea6cc5..0000000 --- a/versioned_docs/version-0.26/installation/worker/worker.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Worker - -Known as the brawn of the Vela application, this service is responsible for managing the state of build resources. - -This includes pulling the build, provided by the [server](/docs/installation/server/server.md), from the queue to be run. - -When a build is fetched from the queue, the worker will create and delete resources through the lifecycle of the build. - -During this time, the worker will send API requests to the server to report the status and progress of these resources. - -Additionally, the worker has its own API for processing web requests. - -![Build Workflow](/img/build_workflow.png) - -## Deployment Guides - -Vela supports a number of deployment strategies to enable the preferences of you and your team. - -This section provides a list of comprehensive guides to install and start the worker: - -### Docker - -From the [Docker official website](https://docker.io/): - -> Docker takes away repetitive, mundane configuration tasks and is used throughout the development lifecycle for fast, easy and portable application development - desktop and cloud. Docker’s comprehensive end to end platform includes UIs, CLIs, APIs and security that are engineered to work together across the entire application delivery lifecycle. - -Please refer to [our Docker deployment guide](/docs/installation/server/docker.md) to get started. - - diff --git a/versioned_docs/version-0.26/reference/_index.md b/versioned_docs/version-0.26/reference/_index.md deleted file mode 100644 index 903122c..0000000 --- a/versioned_docs/version-0.26/reference/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Reference" -linkTitle: "Reference" -layout: reference -description: > - Reference information for creating pipelines and using the CLI, API, or SDKs. -menu: - main: - weight: 605 ---- diff --git a/versioned_docs/version-0.26/reference/api/_category_.json b/versioned_docs/version-0.26/reference/api/_category_.json deleted file mode 100644 index c995733..0000000 --- a/versioned_docs/version-0.26/reference/api/_category_.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "label": "API", - "position": 1, - "link": { - "type": "generated-index" - } -} diff --git a/versioned_docs/version-0.26/reference/api/admin/admin.md b/versioned_docs/version-0.26/reference/api/admin/admin.md deleted file mode 100644 index d218f74..0000000 --- a/versioned_docs/version-0.26/reference/api/admin/admin.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Admin" -linkTitle: "Admin" -description: > - Learn how to use API endpoints as an admin of the platform. ---- - -The below endpoints are available to operate on as an admin of the platform. - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/api/admin/build.md b/versioned_docs/version-0.26/reference/api/admin/build.md deleted file mode 100644 index cfdedaa..0000000 --- a/versioned_docs/version-0.26/reference/api/admin/build.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: "Build" -linkTitle: "Build" -description: > - Learn how to update a build as an admin in the system. ---- - -## Endpoint - -``` -PUT /api/v1/admin/build -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -Note: You must provide the entire build object, as this endpoint overwrites the -existing entry for the build. - -#### File - -```json -{ - "id": 1, - "repo_id": 1, - "number": 1, - "parent": 1, - "event": "push", - "status": "created", - "error": "", - "enqueued": 1563474077, - "created": 1563474076, - "started": 1563474077, - "finished": 0, - "deploy": "", - "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", - "title": "push received from https://github.com/github/octocat", - "message": "this is an updated message", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", - "branch": "main", - "ref": "refs/heads/main", - "base_ref": "", - "host": "company.localhost", - "runtime": "docker", - "distribution": "linux" -} -``` - -#### Request - -```sh -curl \ - -X PUT \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/admin/build" -``` - -#### Response - -```json -{ - "id": 1, - "repo_id": 1, - "number": 1, - "parent": 1, - "event": "push", - "status": "created", - "error": "", - "enqueued": 1563474077, - "created": 1563474076, - "started": 1563474077, - "finished": 0, - "deploy": "", - "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", - "title": "push received from https://github.com/github/octocat", - "message": "this is an updated message", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", - "branch": "main", - "ref": "refs/heads/main", - "base_ref": "", - "host": "company.localhost", - "runtime": "docker", - "distribution": "linux" -} -``` diff --git a/versioned_docs/version-0.26/reference/api/admin/build_queue.md b/versioned_docs/version-0.26/reference/api/admin/build_queue.md deleted file mode 100644 index b336b34..0000000 --- a/versioned_docs/version-0.26/reference/api/admin/build_queue.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: "Build Queue" -linkTitle: "Build Queue" -description: > - Learn how to list all running and pending builds. ---- - -## Endpoint - -``` -GET /api/v1/admin/builds/queue -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/admin/builds/queue" -``` - -#### Response - -```json -[ - { - "id": 2, - "repo_id": 2, - "number": 1, - "parent": 1, - "event": "push", - "status": "pending", - "error": "", - "enqueued": 1563474204, - "created": 1563474204, - "started": 1563474204, - "finished": 0, - "deploy": "", - "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", - "title": "push received from https://github.com/github/octocat", - "message": "Second commit...", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", - "branch": "main", - "ref": "refs/heads/main", - "base_ref": "", - "host": "ed95dcc0687c", - "runtime": "", - "distribution": "" - }, - { - "id": 1, - "repo_id": 1, - "number": 1, - "parent": 1, - "event": "push", - "status": "running", - "error": "", - "enqueued": 1563474077, - "created": 1563474076, - "started": 1563474077, - "finished": 0, - "deploy": "", - "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", - "title": "push received from https://github.com/github/octocat", - "message": "First commit...", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", - "branch": "main", - "ref": "refs/heads/main", - "base_ref": "", - "host": "82823eb770b0", - "runtime": "", - "distribution": "" - } -] -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/admin/clean.md b/versioned_docs/version-0.26/reference/api/admin/clean.md deleted file mode 100644 index 075d35f..0000000 --- a/versioned_docs/version-0.26/reference/api/admin/clean.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: "Clean" -linkTitle: "Clean" -description: > - Learn how to clean dangling resources as an admin in the system. ---- - -## Endpoint - -``` -PUT /api/v1/admin/clean -``` - -## Filters - -The following optional filters are available: - -| Name | Description | -| -------- | ---------------------------------------------------------------------------------------------------------- | -| `before` | clean resources created before a certain time (UNIX Epoch, default = "now" minus repo timeout + 5 minutes) | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `400` | indicates bad request | -| `401` | indicates user does not have proper permissions | -| `500` | indicates internal server issue while cleaning | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "message": "this resource has been set to error by platform admins during maintenance" -} -``` - -Note: the default value for `message` is "build cleaned by platform admin" - -#### Request - -```sh -curl \ - -X PUT \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/admin/clean" -``` - -#### Response - -```json - "42 builds cleaned. 42 services cleaned. 42 steps cleaned." -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/admin/hook.md b/versioned_docs/version-0.26/reference/api/admin/hook.md deleted file mode 100644 index 59bd26e..0000000 --- a/versioned_docs/version-0.26/reference/api/admin/hook.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: "Hook" -linkTitle: "Hook" -description: > - Learn how to update a hook as an admin in the system. ---- - -## Endpoint - -``` -PUT /api/v1/admin/hook -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -Note: You must provide the entire hook object, as this endpoint overwrites the -existing entry for the hook. - -#### File - -```json -{ - "id": 1, - "repo_id": 1, - "build_id": 1, - "number": 1, - "source_id": "c8da1302-07d6-11ea-882f-4893bca275b8", - "created": "1563474076", - "host": "github.com", - "event": "push", - "branch": "main", - "error": "", - "status": "failure", - "link": "" -} -``` - -#### Request - -```sh -curl \ - -X PUT \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/admin/hook" -``` - -#### Response - -```json -{ - "id": 1, - "repo_id": 1, - "build_id": 1, - "number": 1, - "source_id": "c8da1302-07d6-11ea-882f-4893bca275b8", - "created": "1563474076", - "host": "github.com", - "event": "push", - "branch": "main", - "error": "", - "status": "failure", - "link": "" -} -``` diff --git a/versioned_docs/version-0.26/reference/api/admin/repo.md b/versioned_docs/version-0.26/reference/api/admin/repo.md deleted file mode 100644 index 8f0b7c4..0000000 --- a/versioned_docs/version-0.26/reference/api/admin/repo.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: "Repo" -linkTitle: "Repo" -description: > - Learn how to update a repo as an admin in the system. ---- - -## Endpoint - -``` -PUT /api/v1/admin/repo -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -Note: You must provide the entire repo object, as this endpoint overwrites the -existing entry for the repo. - -#### File - -```json -{ - "id": 1, - "user_id": 1, - "org": "github", - "name": "octocat", - "full_name": "github/octocat", - "link": "https://github.com/github/octocat", - "clone": "https://github.com/github/octocat.git", - "branch": "main", - "build_limit": 10, - "timeout": 60, - "counter": 0, - "visibility": "public", - "private": false, - "trusted": true, - "active": true, - "allow_pull": true, - "allow_push": true, - "allow_deploy": false, - "allow_tag": true, - "allow_comment": false, - "pipeline_type": "yaml" -} -``` - -#### Request - -```sh -curl \ - -X PUT \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/admin/repo" -``` - -#### Response - -```json -{ - "id": 1, - "user_id": 1, - "org": "github", - "name": "octocat", - "full_name": "github/octocat", - "link": "https://github.com/github/octocat", - "clone": "https://github.com/github/octocat.git", - "branch": "main", - "build_limit": 10, - "timeout": 60, - "counter": 0, - "visibility": "public", - "private": false, - "trusted": true, - "active": true, - "allow_pull": true, - "allow_push": true, - "allow_deploy": false, - "allow_tag": true, - "allow_comment": false, - "pipeline_type": "yaml" -} -``` diff --git a/versioned_docs/version-0.26/reference/api/admin/secret.md b/versioned_docs/version-0.26/reference/api/admin/secret.md deleted file mode 100644 index 4fcb182..0000000 --- a/versioned_docs/version-0.26/reference/api/admin/secret.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: "Secret" -linkTitle: "Secret" -description: > - Learn how to update a secret as an admin in the system. ---- - -## Endpoint - -``` -PUT /api/v1/admin/secret -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -Note: You must provide the entire secret object, as this endpoint overwrites the -existing entry for the secret. - -#### File - -```json -{ - "id": 1, - "org": "github", - "repo": "octocat", - "team": "", - "name": "foo", - "value": "", - "type": "repo", - "images": ["alpine"], - "events": ["push", "tag"], - "allow_command": true, - "allow_substitution": true, - "allow_events": { - "push": { - "branch": true, - "tag": true, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": true - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "created_at": 1641314085, - "created_by": "octokitty", - "updated_at": 1641314500, - "updated_by": "octocat" -} -``` - -#### Request - -```sh -curl \ - -X PUT \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" - "http://127.0.0.1:8080/api/v1/admin/secret" -``` - -#### Response - -```json -{ - "id": 1, - "org": "github", - "repo": "octocat", - "team": "", - "name": "foo", - "value": "", - "type": "repo", - "images": ["alpine"], - "events": ["push", "tag"], - "allow_command": true, - "allow_substitution": true, - "allow_events": { - "push": { - "branch": true, - "tag": true, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": true - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "created_at": 1641314085, - "created_by": "octokitty", - "updated_at": 1641314500, - "updated_by": "octocat" -} -``` diff --git a/versioned_docs/version-0.26/reference/api/admin/service.md b/versioned_docs/version-0.26/reference/api/admin/service.md deleted file mode 100644 index b64b8cf..0000000 --- a/versioned_docs/version-0.26/reference/api/admin/service.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: "Service" -linkTitle: "Service" -description: > - Learn how to update a service as an admin in the system. ---- - -## Endpoint - -``` -PUT /api/v1/admin/service -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -Note: You must provide the entire service object, as this endpoint overwrites the -existing entry for the service. - -#### File - -```json -{ - "id": 1, - "build_id": 1, - "repo_id": 1, - "number": 1, - "name": "clone", - "status": "failure", - "error": "", - "exit_code": 0, - "created": 1563475419, - "started": 1563475420, - "finished": 1563475421 -} -``` - -#### Request - -```sh -curl \ - -X PUT \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/admin/service" -``` - -#### Response - -```json -{ - "id": 1, - "build_id": 1, - "repo_id": 1, - "number": 1, - "name": "clone", - "status": "failure", - "error": "", - "exit_code": 0, - "created": 1563475419, - "started": 1563475420, - "finished": 1563475421 -} -``` diff --git a/versioned_docs/version-0.26/reference/api/admin/settings/restore.md b/versioned_docs/version-0.26/reference/api/admin/settings/restore.md deleted file mode 100644 index 8dc3033..0000000 --- a/versioned_docs/version-0.26/reference/api/admin/settings/restore.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: "Restore" -linkTitle: "Restore" -description: > - Learn how to restore settings to the server environment defaults. ---- - -## Endpoint - -``` -DELETE /api/v1/admin/settings -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | ---------------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | -| `404` | indicates the server was unable to retrieve a resource | -| `500` | indicates a server failure while processing the request | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X DELETE \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/admin/settings" -``` - -#### Response - -```json -{ - "id": 1, - "compiler": { - "clone_image": "target/vela-git:latest", - "template_depth": 3, - "starlark_exec_limit": 7500 - }, - "queue": { - "routes": [ - "vela" - ] - }, - "repo_allowlist": [ - "*", - ], - "schedule_allowlist": [ - "github/octocat", - ], - "created_at": 1715718878, - "updated_at": 1715718879, - "updated_by": "octocat" -} -``` diff --git a/versioned_docs/version-0.26/reference/api/admin/settings/settings.md b/versioned_docs/version-0.26/reference/api/admin/settings/settings.md deleted file mode 100644 index 037bdae..0000000 --- a/versioned_docs/version-0.26/reference/api/admin/settings/settings.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Settings" -linkTitle: "Settings" -description: > - Learn how to use API endpoints for platform settings. ---- - -The below endpoints are available to operate on the `settings` resource. - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/api/admin/settings/update.md b/versioned_docs/version-0.26/reference/api/admin/settings/update.md deleted file mode 100644 index 903106a..0000000 --- a/versioned_docs/version-0.26/reference/api/admin/settings/update.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: "Update" -linkTitle: "Update" -description: > - Learn how to update platform settings. ---- - -## Endpoint - -``` -PUT /api/v1/admin/settings -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | ---------------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | -| `404` | indicates the server was unable to retrieve a resource | -| `500` | indicates a server failure while processing the request | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "compiler": { - "clone_image": "target/vela-git:latest", - "template_depth": 3, - "starlark_exec_limit": 7500 - }, - "queue": { - "routes": [ - "vela" - ] - }, - "repo_allowlist": [ - "*", - ], - "schedule_allowlist": [ - "github/octocat", - ] -} -``` - -#### Request - -```sh -curl \ - -X PUT \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/admin/settings" -``` - -#### Response - -```json -{ - "id": 1, - "compiler": { - "clone_image": "target/vela-git:latest", - "template_depth": 3, - "starlark_exec_limit": 7500 - }, - "queue": { - "routes": [ - "vela" - ] - }, - "repo_allowlist": [ - "*", - ], - "schedule_allowlist": [ - "github/octocat", - ], - "created_at": 1715718878, - "updated_at": 1715718879, - "updated_by": "octocat" -} -``` diff --git a/versioned_docs/version-0.26/reference/api/admin/settings/view.md b/versioned_docs/version-0.26/reference/api/admin/settings/view.md deleted file mode 100644 index 6406fda..0000000 --- a/versioned_docs/version-0.26/reference/api/admin/settings/view.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to view active platform settings. ---- - -## Endpoint - -``` -GET /api/v1/admin/settings -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | ---------------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | -| `404` | indicates the server was unable to retrieve a resource | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/admin/settings" -``` - -#### Response - -```json -{ - "id": 1, - "compiler": { - "clone_image": "target/vela-git:latest", - "template_depth": 3, - "starlark_exec_limit": 7500 - }, - "queue": { - "routes": [ - "vela" - ] - }, - "repo_allowlist": [ - "*", - ], - "schedule_allowlist": [ - "github/octocat", - ], - "created_at": 1715718878, - "updated_at": 1715718879, - "updated_by": "octocat" -} -``` diff --git a/versioned_docs/version-0.26/reference/api/admin/step.md b/versioned_docs/version-0.26/reference/api/admin/step.md deleted file mode 100644 index 532d532..0000000 --- a/versioned_docs/version-0.26/reference/api/admin/step.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: "Step" -linkTitle: "Step" -description: > - Learn how to update a step as an admin in the system. ---- - -## Endpoint - -``` -PUT /api/v1/admin/step -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -Note: You must provide the entire step object, as this endpoint overwrites the -existing entry for the step. - -#### File - -```json -{ - "id": 1, - "build_id": 1, - "repo_id": 1, - "number": 1, - "name": "clone", - "status": "failure", - "error": "", - "exit_code": 0, - "created": 1563475419, - "started": 0, - "finished": 0, - "host": "company.localhost", - "runtime": "docker", - "distribution": "linux" -} -``` - -#### Request - -```sh -curl \ - -X PUT \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/admin/step" -``` - -#### Response - -```json -{ - "id": 1, - "build_id": 1, - "repo_id": 1, - "number": 1, - "name": "clone", - "status": "failure", - "error": "", - "exit_code": 0, - "created": 1563475419, - "started": 0, - "finished": 0, - "host": "company.localhost", - "runtime": "docker", - "distribution": "linux" -} -``` diff --git a/versioned_docs/version-0.26/reference/api/admin/user.md b/versioned_docs/version-0.26/reference/api/admin/user.md deleted file mode 100644 index 4e177d9..0000000 --- a/versioned_docs/version-0.26/reference/api/admin/user.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: "User" -linkTitle: "User" -description: > - Learn how to update a user as an admin in the system. ---- - -## Endpoint - -``` -PUT /api/v1/admin/user -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -Note: You must provide the entire service object, as this endpoint overwrites the -existing entry for the service. - -#### File - -```json -{ - "id": 1, - "name": "OctoKitty", - "token": null, - "favorites": ["github/octocat"], - "active": true, - "admin": true -} -``` - -#### Request - -```sh -curl \ - -X PUT \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/admin/user" -``` - -#### Response - -```json -{ - "id": 1, - "name": "OctoKitty", - "token": null, - "favorites": ["github/octocat"], - "active": true, - "admin": true -} -``` diff --git a/versioned_docs/version-0.26/reference/api/admin/worker.md b/versioned_docs/version-0.26/reference/api/admin/worker.md deleted file mode 100644 index 912ef96..0000000 --- a/versioned_docs/version-0.26/reference/api/admin/worker.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "Worker" -linkTitle: "Worker" -description: > - Learn how to request a worker registration token as an admin. ---- - -## Endpoint - -``` -POST /api/v1/admin/workers/:worker/register-token -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X PUT \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - "http://127.0.0.1:8080/api/v1/admin/workers/worker_1/register-token" -``` - -#### Response - -```json -{ - "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ3b3JrZXJfMSIsImlhdCI6MTUxNjIzOTAyMiwiZWF0IjoxNTE2MjQ1MDIyLCJ0b2tlbl90eXBlIjoiV29ya2VyUmVnaXN0ZXIifQ.U2zNa3E8Wwd6ndoVMrwEZ1TWlmMVTZP8-UaShZA1Qpw" -} -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/authentication.md b/versioned_docs/version-0.26/reference/api/authentication.md deleted file mode 100644 index cee017b..0000000 --- a/versioned_docs/version-0.26/reference/api/authentication.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: "Authentication" -sidebar_position: 1 ---- - -## Overview - -Authentication for the Vela API is the responsibility of the client initiating the request. - -Each request requires a token to be provided as an `Authorization` HTTP header. - -The content of this header should be using the `Bearer ` scheme. - -```sh -Authorization: Bearer -``` - -:::info -For more information, you can visit the [Swagger authentication documentation](https://swagger.io/docs/specification/authentication/bearer-authentication/). -::: - -## Format - -Vela tokens are based off the format of the [JSON Web Token](https://jwt.io/) (a.k.a. JWT) standard. - -The token can be broken down into 3 distinct sections, separated by periods (`.`): - -* **Header** - metadata about the type of token and the signing algorithm used -* **Payload** - data (a.k.a. claims) providing additional information -* **Signature** - encoded string based off the header, payload and secret - -```sh -# syntax -header.payload.signature - -# sample -xxxxx.yyyyy.zzzzz -``` - -:::info -For more information, you can visit the [JWT introduction documentation](https://jwt.io/introduction/). -::: - -## Sample - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/users" -``` diff --git a/versioned_docs/version-0.26/reference/api/build/add.md b/versioned_docs/version-0.26/reference/api/build/add.md deleted file mode 100644 index 2ecc073..0000000 --- a/versioned_docs/version-0.26/reference/api/build/add.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: "Add" -linkTitle: "Add" -description: > - Learn how to create a build. ---- - -## Endpoint - -``` -POST /api/v1/repos/:org/:repo/builds -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------ | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "author": "Octokitty", - "branch": "main", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "clone": "https://github.com/github/octocat.git", - "event": "push", - "message": "First commit...", - "ref": "refs/heads/main", - "sender": "Octokitty", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", - "title": "push received from https://github.com/github/octocat" -} -``` - -#### Request - -```sh -curl \ - -X POST \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds" -``` - -#### Response - -```json -{ - "id": 1, - "repo_id": 1, - "number": 1, - "parent": 1, - "event": "push", - "status": "created", - "error": "", - "enqueued": 1563474077, - "created": 1563474076, - "started": 1563474077, - "finished": 0, - "deploy": "", - "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", - "title": "push received from https://github.com/github/octocat", - "message": "First commit...", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", - "branch": "main", - "ref": "refs/heads/main", - "base_ref": "", - "host": "company.localhost", - "runtime": "docker", - "distribution": "linux" -} -``` diff --git a/versioned_docs/version-0.26/reference/api/build/build.md b/versioned_docs/version-0.26/reference/api/build/build.md deleted file mode 100644 index 3ed5cf3..0000000 --- a/versioned_docs/version-0.26/reference/api/build/build.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Build" -linkTitle: "Build" -description: > - Learn how to use API endpoints for the build resource. ---- - -The below endpoints are available to operate on the `build` resource. - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/api/build/cancel.md b/versioned_docs/version-0.26/reference/api/build/cancel.md deleted file mode 100644 index c2741a5..0000000 --- a/versioned_docs/version-0.26/reference/api/build/cancel.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: "Cancel" -linkTitle: "Cancel" -description: > - Learn how to cancel a build. ---- - -## Endpoint - -``` -DELETE /api/v1/repos/:org/:repo/builds/:build/cancel -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | ---------------------------------------------------------| -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | -| `404` | indicates that the server was unable to cancel the build | -| `500` | indicates there was an error trying to cancel the build | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X DELETE \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/cancel" -``` - -#### Response - -```json - "canceled build github/octocat/36" -``` diff --git a/versioned_docs/version-0.26/reference/api/build/get.md b/versioned_docs/version-0.26/reference/api/build/get.md deleted file mode 100644 index 736a348..0000000 --- a/versioned_docs/version-0.26/reference/api/build/get.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to list builds. ---- - -## Endpoint - -``` -GET /api/v1/repos/:org/:repo/builds -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------ | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | - -## Filters - -The following optional filters are available: - -| Name | Description | -| -------- | ----------------------------------------------------------------------- | -| `branch` | name of branch to filter to | -| `commit` | commit hash to filter to | -| `event` | name of event to filter to | -| `page` | page number for results (default 1) | -| `per_page` | number of results in a page (default 10, max 100) | -| `status` | name of status to filter to | -| `before` | return builds created before a certain time (UNIX Epoch, default "now") | -| `after` | return builds created after a certain time (UNIX Epoch, default 0) | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds" -``` - -```sh -# with optional event filter -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds?event=push" -``` - -#### Response - -```json -[ - { - "id": 2, - "repo_id": 1, - "number": 2, - "parent": 1, - "event": "push", - "status": "running", - "error": "", - "enqueued": 1563474204, - "created": 1563474204, - "started": 1563474204, - "finished": 0, - "deploy": "", - "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", - "title": "push received from https://github.com/github/octocat", - "message": "Second commit...", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", - "branch": "main", - "ref": "refs/heads/main", - "base_ref": "", - "host": "ed95dcc0687c", - "runtime": "", - "distribution": "" - }, - { - "id": 1, - "repo_id": 1, - "number": 1, - "parent": 1, - "event": "push", - "status": "running", - "error": "", - "enqueued": 1563474077, - "created": 1563474076, - "started": 1563474077, - "finished": 0, - "deploy": "", - "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", - "title": "push received from https://github.com/github/octocat", - "message": "First commit...", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", - "branch": "main", - "ref": "refs/heads/main", - "base_ref": "", - "host": "82823eb770b0", - "runtime": "", - "distribution": "" - } -] -``` diff --git a/versioned_docs/version-0.26/reference/api/build/logs.md b/versioned_docs/version-0.26/reference/api/build/logs.md deleted file mode 100644 index 51d6cd0..0000000 --- a/versioned_docs/version-0.26/reference/api/build/logs.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: "Logs" -linkTitle: "Logs" -description: > - Learn how to view logs for a build. ---- - -## Endpoint - -``` -GET /api/v1/repos/:org/:repo/builds/:build/logs -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------- | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | -| `build` | number of build | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/logs" -``` - -#### Response - -```json -[ - { - "id": 1, - "step_id": 1, - "build_id": 1, - "repo_id": 1, - "data": "SGVsbG8sIFdvcmxkIQ==" - }, - { - "id": 2, - "step_id": 2, - "build_id": 1, - "repo_id": 1, - "data": "SGVsbG8sIFdvcmxkIQ==" - } -] -``` - -The `data` field is base64 encoded. To decode the data, you can use the following command: - -```sh -echo "SGVsbG8sIFdvcmxkIQ==" | base64 --decode -``` diff --git a/versioned_docs/version-0.26/reference/api/build/remove.md b/versioned_docs/version-0.26/reference/api/build/remove.md deleted file mode 100644 index 2abca56..0000000 --- a/versioned_docs/version-0.26/reference/api/build/remove.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "Remove" -linkTitle: "Remove" -description: > - Learn how to delete a build. ---- - -## Endpoint - -``` -DELETE /api/v1/repos/:org/:repo/builds/:build -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------- | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | -| `build` | number of build | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X DELETE \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1" -``` - -#### Response - -```sh -Build github/octocat/1 deleted -``` diff --git a/versioned_docs/version-0.26/reference/api/build/restart.md b/versioned_docs/version-0.26/reference/api/build/restart.md deleted file mode 100644 index 0c7c7ba..0000000 --- a/versioned_docs/version-0.26/reference/api/build/restart.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: "Restart" -linkTitle: "Restart" -description: > - Learn how to rerun a build. ---- - -## Endpoint - -``` -POST /api/v1/repos/:org/:repo/builds/:build -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------- | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | -| `build` | number of build | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X POST \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1" -``` - -#### Response - -```json -{ - "id": 2, - "repo_id": 1, - "number": 2, - "parent": 1, - "event": "push", - "status": "created", - "error": "", - "enqueued": 1563474077, - "created": 1563474076, - "started": 1563474077, - "finished": 0, - "deploy": "", - "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", - "title": "push received from https://github.com/github/octocat", - "message": "First commit...", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", - "branch": "main", - "ref": "refs/heads/main", - "base_ref": "", - "host": "company.localhost", - "runtime": "docker", - "distribution": "linux" -} -``` diff --git a/versioned_docs/version-0.26/reference/api/build/update.md b/versioned_docs/version-0.26/reference/api/build/update.md deleted file mode 100644 index 5acebf5..0000000 --- a/versioned_docs/version-0.26/reference/api/build/update.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: "Update" -linkTitle: "Update" -description: > - Learn how to modify a build. ---- - -## Endpoint - -``` -PUT /api/v1/repos/:org/:repo/builds/:build -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------- | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | -| `build` | number of build | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "message": "this is an updated message" -} -``` - -#### Request - -```sh -curl \ - -X PUT \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1" -``` - -#### Response - -```json -{ - "id": 1, - "repo_id": 1, - "number": 1, - "parent": 1, - "event": "push", - "status": "created", - "error": "", - "enqueued": 1563474077, - "created": 1563474076, - "started": 1563474077, - "finished": 0, - "deploy": "", - "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", - "title": "push received from https://github.com/github/octocat", - "message": "this is an updated message", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", - "branch": "main", - "ref": "refs/heads/main", - "base_ref": "", - "host": "company.localhost", - "runtime": "docker", - "distribution": "linux" -} -``` diff --git a/versioned_docs/version-0.26/reference/api/build/view.md b/versioned_docs/version-0.26/reference/api/build/view.md deleted file mode 100644 index 5e47e19..0000000 --- a/versioned_docs/version-0.26/reference/api/build/view.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect a build. ---- - -## Endpoint - -``` -GET /api/v1/repos/:org/:repo/builds/:build -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------- | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | -| `build` | number of build | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1" -``` - -#### Response - -```json -{ - "id": 1, - "repo_id": 1, - "number": 1, - "parent": 1, - "event": "push", - "status": "created", - "error": "", - "enqueued": 1563474077, - "created": 1563474076, - "started": 1563474077, - "finished": 0, - "deploy": "", - "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", - "title": "push received from https://github.com/github/octocat", - "message": "First commit...", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", - "branch": "main", - "ref": "refs/heads/main", - "base_ref": "", - "host": "company.localhost", - "runtime": "docker", - "distribution": "linux" -} -``` - -## Alternative Endpoint (By ID) - -``` -GET /api/v1/search/builds/:id -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------- | ----------------------- | -| `id` | unique ID of Vela build | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/search/builds/1" -``` - -#### Response - -```json -{ - "id": 1, - "repo_id": 1, - "number": 1, - "parent": 1, - "event": "push", - "status": "created", - "error": "", - "enqueued": 1563474077, - "created": 1563474076, - "started": 1563474077, - "finished": 0, - "deploy": "", - "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", - "title": "push received from https://github.com/github/octocat", - "message": "First commit...", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", - "branch": "main", - "ref": "refs/heads/main", - "base_ref": "", - "host": "company.localhost", - "runtime": "docker", - "distribution": "linux" -} -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/dashboard/add.md b/versioned_docs/version-0.26/reference/api/dashboard/add.md deleted file mode 100644 index a3285ef..0000000 --- a/versioned_docs/version-0.26/reference/api/dashboard/add.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: "Add" -linkTitle: "Add" -description: > - Learn how to create a dashboard. ---- - -## Endpoint - -``` -POST /api/v1/dashboards -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `201` | indicates the request has succeeded | -| `400` | indicates a bad request | -| `401` | indicates the user does not have proper permissions | -| `500` | indicates a server error | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "name": "test", - "created_at": 1721251709, - "created_by": "Octocat", - "updated_at": 1721251709, - "updated_by": "Octocat", - "admins": [ - { - "id": 1, - "name": "Octocat", - "active": true - } - ], - "repos": [ - { - "name": "Octocat/myvela" - } - ] -} -``` - -#### Request - -```sh -curl \ - -X POST \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/dashboards" -``` - -#### Response - -```json -{ - "id": "f460e0a1-a6a5-4724-89e8-4b2b39e12012", - "name": "test", - "created_at": 1721251709, - "created_by": "Octocat", - "updated_at": 1721253772, - "updated_by": "Octocat", - "admins": [ - { - "id": 1, - "name": "Octocat", - "active": true - } - ], - "repos": [ - { - "id": 293, - "name": "Octocat/myvela" - } - ] -} -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/dashboard/dashboard.md b/versioned_docs/version-0.26/reference/api/dashboard/dashboard.md deleted file mode 100644 index e4b3020..0000000 --- a/versioned_docs/version-0.26/reference/api/dashboard/dashboard.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Dashboard" -linkTitle: "Dashboard" -description: > - Learn how to use API endpoints for the dashboard resource. ---- - -The below endpoints are available to operate on the `dashboard` resource. - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/dashboard/delete.md b/versioned_docs/version-0.26/reference/api/dashboard/delete.md deleted file mode 100644 index 6b1b6b2..0000000 --- a/versioned_docs/version-0.26/reference/api/dashboard/delete.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: "Delete" -linkTitle: "Delete" -description: > - Learn how to delete a dashboard. ---- - -## Endpoint - -``` -DELETE /api/v1/dashboards/:id -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `400` | indicates a bad request | -| `401` | indicates the user does not have proper permissions | -| `500` | indicates a server error | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X DELETE \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/dashboards/f460e0a1-a6a5-4724-89e8-4b2b39e12012" -``` - -#### Response - -``` -"dashboard test deleted" -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/dashboard/get.md b/versioned_docs/version-0.26/reference/api/dashboard/get.md deleted file mode 100644 index 10a6ec0..0000000 --- a/versioned_docs/version-0.26/reference/api/dashboard/get.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to get a dashboard. ---- - -## Endpoint - -``` -GET /api/v1/dashboards/:id -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `400` | indicates a bad request | -| `401` | indicates the user does not have proper permissions | -| `404` | indicates the resource does not exist | -| `500` | indicates a server error | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/dashboards/3e84cf64-4730-4067-bdbc-6961e37a3a92" -``` - -#### Response - -```json -{ - "dashboard": { - "id": "3e84cf64-4730-4067-bdbc-6961e37a3a92", - "name": "test", - "created_at": 1721254450, - "created_by": "Octocat", - "updated_at": 1721254596, - "updated_by": "Octocat", - "admins": [ - { - "id": 126, - "name": "Octocat", - "active": true - } - ], - "repos": [ - { - "id": 293, - "name": "Octocat/myvela" - } - ] - }, - "repos": [ - { - "org": "Octocat", - "name": "myvela", - "counter": 1703, - "active": true, - "builds": [ - { - "number": 1703, - "started": 1721164234, - "finished": 1721164240, - "sender": "Octocat", - "status": "success", - "event": "push", - "branch": "develop", - "link": "https://http://127.0.0.1:8080/Octocat/myvela/1703" - }, - { - "number": 1702, - "sender": "Octocat", - "status": "pending approval", - "event": "pull_request", - "branch": "main", - "link": "https://http://127.0.0.1:8080/Octocat/myvela/1702" - }, - { - "number": 1701, - "started": 1721071014, - "finished": 1721071016, - "sender": "Octocat", - "status": "failure", - "event": "push", - "branch": "develop", - "link": "https://http://127.0.0.1:8080/Octocat/myvela/1701" - }, - { - "number": 1700, - "started": 1721070428, - "finished": 1721070441, - "sender": "Octocat", - "status": "failure", - "event": "push", - "branch": "develop", - "link": "https://http://127.0.0.1:8080/Octocat/myvela/1700" - }, - { - "number": 1699, - "started": 1721070363, - "finished": 1721070375, - "sender": "Octocat", - "status": "failure", - "event": "push", - "branch": "develop", - "link": "https://http://127.0.0.1:8080/Octocat/myvela/1699" - } - ] - } - ] -} -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/dashboard/list.md b/versioned_docs/version-0.26/reference/api/dashboard/list.md deleted file mode 100644 index 1e7c81a..0000000 --- a/versioned_docs/version-0.26/reference/api/dashboard/list.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: "List" -linkTitle: "List" -description: > - Learn how to list your dashboards. ---- - -## Endpoint - -``` -GET /api/v1/user/dashboards -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `400` | indicates a bad request | -| `401` | indicates the user does not have proper permissions | -| `404` | indicates the resource does not exist | -| `500` | indicates a server error | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/user/dashboards" -``` - -#### Response - -```json -[ - { - "dashboard": { - "id": "215d0834-a08a-4203-aee5-542681c4dc8d", - "name": "Friends", - "created_at": 1718118753, - "created_by": "Octocat", - "updated_at": 1718120350, - "updated_by": "OctoKitty", - "admins": [ - { - "id": 287, - "name": "OctoKitty", - "active": true - }, - { - "id": 126, - "name": "Octocat", - "active": true - } - ], - "repos": [ - { - "id": 293, - "name": "Octocat/myvela" - }, - { - "id": 34, - "name": "OctoPal/heyvela" - } - ] - }, - "repos": [ - // repo build information - ] - }, - { - "dashboard": { - "id": "3e84cf64-4730-4067-bdbc-6961e37a3a92", - "name": "test", - "created_at": 1721254450, - "created_by": "Octocat", - "updated_at": 1721254596, - "updated_by": "Octocat", - "admins": [ - { - "id": 126, - "name": "Octocat", - "active": true - } - ], - "repos": [ - { - "id": 293, - "name": "Octocat/myvela" - } - ] - }, - "repos": [ - // repo build information - ] - } -] -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/dashboard/update.md b/versioned_docs/version-0.26/reference/api/dashboard/update.md deleted file mode 100644 index 55e7524..0000000 --- a/versioned_docs/version-0.26/reference/api/dashboard/update.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: "Update" -linkTitle: "Update" -description: > - Learn how to update a dashboard. ---- - -## Endpoint - -``` -PUT /api/v1/dashboards/:id -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `400` | indicates a bad request | -| `401` | indicates the user does not have proper permissions | -| `500` | indicates a server error | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "id": "f460e0a1-a6a5-4724-89e8-4b2b39e12012", - "name": "new-name", - "admins": [ - { - "id": 1, - "name": "Octocat", - "active": true - }, - { - "name": "MyFriend" - } - ], - "repos": [ - { - "name": "Octocat/myvela" - }, - { - "name": "Octocat/other-repo" - } - ] -} -``` - -#### Request - -```sh -curl \ - -X PUT \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/dashboards/f460e0a1-a6a5-4724-89e8-4b2b39e12012" -``` - -#### Response - -```json -{ - "id": "f460e0a1-a6a5-4724-89e8-4b2b39e12012", - "name": "new-name", - "created_at": 1721251709, - "created_by": "Octocat", - "updated_at": 1721253772, - "updated_by": "Octocat", - "admins": [ - { - "id": 1, - "name": "Octocat", - "active": true - }, - { - "id": 2, - "name": "MyFriend", - "active": true - } - ], - "repos": [ - { - "id": 293, - "name": "Octocat/myvela" - }, - { - "id": 294, - "name": "Octocat/other-repo" - } - ] -} -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/deployment/add.md b/versioned_docs/version-0.26/reference/api/deployment/add.md deleted file mode 100644 index 9179979..0000000 --- a/versioned_docs/version-0.26/reference/api/deployment/add.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: "Add" -linkTitle: "Add" -description: > - Learn how to create a deployment. ---- - -## Endpoint - -``` -POST /api/v1/deployments/:org/:repo -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------ | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "ref": "main", - "target": "production" -} -``` - -#### Request - -```sh -curl \ - -X POST \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/deployments/github/octocat" -``` - -#### Response - -```json -{ - "id": 1, - "repo_id": 1, - "url": "https://api.github.com/repos/github/octocat/deployments/1", - "user": "octocat", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "ref": "main", - "task": "deploy:vela", - "target": "production", - "description": "Deployment request from Vela" -} -``` - -#### File with Parameters - -If you would like to pass parameters, which can be referenced in the pipeline as `$DEPLOYMENT_PARAMETER_`, include them as a map inside the `payload` key. - -```json -{ - "ref": "main", - "target": "production", - "payload": { - "FIRST_EXAMPLE": "hello", - "SECOND_EXAMPLE": "goodbye" - } -} -``` - -#### Request with Parameters - -```sh -curl \ - -X POST \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/deployments/github/octocat" -``` - -#### Response with Parameters - -```json -{ - "id": 1, - "repo_id": 1, - "url": "https://api.github.com/repos/github/octocat/deployments/1", - "user": "octocat", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "ref": "main", - "task": "deploy:vela", - "target": "production", - "description": "Deployment request from Vela", - "payload": { - "EXAMPLE": "hello", - "SECOND_EXAMPLE": "goodbye" - } -} -``` diff --git a/versioned_docs/version-0.26/reference/api/deployment/deployment.md b/versioned_docs/version-0.26/reference/api/deployment/deployment.md deleted file mode 100644 index 190298e..0000000 --- a/versioned_docs/version-0.26/reference/api/deployment/deployment.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Deployment" -linkTitle: "Deployment" -description: > - Learn how to use API endpoints for the deployment resource. ---- - -The below endpoints are available to operate on the `deployment` resource. - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/api/deployment/get.md b/versioned_docs/version-0.26/reference/api/deployment/get.md deleted file mode 100644 index c41a37c..0000000 --- a/versioned_docs/version-0.26/reference/api/deployment/get.md +++ /dev/null @@ -1,138 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to list deployments. ---- - -## Endpoint - -``` -GET /api/v1/deployments/:org/:repo -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------ | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/deployments/github/octocat" -``` - -#### Response - -```json -[ - { - "id": 2, - "repo_id": 1, - "url": "https://api.github.com/repos/github/octocat/deployments/2", - "user": "octocat", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "ref": "main", - "task": "deploy:vela", - "target": "production", - "description": "Deployment request from Vela", - "payload": {}, - "builds": [ - { - "id": 10, - "repo_id": 1, - "number": 5, - "parent": 4, - "event": "push", - "status": "created", - "error": "", - "enqueued": 1563474204, - "created": 1563474204, - "started": 1563474204, - "finished": 0, - "deploy": "", - "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", - "title": "push received from https://github.com/github/octocat", - "message": "Second commit...", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", - "branch": "main", - "ref": "refs/heads/main", - "base_ref": "", - "host": "ed95dcc0687c", - "runtime": "", - "distribution": "" - } - ] - }, - { - "id": 9, - "repo_id": 1, - "url": "https://api.github.com/repos/github/octocat/deployments/9", - "user": "octocat", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "ref": "main", - "task": "deploy:vela", - "target": "production", - "description": "Deployment request from Vela", - "payload": {}, - "builds": [ - { - "id": 1, - "repo_id": 1, - "number": 3, - "parent": 2, - "event": "push", - "status": "created", - "error": "", - "enqueued": 1563474077, - "created": 1563474076, - "started": 1563474077, - "finished": 0, - "deploy": "", - "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", - "title": "push received from https://github.com/github/octocat", - "message": "First commit...", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", - "branch": "main", - "ref": "refs/heads/main", - "base_ref": "", - "host": "82823eb770b0", - "runtime": "", - "distribution": "" - } - ] - } -] -``` diff --git a/versioned_docs/version-0.26/reference/api/deployment/view.md b/versioned_docs/version-0.26/reference/api/deployment/view.md deleted file mode 100644 index a995bad..0000000 --- a/versioned_docs/version-0.26/reference/api/deployment/view.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect a deployment. ---- - -## Endpoint - -``` -GET /api/v1/deployments/:org/:repo/:deployment -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------------ | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | -| `deployment` | number of deployment | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/deployments/github/octocat/1" -``` - -#### Response - -```json -{ - "id": 1, - "repo_id": 1, - "url": "https://api.github.com/repos/github/octocat/deployments/1", - "user": "octocat", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "ref": "main", - "task": "deploy:vela", - "target": "production", - "description": "Deployment request from Vela" -} -``` diff --git a/versioned_docs/version-0.26/reference/api/hook/add.md b/versioned_docs/version-0.26/reference/api/hook/add.md deleted file mode 100644 index 820adfc..0000000 --- a/versioned_docs/version-0.26/reference/api/hook/add.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -title: "Add" -linkTitle: "Add" -description: > - Learn how to create a hook. ---- - -## Endpoint - -``` -POST /api/v1/hooks/:org/:repo -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------ | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "number": 1, - "source_id": "c8da1302-07d6-11ea-882f-4893bca275b8", - "host": "github.com", - "event": "push", - "branch": "main", - "status": "success" -} -``` - -#### Request - -```sh -curl \ - -X POST \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/hooks/github/octocat" -``` - -#### Response - -```json -{ - "id": 2, - "number": 2, - "source_id": "c8da1302-07d6-11ea-882f-4893bca275b8", - "created": "1563474076", - "host": "github.com", - "event": "push", - "branch": "main", - "error": "", - "status": "success", - "link": "", - "repo": { - "id": 1, - "user_id": 1, - "org": "github", - "name": "octocat", - "full_name": "github/octocat", - "link": "https://github.com/github/octocat", - "clone": "https://github.com/github/octocat.git", - "branch": "main", - "build_limit": 10, - "timeout": 60, - "counter": 0, - "visibility": "public", - "private": false, - "trusted": true, - "active": true, - "allow_pull": true, - "allow_push": true, - "allow_deploy": false, - "allow_tag": false, - "allow_comment": false, - "allow_events": { - "push": { - "branch": true, - "tag": true, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": true - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "pipeline_type": "yaml" - }, - "build": { - "id": 10, - "repo": { - "id": 1, - }, - "number": 5, - "parent": 4, - "event": "push", - "status": "created", - "error": "", - "enqueued": 1563474204, - "created": 1563474204, - "started": 1563474204, - "finished": 0, - "deploy": "", - "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", - "title": "push received from https://github.com/github/octocat", - "message": "Second commit...", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", - "branch": "main", - "ref": "refs/heads/main", - "base_ref": "", - "host": "ed95dcc0687c", - "runtime": "", - "distribution": "" - } -} -``` diff --git a/versioned_docs/version-0.26/reference/api/hook/get.md b/versioned_docs/version-0.26/reference/api/hook/get.md deleted file mode 100644 index e1f3e0f..0000000 --- a/versioned_docs/version-0.26/reference/api/hook/get.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to list hooks. ---- - -## Endpoint - -``` -GET /api/v1/hooks/:org/:repo -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------ | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/hooks/github/octocat" -``` - -#### Response - -```json -[ - { - "id": 2, - "number": 2, - "source_id": "c8da1302-07d6-11ea-882f-4893bca275b8", - "created": "1563474076", - "host": "github.com", - "event": "push", - "branch": "main", - "error": "", - "status": "success", - "link": "", - "repo": { - "id": 1, - "user_id": 1, - "org": "github", - "name": "octocat", - "full_name": "github/octocat", - "link": "https://github.com/github/octocat", - "clone": "https://github.com/github/octocat.git", - "branch": "main", - "build_limit": 10, - "timeout": 60, - "counter": 0, - "visibility": "public", - "private": false, - "trusted": true, - "active": true, - "allow_pull": true, - "allow_push": true, - "allow_deploy": false, - "allow_tag": false, - "allow_comment": false, - "allow_events": { - "push": { - "branch": true, - "tag": true, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": true - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "pipeline_type": "yaml" - }, - "build": { - "id": 10, - "repo": { - "id": 1, - }, - "number": 5, - "parent": 4, - "event": "push", - "status": "created", - "error": "", - "enqueued": 1563474204, - "created": 1563474204, - "started": 1563474204, - "finished": 0, - "deploy": "", - "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", - "title": "push received from https://github.com/github/octocat", - "message": "Second commit...", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", - "branch": "main", - "ref": "refs/heads/main", - "base_ref": "", - "host": "ed95dcc0687c", - "runtime": "", - "distribution": "" - } - } -] -``` diff --git a/versioned_docs/version-0.26/reference/api/hook/hook.md b/versioned_docs/version-0.26/reference/api/hook/hook.md deleted file mode 100644 index f6510b5..0000000 --- a/versioned_docs/version-0.26/reference/api/hook/hook.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Hook" -linkTitle: "Hook" -description: > - Learn how to use API endpoints for the hook resource. ---- - -The below endpoints are available to operate on the `hook` resource. - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/api/hook/remove.md b/versioned_docs/version-0.26/reference/api/hook/remove.md deleted file mode 100644 index 6cafda3..0000000 --- a/versioned_docs/version-0.26/reference/api/hook/remove.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "Remove" -linkTitle: "Remove" -description: > - Learn how to delete a hook. ---- - -## Endpoint - -``` -DELETE /api/v1/hooks/:org/:repo/:hook -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------ | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | -| `hook` | number of hook | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X DELETE \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/hooks/github/octocat/1" -``` - -#### Response - -```sh -Hook github/octocat/1 deleted -``` diff --git a/versioned_docs/version-0.26/reference/api/hook/update.md b/versioned_docs/version-0.26/reference/api/hook/update.md deleted file mode 100644 index 7870402..0000000 --- a/versioned_docs/version-0.26/reference/api/hook/update.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: "Update" -linkTitle: "Update" -description: > - Learn how to modify a hook. ---- - -## Endpoint - -``` -PUT /api/v1/hooks/:org/:repo/:hook -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------ | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | -| `hook` | number of hook | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "status": "failure" -} -``` - -#### Request - -```sh -curl \ - -X PUT \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/hooks/github/octocat/1" -``` - -#### Response - -```json -{ - "id": 2, - "number": 2, - "source_id": "c8da1302-07d6-11ea-882f-4893bca275b8", - "created": "1563474076", - "host": "github.com", - "event": "push", - "branch": "main", - "error": "", - "status": "success", - "link": "", - "repo": { - "id": 1, - "user_id": 1, - "org": "github", - "name": "octocat", - "full_name": "github/octocat", - "link": "https://github.com/github/octocat", - "clone": "https://github.com/github/octocat.git", - "branch": "main", - "build_limit": 10, - "timeout": 60, - "counter": 0, - "visibility": "public", - "private": false, - "trusted": true, - "active": true, - "allow_pull": true, - "allow_push": true, - "allow_deploy": false, - "allow_tag": false, - "allow_comment": false, - "allow_events": { - "push": { - "branch": true, - "tag": true, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": true - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "pipeline_type": "yaml" - }, - "build": { - "id": 10, - "repo": { - "id": 1, - }, - "number": 5, - "parent": 4, - "event": "push", - "status": "created", - "error": "", - "enqueued": 1563474204, - "created": 1563474204, - "started": 1563474204, - "finished": 0, - "deploy": "", - "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", - "title": "push received from https://github.com/github/octocat", - "message": "Second commit...", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", - "branch": "main", - "ref": "refs/heads/main", - "base_ref": "", - "host": "ed95dcc0687c", - "runtime": "", - "distribution": "" - } -} -``` diff --git a/versioned_docs/version-0.26/reference/api/hook/view.md b/versioned_docs/version-0.26/reference/api/hook/view.md deleted file mode 100644 index 9bb043b..0000000 --- a/versioned_docs/version-0.26/reference/api/hook/view.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect a hook. ---- - -## Endpoint - -``` -GET /api/v1/hooks/:org/:repo/:hook -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------ | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | -| `hook` | number of hook | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/hooks/github/octocat/1" -``` - -#### Response - -```json -{ - "id": 2, - "number": 2, - "source_id": "c8da1302-07d6-11ea-882f-4893bca275b8", - "created": "1563474076", - "host": "github.com", - "event": "push", - "branch": "main", - "error": "", - "status": "success", - "link": "", - "repo": { - "id": 1, - "user_id": 1, - "org": "github", - "name": "octocat", - "full_name": "github/octocat", - "link": "https://github.com/github/octocat", - "clone": "https://github.com/github/octocat.git", - "branch": "main", - "build_limit": 10, - "timeout": 60, - "counter": 0, - "visibility": "public", - "private": false, - "trusted": true, - "active": true, - "allow_pull": true, - "allow_push": true, - "allow_deploy": false, - "allow_tag": false, - "allow_comment": false, - "allow_events": { - "push": { - "branch": true, - "tag": true, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": true - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "pipeline_type": "yaml" - }, - "build": { - "id": 10, - "repo": { - "id": 1, - }, - "number": 5, - "parent": 4, - "event": "push", - "status": "created", - "error": "", - "enqueued": 1563474204, - "created": 1563474204, - "started": 1563474204, - "finished": 0, - "deploy": "", - "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", - "title": "push received from https://github.com/github/octocat", - "message": "Second commit...", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", - "branch": "main", - "ref": "refs/heads/main", - "base_ref": "", - "host": "ed95dcc0687c", - "runtime": "", - "distribution": "" - } -} -``` diff --git a/versioned_docs/version-0.26/reference/api/metrics/metrics.md b/versioned_docs/version-0.26/reference/api/metrics/metrics.md deleted file mode 100644 index aa464f5..0000000 --- a/versioned_docs/version-0.26/reference/api/metrics/metrics.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: "Metrics" -linkTitle: "Metrics" -description: > - Learn how to list metrics. ---- - -## Endpoint - -``` -GET /metrics -``` - -## Query Parameters - -The following parameters are used to configure the endpoint: - -| Query Parameter | Description | -| ------------------------ | ----------------------------------------------------------------------------- | -| `user_count` | count of total users | -| `repo_count` | count of total repos | -| `build_count` | count of total builds | -| `running_build_count` | count of builds with status 'running' | -| `failure_build_count` | count of builds with status 'failure' | -| `pending_build_count` | count of builds with status 'pending' | -| `queued_build_count` | count of builds inside the queue | -| `killed_build_count` | count of builds with status 'killed' | -| `success_build_count` | count of builds with status 'success' | -| `error_build_count` | count of builds with status 'error' | -| `step_image_count` | count of total steps executed with each unique image | -| `step_status_count` | count of total steps with each status | -| `service_image_count` | count of total services executed with each unique image | -| `service_status_count` | count of total services with each status | -| `worker_build_limit` | count of worker build limits | -| `active_worker_count` | count of active workers | -| `inactive_worker_count` | count of inactive workers | -| `idle_worker_count` | count of workers with a status of idle (no running builds) | -| `available_worker_count` | count of workers with a status of available (one or more available executors) | -| `busy_worker_count` | count of workers with a status of busy (no available executors) | -| `error_worker_count` | count of workers with a status of error | - -## Permissions - -No permission restrictions for this endpoint. - -## Responses - -| Status Code | Description | -| ----------- | ------------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `500` | indicates a server failure while processing the request | - -## Sample - -#### Request - -```sh -curl \ - -X GET \ - "http://127.0.0.1:8080/metrics?pending_build_count=true" -``` - -#### Response - -```json -# HELP go_gc_duration_seconds A summary of the pause duration of garbage collection cycles. -# TYPE go_gc_duration_seconds summary -go_gc_duration_seconds{quantile="0"} 4.0986e-05 -# TYPE vela_totals gauge -vela_totals{field="status",resource="build",value="pending"} 31 -``` diff --git a/versioned_docs/version-0.26/reference/api/pipeline/add.md b/versioned_docs/version-0.26/reference/api/pipeline/add.md deleted file mode 100644 index 435ebc7..0000000 --- a/versioned_docs/version-0.26/reference/api/pipeline/add.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: "Add" -linkTitle: "Add" -description: > - Learn how to create a pipeline. ---- - -## Endpoint - -``` -POST /api/v1/pipelines/:org/:repo -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -|------------|----------------------| -| `org` | name of organization | -| `repo` | name of repository | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- |-----------------------------------------------------| -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "ref": "refs/heads/main", - "type": "yaml", - "version": "1", - "steps": true, - "data": "LS0tCnZlcnNpb246ICIxIgoKc3RlcHM6CiAgLSBuYW1lOiBlY2hvCiAgICBpbWFnZTogYWxwaW5lOmxhdGVzdAogICAgY29tbWFuZHM6IFtlY2hvIGZvb10=" -} -``` - -#### Request - -```sh -curl \ - -X POST \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/pipelines/github/octocat" -``` - -#### Response - -```json -{ - "id": 1, - "repo_id": 1, - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "flavor": "", - "platform": "", - "ref": "refs/heads/main", - "type": "yaml", - "version": "1", - "external_secrets": false, - "internal_secrets": false, - "services": false, - "stages": false, - "steps": true, - "templates": false, - "data": "LS0tCnZlcnNpb246ICIxIgoKc3RlcHM6CiAgLSBuYW1lOiBlY2hvCiAgICBpbWFnZTogYWxwaW5lOmxhdGVzdAogICAgY29tbWFuZHM6IFtlY2hvIGZvb10=" -} -``` diff --git a/versioned_docs/version-0.26/reference/api/pipeline/compile.md b/versioned_docs/version-0.26/reference/api/pipeline/compile.md deleted file mode 100644 index 051ef16..0000000 --- a/versioned_docs/version-0.26/reference/api/pipeline/compile.md +++ /dev/null @@ -1,212 +0,0 @@ ---- -title: "Compile" -linkTitle: "Compile" -description: > - Learn how to compile a pipeline configuration with templates. ---- - -## Endpoint - -``` -POST /api/v1/pipelines/:org/:repo/:pipeline/compile -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -|------------|-----------------------------------------------------------| -| `org` | name of organization | -| `repo` | name of repository | -| `pipeline` | commit SHA for pipeline from repository | -| `output` | format the output for the compiled pipeline configuration | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `400` | unable to retrieve or compile the pipeline configuration and templates | -| `401` | indicates the user does not have proper permissions | -| `404` | unable to retrieve or compile the pipeline configuration or templates | -| `500` | system error while retrieving or compiling the pipeline configuration templates | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X POST \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/pipelines/github/octocat/48afb5bdc41ad69bf22588491333f7cf71135163/compile" -``` - -#### Response - -:::warning -Notice, when compiling a pipeline configuration step fields such as `image` and `commands` will be arranged in alphabetical order. -::: - -```yaml -version: "1" -secrets: -- name: go_module - key: github/octocat/template_secret - engine: native - type: repo -steps: -- commands: - - go vet ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code) - - go fmt ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code) - image: golang:latest - name: go_validate - pull: not_present -- commands: - - go test ./... - image: golang:latest - name: go_test - pull: not_present -- commands: - - go build -a -ldflags '-extldflags "-static"' -o release/heyvela {$GO_MODULE} - image: golang:latest - name: go_build - pull: not_present - environment: - CGO_ENABLED: "0" - GOOS: linux -templates: -- name: go - source: github.com/github/octocat/go/template.yml - type: github -``` - -```json -{ - "version": "1", - "metadata": {}, - "worker": {}, - "secrets": [ - { - "name": "go_module", - "key": "github/octocat/template_secret", - "engine": "native", - "type": "repo", - "origin": { - "ruleset": { - "if": {}, - "unless": {} - } - } - } - ], - "steps": [ - { - "ruleset": { - "if": {}, - "unless": {} - }, - "commands": [ - "go vet ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code)", - "go fmt ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code)" - ], - "template": {}, - "image": "golang:latest", - "name": "go_validate", - "pull": "not_present" - }, - { - "ruleset": { - "if": {}, - "unless": {} - }, - "commands": [ - "go test ./..." - ], - "template": {}, - "image": "golang:latest", - "name": "go_test", - "pull": "not_present" - }, - { - "ruleset": { - "if": {}, - "unless": {} - }, - "commands": [ - "go build -a -ldflags '-extldflags \"-static\"' -o release/heyvela {$GO_MODULE}" - ], - "template": {}, - "image": "golang:latest", - "name": "go_build", - "pull": "not_present", - "environment": { - "CGO_ENABLED": "0", - "GOOS": "linux" - } - }, - { - "ruleset": { - "if": {}, - "unless": {} - }, - "commands": [ - "go vet ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code)", - "go fmt ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code)" - ], - "template": {}, - "image": "golang:latest", - "name": "go-tag_validate", - "pull": "not_present" - }, - { - "ruleset": { - "if": {}, - "unless": {} - }, - "commands": [ - "go test ./..." - ], - "template": {}, - "image": "golang:latest", - "name": "go-tag_test", - "pull": "not_present" - }, - { - "ruleset": { - "if": {}, - "unless": {} - }, - "commands": [ - "go build -a -ldflags '-extldflags \"-static\"' -o release/heyvela {$GO_MODULE}" - ], - "template": {}, - "image": "golang:latest", - "name": "go-tag_build", - "pull": "not_present", - "environment": { - "CGO_ENABLED": "0", - "GOOS": "linux" - } - }, - ], - "templates": [ - { - "name": "go", - "source": "github.com/github/octocat/go/template.yml", - "type": "github" - } - ] -} -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/pipeline/expand.md b/versioned_docs/version-0.26/reference/api/pipeline/expand.md deleted file mode 100644 index eb4b319..0000000 --- a/versioned_docs/version-0.26/reference/api/pipeline/expand.md +++ /dev/null @@ -1,168 +0,0 @@ ---- -title: "Expand" -linkTitle: "Expand" -description: > - Learn how to expand a pipeline configuration with templates. ---- - -## Endpoint - -``` -POST /api/v1/pipelines/:org/:repo/:pipeline/expand -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -|------------|-----------------------------------------------------------| -| `org` | name of organization | -| `repo` | name of repository | -| `pipeline` | commit SHA for pipeline from repository | -| `output` | format the output for the compiled pipeline configuration | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `400` | unable to retrieve or expand the pipeline configuration and templates | -| `401` | indicates the user does not have proper permissions | -| `404` | unable to retrieve or expand the pipeline configuration or templates | -| `500` | system error while retrieving or expanding the pipeline configuration templates | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X POST \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/pipelines/github/octocat/48afb5bdc41ad69bf22588491333f7cf71135163/expand" -``` - -#### Response - -:::warning -Notice, when expanding a pipeline configuration step fields such as `image` and `commands` will be arranged in alphabetical order. -::: - -```yaml -version: "1" -secrets: -- name: go_module - key: github/octocat/template_secret - engine: native - type: repo -steps: -- commands: - - go vet ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code) - - go fmt ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code) - image: golang:latest - name: go_validate - pull: not_present -- commands: - - go test ./... - image: golang:latest - name: go_test - pull: not_present -- commands: - - go build -a -ldflags '-extldflags "-static"' -o release/heyvela {$GO_MODULE} - image: golang:latest - name: go_build - pull: not_present - environment: - CGO_ENABLED: "0" - GOOS: linux -templates: -- name: go - source: github.com/github/octocat/go/template.yml - type: github -``` - -```json -{ - "version": "1", - "metadata": {}, - "worker": {}, - "secrets": [ - { - "name": "go_module", - "key": "github/octocat/template_secret", - "engine": "native", - "type": "repo", - "origin": { - "ruleset": { - "if": {}, - "unless": {} - } - } - } - ], - "steps": [ - { - "ruleset": { - "if": {}, - "unless": {} - }, - "commands": [ - "go vet ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code)", - "go fmt ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code)" - ], - "template": {}, - "image": "golang:latest", - "name": "go_validate", - "pull": "not_present" - }, - { - "ruleset": { - "if": {}, - "unless": {} - }, - "commands": [ - "go test ./..." - ], - "template": {}, - "image": "golang:latest", - "name": "go_test", - "pull": "not_present" - }, - { - "ruleset": { - "if": {}, - "unless": {} - }, - "commands": [ - "go build -a -ldflags '-extldflags \"-static\"' -o release/heyvela {$GO_MODULE}" - ], - "template": {}, - "image": "golang:latest", - "name": "go_build", - "pull": "not_present", - "environment": { - "CGO_ENABLED": "0", - "GOOS": "linux" - } - }, - ], - "templates": [ - { - "name": "go", - "source": "github.com/github/octocat/go/template.yml", - "type": "github" - } - ] -} -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/pipeline/get.md b/versioned_docs/version-0.26/reference/api/pipeline/get.md deleted file mode 100644 index dd13106..0000000 --- a/versioned_docs/version-0.26/reference/api/pipeline/get.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to list pipelines. ---- - -## Endpoint - -``` -GET /api/v1/pipelines/:org/:repo -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -|------------|----------------------| -| `org` | name of organization | -| `repo` | name of repository | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- |----------------------------------------------------------| -| `200` | indicates the request has succeeded | -| `400` | unable to retrieve the pipeline configuration | -| `401` | indicates the user does not have proper permissions | -| `404` | unable to retrieve the pipeline configuration | -| `500` | system error while retrieving the pipeline configuration | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/pipelines/github/octocat" -``` - -#### Response - -```json -[ - { - "id": 2, - "repo_id": 1, - "commit": "a49aaf4afae6431a79239c95247a2b169fd9f067", - "flavor": "", - "platform": "", - "ref": "refs/heads/main", - "type": "yaml", - "version": "1", - "external_secrets": false, - "internal_secrets": false, - "services": false, - "stages": false, - "steps": true, - "templates": false, - "data": "LS0tCnZlcnNpb246ICIxIgoKc3RlcHM6CiAgLSBuYW1lOiBlY2hvCiAgICBpbWFnZTogYWxwaW5lOmxhdGVzdAogICAgY29tbWFuZHM6IFtlY2hvIGZvb10=" - }, - { - "id": 1, - "repo_id": 1, - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "flavor": "", - "platform": "", - "ref": "refs/heads/main", - "type": "yaml", - "version": "1", - "external_secrets": false, - "internal_secrets": false, - "services": false, - "stages": false, - "steps": true, - "templates": false, - "data": "LS0tCnZlcnNpb246ICIxIgoKc3RlcHM6CiAgLSBuYW1lOiBlY2hvCiAgICBpbWFnZTogYWxwaW5lOmxhdGVzdAogICAgY29tbWFuZHM6IFtlY2hvIGZvb10=" - } -] -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/pipeline/pipeline.md b/versioned_docs/version-0.26/reference/api/pipeline/pipeline.md deleted file mode 100644 index 3792ce2..0000000 --- a/versioned_docs/version-0.26/reference/api/pipeline/pipeline.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Pipeline" -linkTitle: "Pipeline" -description: > - Learn how to use API endpoints for the pipeline resource. ---- - -The below endpoints are available to operate on the `pipeline` resource. - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/api/pipeline/remove.md b/versioned_docs/version-0.26/reference/api/pipeline/remove.md deleted file mode 100644 index c845882..0000000 --- a/versioned_docs/version-0.26/reference/api/pipeline/remove.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "Remove" -linkTitle: "Remove" -description: > - Learn how to delete a pipeline. ---- - -## Endpoint - -``` -DELETE /api/v1/pipelines/:org/:repo/:pipeline -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -|------------|-----------------------------------------| -| `org` | name of organization | -| `repo` | name of repository | -| `pipeline` | commit SHA for pipeline from repository | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X DELETE \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/pipelines/github/octocat/48afb5bdc41ad69bf22588491333f7cf71135163" -``` - -#### Response - -```sh -Pipeline github/octocat/48afb5bdc41ad69bf22588491333f7cf71135163 deleted -``` diff --git a/versioned_docs/version-0.26/reference/api/pipeline/templates.md b/versioned_docs/version-0.26/reference/api/pipeline/templates.md deleted file mode 100644 index 6155fa5..0000000 --- a/versioned_docs/version-0.26/reference/api/pipeline/templates.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: "Templates" -linkTitle: "Templates" -description: > - Learn how to list pipeline templates. ---- - -## Endpoint - -``` -GET /api/v1/pipelines/:org/:repo/:pipeline/templates -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -|------------|-----------------------------------------------------------| -| `org` | name of organization | -| `repo` | name of repository | -| `pipeline` | commit SHA for pipeline from repository | -| `output` | format the output for the compiled pipeline configuration | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- |--------------------------------------------------------------------| -| `200` | indicates the request has succeeded | -| `400` | unable to retrieve the pipeline configuration templates | -| `401` | indicates the user does not have proper permissions | -| `404` | unable to retrieve the pipeline configuration or templates | -| `500` | system error while retrieving the pipeline configuration templates | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/pipelines/github/octocat/48afb5bdc41ad69bf22588491333f7cf71135163/templates" -``` - -#### Response - -```yaml -some_template: - link: https://github.com/github/octocat/blob/main/template.yml - name: some_template - source: github.com/github/octocat/template.yml - type: github -``` - -```json -{ - "some_template": { - "link": "https://github.com/github/octocat/blob/main/template.yml", - "name": "some_template", - "source": "github.com/github/octocat/template.yml", - "type": "github" - }, -} -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/pipeline/update.md b/versioned_docs/version-0.26/reference/api/pipeline/update.md deleted file mode 100644 index ce7f17e..0000000 --- a/versioned_docs/version-0.26/reference/api/pipeline/update.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: "Update" -linkTitle: "Update" -description: > - Learn how to modify a pipeline. ---- - -## Endpoint - -``` -PUT /api/v1/pipelines/:org/:repo/:pipeline -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -|------------|-----------------------------------------| -| `org` | name of organization | -| `repo` | name of repository | -| `pipeline` | commit SHA for pipeline from repository | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "data": "LS0tCnZlcnNpb246ICIxIgoKc3RlcHM6CiAgLSBuYW1lOiBlY2hvCiAgICBpbWFnZTogYWxwaW5lOmxhdGVzdAogICAgZW52aXJvbm1lbnQ6CiAgICAgIEhFTExPOiB3b3JsZAogICAgY29tbWFuZHM6IFtlY2hvICRIRUxMT10=" -} -``` - -#### Request - -```sh -curl \ - -X PUT \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/pipelines/github/octocat/48afb5bdc41ad69bf22588491333f7cf71135163" -``` - -#### Response - -```json -{ - "id": 1, - "repo_id": 1, - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "flavor": "", - "platform": "", - "ref": "refs/heads/main", - "type": "yaml", - "version": "1", - "external_secrets": false, - "internal_secrets": false, - "services": false, - "stages": false, - "steps": true, - "templates": false, - "data": "LS0tCnZlcnNpb246ICIxIgoKc3RlcHM6CiAgLSBuYW1lOiBlY2hvCiAgICBpbWFnZTogYWxwaW5lOmxhdGVzdAogICAgZW52aXJvbm1lbnQ6CiAgICAgIEhFTExPOiB3b3JsZAogICAgY29tbWFuZHM6IFtlY2hvICRIRUxMT10=" -} -``` diff --git a/versioned_docs/version-0.26/reference/api/pipeline/validate.md b/versioned_docs/version-0.26/reference/api/pipeline/validate.md deleted file mode 100644 index 62ac452..0000000 --- a/versioned_docs/version-0.26/reference/api/pipeline/validate.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "Validate" -linkTitle: "Validate" -description: > - Learn how to validate a pipeline configuration with templates. ---- - -## Endpoint - -``` -POST /api/v1/pipelines/:org/:repo/:pipeline/validate -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -|------------|-----------------------------------------------------------| -| `org` | name of organization | -| `repo` | name of repository | -| `pipeline` | commit SHA for pipeline from repository | -| `output` | format the output for the compiled pipeline configuration | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `400` | unable to retrieve or validate the pipeline configuration and templates | -| `401` | indicates the user does not have proper permissions | -| `404` | unable to retrieve or validate the pipeline configuration or templates | -| `500` | system error while retrieving or validating the pipeline configuration templates | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X POST \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/pipelines/github/octocat/48afb5bdc41ad69bf22588491333f7cf71135163/validate" -``` - -#### Response - -``` -"pipeline is valid" -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/pipeline/view.md b/versioned_docs/version-0.26/reference/api/pipeline/view.md deleted file mode 100644 index d2b45ee..0000000 --- a/versioned_docs/version-0.26/reference/api/pipeline/view.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect a pipeline. ---- - -## Endpoint - -``` -GET /api/v1/pipelines/:org/:repo/:pipeline -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -|------------|-----------------------------------------| -| `org` | name of organization | -| `repo` | name of repository | -| `pipeline` | commit SHA for pipeline from repository | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- |----------------------------------------------------------| -| `200` | indicates the request has succeeded | -| `400` | unable to retrieve the pipeline configuration | -| `401` | indicates the user does not have proper permissions | -| `404` | unable to retrieve the pipeline configuration | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/pipelines/github/octocat/48afb5bdc41ad69bf22588491333f7cf71135163" -``` - -#### Response - -```json -{ - "id": 1, - "repo_id": 1, - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "flavor": "", - "platform": "", - "ref": "refs/heads/main", - "type": "yaml", - "version": "1", - "external_secrets": false, - "internal_secrets": false, - "services": false, - "stages": false, - "steps": true, - "templates": false, - "data": "LS0tCnZlcnNpb246ICIxIgoKc3RlcHM6CiAgLSBuYW1lOiBlY2hvCiAgICBpbWFnZTogYWxwaW5lOmxhdGVzdAogICAgY29tbWFuZHM6IFtlY2hvIGZvb10=" -} -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/repo/add.md b/versioned_docs/version-0.26/reference/api/repo/add.md deleted file mode 100644 index 7fe31c4..0000000 --- a/versioned_docs/version-0.26/reference/api/repo/add.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: "Add" -linkTitle: "Add" -description: > - Learn how to create a repo. ---- - -## Endpoint - -``` -POST /api/v1/repos -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "org": "github", - "name": "octocat", - "link": "https://github.com/github/octocat", - "clone": "https://github.com/github/octocat.git" -} -``` - -#### Request - -```sh -curl \ - -X POST \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/repos" -``` - -#### Response - -```json -{ - "id": 1, - "user_id": 1, - "org": "github", - "name": "octocat", - "full_name": "github/octocat", - "link": "https://github.com/github/octocat", - "clone": "https://github.com/github/octocat.git", - "branch": "main", - "build_limit": 10, - "timeout": 60, - "counter": 0, - "visibility": "public", - "private": false, - "trusted": true, - "active": true, - "allow_pull": true, - "allow_push": true, - "allow_deploy": false, - "allow_tag": false, - "allow_comment": false, - "allow_events": { - "push": { - "branch": true, - "tag": true, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": true - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "pipeline_type": "yaml" -} -``` diff --git a/versioned_docs/version-0.26/reference/api/repo/chown.md b/versioned_docs/version-0.26/reference/api/repo/chown.md deleted file mode 100644 index 1db7027..0000000 --- a/versioned_docs/version-0.26/reference/api/repo/chown.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: "Chown" -linkTitle: "Chown" -description: > - Learn how to change ownership of a repo. ---- - -## Endpoint - -``` -PATCH /api/v1/repos/:org/:repo/chown -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------ | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X PATCH \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/chown" -``` - -#### Response - -``` -Repo github/octocat changed owner -``` diff --git a/versioned_docs/version-0.26/reference/api/repo/get.md b/versioned_docs/version-0.26/reference/api/repo/get.md deleted file mode 100644 index ccf26ea..0000000 --- a/versioned_docs/version-0.26/reference/api/repo/get.md +++ /dev/null @@ -1,313 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to list repos by current user or by organization. ---- - -## Endpoint - -``` -GET /api/v1/repos -``` -This will return a list of all repos owned by the user. - -## Filters - -The following optional filters are available: - -| Name | Description | -| -------- | ----------------------------------------------------------------------- | -| `page` | page number for results (default 1) | -| `per_page` | number of results in a page (default 10, max 100) | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos" -``` - -#### Response - -```json -[ - { - "id": 1, - "user_id": 1, - "org": "github", - "name": "octocat", - "full_name": "github/octocat", - "link": "https://github.com/github/octocat", - "clone": "https://github.com/github/octocat.git", - "branch": "main", - "build_limit": 10, - "timeout": 60, - "counter": 0, - "visibility": "public", - "private": false, - "trusted": true, - "active": true, - "allow_pull": true, - "allow_push": true, - "allow_deploy": false, - "allow_tag": false, - "allow_comment": false, - "allow_events": { - "push": { - "branch": true, - "tag": true, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": true - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "pipeline_type": "yaml" - }, - { - "id": 2, - "user_id": 1, - "org": "github", - "name": "octokitty", - "full_name": "github/octokitty", - "link": "https://github.com/github/octokitty", - "clone": "https://github.com/github/octokitty.git", - "branch": "main", - "build_limit": 10, - "timeout": 60, - "counter": 0, - "visibility": "public", - "private": false, - "trusted": true, - "active": true, - "allow_pull": true, - "allow_push": true, - "allow_deploy": false, - "allow_tag": false, - "allow_comment": false, - "allow_events": { - "push": { - "branch": true, - "tag": true, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": true - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "pipeline_type": "yaml" - } -] -``` - -## Endpoint - -``` -GET /api/v1/repos/:org -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------ | -------------------- | -| `org` | name of organization | - -## Filters - -The following optional filters are available: - -| Name | Description | -| -------- | ----------------------------------------------------------------------------------- | -| `active` | filter whether repos are active (default true) | -| `page` | page number for results (default 1) | -| `per_page` | number of results in a page (default 10, max 100) | -| `sort_by` | sort repos by `name` (default) or by `latest`, which sorts by latest build activity | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos/octocat" -``` - -#### Response - -```json -[ - { - "id": 1, - "user_id": 1, - "org": "octocat", - "name": "example", - "full_name": "octocat/example", - "link": "https://github.com/octocat/example", - "clone": "https://github.com/octocat/example.git", - "branch": "main", - "build_limit": 10, - "timeout": 60, - "counter": 0, - "visibility": "public", - "private": false, - "trusted": true, - "active": true, - "allow_pull": true, - "allow_push": true, - "allow_deploy": false, - "allow_tag": false, - "allow_comment": false, - "allow_events": { - "push": { - "branch": true, - "tag": true, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": true - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "pipeline_type": "yaml" - }, - { - "id": 2, - "user_id": 1, - "org": "octocat", - "name": "octokitty", - "full_name": "octocat/octokitty", - "link": "https://github.com/octocat/octokitty", - "clone": "https://github.com/octocat/octokitty.git", - "branch": "main", - "build_limit": 10, - "timeout": 60, - "counter": 0, - "visibility": "public", - "private": false, - "trusted": true, - "active": true, - "allow_pull": true, - "allow_push": true, - "allow_deploy": false, - "allow_tag": false, - "allow_comment": false, - "allow_events": { - "push": { - "branch": true, - "tag": true, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": true - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "pipeline_type": "yaml" - } -] -``` diff --git a/versioned_docs/version-0.26/reference/api/repo/remove.md b/versioned_docs/version-0.26/reference/api/repo/remove.md deleted file mode 100644 index 7edde37..0000000 --- a/versioned_docs/version-0.26/reference/api/repo/remove.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: "Remove" -linkTitle: "Remove" -description: > - Learn how to delete a repo. ---- - -## Endpoint - -``` -DELETE /api/v1/repos/:org/:repo -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------ | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X DELETE \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat" -``` - -#### Response - -``` -Repo github/octocat deleted -``` diff --git a/versioned_docs/version-0.26/reference/api/repo/repair.md b/versioned_docs/version-0.26/reference/api/repo/repair.md deleted file mode 100644 index 19fb2d9..0000000 --- a/versioned_docs/version-0.26/reference/api/repo/repair.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: "Repair" -linkTitle: "Repair" -description: > - Learn how to restore a repo. ---- - -## Endpoint - -``` -PATCH /api/v1/repos/:org/:repo/repair -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------ | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X PATCH \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/repair" -``` - -#### Response - -``` -Repo github/octocat repaired -``` diff --git a/versioned_docs/version-0.26/reference/api/repo/repo.md b/versioned_docs/version-0.26/reference/api/repo/repo.md deleted file mode 100644 index 9da0af0..0000000 --- a/versioned_docs/version-0.26/reference/api/repo/repo.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Repo" -linkTitle: "Repo" -description: > - Learn how to use API endpoints for the repo resource. ---- - -The below endpoints are available to operate on the `repo` resource. - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/api/repo/update.md b/versioned_docs/version-0.26/reference/api/repo/update.md deleted file mode 100644 index 6b1a320..0000000 --- a/versioned_docs/version-0.26/reference/api/repo/update.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: "Update" -linkTitle: "Update" -description: > - Learn how to modify a repo. ---- - -## Endpoint - -``` -PUT /api/v1/repos/:org/:repo -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------ | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "allow_tag": true -} -``` - -#### Request - -```sh -curl \ - -X PUT \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat" -``` - -#### Response - -```json -{ - "id": 1, - "user_id": 1, - "org": "github", - "name": "octocat", - "full_name": "github/octocat", - "link": "https://github.com/github/octocat", - "clone": "https://github.com/github/octocat.git", - "branch": "main", - "build_limit": 10, - "timeout": 60, - "counter": 0, - "visibility": "public", - "private": false, - "trusted": true, - "active": true, - "allow_pull": true, - "allow_push": true, - "allow_deploy": false, - "allow_tag": true, - "allow_comment": false, - "allow_events": { - "push": { - "branch": true, - "tag": true, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": true - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "pipeline_type": "yaml" -} -``` diff --git a/versioned_docs/version-0.26/reference/api/repo/view.md b/versioned_docs/version-0.26/reference/api/repo/view.md deleted file mode 100644 index 38e7330..0000000 --- a/versioned_docs/version-0.26/reference/api/repo/view.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect a repo. ---- - -## Endpoint - -``` -GET /api/v1/repos/:org/:repo -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------ | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat" -``` - -#### Response - -```json -{ - "id": 1, - "user_id": 1, - "org": "github", - "name": "octocat", - "full_name": "github/octocat", - "link": "https://github.com/github/octocat", - "clone": "https://github.com/github/octocat.git", - "branch": "main", - "build_limit": 10, - "timeout": 60, - "counter": 0, - "visibility": "public", - "private": false, - "trusted": true, - "active": true, - "allow_pull": true, - "allow_push": true, - "allow_deploy": false, - "allow_tag": false, - "allow_comment": false, - "allow_events": { - "push": { - "branch": true, - "tag": true, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": true - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "pipeline_type": "yaml" -} -``` diff --git a/versioned_docs/version-0.26/reference/api/schedule/add.md b/versioned_docs/version-0.26/reference/api/schedule/add.md deleted file mode 100644 index 8d0ef60..0000000 --- a/versioned_docs/version-0.26/reference/api/schedule/add.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: "Add" -linkTitle: "Add" -description: > - Learn how to create a schedule. ---- - -## Endpoint - -``` -POST /api/v1/schedules/:org/:repo -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -|--------|----------------------| -| `org` | name of organization | -| `repo` | name of repository | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -|-------------|-----------------------------------------------------| -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "name": "hourly", - "entry": "0 * * * *", - "active": true -} -``` - -#### Request - -```sh -curl \ - -X POST \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/schedules/github/octocat" -``` - -#### Response - -```json -{ - "id": 1, - "repo": { - "id": 1, - "owner": { - "id": 1, - "name": "octokitty", - "active": true - }, - "org": "github", - "name": "octokitty", - "full_name": "github/octokitty", - "link": "https://github.com/github/octokitty", - "clone": "https://github.com/github/octokitty.git", - "branch": "main", - "topics": [], - "build_limit": 10, - "timeout": 30, - "counter": 0, - "visibility": "public", - "private": false, - "trusted": false, - "active": true, - "allow_events": { - "push": { - "branch": true, - "tag": false, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": false - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "pipeline_type": "yaml", - "previous_name": "", - "approve_build": "fork-always" - }, - "active": true, - "name": "hourly", - "entry": "0 * * * *", - "created_at": 1716495910, - "created_by": "octokitty", - "updated_at": 1716495910, - "updated_by": "octokitty", - "scheduled_at": 0, - "branch": "main", - "error": "", - "next_run": 1716499800 -} -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/schedule/get.md b/versioned_docs/version-0.26/reference/api/schedule/get.md deleted file mode 100644 index 836112a..0000000 --- a/versioned_docs/version-0.26/reference/api/schedule/get.md +++ /dev/null @@ -1,189 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to list schedules. ---- - -## Endpoint - -``` -GET /api/v1/schedules/:org/:repo -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -|--------|----------------------| -| `org` | name of organization | -| `repo` | name of repository | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -|-------------|-----------------------------------------------------| -| `200` | indicates the request has succeeded | -| `400` | unable to retrieve the schedules | -| `401` | indicates the user does not have proper permissions | -| `404` | unable to retrieve the schedules | -| `500` | system error while retrieving the schedules | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/schedules/github/octocat" -``` - -#### Response - -```json -[ - { - "id": 1, - "repo": { - "id": 1, - "owner": { - "id": 1, - "name": "octokitty", - "active": true - }, - "org": "github", - "name": "octokitty", - "full_name": "github/octokitty", - "link": "https://github.com/github/octokitty", - "clone": "https://github.com/github/octokitty.git", - "branch": "main", - "topics": [], - "build_limit": 10, - "timeout": 30, - "counter": 0, - "visibility": "public", - "private": false, - "trusted": false, - "active": true, - "allow_events": { - "push": { - "branch": true, - "tag": false, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": false - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "pipeline_type": "yaml", - "previous_name": "", - "approve_build": "fork-always" - }, - "active": true, - "name": "hourly", - "entry": "0 * * * *", - "created_at": 1716495910, - "created_by": "octokitty", - "updated_at": 1716495910, - "updated_by": "octokitty", - "scheduled_at": 0, - "branch": "main", - "error": "", - "next_run": 1716499800 - }, - { - "id": 2, - "repo": { - "id": 1, - "owner": { - "id": 1, - "name": "octokitty", - "active": true - }, - "org": "github", - "name": "octokitty", - "full_name": "github/octokitty", - "link": "https://github.com/github/octokitty", - "clone": "https://github.com/github/octokitty.git", - "branch": "main", - "topics": [], - "build_limit": 10, - "timeout": 30, - "counter": 0, - "visibility": "public", - "private": false, - "trusted": false, - "active": true, - "allow_events": { - "push": { - "branch": true, - "tag": false, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": false - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "pipeline_type": "yaml", - "previous_name": "", - "approve_build": "fork-always" - }, - "active": true, - "name": "nightly", - "entry": "0 0 * * *", - "created_at": 1716495910, - "created_by": "octokitty", - "updated_at": 1716495910, - "updated_by": "octokitty", - "scheduled_at": 0, - "branch": "main", - "error": "", - "next_run": 1716499800 - } -] -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/schedule/remove.md b/versioned_docs/version-0.26/reference/api/schedule/remove.md deleted file mode 100644 index 19c7f53..0000000 --- a/versioned_docs/version-0.26/reference/api/schedule/remove.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "Remove" -linkTitle: "Remove" -description: > - Learn how to delete a schedule. ---- - -## Endpoint - -``` -DELETE /api/v1/schedules/:org/:repo/:schedule -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -|------------|----------------------------------| -| `org` | name of organization | -| `repo` | name of repository | -| `schedule` | name of schedule from repository | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -|-------------|-----------------------------------------------------| -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X DELETE \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/schedules/github/octocat/hourly" -``` - -#### Response - -```sh -"schedule hourly deleted" -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/schedule/schedule.md b/versioned_docs/version-0.26/reference/api/schedule/schedule.md deleted file mode 100644 index 4e7ddb7..0000000 --- a/versioned_docs/version-0.26/reference/api/schedule/schedule.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Schedule" -linkTitle: "Schedule" -description: > - Learn how to use API endpoints for the schedule resource. ---- - -The below endpoints are available to operate on the `schedule` resource. - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/schedule/update.md b/versioned_docs/version-0.26/reference/api/schedule/update.md deleted file mode 100644 index d59137d..0000000 --- a/versioned_docs/version-0.26/reference/api/schedule/update.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: "Update" -linkTitle: "Update" -description: > - Learn how to modify a schedule. ---- - -## Endpoint - -``` -PUT /api/v1/schedules/:org/:repo/:schedule -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -|------------|----------------------------------| -| `org` | name of organization | -| `repo` | name of repository | -| `schedule` | name of schedule from repository | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -|-------------|-----------------------------------------------------| -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "active": false -} -``` - -#### Request - -```sh -curl \ - -X PUT \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/schedules/github/octocat/hourly" -``` - -#### Response - -```json -{ - "id": 1, - "repo": { - "id": 1, - "owner": { - "id": 1, - "name": "octokitty", - "active": true - }, - "org": "github", - "name": "octokitty", - "full_name": "github/octokitty", - "link": "https://github.com/github/octokitty", - "clone": "https://github.com/github/octokitty.git", - "branch": "main", - "topics": [], - "build_limit": 10, - "timeout": 30, - "counter": 0, - "visibility": "public", - "private": false, - "trusted": false, - "active": true, - "allow_events": { - "push": { - "branch": true, - "tag": false, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": false - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "pipeline_type": "yaml", - "previous_name": "", - "approve_build": "fork-always" - }, - "active": false, - "name": "hourly", - "entry": "0 * * * *", - "created_at": 1716495910, - "created_by": "octokitty", - "updated_at": 1716495910, - "updated_by": "octokitty", - "scheduled_at": 0, - "branch": "main", - "error": "", - "next_run": 1716499800 -} -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/schedule/view.md b/versioned_docs/version-0.26/reference/api/schedule/view.md deleted file mode 100644 index ac6eb3d..0000000 --- a/versioned_docs/version-0.26/reference/api/schedule/view.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect a schedule. ---- - -## Endpoint - -``` -GET /api/v1/schedules/:org/:repo/:schedule -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -|------------|----------------------------------| -| `org` | name of organization | -| `repo` | name of repository | -| `schedule` | name of schedule from repository | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -|-------------|-----------------------------------------------------| -| `200` | indicates the request has succeeded | -| `400` | unable to retrieve the schedule | -| `401` | indicates the user does not have proper permissions | -| `404` | unable to retrieve the schedule | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/schedules/github/octocat/hourly" -``` - -#### Response - -```json -{ - "id": 1, - "repo": { - "id": 1, - "owner": { - "id": 1, - "name": "octokitty", - "active": true - }, - "org": "github", - "name": "octokitty", - "full_name": "github/octokitty", - "link": "https://github.com/github/octokitty", - "clone": "https://github.com/github/octokitty.git", - "branch": "main", - "topics": [], - "build_limit": 10, - "timeout": 30, - "counter": 0, - "visibility": "public", - "private": false, - "trusted": false, - "active": true, - "allow_events": { - "push": { - "branch": true, - "tag": false, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": false - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "pipeline_type": "yaml", - "previous_name": "", - "approve_build": "fork-always" - }, - "active": true, - "name": "hourly", - "entry": "0 * * * *", - "created_at": 1716495910, - "created_by": "octokitty", - "updated_at": 1716495910, - "updated_by": "octokitty", - "scheduled_at": 0, - "branch": "main", - "error": "", - "next_run": 1716499800 -} -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/scm/scm.md b/versioned_docs/version-0.26/reference/api/scm/scm.md deleted file mode 100644 index c1d010b..0000000 --- a/versioned_docs/version-0.26/reference/api/scm/scm.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "SCM" -linkTitle: "SCM" -description: > - Learn how to use API endpoints for the SCM resource. ---- - -The below endpoints are available to operate on the `scm` resource. - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/scm/sync.md b/versioned_docs/version-0.26/reference/api/scm/sync.md deleted file mode 100644 index b13b37d..0000000 --- a/versioned_docs/version-0.26/reference/api/scm/sync.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: "Sync" -linkTitle: "Sync" -description: > - Learn how to sync a repo with SCM. ---- - -## Endpoint - -``` -PATCH /api/v1/scm/repos/:org/:repo/sync -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------ | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Description - -The sync endpoint allows users to re-align their repository in Vela with its SCM mirror. This discrepancy can come in the form of a repository that has been deleted from the SCM but not in Vela. - -Further, as of `v0.19.0`, the sync endpoint can be used to adjust events that are sent to Vela from the SCM that the Vela-instance of the repo is not subscribed to. For example, if your audit page has errors like - -```sh -"unable to process webhook: / does not have comment events enabled" -``` - -hitting the sync endpoint should re-configure the SCM webhook to only send events that are allowed. Once aligned, you should not have to hit this endpoint again, even if the subscribed events are changed. - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X PATCH \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/scm/repos/github/octocat/sync" -``` - -#### Response - -```sh -repo "github/octocat" synced -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/api/scm/syncAll.md b/versioned_docs/version-0.26/reference/api/scm/syncAll.md deleted file mode 100644 index 6a460fc..0000000 --- a/versioned_docs/version-0.26/reference/api/scm/syncAll.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: "SyncAll" -linkTitle: "SyncAll" -description: > - Learn how to sync org repos with SCM. ---- - -## Endpoint - -``` -GET /api/v1/scm/orgs/:org/sync -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------ | -------------------- | -| `org` | name of organization | - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Description - -The sync-all endpoint allows users to re-align their organization's repositories in Vela with their SCM mirror. This discrepancy can come in the form of a repository that has been deleted from the SCM but not in Vela. - -Further, as of `v0.19.0`, the sync-all endpoint can be used to adjust events that are sent to Vela from the SCM that the Vela-instance of the repo is not subscribed to. For example, if your audit page has errors like - -```sh -"unable to process webhook: / does not have comment events enabled" -``` - -hitting the sync-all endpoint should re-configure the SCM webhook for all repos in the organization to only send events that are allowed. Once aligned, you should not have to hit this endpoint again, even if the subscribed events are changed. - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X PATCH \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/scm/orgs/github/sync" -``` - -#### Response - -```sh -org "github" synced -``` diff --git a/versioned_docs/version-0.26/reference/api/secret/add.md b/versioned_docs/version-0.26/reference/api/secret/add.md deleted file mode 100644 index 5351c87..0000000 --- a/versioned_docs/version-0.26/reference/api/secret/add.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: "Add" -linkTitle: "Add" -description: > - Learn how to create a secret. ---- - -## Endpoint - -``` -POST /api/v1/secrets/:engine/:type/:org/:name -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| -------- | -------------------------- | -| `engine` | name of engine | -| `type` | name of type of secret | -| `org` | name of organization | -| `name` | name of repository or team | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "name": "foo", - "value": "bar", - "images": ["alpine"], - "events": ["push"] -} -``` - -#### Request - -```sh -curl \ - -X POST \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" - "http://127.0.0.1:8080/api/v1/secrets/native/repo/github/octocat" -``` - -#### Response - -```json -{ - "id": 1, - "org": "github", - "repo": "octocat", - "team": "", - "name": "foo", - "value": null, - "type": "repo", - "images": ["alpine"], - "events": ["push"], - "allow_command": true, - "allow_substitution": true, - "allow_events": { - "push": { - "branch": true, - "tag": true, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": true - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "created_at": 1641314085, - "created_by": "octokitty", - "updated_at": 1641314085, - "updated_by": "octokitty" -} -``` diff --git a/versioned_docs/version-0.26/reference/api/secret/get.md b/versioned_docs/version-0.26/reference/api/secret/get.md deleted file mode 100644 index 4a7ac74..0000000 --- a/versioned_docs/version-0.26/reference/api/secret/get.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to list secrets. ---- - -## Endpoint - -``` -GET /api/v1/secrets/:engine/:type/:org/:name -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| -------- | -------------------------- | -| `engine` | name of engine | -| `type` | name of type of secret | -| `org` | name of organization | -| `name` | name of repository or team | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/secrets/native/repo/github/octocat" -``` - -#### Response - -```json -[ - { - "id": 1, - "org": "github", - "repo": "octocat", - "team": "", - "name": "foo", - "value": null, - "type": "repo", - "images": ["alpine"], - "events": ["push"], - "allow_command": true, - "allow_substitution": true, - "allow_events": { - "push": { - "branch": true, - "tag": true, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": true - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "created_at": 1641314085, - "created_by": "octokitty", - "updated_at": 1641314085, - "updated_by": "octokitty" - }, - { - "id": 2, - "org": "github", - "repo": "octocat", - "team": "", - "name": "bar", - "value": null, - "type": "repo", - "images": ["alpine"], - "events": ["push"], - "allow_command": true, - "allow_substitution": true, - "allow_events": { - "push": { - "branch": true, - "tag": true, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": true - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "created_at": 1641314500, - "created_by": "octokitty", - "updated_at": 1641314500, - "updated_by": "octokitty" - } -] -``` diff --git a/versioned_docs/version-0.26/reference/api/secret/remove.md b/versioned_docs/version-0.26/reference/api/secret/remove.md deleted file mode 100644 index dea7e2c..0000000 --- a/versioned_docs/version-0.26/reference/api/secret/remove.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: "Remove" -linkTitle: "Remove" -description: > - Learn how to delete a secret. ---- - -## Endpoint - -``` -DELETE /api/v1/secrets/:engine/:type/:org/:name/:secret -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| -------- | -------------------------- | -| `engine` | name of engine | -| `type` | name of type of secret | -| `org` | name of organization | -| `name` | name of repository or team | -| `secret` | name of secret | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X DELETE \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/secrets/native/repo/github/octocat/foo" -``` - -#### Response - -```json -Secret repo/github/octocat/foo deleted from native service -``` diff --git a/versioned_docs/version-0.26/reference/api/secret/secret.md b/versioned_docs/version-0.26/reference/api/secret/secret.md deleted file mode 100644 index 1cf5c4e..0000000 --- a/versioned_docs/version-0.26/reference/api/secret/secret.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Secret" -linkTitle: "Secret" -description: > - Learn how to use API endpoints for the secret resource. ---- - -The below endpoints are available to operate on the `secret` resource. - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/api/secret/update.md b/versioned_docs/version-0.26/reference/api/secret/update.md deleted file mode 100644 index d1ecd6a..0000000 --- a/versioned_docs/version-0.26/reference/api/secret/update.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: "Update" -linkTitle: "Update" -description: > - Learn how to modify a secret. ---- - -## Endpoint - -``` -PUT /api/v1/secrets/:engine/:type/:org/:name/:secret -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| -------- | -------------------------- | -| `engine` | name of engine | -| `type` | name of type of secret | -| `org` | name of organization | -| `name` | name of repository or team | -| `secret` | name of secret | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "allow_command": false -} -``` - -#### Request - -```sh -curl \ - -X PUT \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" - "http://127.0.0.1:8080/api/v1/secrets/native/repo/github/octocat/foo" -``` - -#### Response - -```json -{ - "id": 1, - "org": "github", - "repo": "octocat", - "team": "", - "name": "foo", - "value": "", - "type": "repo", - "images": ["alpine"], - "events": ["push", "tag"], - "allow_command": true, - "allow_substitution": true, - "allow_events": { - "push": { - "branch": true, - "tag": true, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": true - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "created_at": 1641314085, - "created_by": "octokitty", - "updated_at": 1641314500, - "updated_by": "octocat" -} -``` diff --git a/versioned_docs/version-0.26/reference/api/secret/view.md b/versioned_docs/version-0.26/reference/api/secret/view.md deleted file mode 100644 index 112bec5..0000000 --- a/versioned_docs/version-0.26/reference/api/secret/view.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect a secret. ---- - -## Endpoint - -``` -GET /api/v1/secrets/:engine/:type/:org/:name/:secret -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| -------- | -------------------------- | -| `engine` | name of engine | -| `type` | name of type of secret | -| `org` | name of organization | -| `name` | name of repository or team | -| `secret` | name of secret | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/secrets/native/repo/github/octocat/foo" -``` - -#### Response - -```json -{ - "id": 1, - "org": "github", - "repo": "octocat", - "team": "", - "name": "foo", - "value": "", - "type": "repo", - "images": ["alpine"], - "events": ["push"], - "allow_command": true, - "allow_substitution": true, - "allow_events": { - "push": { - "branch": true, - "tag": true, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": true - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "created_at": 1641314085, - "created_by": "octokitty", - "updated_at": 1641314500, - "updated_by": "octocat" -} -``` diff --git a/versioned_docs/version-0.26/reference/api/service/add.md b/versioned_docs/version-0.26/reference/api/service/add.md deleted file mode 100644 index c9ad084..0000000 --- a/versioned_docs/version-0.26/reference/api/service/add.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: "Add" -linkTitle: "Add" -description: > - Learn how to create a service. ---- - -## Endpoint - -``` -POST /api/v1/repos/:org/:repo/builds/:build/services -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------- | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | -| `build` | number of build | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "number": 1, - "name": "clone" -} -``` - -#### Request - -```sh -curl \ - -X POST \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/services" -``` - -#### Response - -```json -{ - "id": 1, - "build_id": 1, - "repo_id": 1, - "number": 1, - "name": "clone", - "status": "success", - "error": "", - "exit_code": 0, - "created": 1563475419, - "started": 1563475420, - "finished": 1563475421 -} -``` diff --git a/versioned_docs/version-0.26/reference/api/service/get.md b/versioned_docs/version-0.26/reference/api/service/get.md deleted file mode 100644 index 78d0150..0000000 --- a/versioned_docs/version-0.26/reference/api/service/get.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to list services. ---- - -## Endpoint - -``` -GET /api/v1/repos/:org/:repo/builds/:build/services -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------- | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | -| `build` | number of build | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/services" -``` - -#### Response - -```json -[ - { - "id": 2, - "build_id": 1, - "repo_id": 1, - "number": 2, - "name": "build", - "status": "success", - "error": "", - "exit_code": 0, - "created": 1563475419, - "started": 1563475420, - "finished": 1563475421 - }, - { - "id": 1, - "build_id": 1, - "repo_id": 1, - "number": 1, - "name": "clone", - "status": "success", - "error": "", - "exit_code": 0, - "created": 1563475419, - "started": 1563475420, - "finished": 1563475421 - } -] -``` diff --git a/versioned_docs/version-0.26/reference/api/service/logs.md b/versioned_docs/version-0.26/reference/api/service/logs.md deleted file mode 100644 index 2bdc66d..0000000 --- a/versioned_docs/version-0.26/reference/api/service/logs.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: "Logs" -linkTitle: "Logs" -description: > - Learn how to view logs for a service. ---- - -## Endpoint - -``` -GET /api/v1/repos/:org/:repo/builds/:build/services/:service/logs -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| --------- | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | -| `build` | number of build | -| `service` | number of service | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/services/1/logs" -``` - -#### Response - -```json -{ - "id": 1, - "build_id": 1, - "repo_id": 1, - "service_id": 1, - "data": "SGVsbG8sIFdvcmxkIQ==" -} -``` - -The `data` field is base64 encoded. To decode the data, you can use the following command: - -```sh -echo "SGVsbG8sIFdvcmxkIQ==" | base64 --decode -``` diff --git a/versioned_docs/version-0.26/reference/api/service/remove.md b/versioned_docs/version-0.26/reference/api/service/remove.md deleted file mode 100644 index 7b186ed..0000000 --- a/versioned_docs/version-0.26/reference/api/service/remove.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: "Remove" -linkTitle: "Remove" -description: > - Learn how to delete a service. ---- - -## Endpoint - -``` -DELETE /api/v1/repos/:org/:repo/builds/:build/services/:service -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| --------- | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | -| `build` | number of build | -| `service` | number of service | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X DELETE \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/services/1" -``` - -#### Response - -``` -Service github/octocat/1/1 deleted -``` diff --git a/versioned_docs/version-0.26/reference/api/service/service.md b/versioned_docs/version-0.26/reference/api/service/service.md deleted file mode 100644 index 78cabcf..0000000 --- a/versioned_docs/version-0.26/reference/api/service/service.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Service" -linkTitle: "Service" -description: > - Learn how to use API endpoints for the service resource. ---- - -The below endpoints are available to operate on the `service` resource. - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/api/service/update.md b/versioned_docs/version-0.26/reference/api/service/update.md deleted file mode 100644 index c50fc15..0000000 --- a/versioned_docs/version-0.26/reference/api/service/update.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: "Update" -linkTitle: "Update" -description: > - Learn how to modify a service. ---- - -## Endpoint - -``` -PUT /api/v1/repos/:org/:repo/builds/:build/services/:service -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| --------- | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | -| `build` | number of build | -| `service` | number of service | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "status": "failure" -} -``` - -#### Request - -```sh -curl \ - -X PUT \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/services/1" -``` - -#### Response - -```json -{ - "id": 1, - "build_id": 1, - "repo_id": 1, - "number": 1, - "name": "clone", - "status": "failure", - "error": "", - "exit_code": 0, - "created": 1563475419, - "started": 1563475420, - "finished": 1563475421 -} -``` diff --git a/versioned_docs/version-0.26/reference/api/service/view.md b/versioned_docs/version-0.26/reference/api/service/view.md deleted file mode 100644 index 7a10562..0000000 --- a/versioned_docs/version-0.26/reference/api/service/view.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect a service. ---- - -## Endpoint - -``` -GET /api/v1/repos/:org/:repo/builds/:build/services/:service -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| --------- | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | -| `build` | number of build | -| `service` | number of service | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/services/1" -``` - -#### Response - -```json -{ - "id": 1, - "build_id": 1, - "repo_id": 1, - "number": 1, - "name": "clone", - "status": "success", - "error": "", - "exit_code": 0, - "created": 1563475419, - "started": 1563475420, - "finished": 1563475421 -} -``` diff --git a/versioned_docs/version-0.26/reference/api/step/add.md b/versioned_docs/version-0.26/reference/api/step/add.md deleted file mode 100644 index 10c7d11..0000000 --- a/versioned_docs/version-0.26/reference/api/step/add.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: "Add" -linkTitle: "Add" -description: > - Learn how to create a step. ---- - -## Endpoint - -``` -POST /api/v1/repos/:org/:repo/builds/:build/steps -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------- | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | -| `build` | number of build | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "number": 1, - "name": "clone" -} -``` - -#### Request - -```sh -curl \ - -X POST \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/steps" -``` - -#### Response - -```json -{ - "id": 1, - "build_id": 1, - "repo_id": 1, - "number": 1, - "name": "clone", - "status": "success", - "error": "", - "exit_code": 0, - "created": 1563475419, - "started": 0, - "finished": 0, - "host": "company.localhost", - "runtime": "docker", - "distribution": "linux" -} -``` diff --git a/versioned_docs/version-0.26/reference/api/step/get.md b/versioned_docs/version-0.26/reference/api/step/get.md deleted file mode 100644 index 619c376..0000000 --- a/versioned_docs/version-0.26/reference/api/step/get.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to list steps. ---- - -## Endpoint - -``` -GET /api/v1/repos/:org/:repo/builds/:build/steps -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------- | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | -| `build` | number of build | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/steps" -``` - -#### Response - -```json -[ - { - "id": 2, - "build_id": 1, - "repo_id": 1, - "number": 2, - "name": "build", - "status": "success", - "error": "", - "exit_code": 0, - "created": 1563475419, - "started": 0, - "finished": 0, - "host": "company.localhost", - "runtime": "docker", - "distribution": "linux" - }, - { - "id": 1, - "build_id": 1, - "repo_id": 1, - "number": 1, - "name": "clone", - "status": "success", - "error": "", - "exit_code": 0, - "created": 1563475419, - "started": 0, - "finished": 0, - "host": "company.localhost", - "runtime": "docker", - "distribution": "linux" - } -] -``` diff --git a/versioned_docs/version-0.26/reference/api/step/logs.md b/versioned_docs/version-0.26/reference/api/step/logs.md deleted file mode 100644 index 38f0d31..0000000 --- a/versioned_docs/version-0.26/reference/api/step/logs.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: "Logs" -linkTitle: "Logs" -description: > - Learn how to view step logs. ---- - -## Endpoint - -``` -GET /api/v1/repos/:org/:repo/builds/:build/steps/:step/logs -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------- | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | -| `build` | number of build | -| `step` | number of step | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/steps/1/logs" -``` - -#### Response - -```json -{ - "id": 1, - "build_id": 1, - "repo_id": 1, - "step_id": 1, - "data": "SGVsbG8sIFdvcmxkIQ==" -} -``` - -The `data` field is base64 encoded. To decode the data, you can use the following command: - -```sh -echo "SGVsbG8sIFdvcmxkIQ==" | base64 --decode -``` diff --git a/versioned_docs/version-0.26/reference/api/step/remove.md b/versioned_docs/version-0.26/reference/api/step/remove.md deleted file mode 100644 index 807cc67..0000000 --- a/versioned_docs/version-0.26/reference/api/step/remove.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: "Remove" -linkTitle: "Remove" -description: > - Learn how to delete a step. ---- - -## Endpoint - -``` -DELETE /api/v1/repos/:org/:repo/builds/:build/steps/:step -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------- | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | -| `build` | number of build | -| `step` | number of step | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X DELETE \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/steps/1" -``` - -#### Response - -``` -Step github/octocat/1/1 deleted -``` diff --git a/versioned_docs/version-0.26/reference/api/step/step.md b/versioned_docs/version-0.26/reference/api/step/step.md deleted file mode 100644 index a4db5da..0000000 --- a/versioned_docs/version-0.26/reference/api/step/step.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Step" -linkTitle: "Step" -description: > - Learn how to use API endpoints for the step resource. ---- - -The below endpoints are available to operate on the `step` resource. - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/api/step/update.md b/versioned_docs/version-0.26/reference/api/step/update.md deleted file mode 100644 index 8d01732..0000000 --- a/versioned_docs/version-0.26/reference/api/step/update.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: "Update" -linkTitle: "Update" -description: > - Learn how to modify a step. ---- - -## Endpoint - -``` -PUT /api/v1/repos/:org/:repo/builds/:build/steps/:step -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------- | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | -| `build` | number of build | -| `step` | number of step | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "status": "failure" -} -``` - -#### Request - -```sh -curl \ - -X PUT \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/steps/1" -``` - -#### Response - -```json -{ - "id": 1, - "build_id": 1, - "repo_id": 1, - "number": 1, - "name": "clone", - "status": "failure", - "error": "", - "exit_code": 0, - "created": 1563475419, - "started": 0, - "finished": 0, - "host": "company.localhost", - "runtime": "docker", - "distribution": "linux" -} -``` diff --git a/versioned_docs/version-0.26/reference/api/step/view.md b/versioned_docs/version-0.26/reference/api/step/view.md deleted file mode 100644 index 68f806d..0000000 --- a/versioned_docs/version-0.26/reference/api/step/view.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect a step. ---- - -## Endpoint - -``` -GET /api/v1/repos/:org/:repo/builds/:build/steps/:step -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------- | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | -| `build` | number of build | -| `step` | number of step | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/steps/1" -``` - -#### Response - -```json -{ - "id": 1, - "build_id": 1, - "repo_id": 1, - "number": 1, - "name": "clone", - "status": "success", - "error": "", - "exit_code": 0, - "created": 1563475419, - "started": 0, - "finished": 0, - "host": "company.localhost", - "runtime": "docker", - "distribution": "linux" -} -``` diff --git a/versioned_docs/version-0.26/reference/api/user/add.md b/versioned_docs/version-0.26/reference/api/user/add.md deleted file mode 100644 index 9f7c883..0000000 --- a/versioned_docs/version-0.26/reference/api/user/add.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: "Add" -linkTitle: "Add" -description: > - Learn how to create a user. ---- - -## Endpoint - -``` -POST /api/v1/users -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "name": "OctoKitty", - "favorites": ["github/octocat"], - "active": true, - "admin": false -} -``` - -#### Request - -```sh -curl \ - -X POST \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/users" -``` - -#### Response - -```json -{ - "id": 1, - "name": "OctoKitty", - "token": null, - "favorites": ["github/octocat"], - "active": true, - "admin": false -} -``` diff --git a/versioned_docs/version-0.26/reference/api/user/current/current.md b/versioned_docs/version-0.26/reference/api/user/current/current.md deleted file mode 100644 index 30ae559..0000000 --- a/versioned_docs/version-0.26/reference/api/user/current/current.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Current" -linkTitle: "Current" -description: > - Learn how to use API endpoints for the current user. ---- - -The below endpoints are available to operate on for the current user. - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/api/user/current/repos.md b/versioned_docs/version-0.26/reference/api/user/current/repos.md deleted file mode 100644 index fd2ebb3..0000000 --- a/versioned_docs/version-0.26/reference/api/user/current/repos.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: "Repos" -linkTitle: "Repos" -description: > - Learn how to list repos for the current user. ---- - -## Endpoint - -``` -GET /api/v1/user/source/repos -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/user/source/repos" -``` - -#### Response - -```json -[ - { - "id": 1, - "user_id": 1, - "org": "github", - "name": "octocat", - "full_name": "github/octocat", - "link": "https://github.com/github/octocat", - "clone": "https://github.com/github/octocat.git", - "branch": "main", - "timeout": 60, - "visibility": "public", - "private": false, - "trusted": true, - "active": true, - "allow_pull": true, - "allow_push": true, - "allow_deploy": false, - "allow_tag": false, - "allow_comment": false - }, - { - "id": 2, - "user_id": 1, - "org": "github", - "name": "octokitty", - "full_name": "github/octokitty", - "link": "https://github.com/github/octokitty", - "clone": "https://github.com/github/octokitty.git", - "branch": "main", - "timeout": 60, - "visibility": "public", - "private": false, - "trusted": true, - "active": true, - "allow_pull": true, - "allow_push": true, - "allow_deploy": false, - "allow_tag": false, - "allow_comment": false - } -] -``` diff --git a/versioned_docs/version-0.26/reference/api/user/current/update.md b/versioned_docs/version-0.26/reference/api/user/current/update.md deleted file mode 100644 index d293d4e..0000000 --- a/versioned_docs/version-0.26/reference/api/user/current/update.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: "Update" -linkTitle: "Update" -description: > - Learn how to modify the current user. ---- - -## Endpoint - -``` -PUT /api/v1/user -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "admin": true -} -``` - -#### Request - -```sh -curl \ - -X PUT \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/user" -``` - -#### Response - -```json -{ - "id": 1, - "name": "OctoKitty", - "token": null, - "favorites": ["github/octocat"], - "active": true, - "admin": true -} -``` diff --git a/versioned_docs/version-0.26/reference/api/user/current/view.md b/versioned_docs/version-0.26/reference/api/user/current/view.md deleted file mode 100644 index de2229f..0000000 --- a/versioned_docs/version-0.26/reference/api/user/current/view.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect the current user. ---- - -## Endpoint - -``` -GET /api/v1/user -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/user" -``` - -#### Response - -```json -{ - "id": 1, - "name": "OctoKitty", - "token": null, - "favorites": ["github/octocat"], - "active": true, - "admin": false -} -``` diff --git a/versioned_docs/version-0.26/reference/api/user/get.md b/versioned_docs/version-0.26/reference/api/user/get.md deleted file mode 100644 index 27739dd..0000000 --- a/versioned_docs/version-0.26/reference/api/user/get.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to list users. ---- - -## Endpoint - -``` -GET /api/v1/users -``` - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/users" -``` - -#### Response - -```json -[ - { - "id": 2, - "name": "octocat", - "token": null, - "favorites": ["github/octocat"], - "active": true, - "admin": false - }, - { - "id": 1, - "name": "OctoKitty", - "token": null, - "favorites": ["github/octocat"], - "active": true, - "admin": false - } -] -``` diff --git a/versioned_docs/version-0.26/reference/api/user/remove.md b/versioned_docs/version-0.26/reference/api/user/remove.md deleted file mode 100644 index 419e335..0000000 --- a/versioned_docs/version-0.26/reference/api/user/remove.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "Remove" -linkTitle: "Remove" -description: > - Learn how to delete a user. ---- - -## Endpoint - -``` -DELETE /api/v1/users/:user -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------ | ------------ | -| `user` | name of user | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X DELETE \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/users/OctoKitty" -``` - -#### Response - -```sh -User OctoKitty deleted -``` diff --git a/versioned_docs/version-0.26/reference/api/user/update.md b/versioned_docs/version-0.26/reference/api/user/update.md deleted file mode 100644 index e8212a5..0000000 --- a/versioned_docs/version-0.26/reference/api/user/update.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: "Update" -linkTitle: "Update" -description: > - Learn how to modify a user. ---- - -## Endpoint - -``` -PUT /api/v1/users/:user -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------ | ------------ | -| `user` | name of user | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### File - -```json -{ - "admin": true -} -``` - -#### Request - -```sh -curl \ - -X PUT \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - "http://127.0.0.1:8080/api/v1/users/OctoKitty" -``` - -#### Response - -```json -{ - "id": 1, - "name": "OctoKitty", - "token": null, - "favorites": ["github/octocat"], - "active": true, - "admin": true -} -``` diff --git a/versioned_docs/version-0.26/reference/api/user/user.md b/versioned_docs/version-0.26/reference/api/user/user.md deleted file mode 100644 index a87fd64..0000000 --- a/versioned_docs/version-0.26/reference/api/user/user.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "User" -linkTitle: "User" -description: > - Learn how to use API endpoints for the user resource. ---- - -The below endpoints are available to operate on the `user` resource. - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/api/user/view.md b/versioned_docs/version-0.26/reference/api/user/view.md deleted file mode 100644 index 74b6726..0000000 --- a/versioned_docs/version-0.26/reference/api/user/view.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect a user. ---- - -## Endpoint - -``` -GET /api/v1/users/:user -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------ | ------------ | -| `user` | name of user | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/users/OctoKitty" -``` - -#### Response - -```json -{ - "id": 1, - "name": "OctoKitty", - "token": null, - "favorites": ["github/octocat"], - "active": true, - "admin": false -} -``` diff --git a/versioned_docs/version-0.26/reference/cli/_category_.json b/versioned_docs/version-0.26/reference/cli/_category_.json deleted file mode 100644 index 1e341af..0000000 --- a/versioned_docs/version-0.26/reference/cli/_category_.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "label": "CLI", - "position": 2, - "link": { - "type": "generated-index" - } -} diff --git a/versioned_docs/version-0.26/reference/cli/authentication.md b/versioned_docs/version-0.26/reference/cli/authentication.md deleted file mode 100644 index 7afdb32..0000000 --- a/versioned_docs/version-0.26/reference/cli/authentication.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: "Authentication" -sidebar_position: 1 ---- - -## Overview - -Authentication with the Vela CLI is the responsibility of the client initiating the request. - -Each request requires a server address. You can provide this variable to the CLI in three ways: - -- Configuration File -- Environment Variable -- Flag - -:::tip -A configuration file is the recommended method for providing the API address to the CLI. -::: - -### Configuration File - -:::tip -The default path for this configuration file can be found @ `$HOME/.vela/config.yml`. -::: - -Log in: - -```sh -# Syntax -vela login --api.addr - -# Example -vela login --api.addr https://vela.example.com -``` - -Confirm authentication via browser prompt: - -``` -Open https://vela.example.com in your browser and complete authentication (Press Enter to confirm): -``` - -Confirm to generate or update the configuration file prompt: - -``` -Authentication complete. Continue to save configuration (existing config will be overwritten): -``` - -:::tip -For more information, you can visit the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -### Environment Variables - -Configure the environment with the `VELA_ADDR` environment variable: - -```sh -export VELA_ADDR=https://vela.example.com -``` - -Log in and confirm the two prompts as stated above: - -```sh -vela login -``` - -:::tip -It's recommended to add these to your terminal profile (`~/.bashrc` or `~/.zshrc`) -::: - -### Flags - -Log in and confirm the two prompts as stated above: - -```sh -# Syntax -vela login --api.addr - -# Example -vela login --api.addr https://vela.example.com -``` diff --git a/versioned_docs/version-0.26/reference/cli/build/approve.md b/versioned_docs/version-0.26/reference/cli/build/approve.md deleted file mode 100644 index 5e0e9f4..0000000 --- a/versioned_docs/version-0.26/reference/cli/build/approve.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: "Approve" -linkTitle: "Approve" -description: > - Learn how to approve a build as a repository admin. ---- - -## Command - -``` -$ vela approve build -``` - -:::tip -For more information, you can run `vela approve build --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| -------- | ---------------------------------- | --------------------------------- | -| `org` | name of organization for the build | `VELA_ORG`, `BUILD_ORG` | -| `repo` | name of repository for the build | `VELA_REPO`, `BUILD_REPO` | -| `build` | number of the build | `VELA_BUILD`, `BUILD_NUMBER` | -| `output` | format the output for the build | `VELA_OUTPUT`, `BUILD_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela approve build --build 1 -``` - -#### Targeted Request - -```sh -$ vela approve build --org github --repo octocat --build 1 -``` - -#### Response - -```sh -"successfully approved build github/octocat/1" -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/cli/build/build.md b/versioned_docs/version-0.26/reference/cli/build/build.md deleted file mode 100644 index 5fb8a84..0000000 --- a/versioned_docs/version-0.26/reference/cli/build/build.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "Build" ---- - -The below commands are available to operate on the `build` resource. - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/cli/build/cancel.md b/versioned_docs/version-0.26/reference/cli/build/cancel.md deleted file mode 100644 index d03eb60..0000000 --- a/versioned_docs/version-0.26/reference/cli/build/cancel.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: "Cancel" -linkTitle: "Cancel" -description: > - Learn how to cancel a build. ---- - -## Command - -``` -$ vela cancel build -``` - -:::tip -For more information, you can run `vela cancel build --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| -------- | ---------------------------------- | --------------------------------- | -| `org` | name of organization for the build | `VELA_ORG`, `BUILD_ORG` | -| `repo` | name of repository for the build | `VELA_REPO`, `BUILD_REPO` | -| `build` | number of the build | `VELA_BUILD`, `BUILD_NUMBER` | -| `output` | format the output for the build | `VELA_OUTPUT`, `BUILD_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela cancel build --build 1 -``` - -#### Targeted Request - -```sh -$ vela cancel build --org github --repo octocat --build 1 -``` - -#### Response - -```sh -canceled build github/octocat/1 -``` diff --git a/versioned_docs/version-0.26/reference/cli/build/get.md b/versioned_docs/version-0.26/reference/cli/build/get.md deleted file mode 100644 index 897a5ca..0000000 --- a/versioned_docs/version-0.26/reference/cli/build/get.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to list builds. ---- - -## Command - -``` -$ vela get build -``` - -:::tip -For more information, you can run `vela get build --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| ---------- | ------------------------------------ | --------------------------------- | -| `org` | name of organization for the builds | `VELA_ORG`, `BUILD_ORG` | -| `repo` | name of repository for the builds | `VELA_REPO`, `BUILD_REPO` | -| `event` | name of event filter for the builds | `VELA_EVENT`, `BUILD_EVENT` | -| `status` | name of status filter for the builds | `VELA_STATUS`, `BUILD_STATUS` | -| `branch` | name of branch filter for the builds | `VELA_BRANCH`, `BUILD_BRANCH` | -| `output` | format the output for the builds | `VELA_OUTPUT`, `BUILD_OUTPUT` | -| `page` | prints a specific page of builds | `VELA_PAGE`, `BUILD_PAGE` | -| `per.page` | number of builds to print per page | `VELA_PER_PAGE`, `BUILD_PER_PAGE` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela get build --build 1 -``` - -#### Targeted Request - -```sh -$ vela get build --org github --repo octocat --build 1 -``` - -#### Response - -```sh -NUMBER STATUS EVENT BRANCH DURATION -5 failure push main 45s -4 failure push main 50s -3 success push main 54s -2 success push main 55s -1 pending push main ... -``` diff --git a/versioned_docs/version-0.26/reference/cli/build/restart.md b/versioned_docs/version-0.26/reference/cli/build/restart.md deleted file mode 100644 index 7aa08e0..0000000 --- a/versioned_docs/version-0.26/reference/cli/build/restart.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: "Restart" -linkTitle: "Restart" -description: > - Learn how to rerun a build. ---- - -## Command - -``` -$ vela restart build -``` - -:::tip -For more information, you can run `vela restart build --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| -------- | ---------------------------------- | --------------------------------- | -| `org` | name of organization for the build | `VELA_ORG`, `BUILD_ORG` | -| `repo` | name of repository for the build | `VELA_REPO`, `BUILD_REPO` | -| `build` | number of the build | `VELA_BUILD`, `BUILD_NUMBER` | -| `output` | format the output for the build | `VELA_OUTPUT`, `BUILD_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela restart build --build 1 -``` - -#### Targeted Request - -```sh -$ vela restart build --org github --repo octocat --build 1 -``` - -#### Response - -```sh -id: 2 -repo_id: 1 -number: 2 -parent: 1 -event: push -status: created -error: "" # Populates when the platform runs into an error with the build -enqueued: 1563474087 -created: 1563474086 -started: 1563474087 -finished: 0 -deploy: "" -clone: https://github.com/github/octocat.git -source: https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163 -title: push received from https://github.com/github/octocat -message: First commit... -commit: 48afb5bdc41ad69bf22588491333f7cf71135163 -sender: OctoKitty -author: OctoKitty -branch: main -ref: refs/heads/main -baseref: "" -host: "company.localhost" -runtime: "docker" -distribution: "linux" -``` diff --git a/versioned_docs/version-0.26/reference/cli/build/view.md b/versioned_docs/version-0.26/reference/cli/build/view.md deleted file mode 100644 index a0cb2b6..0000000 --- a/versioned_docs/version-0.26/reference/cli/build/view.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect a build. ---- - -## Command - -``` -$ vela view build -``` - -:::tip -For more information, you can run `vela view build --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| -------- | ---------------------------------- | --------------------------------- | -| `org` | name of organization for the build | `VELA_ORG`, `BUILD_ORG` | -| `repo` | name of repository for the build | `VELA_REPO`, `BUILD_REPO` | -| `build` | number of the build | `VELA_BUILD`, `BUILD_NUMBER` | -| `output` | format the output for the build | `VELA_OUTPUT`, `BUILD_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela view build --build 1 -``` - -#### Targeted Request - -```sh -$ vela view build --org github --repo octocat --build 1 -``` - -#### Response - -```sh -id: 1 -repo_id: 1 -number: 1 -parent: 1 -event: push -status: created -error: "" # Populates when the platform runs into an error with the build -enqueued: 1563474077 -created: 1563474076 -started: 1563474077 -finished: 0 -deploy: "" -clone: https://github.com/github/octocat.git -source: https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163 -title: push received from https://github.com/github/octocat -message: First commit... -commit: 48afb5bdc41ad69bf22588491333f7cf71135163 -sender: OctoKitty -author: OctoKitty -branch: main -ref: refs/heads/main -baseref: "" -host: "company.localhost" -runtime: "docker" -distribution: "linux" -``` diff --git a/versioned_docs/version-0.26/reference/cli/completion/completion.md b/versioned_docs/version-0.26/reference/cli/completion/completion.md deleted file mode 100644 index 291be1a..0000000 --- a/versioned_docs/version-0.26/reference/cli/completion/completion.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Completion" -linkTitle: "Completion" -description: > - Learn how to enable auto-completion in your terminal. ---- - -The below commands are available to operate on the `completion` resource. - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/cli/completion/generate.md b/versioned_docs/version-0.26/reference/cli/completion/generate.md deleted file mode 100644 index 7924c9d..0000000 --- a/versioned_docs/version-0.26/reference/cli/completion/generate.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -title: "Generate" -linkTitle: "Generate" -description: > - Learn how to produce auto-completion for your terminal. ---- - -## Command - -``` -$ vela generate completion -``` - -:::info -For more information, you can run `vela generate completion --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| ------ | -------------------------------------- | ------------------------------ | -| `bash` | generate a Bash auto-completion script | `VELA_BASH`, `COMPLETION_BASH` | -| `zsh` | generate a Zsh auto-completion script | `VELA_ZSH`, `COMPLETION_ZSH` | - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -vela generate completion --bash -``` - -#### Response - -```sh -#! /bin/bash - -_cli_bash_autocomplete() { - if [[ "${COMP_WORDS[0]}" != "source" ]]; then - local cur opts base - COMPREPLY=() - cur="${COMP_WORDS[COMP_CWORD]}" - - if [[ "$cur" == "-"* ]]; then - opts=$( ${COMP_WORDS[@]:0:$COMP_CWORD} ${cur} --generate-bash-completion ) - else - opts=$( ${COMP_WORDS[@]:0:$COMP_CWORD} --generate-bash-completion ) - fi - - COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) ) - return 0 - fi -} - -complete -o bashdefault -o default -o nospace -F _cli_bash_autocomplete vela -``` - -## Permanent Automatic Completion - -This section covers how to enable auto-completion for your terminal permanently. - -#### Bash - -:::info -This section assumes you have a version of Bash greater than 4. - -You can check your Bash version with: - -```sh -bash --version -``` - -If you have a version older than 4, you can use [brew](https://brew.sh) to install a newer version. - -```sh -brew install bash -``` -::: - -1. Install v2 of Bash Completion - -```sh -brew install bash-completion@2 -``` - -2. Copy Vela Bash Completion script - -```sh -vela generate completion --bash >> /usr/local/etc/bash_completion.d/vela.sh -``` - -3. Update Bash Profile with Completion - -```sh -export BASH_COMPLETION_COMPAT_DIR="/usr/local/etc/bash_completion.d" >> $HOME/.bash_profile -[[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh" >> $HOME/.bash_profile -``` - -4. Source Bash Profile in Current Terminal - -```sh -source $HOME/.bash_profile -``` - -#### Zsh - -1. Update Zsh Profile with Completion - -```sh -source <(vela generate completion --zsh) >> $HOME/.zshrc -``` - -:::info -If you're met with an error like: - -```sh -complete:13: command not found: compdef -``` - -Then you need to add the following to the top of your `$HOME/.zshrc`: - -```sh -autoload -Uz compinit -compinit -``` -::: diff --git a/versioned_docs/version-0.26/reference/cli/config/config.md b/versioned_docs/version-0.26/reference/cli/config/config.md deleted file mode 100644 index 7fa3939..0000000 --- a/versioned_docs/version-0.26/reference/cli/config/config.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Config" -linkTitle: "Config" -description: > - Learn how to use CLI commands for the config resource. ---- - -The below commands are available to operate on the `config` resource. - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/cli/config/generate.md b/versioned_docs/version-0.26/reference/cli/config/generate.md deleted file mode 100644 index 5c8ad9c..0000000 --- a/versioned_docs/version-0.26/reference/cli/config/generate.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: "Generate" -linkTitle: "Generate" -description: > - Learn how to produce a config. ---- - -## Command - -``` -$ vela generate config -``` - -:::tip -For more information, you can run `vela generate config --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| ------------------- | ----------------------------------------------- | -------------------------------------------- | -| `api.addr` | full URL to API server | `VELA_ADDR`, `CONFIG_ADDR` | -| `api.token.access` | API access token | `VELA_ACCESS_TOKEN`, `CONFIG_ACCESS_TOKEN` | -| `api.token.refresh` | API refresh token | `VELA_REFRESH_TOKEN`, `CONFIG_REFRESH_TOKEN` | -| `api.token` | PAT for API server | `VELA_TOKEN`, `CONFIG_TOKEN` | -| `api.version` | version of API for server | `VELA_API_VERSION`, `CONFIG_API_VERSION` | -| `log.level` | set the level of logging | `VELA_LOG_LEVEL`, `CONFIG_LOG_LEVEL` | -| `no-git` | set whether CLI finds repo of cwd automatically | `VELA_NO_GIT`, `CONFIG_NO_GIT` | -| `output` | format the output for API results | `VELA_OUTPUT`, `CONFIG_OUTPUT` | -| `org` | name of organization for API calls | `VELA_ORG`, `CONFIG_ORG` | -| `repo` | name of repository for API calls | `VELA_REPO`, `CONFIG_REPO` | -| `secret.engine` | name of secret engine for API calls | `VELA_ENGINE`, `CONFIG_ENGINE` | -| `secret.type` | name of secret type for API calls | `VELA_TYPE`, `CONFIG_TYPE` | - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -vela generate config --api.addr https://vela.example.com --log.level info -``` - -#### Response - -```sh -api: - addr: https://vela.example.com -log: - level: info -no-git: "false" -secret: {} -``` diff --git a/versioned_docs/version-0.26/reference/cli/config/remove.md b/versioned_docs/version-0.26/reference/cli/config/remove.md deleted file mode 100644 index bfbe02a..0000000 --- a/versioned_docs/version-0.26/reference/cli/config/remove.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "Remove" -linkTitle: "Remove" -description: > - Learn how to delete a config. ---- - -## Command - -``` -$ vela remove config -``` - -:::tip -For more information, you can run `vela remove config --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -:::warning -Providing no parameters to this command will remove the entire configuration file. -::: - -| Name | Description | Environment Variables | -| ------------------- | ----------------------------------- | -------------------------------------------- | -| `api.addr` | removes the API address field | `VELA_ADDR`, `CONFIG_ADDR` | -| `api.token.access` | removes the API access token field | `VELA_ACCESS_TOKEN`, `CONFIG_ACCESS_TOKEN` | -| `api.token.refresh` | removes the API refresh token field | `VELA_REFRESH_TOKEN`, `CONFIG_REFRESH_TOKEN` | -| `api.token` | removes the API token field | `VELA_TOKEN`, `CONFIG_TOKEN` | -| `api.version` | removes the API version field | `VELA_API_VERSION`, `CONFIG_API_VERSION` | -| `log.level` | removes the log level field | `VELA_LOG_LEVEL`, `CONFIG_LOG_LEVEL` | -| `output` | removes the output field | `VELA_OUTPUT`, `CONFIG_OUTPUT` | -| `org` | removes the org field | `VELA_ORG`, `CONFIG_ORG` | -| `repo` | removes the repo field | `VELA_REPO`, `CONFIG_REPO` | -| `secret.engine` | removes the secret engine field | `VELA_ENGINE`, `CONFIG_ENGINE` | -| `secret.type` | removes the secret type field | `VELA_TYPE`, `CONFIG_TYPE` | - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -vela remove config -``` - -#### Response diff --git a/versioned_docs/version-0.26/reference/cli/config/update.md b/versioned_docs/version-0.26/reference/cli/config/update.md deleted file mode 100644 index c491140..0000000 --- a/versioned_docs/version-0.26/reference/cli/config/update.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: "Update" -linkTitle: "Update" -description: > - Learn how to modify a config. ---- - -## Command - -``` -$ vela update config -``` - -:::tip -For more information, you can run `vela update config --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| ------------------- | ----------------------------------- | -------------------------------------------- | -| `api.addr` | updates the API address field | `VELA_ADDR`, `CONFIG_ADDR` | -| `api.token.access` | updates the API access token field | `VELA_ACCESS_TOKEN`, `CONFIG_ACCESS_TOKEN` | -| `api.token.refresh` | updates the API refresh token field | `VELA_REFRESH_TOKEN`, `CONFIG_REFRESH_TOKEN` | -| `api.token` | updates the API token field | `VELA_TOKEN`, `CONFIG_TOKEN` | -| `api.version` | updates the API version field | `VELA_API_VERSION`, `CONFIG_API_VERSION` | -| `log.level` | updates the log level field | `VELA_LOG_LEVEL`, `CONFIG_LOG_LEVEL` | -| `output` | updates the output field | `VELA_OUTPUT`, `CONFIG_OUTPUT` | -| `org` | updates the org field | `VELA_ORG`, `CONFIG_ORG` | -| `repo` | updates the repo field | `VELA_REPO`, `CONFIG_REPO` | -| `secret.engine` | updates the secret engine field | `VELA_ENGINE`, `CONFIG_ENGINE` | -| `secret.type` | updates the secret type field | `VELA_TYPE`, `CONFIG_TYPE` | - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -vela update config --org github -``` - -#### Response - -```sh -api: - addr: https://vela.example.com - access_token: superSecretAccessToken - refresh_token: superSecretRefreshToken - version: v1 -log: - level: info -no-git: "false" -secret: {} -org: github -``` diff --git a/versioned_docs/version-0.26/reference/cli/config/view.md b/versioned_docs/version-0.26/reference/cli/config/view.md deleted file mode 100644 index a1a75e5..0000000 --- a/versioned_docs/version-0.26/reference/cli/config/view.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect a config. ---- - -## Command - -``` -$ vela view config -``` - -:::tip -For more information, you can run `vela view config --help`. -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -vela view config -``` - -#### Response - -```sh -api: - addr: https://vela.example.com - access_token: superSecretAccessToken - refresh_token: superSecretRefreshToken - version: v1 -log: - level: info -no-git: "false" -secret: {} -``` diff --git a/versioned_docs/version-0.26/reference/cli/dashboard/add.md b/versioned_docs/version-0.26/reference/cli/dashboard/add.md deleted file mode 100644 index 872a9c0..0000000 --- a/versioned_docs/version-0.26/reference/cli/dashboard/add.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: "Add" -linkTitle: "Add" -description: > - Learn how to create a dashboard. ---- - -## Command - -``` -$ vela add dashboard -``` - -:::tip -For more information, you can run `vela add dashboard --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| ---------- | ------------------------------------------------- | ------------------------------------------------------- | -| `name` | name for the dashboard | `VELA_DASHBOARD_NAME`, `DASHBOARD_NAME` | -| `repos` | list of repositories (org/repo) for the dashboard | `VELA_DASHBOARD_REPOS`, `DASHBOARD_REPOS` | -| `branches` | filter builds in all repositories by branch | `VELA_DASHBOARD_REPOS_BRANCH`, `DASHBOARD_REPOS_BRANCH` | -| `events` | filter builds in all repositories by event | `VELA_DASHBOARD_REPOS_EVENT`, `DASHBOARD_REPOS_EVENT` | -| `admins` | provide the list of admins for the dashboard | `VELA_DASHBOARD_ADMINS`, `DASHBOARD_ADMINS` | -| `output` | format the output for the dashboard | `VELA_OUTPUT`, `REPO_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ vela add dashboard --name 'Octocat Main Branches' --repos octocat/Hello-World,octocat/Spoon-Knife --branches main -``` - -#### Response - -```sh -{ - Name: Octocat Main Branches, - ID: d3040cd7-9bb6-45d1-a2a1-d794483a902c, - Admins: [{ - Active: true, - Admin: false, - Dashboards: [], - Favorites: [], - ID: 1, - Name: octokitty, - Token: , -}], - CreatedAt: 1716572402, - CreatedBy: octokitty, - UpdatedAt: 1716572402, - UpdatedBy: octokitty, - Repos: [{ - Name: octocat/Hello-World, - ID: 1, - Branches: [main], - Events: [], -} { - Name: octocat/Spoon-Knife, - ID: 2, - Branches: [main], - Events: [], -}], -} -``` - -## Examples - -```sh -EXAMPLES: - 1. Add a dashboard. - $ vela add dashboard --name my-dashboard - 2. Add a dashboard with repositories. - $ vela add dashboard --name my-dashboard --repos Org-1/Repo-1,Org-2/Repo-2 - 3. Add a dashboard with repositories filtering builds by pushes to main. - $ vela add dashboard --name my-dashboard --repos Org-1/Repo-1,Org-2/Repo-2 --branch main --event push - 4. Add a dashboard with multiple admins. - $ vela add dashboard --name my-dashboard --admins JohnDoe,JaneDoe -``` diff --git a/versioned_docs/version-0.26/reference/cli/dashboard/dashboard.md b/versioned_docs/version-0.26/reference/cli/dashboard/dashboard.md deleted file mode 100644 index 8448a04..0000000 --- a/versioned_docs/version-0.26/reference/cli/dashboard/dashboard.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Dashboard" -linkTitle: "Dashboard" -description: > - Learn how to use CLI commands for the dashboard resource. ---- - -The below commands are available to operate on the `dashboard` resource. - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/cli/dashboard/get.md b/versioned_docs/version-0.26/reference/cli/dashboard/get.md deleted file mode 100644 index 1931d1e..0000000 --- a/versioned_docs/version-0.26/reference/cli/dashboard/get.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to list dashboards. ---- - -## Command - -``` -$ vela get dashboard -``` - -:::tip -For more information, you can run `vela get dashboard --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| -------- | ------------------------------------------------------- | --------------------------------- | -| `full` | output the repo and build information for the dashboard | `VELA_FULL`, `DASHBOARD_FULL` | -| `output` | format the output for dashboards | `VELA_OUTPUT`, `DASHBOARD_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ vela get dashboard -``` - -#### Response - -```sh -[{ - Name: Octocat Main Branches, - ID: 59376e53-879f-478e-b6d2-b8aefe219c6d, - Admins: [{ - Active: true, - Admin: false, - Dashboards: [], - Favorites: [], - ID: 1, - Name: octokitty, - Token: , -}], - CreatedAt: 1715117480, - CreatedBy: octokitty, - UpdatedAt: 1715117480, - UpdatedBy: octokitty, - Repos: [{ - Name: octocat/Hello-World, - ID: 1, - Branches: [main], - Events: [], -} { - Name: octocat/Spoon-Knife, - ID: 2, - Branches: [main], - Events: [], -}], -} { - Name: Octocat PR Events, - ID: 0ebb9f01-389c-4a0f-b301-6bf2f9a0fe3b, - Admins: [{ - Active: true, - Admin: false, - Dashboards: [], - Favorites: [], - ID: 1, - Name: octokitty, - Token: , -}], - CreatedAt: 1716397739, - CreatedBy: octokitty, - UpdatedAt: 1716397739, - UpdatedBy: octokitty, - Repos: [{ - Name: octocat/Hello-World, - ID: 1, - Branches: [], - Events: [pull_request], -} { - Name: octocat/Spoon-Knife, - ID: 2, - Branches: [], - Events: [pull_request], -}], -}] -``` - -## Examples - -```sh -EXAMPLES: - 1. Get user dashboards. - $ vela get dashboard - 2. Get user dashboards with repo and build information. - $ vela get dashboard --full -``` diff --git a/versioned_docs/version-0.26/reference/cli/dashboard/update.md b/versioned_docs/version-0.26/reference/cli/dashboard/update.md deleted file mode 100644 index d0f0826..0000000 --- a/versioned_docs/version-0.26/reference/cli/dashboard/update.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: "Update" -linkTitle: "Update" -description: > - Learn how to modify a dashboard. ---- - -## Command - -``` -$ vela update dashboard -``` - -:::tip -For more information, you can run `vela update dashboard --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| -------------- | ------------------------------------------------------------ | ------------------------------------------------------- | -| `id` | uuid for the dashboard | `VELA_DASHBOARD_ID`, `DASHBOARD_ID` | -| `name` | name for the dashboard | `VELA_DASHBOARD_NAME`, `DASHBOARD_NAME` | -| `add-repos` | list of repositories to add for the dashboard | `VELA_DASHBOARD_ADD_REPOS`, `DASHBOARD_ADD_REPOS` | -| `drop-repos` | list of repositories to remove from the dashboard | `VELA_DASHBOARD_DROP_REPOS`, `DASHBOARD_DROP_REPOS` | -| `target-repos` | list of repositories to target for updates for the dashboard | `VELA_DASHBOARD_TARGET_REPOS`, `DASHBOARD_TARGET_REPOS` | -| `add-admins` | list of admins to add for the dashboard | `VELA_DASHBOARD_ADD_ADMINS`, `DASHBOARD_ADD_ADMINS` | -| `drop-admins` | list of admins to remove from the dashboard | `VELA_DASHBOARD_DROP_ADMINS`, `DASHBOARD_DROP_ADMINS` | -| `branches` | filter builds in all repositories by branch | `VELA_DASHBOARD_REPOS_BRANCH`, `DASHBOARD_REPOS_BRANCH` | -| `events` | filter builds in all repositories by event | `VELA_DASHBOARD_REPOS_EVENT`, `DASHBOARD_REPOS_EVENT` | -| `output` | format the output for the dashboard | `VELA_OUTPUT`, `DASHBOARD_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ vela update dashboard --id d3040cd7-9bb6-45d1-a2a1-d794483a902c --name 'Octocat Dev Branches' --target-repos octocat/Hello-world,octocat/Spoon-Knife --branches dev -``` - -#### Response - -```sh -{ - Name: Octocat Dev Branches, - ID: d3040cd7-9bb6-45d1-a2a1-d794483a902c, - Admins: [{ - Active: true, - Admin: false, - Dashboards: [], - Favorites: [], - ID: 1, - Name: octokitty, - Token: , -}], - CreatedAt: 1716572402, - CreatedBy: octokitty, - UpdatedAt: 1716572402, - UpdatedBy: octokitty, - Repos: [{ - Name: octocat/Hello-World, - ID: 1, - Branches: [dev], - Events: [], -} { - Name: octocat/Spoon-Knife, - ID: 2, - Branches: [dev], - Events: [], -}], -} -``` - -## Examples - -```sh -EXAMPLES: - 1. Update a dashboard to add a repository. - $ vela update dashboard --id c8da1302-07d6-11ea-882f-4893bca275b8 --add-repos Org-1/Repo-1 - 2. Update a dashboard to remove a repository. - $ vela update dashboard --id c8da1302-07d6-11ea-882f-4893bca275b8 --drop-repos Org-1/Repo-1 - 3. Update a dashboard to add event and branch filters to specific repositories. - $ vela update dashboard --id c8da1302-07d6-11ea-882f-4893bca275b8 --target-repos Org-1/Repo-1,Org-2/Repo-2 --branches main --events push - 4. Update a dashboard to change the name. - $ vela update dashboard --id c8da1302-07d6-11ea-882f-4893bca275b8 --name MyDashboard - 5. Update a dashboard to add an admin. - $ vela update dashboard --id c8da1302-07d6-11ea-882f-4893bca275b8 --add-admins JohnDoe - 6. Update a dashboard to remove an admin. - $ vela update dashboard --id c8da1302-07d6-11ea-882f-4893bca275b8 --drop-admins JohnDoe -``` diff --git a/versioned_docs/version-0.26/reference/cli/dashboard/view.md b/versioned_docs/version-0.26/reference/cli/dashboard/view.md deleted file mode 100644 index 2b5b23e..0000000 --- a/versioned_docs/version-0.26/reference/cli/dashboard/view.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect a dashboard. ---- - -## Command - -``` -$ vela view dashboard -``` - -:::tip -For more information, you can run `vela view dashboard --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| -------- | ------------------------------------------------------- | ----------------------------------- | -| `id` | uuid for the dashboard | `VELA_DASHBOARD_ID`, `DASHBOARD_ID` | -| `full` | output the repo and build information for the dashboard | `VELA_FULL`, `DASHBOARD_FULL` | -| `output` | format the output for the dashboard | `VELA_OUTPUT`, `REPO_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ vela view dashboard --id d3040cd7-9bb6-45d1-a2a1-d794483a902c -``` - -#### Response - -```sh -{ - Name: Octocat Main Branches, - ID: d3040cd7-9bb6-45d1-a2a1-d794483a902c, - Admins: [{ - Active: true, - Admin: false, - Dashboards: [], - Favorites: [], - ID: 1, - Name: octokitty, - Token: , -}], - CreatedAt: 1716572402, - CreatedBy: octokitty, - UpdatedAt: 1716572402, - UpdatedBy: octokitty, - Repos: [{ - Name: octocat/Hello-World, - ID: 1, - Branches: [main], - Events: [], -} { - Name: octocat/Spoon-Knife, - ID: 2, - Branches: [main], - Events: [], -}], -} -``` - -## Examples - -```sh -EXAMPLES: - 1. View a dashboard. - $ vela view dashboard --id c8da1302-07d6-11ea-882f-4893bca275b8 - 2. View a dashboard with repo and build information. - $ vela view dashboard --id c8da1302-07d6-11ea-882f-4893bca275b8 --full -``` diff --git a/versioned_docs/version-0.26/reference/cli/deployment/add.md b/versioned_docs/version-0.26/reference/cli/deployment/add.md deleted file mode 100644 index b97c168..0000000 --- a/versioned_docs/version-0.26/reference/cli/deployment/add.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: "Add" -linkTitle: "Add" -description: > - Learn how to create a deployment. ---- - -## Command - -``` -$ vela add deployment -``` - -:::tip -For more information, you can run `vela add deployment --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| ------------- | --------------------------------------------------- | -------------------------------------------- | -| `org` | name of organization for the deployment | `VELA_ORG`, `DEPLOYMENT_ORG` | -| `repo` | name of repository for the deployment | `VELA_REPO`, `DEPLOYMENT_REPO` | -| `ref` | name of branch, commit, or tag for the deployment | `VELA_DEPLOYMENT`, `DEPLOYMENT_NUMBER` | -| `target` | name of target environment for the deployment | `VELA_TARGET`, `DEPLOYMENT_TARGET` | -| `description` | short description for the deployment | `VELA_DESCRIPTION`, `DEPLOYMENT_DESCRIPTION` | -| `parameter` | parameter(s) in key=value format for the deployment | `VELA_PARAMETERS,`, `DEPLOYMENT_PARAMETERS` | -| `task` | name of task for the deployment | `VELA_TASK`, `DEPLOYMENT_TASK` | -| `output` | format the output for the deployment | `VELA_OUTPUT`, `DEPLOYMENT_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela add deployment -``` - -#### Targeted Request - -```sh -$ vela add deployment --org github --repo octocat -``` - -#### Response generated from successful CLI command -```sh -deployment "https://api.github.com/repos/github/octocat/deployments/1" was created -``` - -## Examples - -```sh -EXAMPLES: - 1. Add a deployment for a repository. - $ vela add deployment --org MyOrg --repo MyRepo - 2. Add a deployment for a repository with a specific target environment. - $ vela add deployment --org MyOrg --repo MyRepo --target stage - 3. Add a deployment for a repository with a specific branch reference. - $ vela add deployment --org MyOrg --repo MyRepo --ref dev - 4. Add a deployment for a repository with a specific commit reference. - $ vela add deployment --org MyOrg --repo MyRepo --ref 48afb5bdc41ad69bf22588491333f7cf71135163 - 5. Add a deployment for a repository with a specific tag. - $ vela add deployment --org MyOrg --repo MyRepo --ref 'refs/tags/example.tag' - 6. Add a deployment for a repository with a specific description. - $ vela add deployment --org MyOrg --repo MyRepo --description 'my custom message' - 7. Add a deployment for a repository with two parameters. - $ vela add deployment --org MyOrg --repo MyRepo --parameter 'key=value' --parameter 'foo=bar' - 8. Add a deployment for a repository when config or environment variables are set. - $ vela add deployment -``` diff --git a/versioned_docs/version-0.26/reference/cli/deployment/deployment.md b/versioned_docs/version-0.26/reference/cli/deployment/deployment.md deleted file mode 100644 index 3af3ef7..0000000 --- a/versioned_docs/version-0.26/reference/cli/deployment/deployment.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Deployment" -linkTitle: "Deployment" -description: > - Learn how to use CLI commands for the deployment resource. ---- - -The below commands are available to operate on the `deployment` resource. - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/cli/deployment/get.md b/versioned_docs/version-0.26/reference/cli/deployment/get.md deleted file mode 100644 index 8fe9dd1..0000000 --- a/versioned_docs/version-0.26/reference/cli/deployment/get.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to list deployments. ---- - -## Command - -``` -$ vela get deployment -``` - -:::tip -For more information, you can run `vela get deployment --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| ---------- | ---------------------------------------- | -------------------------------------- | -| `org` | name of organization for the deployments | `VELA_ORG`, `DEPLOYMENT_ORG` | -| `repo` | name of repository for the deployments | `VELA_REPO`, `DEPLOYMENT_REPO` | -| `output` | format the output for the deployments | `VELA_OUTPUT`, `DEPLOYMENT_OUTPUT` | -| `page` | prints a specific page of deployments | `VELA_PAGE`, `DEPLOYMENT_PAGE` | -| `per.page` | number of deployments to print per page | `VELA_PER_PAGE`, `DEPLOYMENT_PER_PAGE` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela get deployment -``` - -#### Targeted Request - -```sh -$ vela get deployment --org github --repo octocat -``` - -#### Response generated from successful CLI command -```sh -ID TASK USER REF TARGET -2 deploy:vela octocat main production -1 deploy:vela octocat main production -``` - -## Examples - -```sh -EXAMPLES: - 1. Get deployments for a repository. - $ vela get deployment --org MyOrg --repo MyRepo - 2. Get deployments for a repository with wide view output. - $ vela get deployment --org MyOrg --repo MyRepo --output wide - 3. Get deployments for a repository with yaml output. - $ vela get deployment --org MyOrg --repo MyRepo --output yaml - 4. Get deployments for a repository with json output. - $ vela get deployment --org MyOrg --repo MyRepo --output json - 5. Get deployments for a repository when config or environment variables are set. - $ vela get deployment -``` diff --git a/versioned_docs/version-0.26/reference/cli/deployment/view.md b/versioned_docs/version-0.26/reference/cli/deployment/view.md deleted file mode 100644 index 5e76493..0000000 --- a/versioned_docs/version-0.26/reference/cli/deployment/view.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect a deployment. ---- - -## Command - -``` -$ vela view deployment -``` - -:::tip -For more information, you can run `vela view deployment --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| ------------ | --------------------------------------- | -------------------------------------- | -| `org` | name of organization for the deployment | `VELA_ORG`, `DEPLOYMENT_ORG` | -| `repo` | name of repository for the deployment | `VELA_REPO`, `DEPLOYMENT_REPO` | -| `deployment` | number of the deployment | `VELA_DEPLOYMENT`, `DEPLOYMENT_NUMBER` | -| `output` | format the output for the deployment | `VELA_OUTPUT`, `DEPLOYMENT_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela view deployment --deployment 1 -``` - -#### Targeted Request - -```sh -$ vela view deployment --org github --repo octocat --deployment 1 -``` - -#### Response generated from successful CLI command -```sh -id: 1 -repo_id: 1 -url: https://api.github.com/repos/github/octocat/deployments/1 -user: octocat -commit: 48afb5bdc41ad69bf22588491333f7cf71135163 -ref: main -task: deploy:vela -target: production -description: Deployment request from Vela -``` - -## Examples - -```sh -EXAMPLES: - 1. View deployment details for a repository. - $ vela view deployment --org MyOrg --repo MyRepo --deployment 1 - 2. View deployment details for a repository with json output. - $ vela view deployment --org MyOrg --repo MyRepo --deployment 1 --output json - 3. View deployment details for a repository config or environment variables are set. - $ vela view deployment --deployment 1 -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/cli/hook/get.md b/versioned_docs/version-0.26/reference/cli/hook/get.md deleted file mode 100644 index b3b7f3f..0000000 --- a/versioned_docs/version-0.26/reference/cli/hook/get.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to list hooks. ---- - -## Command - -``` -$ vela get hook -``` - -:::tip -For more information, you can run `vela get hook --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| ---------- | ---------------------------------- | -------------------------------- | -| `org` | name of organization for the hooks | `VELA_ORG`, `HOOK_ORG` | -| `repo` | name of repository for the hooks | `VELA_REPO`, `HOOK_REPO` | -| `output` | format the output for the hooks | `VELA_OUTPUT`, `HOOK_OUTPUT` | -| `page` | prints a specific page of hooks | `VELA_PAGE`, `HOOK_PAGE` | -| `per.page` | number of hooks to print per page | `VELA_PER_PAGE`, `HOOK_PER_PAGE` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela get hook -``` - -#### Targeted Request - -```sh -$ vela get hook --org github --repo octocat -``` - -#### Response - -```sh -NUMBER STATUS EVENT BRANCH -5 failure push main -4 failure push main -3 success push main -2 success push main -1 success push main -``` diff --git a/versioned_docs/version-0.26/reference/cli/hook/hook.md b/versioned_docs/version-0.26/reference/cli/hook/hook.md deleted file mode 100644 index 5757186..0000000 --- a/versioned_docs/version-0.26/reference/cli/hook/hook.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Hook" -linkTitle: "Hook" -description: > - Learn how to use CLI commands for the hook resource. ---- - -The below commands are available to operate on the `hook` resource. - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/cli/hook/view.md b/versioned_docs/version-0.26/reference/cli/hook/view.md deleted file mode 100644 index 22d9524..0000000 --- a/versioned_docs/version-0.26/reference/cli/hook/view.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect a hook. ---- - -## Command - -``` -$ vela view hook -``` - -:::tip -For more information, you can run `vela view hook --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| -------- | --------------------------------- | ---------------------------- | -| `org` | name of organization for the hook | `VELA_ORG`, `HOOK_ORG` | -| `repo` | name of repository for the hook | `VELA_REPO`, `HOOK_REPO` | -| `hook` | number of the hook | `VELA_HOOK`, `HOOK_NUMBER` | -| `output` | format the output for the hook | `VELA_OUTPUT`, `HOOK_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela view hook --hook 1 -``` - -#### Targeted Request - -```sh -$ vela view hook --org github --repo octocat --hook 1 -``` - -#### Response - -```sh -id: 1 -repo_id: 1 -build_id: 1 -number: 1 -source_id: c8da1302-07d6-11ea-882f-4893bca275b8 -created: 1563475419 -host: github.com -event: push -branch: main -error: -status: success -link: https://github.com/github/octocat/settings/hooks/1 -``` diff --git a/versioned_docs/version-0.26/reference/cli/install.md b/versioned_docs/version-0.26/reference/cli/install.md deleted file mode 100644 index 1dc39b2..0000000 --- a/versioned_docs/version-0.26/reference/cli/install.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: "Install" -sidebar_position: 2 ---- - -:::tip -Please keep in mind your operating system (OS) when referring to the installation instructions below. -::: - -## MacOS - -:::tip -[Homebrew](https://brew.sh/) is the recommended method for installing the Vela CLI on a Mac. -::: - -#### Homebrew - -```sh -# add Vela tap to your brew configuration -brew tap go-vela/vela - -# update your taps -brew update - -# install Vela CLI -brew install vela -``` - -#### cURL - -```sh -# download the binary -curl -L https://github.com/go-vela/cli/releases/latest/download/vela_darwin_amd64.tar.gz | tar zx - -# copy binary to $PATH -sudo cp vela /usr/local/bin/ -``` - -## Linux - -#### cURL - -```sh -# download the binary -curl -L https://github.com/go-vela/cli/releases/latest/download/vela_linux_amd64.tar.gz | tar zx - -# copy binary to $PATH -sudo cp vela /usr/local/bin/ -``` - -## Windows - -:::tip -The `curl` utility must be installed before following the instructions below. -::: - -#### Command Prompt - -```sh -# download the binary -curl -L https://github.com/go-vela/cli/releases/latest/download/vela_windows_amd64.tar.gz --output vela_windows_amd64.tar.gz - -# unzip the tarball -tar xzvf vela_windows_amd64.tar.gz - -# copy binary to $PATH -copy vela C:\Windows\System32/vela.exe -``` - -#### Windows PowerShell - -```sh -# download the binary -curl https://github.com/go-vela/cli/releases/latest/download/vela_windows_amd64.tar.gz -OutFile vela_windows_amd64.tar.gz - -# unzip the tarball -tar xzvf vela_windows_amd64.tar.gz - -# copy binary to $PATH -cp vela C:\Windows\System32/vela.exe -``` - -#### PowerShell 6 (PowerShell Core) - -```sh -# download the binary -curl -L https://github.com/go-vela/cli/releases/latest/download/vela_windows_amd64.tar.gz --output vela_windows_amd64.tar.gz - -# unzip the tarball -tar xzvf vela_windows_amd64.tar.gz - -# copy binary to $PATH -cp vela C:\Windows\System32/vela.exe -``` - -## From Source - -:::warning -This method is intended for **developers and advanced users only**. -::: - -:::tip -This section assumes you have already installed and setup [Golang](https://golang.org/). - -To install and setup Golang, please review the [installation documentation](https://golang.org/doc/install). -::: - -```sh -# download the repo -go get -d github.com/go-vela/cli - -# change to the cli directory -cd ${GOPATH}/src/github.com/go-vela/cli - -# build a release binary with Go -go build -o releases/vela - -# copy binary to $PATH -sudo cp releases/vela /usr/local/bin/ -``` diff --git a/versioned_docs/version-0.26/reference/cli/log/get.md b/versioned_docs/version-0.26/reference/cli/log/get.md deleted file mode 100644 index 02bc489..0000000 --- a/versioned_docs/version-0.26/reference/cli/log/get.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to list logs for a build. ---- - -## Command - -``` -$ vela get log -``` - -:::tip -For more information, you can run `vela get log --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| -------- | -------------------------------- | --------------------------- | -| `org` | name of organization for the log | `VELA_ORG`, `LOG_ORG` | -| `repo` | name of repository for the log | `VELA_REPO`, `LOG_REPO` | -| `build` | number of the build for the log | `VELA_BUILD`, `LOG_BUILD` | -| `output` | format the output for the logs | `VELA_OUTPUT`, `LOG_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela get log --build 5 -``` - -#### Targeted Request - -```sh -$ vela get log --org github --repo octocat --build 5 -``` - -#### Response - -```sh -$ git init -Initialized empty Git repository in /vela/src/github.com/github/octocat/.git/ -$ git remote add origin https://github.com/github/octocat.git -$ git remote --verbose -origin https://github.com/github/octocat.git (fetch) -origin https://github.com/github/octocat.git (push) -$ git fetch --no-tags origin refs/heads/main -From https://github.com/github/octocat - * branch main -> FETCH_HEAD - * [new branch] main -> origin/main -$ git reset --hard afafce5e33a8efd4340613b31a953107d6dec3a3 -HEAD is now at afafce5 Dummy commit - -$ echo "Hello World!" -Hello World! -``` diff --git a/versioned_docs/version-0.26/reference/cli/log/log.md b/versioned_docs/version-0.26/reference/cli/log/log.md deleted file mode 100644 index 6f9376a..0000000 --- a/versioned_docs/version-0.26/reference/cli/log/log.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Log" -linkTitle: "Log" -description: > - Learn how to use CLI commands for the log resource. ---- - -The below commands are available to operate on the `log` resource. - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/cli/log/view.md b/versioned_docs/version-0.26/reference/cli/log/view.md deleted file mode 100644 index 16044ce..0000000 --- a/versioned_docs/version-0.26/reference/cli/log/view.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect logs for a build, step, or service. ---- - -## Command - -``` -$ vela view log -``` - -:::tip -For more information, you can run `vela view log --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| --------- | --------------------------------- | ----------------------------- | -| `org` | name of organization for the log | `VELA_ORG`, `LOG_ORG` | -| `repo` | name of repository for the log | `VELA_REPO`, `LOG_REPO` | -| `build` | number of the build for the log | `VELA_BUILD`, `LOG_BUILD` | -| `service` | number of the service for the log | `VELA_SERVICE`, `LOG_SERVICE` | -| `step` | number of the step for the log | `VELA_STEP`, `LOG_STEP` | -| `output` | format the output for the logs | `VELA_OUTPUT`, `LOG_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela view log --build 5 --step 1 -``` - -#### Targeted Request - -```sh -$ vela view log --org github --repo octocat --build 5 --step 1 -``` - -#### Response - -```sh -$ git init -Initialized empty Git repository in /vela/src/github.com/github/octocat/.git/ -$ git remote add origin https://github.com/github/octocat.git -$ git remote --verbose -origin https://github.com/github/octocat.git (fetch) -origin https://github.com/github/octocat.git (push) -$ git fetch --no-tags origin refs/heads/main -From https://github.com/github/octocat - * branch main -> FETCH_HEAD - * [new branch] main -> origin/main -$ git reset --hard afafce5e33a8efd4340613b31a953107d6dec3a3 -HEAD is now at afafce5 Dummy commit -``` diff --git a/versioned_docs/version-0.26/reference/cli/pipeline/exec.md b/versioned_docs/version-0.26/reference/cli/pipeline/exec.md deleted file mode 100644 index 99f9c7f..0000000 --- a/versioned_docs/version-0.26/reference/cli/pipeline/exec.md +++ /dev/null @@ -1,271 +0,0 @@ ---- -title: "Exec" -linkTitle: "Exec" -description: > - Learn how to execute a pipeline locally. ---- - -## Command - -``` -$ vela exec pipeline -``` - -:::tip -For more information, you can run `vela exec pipeline --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -### Ruleset Parameters - -| Name | Description | Environment Variables | -| ---------------- | --------------------------------------------- | -------------------------------------- | -| `branch` | the build branch for the pipeline | `VELA_BRANCH`, `PIPELINE_BRANCH` | -| `comment` | the build comment for the pipeline | `VELA_COMMENT`, `PIPELINE_COMMENT` | -| `event` | the build event for the pipeline | `VELA_EVENT`, `PIPELINE_EVENT` | -| `tag` | the build tag for the pipeline | `VELA_TAG`, `PIPELINE_TAG` | -| `target` | the build target for the pipeline | `VELA_TARGET`, `PIPELINE_TARGET` | -| `file-changeset` | the build file changeset for the pipeline | `VELA_FILE_CHANGESET`, `FILE_CHANGESET`| - -### Repo Settings Parameters - -| Name | Description | Environment Variables | -| --------------- | --------------------------------------------- | -------------------------------------- | -| `org` | provide the organization for the pipeline | `VELA_ORG`, `PIPELINE_ORG` | -| `repo` | provide the repository for the pipeline | `VELA_REPO`, `PIPELINE_REPO` | -| `pipeline-type` | provide the repository pipeline type | `VELA_PIPELINE_TYPE`, `PIPELINE_TYPE` | - -### Template Parameters - -| Name | Description | Environment Variables | -| ----------------------- | ------------------------------------------------ | ----------------------------------------------------- | -| `compiler.github.token` | PAT for accessing GitHub sourced templates | `VELA_COMPILER_GITHUB_TOKEN`, `COMPILER_GITHUB_TOKEN` | -| `compiler.github.url` | URL for accessing GitHub sourced templates | `VELA_COMPILER_GITHUB_URL`, `COMPILER_GITHUB_URL` | -| `template-file` | list of local templates in form of \:\ | `VELA_TEMPLATE_FILE`, `PIPELINE_TEMPLATE_FILE` | -| `max-template-depth` | maximum depth for requesting nested templates | `VELA_MAX_TEMPLATE_DEPTH`, `MAX_TEMPLATE_DEPTH` | - -### Environment Parameters - -| Name | Description | Environment Variables | -| --------------- | ------------------------------------------------------------------------- | ------------------------------------- | -| `env-file` | Bool value for whether or not to source from an env file (default `.env`) | `VELA_ENV_FILE`, `ENV_FILE` | -| `env-file-path` | Path to override default `.env` sourcing of environment | `VELA_ENV_FILE_PATH`, `ENV_FILE_PATH` | -| `local-env` | Bool value for whether or not to onboard your local environment | `ONBOARD_LOCAL_ENV`, `LOCAL_ENV` | -| `env-vars` | list of environment variables to include in form of \=\ | `VELA_ENV_VARS` | - -### Other Parameters - -| Name | Description | Environment Variables | -| -------- | --------------------------------------------- | --------------------------------- | -| `output` | format the output in json, spew or yaml | `VELA_OUTPUT`, `PIPELINE_OUTPUT` | -| `file` | name of the file for the pipeline | `VELA_FILE`, `PIPELINE_FILE` | -| `path` | path to the file for the pipeline | `VELA_PATH`, `PIPELINE_PATH` | -| `local` | enables mounting local directory to pipeline | `VELA_LOCAL`, `PIPELINE_LOCAL` | -| `volume` | provide list of local volumes to mount | `VELA_VOLUMES`, `PIPELINE_VOLUMES`| - -## Environment - -Unless the `local-env` flag is supplied, the `vela exec pipeline` command will execute without any set environment. Instead, users are encouraged to supply their own environment variables in the form of an env file (e.g. `--env-file` OR `--env-file-path custom.env`). - -Many plugins, Starlark/Go templates, and other build resources depend on Vela-injected environment variables, such as `VELA_BUILD_COMMIT`. These variables will have to be supplied by the user, as there is no way for the compiler to determine these values locally. - -## Secrets - -The Vela Exec command does not have access to any secret you have stored in Vela or any other attached secret store. - -Environment variables can be set for the command by using the `env-vars` flag, ie `vela exec pipeline --env-vars MY_SECRET=foo`. They can also be set with the `env-file` or `local-env` flags. - -For example, if a pipeline is using the [kaniko plugin](https://go-vela.github.io/docs/plugins/registry/pipeline/kaniko/), it may require the secret `kaniko_password`, which can be provided with `vela exec pipeline --env-vars KANIKO_PASSWORD=mypass`. - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -vela exec pipeline -``` - -#### Response - -```sh -[step: init] > Inspecting runtime network... -[step: init] $ docker network inspect localOrg_localRepo_1 -{ - "Name": "localOrg_localRepo_1", - "Id": "cf204e6081cd4c10e3a285e7545790152afca05991c2dc67534f496844c1d274", - "Created": "2021-06-01T19:37:35.4772628Z", - "Scope": "local", - "Driver": "bridge", - "EnableIPv6": false, - "IPAM": { - "Driver": "default", - "Options": null, - "Config": [ - { - "Subnet": "192.168.0.0/20", - "Gateway": "192.168.0.1" - } - ] - }, - "Internal": false, - "Attachable": false, - "Ingress": false, - "ConfigFrom": { - "Network": "" - }, - "ConfigOnly": false, - "Containers": {}, - "Options": {}, - "Labels": {} -} - -[step: init] > Inspecting runtime volume... -[step: init] $ docker volume inspect localOrg_localRepo_1 -{ - "CreatedAt": "2021-06-01T19:37:35Z", - "Driver": "local", - "Labels": null, - "Mountpoint": "/var/lib/docker/volumes/localOrg_localRepo_1/_data", - "Name": "localOrg_localRepo_1", - "Options": null, - "Scope": "local" -} - -[step: init] > Pulling service images... -[step: init] > Pulling stage images... -[step: init] > Pulling step images... -[step: init] $ docker image inspect alpine:latest -sha256:6dbb9cc54074106d46d4ccb330f2a40a682d49dda5f4844962b7dce9fe44aaec - - -[step: hello Vela] $ echo "hello Vela!" -[step: hello Vela] hello Vela! -``` - -## Complex Samples - -Below are several examples using the following Vela pipeline + template - -### .vela.yml -```yaml -version: "1" - -templates: - - name: tmpl - source: git.example.com/cloud/vela-templates/kaniko.yml@main - type: github - -steps: - - name: testing - image: alpine:latest - commands: - - echo hello - - - name: file path ruleset - image: alpine:latest - ruleset: - matcher: regexp - path: [ src/* ] - commands: - - echo ran - - - name: docker build - template: - name: tmpl - vars: - repo: docker.example.com/octocat/hello-world -``` - -### kaniko.yml Template -```yaml -version: "1" - -metadata: - template: true - -environment: - REPO: {{ .repo }} - -secrets: - - name: docker_username - key: octocat/docker_username - engine: native - type: org - - - name: docker_password - key: octocat/docker_password - engine: native - type: org - -steps: - - name: Build and Publish - image: target/vela-kaniko:latest - secrets: [ docker_username, docker_password ] - parameters: - registry: docker.example.com - repo: ${REPO} -``` - -### Remote Template + Local Environment Onboarding - -```sh -$ DOCKER_USERNAME=octocat DOCKER_PASSWORD=abc123 VELA_BUILD_COMMIT=1a2b3c vela exec pipeline --ct --cgu https://git.example.com --local-env -``` - -Note: `--local-env` onboards the entire bash environment. To load specific environment variables, use `--env-vars`: - -```sh -$ vela exec pipeline --ct --cgu https://git.example.com --env-vars DOCKER_USERNAME=octocat,DOCKER_PASSWORD=abc123,VELA_BUILD_COMMIT=1a2b3c -``` - -### Template Override - -```sh -$ vela exec pipeline --template-file tmpl:path/to/template.yml --env-vars DOCKER_USERNAME=octocat,DOCKER_PASSWORD=abc123,VELA_BUILD_COMMIT=1a2b3c -``` - -### Environment File - -`.env` -``` -DOCKER_USERNAME=octocat -DOCKER_PASSWORD=abc123 -VELA_BUILD_COMMIT=1a2b3c -``` - -```sh -$ vela exec pipeline --ct --cgu https://git.example.com --env-file -``` - -`vela_exec.env` -``` -DOCKER_USERNAME=octocat -DOCKER_PASSWORD=abc123 -VELA_BUILD_COMMIT=1a2b3c -``` - -```sh -$ vela exec pipeline --ct --cgu https://git.example.com --env-file-path vela_exec.env -``` - -### Path Ruleset Inclusion - -In order to execute steps with rulesets, be sure to include all necessary flags that match the rules - -```sh -$ vela exec pipeline --ct --cgu https://git.example.com --env-file --file-changeset src/main.go -``` - -Other rules: `--branch`, `--event`, `--comment`, `--tag`, `--target` - diff --git a/versioned_docs/version-0.26/reference/cli/pipeline/generate.md b/versioned_docs/version-0.26/reference/cli/pipeline/generate.md deleted file mode 100644 index c161760..0000000 --- a/versioned_docs/version-0.26/reference/cli/pipeline/generate.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: "Generate" -linkTitle: "Generate" -description: > - Learn how to produce a pipeline. ---- - -## Command - -``` -$ vela generate pipeline -``` - -:::tip -For more information, you can run `vela generate pipeline --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| -------- | ---------------------------------- | -------------------------------- | -| `file` | name of the file for the pipeline | `VELA_FILE`, `PIPELINE_FILE` | -| `path` | path to the file for the pipeline | `VELA_PATH`, `PIPELINE_PATH` | -| `stages` | generates the pipeline with stages | `VELA_STAGES`, `PIPELINE_STAGES` | -| `type` | type of pipeline being generated | `VELA_TYPE`, `PIPELINE_TYPE` | - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -vela generate pipeline -``` - -#### Response - -```sh -".vela.yml" go pipeline generated -``` diff --git a/versioned_docs/version-0.26/reference/cli/pipeline/get.md b/versioned_docs/version-0.26/reference/cli/pipeline/get.md deleted file mode 100644 index b39ea3e..0000000 --- a/versioned_docs/version-0.26/reference/cli/pipeline/get.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to list pipelines. ---- - -## Command - -``` -$ vela get pipeline -``` - -:::tip -For more information, you can run `vela get pipeline --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| ---------- |----------------------------------------| -------------------------------- | -| `org` | name of organization for the pipelines | `VELA_ORG`, `HOOK_ORG` | -| `repo` | name of repository for the pipelines | `VELA_REPO`, `HOOK_REPO` | -| `output` | format the output for the pipelines | `VELA_OUTPUT`, `HOOK_OUTPUT` | -| `page` | prints a specific page of pipelines | `VELA_PAGE`, `HOOK_PAGE` | -| `per.page` | number of pipelines to print per page | `VELA_PER_PAGE`, `HOOK_PER_PAGE` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela get pipeline -``` - -#### Targeted Request - -```sh -$ vela get pipeline --org github --repo octocat -``` - -#### Response - -```sh -COMMIT REF TYPE VERSION STAGES STEPS -a49aaf4afae6431a79239c95247a2b169fd9f067 refs/heads/main yaml 1 f t -48afb5bdc41ad69bf22588491333f7cf71135163 refs/heads/main yaml 1 f t -``` diff --git a/versioned_docs/version-0.26/reference/cli/pipeline/pipeline.md b/versioned_docs/version-0.26/reference/cli/pipeline/pipeline.md deleted file mode 100644 index 078b08b..0000000 --- a/versioned_docs/version-0.26/reference/cli/pipeline/pipeline.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Pipeline" -linkTitle: "Pipeline" -description: > - Learn how to use CLI commands for the pipeline resource. ---- - -The below commands are available to operate on the `pipeline` resource. - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/cli/pipeline/validate.md b/versioned_docs/version-0.26/reference/cli/pipeline/validate.md deleted file mode 100644 index 55166aa..0000000 --- a/versioned_docs/version-0.26/reference/cli/pipeline/validate.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: "Validate" -linkTitle: "Validate" -description: > - Learn how to validate a Vela pipeline. ---- - -## Command - -``` -$ vela validate pipeline -``` - -:::tip -For more information, please run `vela validate pipeline --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| ------------------------------ | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | -| `org` | name of organization for the builds | `VELA_ORG`, `BUILD_ORG` | -| `pipeline-type` | provide the repository pipeline type | `VELA_PIPELINE_TYPE`, `PIPELINE_TYPE` | -| `repo` | name of repository for the builds | `VELA_REPO`, `BUILD_REPO` | -| `compiler-starlark-exec-limit` | set the starlark execution step limit for compiling starlark pipelines (default 7500) | `VELA_COMPILER_STARLARK_EXEC_LIMIT`, `COMPILER_STARLARK_EXEC_LIMIT` | -| `file` | name of the file for the pipeline | `VELA_FILE`, `PIPELINE_FILE` | -| `max-template-depth` | set the maximum depth for nested templates (default: 3) | `VELA_MAX_TEMPLATE_DEPTH`, `MAX_TEMPLATE_DEPTH` | -| `path` | path to the file for the pipeline | `VELA_PATH`, `PIPELINE_PATH` | -| `ref` | repository reference for the pipeline | `VELA_REF`, `PIPELINE_REF` | -| `remote` | enables validating a pipeline on a remote server | `VELA_REMOTE`, `PIPELINE_REMOTE` | -| `template` | enables templates to be included in pipeline validation | `VELA_TEMPLATE`, `PIPELINE_TEMPLATE` | -| `template-file` | enables using a local template file for expansion | `VELA_TEMPLATE_FILE`, `PIPELINE_TEMPLATE_FILE` | -| `branch` | provide the build branch for the pipeline | `VELA_BRANCH`, `PIPELINE_BRANCH`, `VELA_BUILD_BRANCH` | -| `comment` | provide the build comment for the pipeline | `VELA_COMMENT`, `PIPELINE_COMMENT`, `VELA_BUILD_COMMENT` | -| `event` | provide the build event for the pipeline | `VELA_EVENT`, `PIPELINE_EVENT`, `VELA_BUILD_EVENT` | -| `file-changeset` | provide a list of files changed for ruleset matching | `VELA_FILE_CHANGESET`, `FILE_CHANGESET` | -| `status` | provide the expected build status for the local validation (default: "success") | `VELA_STATUS`, `PIPELINE_STATUS`, `VELA_BUILD_STATUS` | -| `tag` | provide the build tag for the pipeline | `VELA_TAG`, `PIPELINE_TAG`, `VELA_BUILD_TAG` | -| `target` | provide the build target for the pipeline | `VELA_TARGET`, `PIPELINE_TARGET`, `VELA_BUILD_TARGET` | -| `clone-image` | the clone image to use for the injected clone step | `VELA_CLONE_IMAGE`, `COMPILER_CLONE_IMAGE` | -| `compiler.github.token` | github compiler token | `VELA_COMPILER_GITHUB_TOKEN`, `COMPILER_GITHUB_TOKEN` | -| `compiler.github.url` | github url, used by compiler, for pulling registry templates | `VELA_COMPILER_GITHUB_URL`, `COMPILER_GITHUB_URL` | - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Simple Request - -```sh -vela validate pipeline -``` - -#### Expanded Template Request (GitHub) - -```sh -vela validate pipeline --template --compiler.github.token --compiler.github.url https://git.example.com -``` - -#### Expanded Template Request (Local) - -```sh -vela validate pipeline --template --template-file name:/path/to/file -``` - -#### Response - -```sh -".vela.yml" is valid -``` - -Using a template in your pipeline? You can [validate templates also](/usage/templates/#cli-pipeline-validation). diff --git a/versioned_docs/version-0.26/reference/cli/repo/add.md b/versioned_docs/version-0.26/reference/cli/repo/add.md deleted file mode 100644 index d86a05a..0000000 --- a/versioned_docs/version-0.26/reference/cli/repo/add.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: "Add" -linkTitle: "Add" -description: > - Learn how to create a repo. ---- - -## Command - -``` -$ vela add repo -``` - -:::tip -For more information, you can run `vela add repo --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| --------------- | -------------------------------------------------- | -------------------------------------- | -| `org` | name of organization for the repository | `VELA_ORG`, `REPO_ORG` | -| `repo` | name of repository | `VELA_REPO`, `REPO_NAME` | -| `branch` | default branch for the repository | `VELA_BRANCH`, `REPO_BRANCH` | -| `link` | full URL for the repository | `VELA_LINK`, `REPO_LINK` | -| `clone` | clone URL for the repository | `VELA_CLONE`, `REPO_CLONE` | -| `visibility` | access level required to view the repository | `VELA_VISIBILITY`, `REPO_VISIBILITY` | -| `build.limit` | limit of concurrent builds allowed for repository | `VELA_BUILD_LIMIT`, `REPO_BUILD_LIMIT` | -| `timeout` | max time allowed per build | `VELA_TIMEOUT`, `REPO_TIMEOUT` | -| `counter` | set a value for a new build number | `VELA_COUNTER`, `REPO_COUNTER` | -| `private` | disables public access to the repository | `VELA_PRIVATE`, `REPO_PRIVATE` | -| `trusted` | elevates permissions for builds for the repository | `VELA_TRUSTED`, `REPO_TRUSTED` | -| `active` | enables/disables the repository | `VELA_ACTIVE`, `REPO_ACTIVE` | -| `event` | events to trigger builds for the repository | `VELA_EVENTS`, `REPO_EVENTS` | -| `pipeline-type` | type of base pipeline for the compiler to render | `VELA_PIPELINE_TYPE`, `PIPELINE_TYPE` | -| `output` | format the output for the repository | `VELA_OUTPUT`, `REPO_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela add repo -``` - -#### Targeted Request - -```sh -$ vela add repo --org github --repo octocat -``` - -#### Response - -```sh -id: 1 -userid: 1 -org: github -name: octocat -fullname: github/octocat -link: https://github.com/github/octocat -clone: https://github.com/github/octocat.git -branch: main -buildlimit: 10 -timeout: 60 -timeout: 0 -visibility: public -private: false -trusted: false -active: true -allowpull: true -allowpush: true -allowdeploy: false -allowtag: false -allowcomment: false -allowevents: [push pull_request:opened pull_request:synchronize ] -pipelinetype: yaml -``` diff --git a/versioned_docs/version-0.26/reference/cli/repo/chown.md b/versioned_docs/version-0.26/reference/cli/repo/chown.md deleted file mode 100644 index 416fec7..0000000 --- a/versioned_docs/version-0.26/reference/cli/repo/chown.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: "Chown" -linkTitle: "Chown" -description: > - Learn how to change ownership of a repo. ---- - -## Command - -``` -$ vela chown repo -``` - -:::tip -For more information, you can run `vela chown repo --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| -------- | --------------------------------------- | ---------------------------- | -| `org` | name of organization for the repository | `VELA_ORG`, `REPO_ORG` | -| `repo` | name of repository | `VELA_REPO`, `REPO_NAME` | -| `output` | format the output for the repository | `VELA_OUTPUT`, `REPO_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela chown repo -``` - -#### Targeted Request - -```sh -$ pwd -~/github/octocat -$ vela chown repo --org github --repo octocat -``` - -#### Response - -```sh -repo "github/octocat" changed owner -``` diff --git a/versioned_docs/version-0.26/reference/cli/repo/get.md b/versioned_docs/version-0.26/reference/cli/repo/get.md deleted file mode 100644 index cf110aa..0000000 --- a/versioned_docs/version-0.26/reference/cli/repo/get.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to list repos. ---- - -## Command - -``` -$ vela get repo -``` - -:::tip -For more information, you can run `vela get repo --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| ---------- | ----------------------------------------- | -------------------------------- | -| `org` | name of organization for the repository | `VELA_ORG`, `REPO_ORG` | -| `repo` | name of repository | `VELA_REPO`, `REPO_NAME` | -| `output` | format the output for the repository | `VELA_OUTPUT`, `REPO_OUTPUT` | -| `page` | prints a specific page of repositories | `VELA_PAGE`, `REPO_PAGE` | -| `per.page` | number of repositories to print per page | `VELA_PER_PAGE`, `REPO_PER_PAGE` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -vela get repos -``` - -#### Response - -```sh -ORG/REPO STATUS EVENTS VISIBILITY BRANCH -github/octocat true push,pull_request public main -``` diff --git a/versioned_docs/version-0.26/reference/cli/repo/remove.md b/versioned_docs/version-0.26/reference/cli/repo/remove.md deleted file mode 100644 index 8640c3e..0000000 --- a/versioned_docs/version-0.26/reference/cli/repo/remove.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: "Remove" -linkTitle: "Remove" -description: > - Learn how to delete a repo. ---- - -## Command - -``` -$ vela remove repo -``` - -:::tip -For more information, you can run `vela remove repo --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| -------- | --------------------------------------- | ---------------------------- | -| `org` | name of organization for the repository | `VELA_ORG`, `REPO_ORG` | -| `repo` | name of repository | `VELA_REPO`, `REPO_NAME` | -| `output` | format the output for the repository | `VELA_OUTPUT`, `REPO_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela remove repo -``` - -#### Targeted Request - -```sh -$ pwd -~/github/octocat -$ vela remove repo --org github --repo octocat -``` - -#### Response - -```sh -repo "github/octocat" was deleted -``` diff --git a/versioned_docs/version-0.26/reference/cli/repo/repair.md b/versioned_docs/version-0.26/reference/cli/repo/repair.md deleted file mode 100644 index 06fa7f1..0000000 --- a/versioned_docs/version-0.26/reference/cli/repo/repair.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: "Repair" -linkTitle: "Repair" -description: > - Learn how to restore a repo. ---- - -## Command - -``` -$ vela repair repo -``` - -:::tip -For more information, you can run `vela repair repo --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| -------- | --------------------------------------- | ---------------------------- | -| `org` | name of organization for the repository | `VELA_ORG`, `REPO_ORG` | -| `repo` | name of repository | `VELA_REPO`, `REPO_NAME` | -| `output` | format the output for the repository | `VELA_OUTPUT`, `REPO_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela repair repo -``` - -#### Targeted Request - -```sh -$ vela repair repo --org github --repo octocat -``` - -#### Response - -```sh -repo "github/octocat" repaired -``` diff --git a/versioned_docs/version-0.26/reference/cli/repo/repo.md b/versioned_docs/version-0.26/reference/cli/repo/repo.md deleted file mode 100644 index 00b9248..0000000 --- a/versioned_docs/version-0.26/reference/cli/repo/repo.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Repo" -linkTitle: "Repo" -description: > - Learn how to use CLI commands for the repo resource. ---- - -The below commands are available to operate on the `repo` resource. - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/cli/repo/sync.md b/versioned_docs/version-0.26/reference/cli/repo/sync.md deleted file mode 100644 index b2b72fa..0000000 --- a/versioned_docs/version-0.26/reference/cli/repo/sync.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: "Sync" -linkTitle: "Sync" -description: > - Learn how to sync repos in database with GitHub. ---- - -## Command - -``` -$ vela sync repo -``` - -:::tip -For more information, you can run `vela sync repo --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| -------- | --------------------------------------- | ---------------------------- | -| `org` | name of organization for the repository | `VELA_ORG`, `REPO_ORG` | -| `repo` | name of repository | `VELA_REPO`, `REPO_NAME` | -| `all` | bool flag to sync all repos in an org | `VELA_SYNC_ALL`, `SYNC_ALL` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Description - -The sync command allows users to re-align their repository in Vela with its SCM mirror. This discrepancy can come in the form of a repository that has been deleted from the SCM but not in Vela. - -Further, as of `v0.19.0`, the sync command can be used to adjust events that are sent to Vela from the SCM that the Vela-instance of the repo is not subscribed to. For example, if your audit page has errors like - -```sh -"unable to process webhook: / does not have comment events enabled" -``` - -running the sync command should re-configure the SCM webhook to only send events that are allowed. Once aligned, you should not have to run this command again, even if the subscribed events are changed. - -## Samples - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela sync repo -``` - -#### Targeted Request - -```sh -$ vela sync repo --org github --repo octocat -``` - -#### Response - -```sh -repo "github/octocat" synced -``` - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela sync repo --all -``` - -#### Targeted Request - -```sh -$ vela sync repo --org github --all -``` - -#### Response - -```sh -org "github" synced \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/cli/repo/update.md b/versioned_docs/version-0.26/reference/cli/repo/update.md deleted file mode 100644 index 6882231..0000000 --- a/versioned_docs/version-0.26/reference/cli/repo/update.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: "Update" -linkTitle: "Update" -description: > - Learn how to modify a repo. ---- - -## Command - -``` -$ vela update repo -``` - -:::tip -For more information, you can run `vela update repo --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| --------------- | -------------------------------------------------- | -------------------------------------- | -| `org` | name of organization for the repository | `VELA_ORG`, `REPO_ORG` | -| `repo` | name of repository | `VELA_REPO`, `REPO_NAME` | -| `branch` | default branch for the repository | `VELA_BRANCH`, `REPO_BRANCH` | -| `link` | full URL for the repository | `VELA_LINK`, `REPO_LINK` | -| `clone` | clone URL for the repository | `VELA_CLONE`, `REPO_CLONE` | -| `visibility` | access level required to view the repository | `VELA_VISIBILITY`, `REPO_VISIBILITY` | -| `build.limit` | limit of concurrent builds allowed for repository | `VELA_BUILD_LIMIT`, `REPO_BUILD_LIMIT` | -| `timeout` | max time allowed per build | `VELA_TIMEOUT`, `REPO_TIMEOUT` | -| `counter` | set a value for a new build number | `VELA_COUNTER`, `REPO_COUNTER` | -| `private` | disables public access to the repository | `VELA_PRIVATE`, `REPO_PRIVATE` | -| `trusted` | elevates permissions for builds for the repository | `VELA_TRUSTED`, `REPO_TRUSTED` | -| `active` | enables/disables the repository | `VELA_ACTIVE`, `REPO_ACTIVE` | -| `event` | events to trigger builds for the repository | `VELA_EVENTS`, `REPO_EVENTS` | -| `pipeline-type` | type of base pipeline for the compiler to render | `VELA_PIPELINE_TYPE`, `PIPELINE_TYPE` | -| `output` | format the output for the repository | `VELA_OUTPUT`, `REPO_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -:::warning -As of Vela `v0.23.0`, the `event` flag is an overwrite/clobber operation. - -```sh -$ vela update repo --org github --repo octocat --event tag -``` - -The above will set the allowed events to only `tag`. Be sure to specify _all_ events when updating a repo via the CLI. -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela update repo --event tag -``` - -#### Targeted Request - -```sh -$ vela update repo --org github --repo octocat --event tag -``` - -#### Response - -```sh -id: 1 -userid: 1 -org: github -name: octocat -fullname: github/octocat -link: https://github.com/github/octocat -clone: https://github.com/github/octocat.git -branch: main -buildlimit: 10 -timeout: 60 -counter: 0 -visibility: public -private: false -trusted: false -active: true -allowpull: true -allowpush: true -allowdeploy: false -allowtag: true -allowcomment: false -allowevents: [tag] -pipelinetype: yaml -``` diff --git a/versioned_docs/version-0.26/reference/cli/repo/view.md b/versioned_docs/version-0.26/reference/cli/repo/view.md deleted file mode 100644 index 71458d6..0000000 --- a/versioned_docs/version-0.26/reference/cli/repo/view.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect a repo. ---- - -## Command - -``` -$ vela view repo -``` - -:::tip -For more information, you can run `vela view repo --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| -------- | --------------------------------------- | ---------------------------- | -| `org` | name of organization for the repository | `VELA_ORG`, `REPO_ORG` | -| `repo` | name of repository | `VELA_REPO`, `REPO_NAME` | -| `output` | format the output for the repository | `VELA_OUTPUT`, `REPO_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela view repo -``` - -#### Targeted Request - -```sh -$ vela view repo --org github --repo octocat -``` - -#### Response - -```sh -id: 1 -userid: 1 -org: github -name: octocat -fullname: github/octocat -link: https://github.com/github/octocat -clone: https://github.com/github/octocat.git -branch: main -buildlimit: 10 -timeout: 60 -counter: 0 -visibility: public -private: false -trusted: false -active: true -allowpull: true -allowpush: true -allowdeploy: false -allowtag: false -allowcomment: false -pipelinetype: yaml -``` diff --git a/versioned_docs/version-0.26/reference/cli/schedule/add.md b/versioned_docs/version-0.26/reference/cli/schedule/add.md deleted file mode 100644 index 720a88f..0000000 --- a/versioned_docs/version-0.26/reference/cli/schedule/add.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -title: "Add" -linkTitle: "Add" -description: > - Learn how to create a schedule. ---- - -## Command - -``` -$ vela add schedule -``` - -:::tip -For more information, you can run `vela add schedule --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -|------------|---------------------------------------|----------------------------------| -| `org` | name of organization for the schedule | `VELA_ORG`, `SCHEDULE_ORG` | -| `repo` | name of repository for the schedule | `VELA_REPO`, `SCHEDULE_REPO` | -| `schedule` | name of the schedule | `VELA_SCHEDULE`, `SCHEDULE_NAME` | -| `entry` | frequency for the schedule | `VELA_ENTRY`, `SCHEDULE_ENTRY` | -| `active` | enables/disables the schedule | `VELA_ACTIVE`, `SCHEDULE_ACTIVE` | -| `output` | format the output for the schedule | `VELA_OUTPUT`, `SCHEDULE_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela add schedule --schedule hourly --entry '0 * * * *' -``` - -#### Targeted Request - -```sh -$ vela add schedule --org github --repo octocat --schedule hourly --entry '0 * * * *' --output json -``` - -#### Response -```sh -{ - "id": 1, - "repo": { - "id": 1, - "owner": { - "id": 1, - "name": "octokitty", - "active": true - }, - "org": "github", - "name": "octokitty", - "full_name": "github/octokitty", - "link": "https://github.com/github/octokitty", - "clone": "https://github.com/github/octokitty.git", - "branch": "main", - "topics": [], - "build_limit": 10, - "timeout": 30, - "counter": 0, - "visibility": "public", - "private": false, - "trusted": false, - "active": true, - "allow_events": { - "push": { - "branch": true, - "tag": false, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": false - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "pipeline_type": "yaml", - "previous_name": "", - "approve_build": "fork-always" - }, - "active": true, - "name": "hourly", - "entry": "0 * * * *", - "created_at": 1716495910, - "created_by": "octokitty", - "updated_at": 1716495910, - "updated_by": "octokitty", - "scheduled_at": 0, - "branch": "main", - "error": "", - "next_run": 1716499800 -} -``` - -## Examples - -```sh -EXAMPLES: - 1. Add a schedule to a repository with active not enabled. - $ vela add schedule --org MyOrg --repo MyRepo --schedule hourly --entry '0 * * * *' --active false - 2. Add a schedule to a repository with a nightly entry. - $ vela add schedule --org MyOrg --repo MyRepo --schedule nightly --entry '0 0 * * *' - 3. Add a schedule to a repository with a weekly entry. - $ vela add schedule --org MyOrg --repo MyRepo --schedule weekly --entry '@weekly' - 4. Add a schedule to a repository when config or environment variables are set. - $ vela add schedule -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/cli/schedule/get.md b/versioned_docs/version-0.26/reference/cli/schedule/get.md deleted file mode 100644 index cf2803a..0000000 --- a/versioned_docs/version-0.26/reference/cli/schedule/get.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to list schedules. ---- - -## Command - -``` -$ vela get schedule -``` - -:::tip -For more information, you can run `vela get schedule --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -|------------|----------------------------------------|--------------------------------------| -| `org` | name of organization for the schedules | `VELA_ORG`, `SCHEDULE_ORG` | -| `repo` | name of repository for the schedules | `VELA_REPO`, `SCHEDULE_REPO` | -| `output` | format the output for the schedules | `VELA_OUTPUT`, `SCHEDULE_OUTPUT` | -| `page` | prints a specific page of schedules | `VELA_PAGE`, `SCHEDULE_PAGE` | -| `per.page` | number of schedules to print per page | `VELA_PER_PAGE`, `SCHEDULE_PER_PAGE` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela get schedule -``` - -#### Targeted Request - -```sh -$ vela get schedule --org github --repo octocat -``` - -#### Response -```sh -NAME ENTRY ACTIVE SCHEDULED_AT BRANCH -nightly 0 0 * * * true a long while ago main -hourly 0 * * * * true a long while ago main -``` - -## Examples - -```sh -EXAMPLES: - 1. Get a list of schedules for a repository. - $ vela get schedule --org MyOrg --repo MyRepo - 2. Get a list of schedules for a repository with wide view output. - $ vela get schedule --org MyOrg --repo MyRepo --output wide - 3. Get a list of schedules for a repository with yaml output. - $ vela get schedule --org MyOrg --repo MyRepo --output yaml - 4. Get a list of schedules for a repository with json output. - $ vela get schedule --org MyOrg --repo MyRepo --output json - 5. Get a list of schedules for a repository when config or environment variables are set. - $ vela get schedule -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/cli/schedule/remove.md b/versioned_docs/version-0.26/reference/cli/schedule/remove.md deleted file mode 100644 index c7a3e85..0000000 --- a/versioned_docs/version-0.26/reference/cli/schedule/remove.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: "Remove" -linkTitle: "Remove" -description: > - Learn how to delete a schedule. ---- - -## Command - -``` -$ vela remove schedule -``` - -:::tip -For more information, you can run `vela remove schedule --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -|------------|---------------------------------------|----------------------------------| -| `org` | name of organization for the schedule | `VELA_ORG`, `SCHEDULE_ORG` | -| `repo` | name of repository for the schedule | `VELA_REPO`, `SCHEDULE_REPO` | -| `schedule` | name of the schedule | `VELA_SCHEDULE`, `SCHEDULE_NAME` | -| `output` | format the output for the schedule | `VELA_OUTPUT`, `SCHEDULE_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela remove schedule --schedule hourly -``` - -#### Targeted Request - -```sh -$ pwd -~/github/octocat -$ vela remove schedule --org github --repo octocat --schedule hourly -``` - -#### Response - -```sh -schedule hourly deleted -``` - -## Examples - -```sh -EXAMPLES: - 1. Remove a schedule from a repository. - $ vela remove schedule --org MyOrg --repo MyRepo --schedule daily - 2. Remove a schedule from a repository with json output. - $ vela remove schedule --org MyOrg --repo MyRepo --schedule daily --output json - 3. Remove a schedule from a repository when config or environment variables are set. - $ vela remove schedule -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/cli/schedule/schedule.md b/versioned_docs/version-0.26/reference/cli/schedule/schedule.md deleted file mode 100644 index ef626b2..0000000 --- a/versioned_docs/version-0.26/reference/cli/schedule/schedule.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Schedule" -linkTitle: "Schedule" -description: > - Learn how to use CLI commands for the schedule resource. ---- - -The below commands are available to operate on the `schedule` resource. - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/cli/schedule/update.md b/versioned_docs/version-0.26/reference/cli/schedule/update.md deleted file mode 100644 index abdf38a..0000000 --- a/versioned_docs/version-0.26/reference/cli/schedule/update.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -title: "Update" -linkTitle: "Update" -description: > - Learn how to modify a schedule. ---- - -## Command - -``` -$ vela update schedule -``` - -:::tip -For more information, you can run `vela update schedule --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -|------------|---------------------------------------|----------------------------------| -| `org` | name of organization for the schedule | `VELA_ORG`, `SCHEDULE_ORG` | -| `repo` | name of repository for the schedule | `VELA_REPO`, `SCHEDULE_REPO` | -| `schedule` | name of the schedule | `VELA_SCHEDULE`, `SCHEDULE_NAME` | -| `entry` | frequency for the schedule | `VELA_ENTRY`, `SCHEDULE_ENTRY` | -| `active` | enables/disables the schedule | `VELA_ACTIVE`, `SCHEDULE_ACTIVE` | -| `output` | format the output for the schedule | `VELA_OUTPUT`, `SCHEDULE_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela update schedule --name hourly --active false -``` - -#### Targeted Request - -```sh -$ vela update schedule --org github --repo octocat --name hourly --active false --output json -``` - -#### Response - -```sh -{ - "id": 1, - "repo": { - "id": 1, - "owner": { - "id": 1, - "name": "octokitty", - "active": true - }, - "org": "github", - "name": "octokitty", - "full_name": "github/octokitty", - "link": "https://github.com/github/octokitty", - "clone": "https://github.com/github/octokitty.git", - "branch": "main", - "topics": [], - "build_limit": 10, - "timeout": 30, - "counter": 0, - "visibility": "public", - "private": false, - "trusted": false, - "active": true, - "allow_events": { - "push": { - "branch": true, - "tag": false, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": false - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "pipeline_type": "yaml", - "previous_name": "", - "approve_build": "fork-always" - }, - "active": false, - "name": "hourly", - "entry": "0 * * * *", - "created_at": 1716495910, - "created_by": "octokitty", - "updated_at": 1716495910, - "updated_by": "octokitty", - "scheduled_at": 0, - "branch": "main", - "error": "", - "next_run": 1716499800 -} -``` - -## Examples - -```sh -EXAMPLES: - 1. Update a schedule for a repository with active disabled. - $ vela update schedule --org MyOrg --repo MyRepo --schedule hourly --active false - 2. Update a schedule for a repository with a new entry. - $ vela update schedule --org MyOrg --repo MyRepo --schedule nightly --entry '@nightly' - 3. Update a schedule for a repository when config or environment variables are set. - $ vela update schedule -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/cli/schedule/view.md b/versioned_docs/version-0.26/reference/cli/schedule/view.md deleted file mode 100644 index 0540546..0000000 --- a/versioned_docs/version-0.26/reference/cli/schedule/view.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect a schedule. ---- - -## Command - -``` -$ vela view schedule -``` - -:::tip -For more information, you can run `vela view schedule --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -|------------|---------------------------------------|----------------------------------| -| `org` | name of organization for the schedule | `VELA_ORG`, `SCHEDULE_ORG` | -| `repo` | name of repository for the schedule | `VELA_REPO`, `SCHEDULE_REPO` | -| `schedule` | name of the schedule | `VELA_SCHEDULE`, `SCHEDULE_NAME` | -| `output` | format the output for the schedule | `VELA_OUTPUT`, `SCHEDULE_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela view schedule --schedule hourly -``` - -#### Targeted Request - -```sh -$ vela view schedule --org github --repo octocat --schedule hourly --output json -``` - -#### Response -```sh -{ - "id": 1, - "repo": { - "id": 1, - "owner": { - "id": 1, - "name": "octokitty", - "active": true - }, - "org": "github", - "name": "octokitty", - "full_name": "github/octokitty", - "link": "https://github.com/github/octokitty", - "clone": "https://github.com/github/octokitty.git", - "branch": "main", - "topics": [], - "build_limit": 10, - "timeout": 30, - "counter": 0, - "visibility": "public", - "private": false, - "trusted": false, - "active": true, - "allow_events": { - "push": { - "branch": true, - "tag": false, - "delete_branch": false, - "delete_tag": false - }, - "pull_request": { - "opened": false, - "edited": false, - "synchronize": false, - "reopened": false, - "labeled": false, - "unlabeled": false - }, - "deployment": { - "created": false - }, - "comment": { - "created": false, - "edited": false - }, - "schedule": { - "run": false - } - }, - "pipeline_type": "yaml", - "previous_name": "", - "approve_build": "fork-always" - }, - "active": true, - "name": "hourly", - "entry": "0 * * * *", - "created_at": 1716495910, - "created_by": "octokitty", - "updated_at": 1716495910, - "updated_by": "octokitty", - "scheduled_at": 0, - "branch": "main", - "error": "", - "next_run": 1716499800 -} -``` - -## Examples - -```sh -EXAMPLES: - 1. View details of a schedule for a repository. - $ vela view schedule --org MyOrg --repo MyRepo --schedule hourly - 2. View details of a schedule for a repository with json output. - $ vela view schedule --org MyOrg --repo MyRepo --schedule hourly --output json - 3. View details of a schedule for a repository when config or environment variables are set. - $ vela view schedule -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/cli/secret/add.md b/versioned_docs/version-0.26/reference/cli/secret/add.md deleted file mode 100644 index 8a82c63..0000000 --- a/versioned_docs/version-0.26/reference/cli/secret/add.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: "Add" -linkTitle: "Add" -description: > - Learn how to create a secret. ---- - -## Command - -``` -$ vela add secret -``` - -:::tip -For more information, you can run `vela add secret --help`. -::: - -:::warning -Note on special characters: - -Certain characters may require you to encapsulate your secret with `"` or `'`. -`\` characters have to be double escaped to be `\\\`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| --------------- | ------------------------------------------------ | ----------------------------------------- | -| `org` | name of organization for the secret | `VELA_ORG`, `SECRET_ORG` | -| `repo` | name of repository for the secret | `VELA_REPO`, `SECRET_REPO` | -| `secret.engine` | name of engine that stores the secret | `VELA_ENGINE`. `SECRET_ENGINE` | -| `secret.type` | name of type of secret being stored | `VELA_TYPE`, `SECRET_TYPE` | -| `team` | name of team for the secret | `VELA_TEAM`, `SECRET_TEAM` | -| `name` | name of the secret | `VELA_NAME`, `SECRET_NAME` | -| `value` | value of the secret | `VELA_VALUE`, `SECRET_VALUE` | -| `image` | build image(s) that can access the secret | `VELA_IMAGES`, `SECRET_IMAGES` | -| `event` | build event(s) that can access the secret | `VELA_EVENTS`, `SECRET_EVENTS` | -| `commands` | allows a step with commands to access the secret | `VELA_COMMANDS`, `SECRET_COMMANDS` | -| `substitution` | allows substitution of secret using $\{KEY\} format | `VELA_SUBSTITUTION`, `SECRET_SUBSTITUTION` | -| `file` | name of file used to add the secret(s) | `VELA_FILE`, `SECRET_FILE` | -| `output` | format the output for the secret | `VELA_OUTPUT`, `SECRET_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `secret.engine` -- `secret.type` -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela add secret --secret.engine native --secret.type repo --name foo --value bar -``` - -#### Targeted Request - -```sh -$ vela add secret --secret.engine native --secret.type repo --org github --repo octocat --name foo --value bar -``` - -#### Response - -```sh -secret "foo" was added -``` - -## Advanced - -#### Input From File - -Vela supports creating a single-line or multi-line secret from a file using the `@` symbol. - -```sh -# Syntax -vela add secret --secret.engine native --secret.type repo --org github --repo octocat --name foo --value @/path/to/file - -# Example -vela add secret --secret.engine native --secret.type repo --org github --repo octocat --name foo --value @$HOME/tmp/secret.txt -``` - -#### Secrets From File - -Vela supports creating multiple secrets from a file using the `filename` parameter. - -```sh -vela add secret -f secret.yml -``` - -### Single YAML document - -```yaml ---- -metadata: - version: v1 - engine: native -secrets: - - org: octocat - repo: github - name: foo - value: bar - type: repo - images: - - golang:latest - events: - - push - - pull_request - - org: github - team: octokitties - name: foo1 - value: "@/path/to/file/bar1" - type: shared - images: - - golang:latest - events: - - push - - pull_request -``` - -### Multiple YAML document - -```yaml ---- -metadata: - version: v1 - engine: native -secrets: - - org: github - repo: octocat - name: foo - value: bar - type: repo - images: - - golang:latest - events: - - push - - pull_request - ---- -metadata: - version: v1 - engine: vault -secrets: - - org: github - team: octokitties - name: foo1 - value: "@/path/to/file/bar1" - type: shared - images: - - golang:latest - events: - - push - - pull_request -``` diff --git a/versioned_docs/version-0.26/reference/cli/secret/get.md b/versioned_docs/version-0.26/reference/cli/secret/get.md deleted file mode 100644 index 4980e4c..0000000 --- a/versioned_docs/version-0.26/reference/cli/secret/get.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to list secrets. ---- - -## Command - -``` -$ vela get secret -``` - -:::tip -For more information, you can run `vela get secret --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| --------------- | --------------------------------------------------- | ------------------------------ | -| `org` | name of organization for the secrets | `VELA_ORG`, `SECRET_ORG` | -| `repo` | name of repository for the secrets | `VELA_REPO`, `SECRET_REPO` | -| `secret.engine` | name of engine that stores the secrets | `VELA_ENGINE`. `SECRET_ENGINE` | -| `secret.type` | name of type of secrets being stored | `VELA_TYPE`, `SECRET_TYPE` | -| `team` | name of team for the secrets, or '\*' for all teams | `VELA_TEAM`, `SECRET_TEAM` | -| `output` | format the output for the secrets | `VELA_OUTPUT`, `SECRET_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `secret.engine` -- `secret.type` -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela get secret --secret.engine native --secret.type repo -``` - -#### Targeted Request - -```sh -$ vela get secret --secret.engine native --secret.type repo --org github --repo octocat -``` - -#### Response - -```sh -NAME ORG TYPE EVENTS -foo github/octocat repo push,pull_request -``` diff --git a/versioned_docs/version-0.26/reference/cli/secret/remove.md b/versioned_docs/version-0.26/reference/cli/secret/remove.md deleted file mode 100644 index 6cbf8db..0000000 --- a/versioned_docs/version-0.26/reference/cli/secret/remove.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: "Remove" -linkTitle: "Remove" -description: > - Learn how to delete a secret. ---- - -## Command - -``` -$ vela remove secret -``` - -:::tip -For more information, you can run `vela remove secret --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| --------------- | ------------------------------------- | ------------------------------ | -| `org` | name of organization for the secret | `VELA_ORG`, `SECRET_ORG` | -| `repo` | name of repository for the secret | `VELA_REPO`, `SECRET_REPO` | -| `secret.engine` | name of engine that stores the secret | `VELA_ENGINE`. `SECRET_ENGINE` | -| `secret.type` | name of type of secret being stored | `VELA_TYPE`, `SECRET_TYPE` | -| `team` | name of team for the secret | `VELA_TEAM`, `SECRET_TEAM` | -| `name` | name of the secret | `VELA_NAME`, `SECRET_NAME` | -| `output` | format the output for the secret | `VELA_OUTPUT`, `SECRET_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `secret.engine` -- `secret.type` -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela remove secret --secret.engine native --secret.type repo --name foo -``` - -#### Targeted Request - -```sh -$ pwd -~/github/octocat -$ vela remove secret --secret.engine native --secret.type repo --org github --repo octocat --name foo -``` - -#### Response - -```sh -secret "foo" was deleted -``` diff --git a/versioned_docs/version-0.26/reference/cli/secret/secret.md b/versioned_docs/version-0.26/reference/cli/secret/secret.md deleted file mode 100644 index 9a72a9e..0000000 --- a/versioned_docs/version-0.26/reference/cli/secret/secret.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Secret" -linkTitle: "Secret" -description: > - Learn how to use CLI commands for the secret resource. ---- - -The below commands are available to operate on the `secret` resource. - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/cli/secret/update.md b/versioned_docs/version-0.26/reference/cli/secret/update.md deleted file mode 100644 index fcc59f8..0000000 --- a/versioned_docs/version-0.26/reference/cli/secret/update.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: "Update" -linkTitle: "Update" -description: > - Learn how to modify a secret. ---- - -## Command - -``` -$ vela update secret -``` - -:::tip -For more information, you can run `vela update secret --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| --------------- | ------------------------------------------------ | ----------------------------------------- | -| `org` | name of organization for the secret | `VELA_ORG`, `SECRET_ORG` | -| `repo` | name of repository for the secret | `VELA_REPO`, `SECRET_REPO` | -| `secret.engine` | name of engine that stores the secret | `VELA_ENGINE`. `SECRET_ENGINE` | -| `secret.type` | name of type of secret being stored | `VELA_TYPE`, `SECRET_TYPE` | -| `team` | name of team for the secret | `VELA_TEAM`, `SECRET_TEAM` | -| `name` | name of the secret | `VELA_NAME`, `SECRET_NAME` | -| `value` | value of the secret | `VELA_VALUE`, `SECRET_VALUE` | -| `image` | build image(s) that can access the secret | `VELA_IMAGES`, `SECRET_IMAGES` | -| `event` | build event(s) that can access the secret | `VELA_EVENTS`, `SECRET_EVENTS` | -| `commands` | allows a step with commands to access the secret | `VELA_COMMANDS`, `SECRET_COMMANDS` | -| `substitution` | allows substitution of secret using $\{KEY\} format | `VELA_SUBSTITUTION`, `SECRET_SUBSTITUTION` | -| `file` | name of file used to add the secret(s) | `VELA_FILE`, `SECRET_FILE` | -| `output` | format the output for the secret | `VELA_OUTPUT`, `SECRET_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `secret.engine` -- `secret.type` -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela update secret --secret.engine native --secret.type repo --name foo --value bar -``` - -#### Targeted Request - -```sh -$ vela update secret --secret.engine native --secret.type repo --org github --repo octocat --name foo --value bar -``` - -#### Response - -```sh -secret "foo" was updated -``` - -## Advanced - -#### Input From File - -Vela supports updating a single-line or multi-line secret from a file using the `@` symbol. - -```sh -# Syntax -vela update secret --secret.engine native --secret.type repo --org github --repo octocat --name foo --value @/path/to/file - -# Example -vela update secret --secret.engine native --secret.type repo --org github --repo octocat --name foo --value @$HOME/tmp/secret.txt -``` - -#### Secrets From File - -Vela supports updating multiple secrets from a file using the `filename` parameter. - -```sh -vela update secret -f secret.yml -``` - -### Single YAML document - -```yaml ---- -metadata: - version: v1 - engine: native -secrets: - - org: octocat - repo: github - name: foo - value: bar - type: repo - images: - - golang:latest - events: - - push - - pull_request - - org: github - team: octokitties - name: foo1 - value: "@/path/to/file/bar1" - type: shared - images: - - golang:latest - events: - - push - - pull_request -``` - -### Multiple YAML document - -```yaml ---- -metadata: - version: v1 - engine: native -secrets: - - org: github - repo: octocat - name: foo - value: bar - type: repo - images: - - golang:latest - events: - - push - - pull_request - ---- -metadata: - version: v1 - engine: vault -secrets: - - org: github - team: octokitties - name: foo1 - value: "@/path/to/file/bar1" - type: shared - images: - - golang:latest - events: - - push - - pull_request -``` diff --git a/versioned_docs/version-0.26/reference/cli/secret/view.md b/versioned_docs/version-0.26/reference/cli/secret/view.md deleted file mode 100644 index 0e7fa87..0000000 --- a/versioned_docs/version-0.26/reference/cli/secret/view.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect a secret. ---- - -## Command - -``` -$ vela view secret -``` - -:::tip -For more information, you can run `vela view secret --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| --------------- | ------------------------------------- | ------------------------------ | -| `org` | name of organization for the secret | `VELA_ORG`, `SECRET_ORG` | -| `repo` | name of repository for the secret | `VELA_REPO`, `SECRET_REPO` | -| `secret.engine` | name of engine that stores the secret | `VELA_ENGINE`. `SECRET_ENGINE` | -| `secret.type` | name of type of secret being stored | `VELA_TYPE`, `SECRET_TYPE` | -| `team` | name of team for the secret | `VELA_TEAM`, `SECRET_TEAM` | -| `name` | name of the secret | `VELA_NAME`, `SECRET_NAME` | -| `output` | format the output for the secret | `VELA_OUTPUT`, `SECRET_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `secret.engine` -- `secret.type` -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela view secret --secret.engine native --secret.type repo --name foo -``` - -#### Targeted Request - -```sh -$ pwd -~/github/octocat -$ vela view secret --secret.engine native --secret.type repo --org github --repo octocat --name foo -``` - -#### Response - -```sh -id: 1 -org: github -repo: octocat -team: "" -name: foo -value: "[secure]" -type: repo -images: null -events: - - push - - pull_request -allowcommand: true -createdat: 1641312765 -createdby: octokitty -updatedat: 1641312765 -updatedby: octokitty -``` diff --git a/versioned_docs/version-0.26/reference/cli/service/get.md b/versioned_docs/version-0.26/reference/cli/service/get.md deleted file mode 100644 index 6a43d88..0000000 --- a/versioned_docs/version-0.26/reference/cli/service/get.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to list services. ---- - -## Command - -``` -$ vela get service -``` - -:::tip -For more information, you can run `vela get service --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| ---------- | ------------------------------------- | ----------------------------------- | -| `org` | name of organization for the services | `VELA_ORG`, `SERVICE_ORG` | -| `repo` | name of repository for the services | `VELA_REPO`, `SERVICE_REPO` | -| `build` | number of build for the services | `VELA_BUILD`, `SERVICE_BUILD` | -| `output` | format the output for the services | `VELA_OUTPUT`, `SERVICE_OUTPUT` | -| `page` | prints a specific page of services | `VELA_PAGE`, `SERVICE_PAGE` | -| `per.page` | number of services to print per page | `VELA_PER_PAGE`, `SERVICE_PER_PAGE` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela get service --build 1 -``` - -#### Targeted Request - -```sh -$ vela get service --org github --repo octocat --build 1 -``` - -#### Response - -```sh -NAME STATUS RUNTIME DURATION -publish failure 1s -build success 17s -test success 10s -clone success 2s -``` diff --git a/versioned_docs/version-0.26/reference/cli/service/service.md b/versioned_docs/version-0.26/reference/cli/service/service.md deleted file mode 100644 index 8df8322..0000000 --- a/versioned_docs/version-0.26/reference/cli/service/service.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Service" -linkTitle: "Service" -description: > - Learn how to use CLI commands for the service resource. ---- - -The below commands are available to operate on the `service` resource. - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/cli/service/view.md b/versioned_docs/version-0.26/reference/cli/service/view.md deleted file mode 100644 index 84f4b68..0000000 --- a/versioned_docs/version-0.26/reference/cli/service/view.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect a service. ---- - -## Command - -``` -$ vela view service -``` - -:::tip -For more information, you can run `vela view service --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| --------- | ------------------------------------ | -------------------------------- | -| `org` | name of organization for the service | `VELA_ORG`, `SERVICE_ORG` | -| `repo` | name of repository for the service | `VELA_REPO`, `SERVICE_REPO` | -| `build` | number of build for the service | `VELA_BUILD`, `SERVICE_BUILD` | -| `service` | number of the service | `VELA_SERVICE`, `SERVICE_NUMBER` | -| `output` | format the output for the service | `VELA_OUTPUT`, `SERVICE_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela view service --build 1 --service 1 -``` - -#### Targeted Request - -```sh -$ vela get service --org github --repo octocat --build 1 --service 1 -``` - -#### Response - -```sh -id: 1 -build_id: 1 -repo_id: 1 -number: 1 -name: clone -status: success -error: "" -exitcode: 0 -created: 1561748980 -started: 1561748979 -finished: 1561748981 -host: "worker.host.com" -runtime: "docker" -distribution: "linux" -``` diff --git a/versioned_docs/version-0.26/reference/cli/settings/settings.md b/versioned_docs/version-0.26/reference/cli/settings/settings.md deleted file mode 100644 index fcf00cb..0000000 --- a/versioned_docs/version-0.26/reference/cli/settings/settings.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Settings" -linkTitle: "Settings" -description: > - Learn how to use CLI commands for platform settings. ---- - -The below commands are available to operate on the `settings` resource. - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/cli/settings/update.md b/versioned_docs/version-0.26/reference/cli/settings/update.md deleted file mode 100644 index 2359afd..0000000 --- a/versioned_docs/version-0.26/reference/cli/settings/update.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: "Update" -linkTitle: "Update" -description: > - Learn how to modify platform settings. ---- - -## Command - -``` -$ vela update settings -``` - -:::tip -For more information, you can run `vela update settings --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| ------------------------------ | ------------------------------------------------------- | ------------------------------------ | -| `compiler.clone-image` | image used by the compiler to clone repositories | `VELA_COMPILER_CLONE_IMAGE` | -| `compiler.template-depth` | maximum depth of nested templates | `VELA_COMPILER_TEMPLATE_DEPTH` | -| `compiler.starlark-exec-limit` | maximum execution limit for Starlark templates | `VELA_COMPILER_STARLARK_EXEC_LIMIT` | -| `queue.add-route` | add a route to the queue | `VELA_QUEUE_ADD_ROUTES` | -| `queue.drop-route` | drop a route from the queue | `VELA_QUEUE_DROP_ROUTES` | -| `add-repo` | name of repository to add to the global allowlist | `VELA_REPO_ALLOWLIST_ADD_REPOS` | -| `drop-repo` | name of repository to drop from the global allowlist | `VELA_REPO_ALLOWLIST_DROP_REPOS` | -| `add-schedule` | name of repository to add to the schedules allowlist | `VELA_SCHEDULE_ALLOWLIST_ADD_REPOS` | -| `drop-schedule` | name of repository to drop from the schedules allowlist | `VELA_SCHEDULE_ALLOWLIST_DROP_REPOS` | -| `file` | path to a json/yaml file containing settings updates | `VELA_FILE` | - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela update settings --compiler.clone-image target/vela-git:abc123 --queue.add-route large -``` - -#### Response - -```yaml -id: 1 -compiler: - clone_image: target/vela-git:latest - template_depth: 3 - starlark_exec_limit: 7500 -queue: - routes: - - vela -repo_allowlist: - - 'github/octocat' -schedule_allowlist: - - '*' -created_at: 0 -updated_at: 1715791151 -updated_by: octocat -``` - -## Advanced - -#### Input From File - -Vela supports updating a settings record from a file using the `@` symbol. - -```sh -# Syntax -vela update settings --file @/path/to/file - -# Example -vela update settings --file @$HOME/tmp/settings.yml -``` - -### Single YAML document - -```yaml ---- -platform: - compiler: - clone_image: target/vela-git:latest - template_depth: 3 - starlark_exec_limit: 7500 - queue: - routes: - - vela - repo_allowlist: - - 'github/octocat' - schedule_allowlist: - - '*' - created_at: 0 - updated_at: 1715791151 - updated_by: octocat -``` diff --git a/versioned_docs/version-0.26/reference/cli/settings/view.md b/versioned_docs/version-0.26/reference/cli/settings/view.md deleted file mode 100644 index 742702e..0000000 --- a/versioned_docs/version-0.26/reference/cli/settings/view.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect platform settings. ---- - -## Command - -``` -$ vela view settings -``` - -:::tip -For more information, you can run `vela view settings --help`. -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela view settings -``` - -#### Response - -```yaml -id: 1 -compiler: - clone_image: target/vela-git:latest - template_depth: 3 - starlark_exec_limit: 7500 -queue: - routes: - - vela -repo_allowlist: - - 'github/octocat' -schedule_allowlist: - - '*' -created_at: 0 -updated_at: 1715791151 -updated_by: octocat -``` diff --git a/versioned_docs/version-0.26/reference/cli/step/get.md b/versioned_docs/version-0.26/reference/cli/step/get.md deleted file mode 100644 index 2ba335e..0000000 --- a/versioned_docs/version-0.26/reference/cli/step/get.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to list steps. ---- - -## Command - -``` -$ vela get step -``` - -:::tip -For more information, you can run `vela get step --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| ---------- | ---------------------------------- | -------------------------------- | -| `org` | name of organization for the steps | `VELA_ORG`, `STEP_ORG` | -| `repo` | name of repository for the steps | `VELA_REPO`, `STEP_REPO` | -| `build` | number of build for the steps | `VELA_BUILD`, `STEP_BUILD` | -| `output` | format the output for the steps | `VELA_OUTPUT`, `STEP_OUTPUT` | -| `page` | prints a specific page of steps | `VELA_PAGE`, `STEP_PAGE` | -| `per.page` | number of steps to print per page | `VELA_PER_PAGE`, `STEP_PER_PAGE` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela get step --build 1 -``` - -#### Targeted Request - -```sh -$ vela get step --org github --repo octocat --build 1 -``` - -#### Response - -```sh -NAME STATUS RUNTIME DURATION -publish failure 1s -build success 17s -test success 10s -clone success 2s -``` diff --git a/versioned_docs/version-0.26/reference/cli/step/step.md b/versioned_docs/version-0.26/reference/cli/step/step.md deleted file mode 100644 index 6557130..0000000 --- a/versioned_docs/version-0.26/reference/cli/step/step.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Step" -linkTitle: "Step" -description: > - Learn how to use CLI commands for the step resource. ---- - -The below commands are available to operate on the `step` resource. - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/cli/step/view.md b/versioned_docs/version-0.26/reference/cli/step/view.md deleted file mode 100644 index 43b35ea..0000000 --- a/versioned_docs/version-0.26/reference/cli/step/view.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect a step. ---- - -## Command - -``` -$ vela view step -``` - -:::tip -For more information, you can run `vela view step --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| -------- | --------------------------------- | ---------------------------- | -| `org` | name of organization for the step | `VELA_ORG`, `STEP_ORG` | -| `repo` | name of repository for the step | `VELA_REPO`, `STEP_REPO` | -| `build` | number of build for the step | `VELA_BUILD`, `STEP_BUILD` | -| `step` | number of the step | `VELA_STEP`, `STEP_NUMBER` | -| `output` | format the output for the step | `VELA_OUTPUT`, `STEP_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `org` -- `repo` -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ pwd -~/github/octocat -$ vela view step --build 1 --step 1 -``` - -#### Targeted Request - -```sh -$ vela view step --org github --repo octocat --build 1 --step 1 -``` - -#### Response - -```sh -id: 1 -build_id: 1 -repo_id: 1 -number: 1 -name: clone -status: success -error: "" # Populates when the platform runs into an error with the build -exitcode: 0 -created: 1561748980 -started: 1561748979 -finished: 1561748981 -host: "worker.host.com" -runtime: "docker" -distribution: "linux" -``` diff --git a/versioned_docs/version-0.26/reference/cli/validate.md b/versioned_docs/version-0.26/reference/cli/validate.md deleted file mode 100644 index 7e11914..0000000 --- a/versioned_docs/version-0.26/reference/cli/validate.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Validate" -sidebar_position: 3 ---- - -:::tip -This command has been moved to `vela validate pipeline`. - -For more information, please see the [command documentation](/docs/reference/cli/pipeline/validate.md) -::: diff --git a/versioned_docs/version-0.26/reference/cli/version.md b/versioned_docs/version-0.26/reference/cli/version.md deleted file mode 100644 index 208f344..0000000 --- a/versioned_docs/version-0.26/reference/cli/version.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: "Version" -sidebar_position: 4 ---- - -## Command - -``` -$ vela version -``` - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -vela version -``` - -#### Response - -```sh -{ - Canonical: v0.7.0, - Major: 0, - Minor: 7, - Patch: 0, - Metadata: { - Architecture: amd64, - BuildDate: 2021-02-01T15:40:21Z, - Compiler: gc, - GitCommit: 6225623858e09b7277f3d274d1ed75289a9eb549, - GoVersion: go1.15.7, - OperatingSystem: darwin, - } -} -``` diff --git a/versioned_docs/version-0.26/reference/cli/worker/add.md b/versioned_docs/version-0.26/reference/cli/worker/add.md deleted file mode 100644 index ce81de5..0000000 --- a/versioned_docs/version-0.26/reference/cli/worker/add.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: "Add" -linkTitle: "Add" -description: > - Learn how to add a worker (Vela Platform Admins only). ---- - -## Command - -``` -$ vela add worker -``` - -:::tip -For more information, you can run `vela add worker --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| ----------------- | -------------------------------- | ----------------------------------------- | -| `worker.address` | address of the worker | `VELA_WORKER_ADDRESS`, `WORKER_ADDRESS` | -| `worker.hostname` | hostname of the worker | `VELA_WORKER_HOSTNAME`, `WORKER_HOSTNAME` | -| `output` | format the output for the worker | `VELA_OUTPUT`, `WORKER_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -Vela Platform Admin - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI and are authenticated as a Vela platform admin. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ vela add worker --worker.address myworker.example.com -``` - -:::tip -Not passing `--worker.hostname` will automatically use the hostname part of the passed in `--worker.address` as the hostname. -::: - -#### Response generated from successful CLI command -```sh -worker registered successfully -``` - -## Examples - -```sh -EXAMPLES: - 1. Add a worker reachable at the provided address. - $ vela add worker --worker.address myworker.example.com - 2. Add a worker with the provided hostname and reachable at the address given. - $ vela add worker --worker.hostname MyWorker --worker.address myworker.example.com -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/cli/worker/get.md b/versioned_docs/version-0.26/reference/cli/worker/get.md deleted file mode 100644 index 885c15b..0000000 --- a/versioned_docs/version-0.26/reference/cli/worker/get.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to list workers. ---- - -## Command - -``` -$ vela get workers -``` - -:::tip -For more information, you can run `vela get workers --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| ---------- | ------------------------------------ | ---------------------------------- | -| `output` | format the output for the workers | `VELA_OUTPUT`, `WORKER_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ vela get workers -``` - -#### Response generated from successful CLI command -```sh -HOSTNAME ACTIVE ROUTES LAST_CHECKED_IN -MyWorker1 true [vela] 1681485812 -MyWorker2 true [vela] 1681485814 -``` - -## Examples - -```sh -EXAMPLES: - 1. Get a list of workers. - $ vela get worker - 2. Get a list of workers with wide view output. - $ vela get worker --output wide - 3. Get a list of workers with yaml output. - $ vela get worker --output yaml - 4. Get a list of workers with json output. - $ vela get worker --output json - 5. Get a list of workers when config or environment variables are set. - $ vela get worker -``` diff --git a/versioned_docs/version-0.26/reference/cli/worker/update.md b/versioned_docs/version-0.26/reference/cli/worker/update.md deleted file mode 100644 index d15878c..0000000 --- a/versioned_docs/version-0.26/reference/cli/worker/update.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: "Update" -linkTitle: "Update" -description: > - Learn how to modify a worker. ---- - -## Command - -``` -$ vela update worker -``` - -:::tip -For more information, you can run `vela update worker --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| ----------------- | ---------------------------------------- | ----------------------------------------------- | -| `worker.address` | address of the worker | `VELA_WORKER_ADDRESS`, `WORKER_ADDRESS` | -| `worker.hostname` | hostname of the worker | `VELA_WORKER_HOSTNAME`, `WORKER_HOSTNAME` | -| `active` | current status of the worker (unused) | `VELA_WORKER_ACTIVE`, `WORKER_ACTIVE` | -| `build-limit` | build limit for the worker (ignored) | `VELA_WORKER_BUILD_LIMIT`, `WORKER_BUILD_LIMIT` | -| `routes` | route assignment for the worker (unused) | `VELA_WORKER_ROUTES`, `WORKER_ROUTES` | -| `output` | format the output for the worker | `VELA_OUTPUT`, `WORKER_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -Vela Platform Admin - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ vela update worker --worker.hostname MyWorker --worker.address newaddress.example.com -``` - -#### Response - -```sh -{ - ID: 1, - Hostname: MyWorker, - Address: newaddress.example.com, - Routes: [vela], - Active: true, - Status: busy, - LastStatusUpdateAt: 1681486769, - RunningBuildIDs: [123], - LastBuildStartedAt: 1681486769, - LastBuildFinishedAt: 1681486769, - LastCheckedIn: 1681486769, - BuildLimit: 1, -} -``` diff --git a/versioned_docs/version-0.26/reference/cli/worker/view.md b/versioned_docs/version-0.26/reference/cli/worker/view.md deleted file mode 100644 index caad51b..0000000 --- a/versioned_docs/version-0.26/reference/cli/worker/view.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: "View" -linkTitle: "View" -description: > - Learn how to inspect a worker. ---- - -## Command - -``` -$ vela view worker -``` - -:::tip -For more information, you can run `vela view worker --help`. -::: - -## Parameters - -The following parameters are used to configure the command: - -| Name | Description | Environment Variables | -| --------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------- | -| `worker.hostname` | hostname of the worker | `VELA_WORKER_HOSTNAME`, `WORKER_HOSTNAME` | -| `worker.registration.token` | generate a registration token for the worker (requires Vela Platform Admin) | `VELA_WORKER_REGISTRATION_TOKEN`, `WORKER_REGISTRATION_TOKEN` | -| `output` | format the output for the repository | `VELA_OUTPUT`, `WORKER_OUTPUT` | - -:::tip -This command also supports setting the following parameters via a configuration file: - -- `output` - -For more information, please review the [CLI config documentation](/docs/reference/cli/config/config.md). -::: - -## Permissions - -COMING SOON! - -## Sample - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: - -#### Request - -```sh -$ vela view worker --worker.hostname MyWorker -``` - -#### Response - -```sh -id: 1 -hostname: MyWorker -address: myworker.example.com -routes: -- vela -active: true -status: busy -laststatusupdatedat: 1681487969 -runningbuildids: -- 123 -lastbuildstartedat: 1681487969 -lastbuildfinishedat: 1681487969 -lastcheckedin: 1681487969 -buildlimit: 1 - -``` diff --git a/versioned_docs/version-0.26/reference/cli/worker/worker.md b/versioned_docs/version-0.26/reference/cli/worker/worker.md deleted file mode 100644 index 35afb6f..0000000 --- a/versioned_docs/version-0.26/reference/cli/worker/worker.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Worker" -linkTitle: "Worker" -description: > - Learn how to use CLI commands for the worker resource. ---- - -The below commands are available to operate on the `worker` resource. - -:::warning -This section assumes you have already installed and setup the CLI. - -To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). - -To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication.md). -::: diff --git a/versioned_docs/version-0.26/reference/environment/environment.md b/versioned_docs/version-0.26/reference/environment/environment.md deleted file mode 100644 index b6e9d7d..0000000 --- a/versioned_docs/version-0.26/reference/environment/environment.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "Environment" -linkTitle: "Environment" -layout: Environment -description: > - This section contains information on how to use the Vela pipeline environment. ---- - -Vela allows ways to set environment variables within the step, service, or secret container environment. This allows users to pass custom environment configurations to the container. Custom environment configuration can allow you to customize the build environment or simply add metadata for whatever the container image is running. - -:::tip -An example is available within the usage tab called ["Using the Environment"](/docs/usage/environment.md) -::: diff --git a/versioned_docs/version-0.26/reference/environment/substitution.md b/versioned_docs/version-0.26/reference/environment/substitution.md deleted file mode 100644 index 0c0b9ad..0000000 --- a/versioned_docs/version-0.26/reference/environment/substitution.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "Substitution" -linkTitle: "Substitution" -description: > - Learn how to use substitution on environment variables ---- - -Vela imports a substitution library to provide the ability to expand, or substitute, repository and build metadata to facilitate dynamic pipeline configurations. - -## String Operations - -| Syntax | Example with Output | Description | -| ------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `${VAR^}` | `VAR=example; echo ${VAR^}`► `Example` | Converts the first character of the variable to uppercase | -| `${VAR^^}` | `VAR=example; echo ${VAR^^}`► `EXAMPLE` | Converts all characters of the variable to uppercase | -| `${VAR,}` | `VAR=EXAMPLE; echo ${VAR,}`► `eXAMPLE` | Converts the first character of the variable to lowercase | -| `${VAR,,}` | `VAR=EXAMPLE; echo ${VAR,,}`► `example` | Converts all characters of the variable to lowercase | -| `${VAR:position}` | `VAR=example; echo ${VAR:1}`► `xample` | Extracts a substring from the variable starting at the position | -| `${VAR:position:length}` | `VAR=example; echo ${VAR:2:3}`► `amp` | Extracts a substring from the variable starting at the position with the specified length | -| `${VAR#substring}` | `VAR=exampleexample; echo ${VAR#exa}`► `mpleexample` | Removes the shortest match of substring from the start of the variable | -| `${VAR##substring}` | `VAR=exampleexample; echo ${VAR##*exa}`► `mple` | Removes the longest match of substring from the start of the variable | -| `${VAR%substring}` | `VAR=exampleexample; echo ${VAR%mple}`► `exampleexa` | Removes the shortest match of substring from the end of the variable | -| `${VAR%%substring}` | `VAR=exampleexample; echo ${VAR%%mple*}`► `exa` | Removes the longest match of substring from the end of the variable | -| `${VAR/substring/replacement}` | `VAR=exampleexample; echo ${VAR/exam/ap}`► `appleexample` | Replaces the first match of substring with replacement in the variable | -| `${VAR//substring/replacement}` | `VAR=exampleexample; echo ${VAR//exam/ap}`► `appleapple` | Replaces all matches of substring with replacement in the variable | -| `${VAR/#substring/replacement}` | `VAR=example; echo ${VAR/#exam/ap}`► `apple` | If the variable starts with substring, replace it with replacement | -| `${VAR/%substring/replacement}` | `VAR=example; echo ${VAR/%mple/ctly}`► `exactly` | If the variable ends with substring, replace it with replacement | -| `${#VAR}` | `VAR=example; echo ${#VAR}`► `7` | Returns the length of the variable | -| `${VAR=default}` | `unset VAR; echo ${VAR=default}`► `default` | If the variable is unset or null, it will be set to `default` | -| `${VAR:=default}` | `unset VAR; echo ${VAR:=default}`► `default` | If the variable is unset or null, it will be set to `default` and the assignment is exported | -| `${VAR:-default}` | `unset VAR; echo ${VAR:-default}`► `default` | If the variable is unset or null, it will be replaced with `default` without changing the value of `VAR` | - -:::tip -If you want to play with the examples above in a terminal, make sure you are in a `bash` shell. -::: - -### Escaping - -:::tip -var expressions are evaluated before the yaml is parsed. If you do not want the system to evaluate an expression it must be escaped. -::: - -This can come in handy particularly when dealing with [runtime build environment variables](/reference/environment/variables/#using-substitution-for-platform-variables). - -```diff -version: "1" -steps: - - name: echo - commands: - # This expression does not escape the evaluation -+ - echo ${VELA_BUILD_COMMIT} - # This expression does escape the evaluation by adding the double '$$' -+ - echo $${VELA_BUILD_COMMIT} -``` diff --git a/versioned_docs/version-0.26/reference/environment/variables.md b/versioned_docs/version-0.26/reference/environment/variables.md deleted file mode 100644 index d56dd28..0000000 --- a/versioned_docs/version-0.26/reference/environment/variables.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -title: "Variables" -linkTitle: "Variables" -description: > - Learn what environment variables are injected into containers ---- - -## Container Defaults - -The following environment variables are injected into every step, service, or secret container. - -#### Build Environment Variables - -| Key | Value | Explanation | -| ------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------- | -| `VELA_BUILD_APPROVED_AT` | `1556720958` | unix timestamp representing when build was approved | -| `VELA_BUILD_APPROVED_BY` | `RepoAdmin` | user who approved the build | -| `VELA_BUILD_AUTHOR` | `octocat` | author from the source commit | -| `VELA_BUILD_AUTHOR_EMAIL` | `octocat@github.com` | author email from the source commit, available only in `push` events | -| `VELA_BUILD_BASE_REF` | `refs/heads/dev` | reference from the base commit | -| `VELA_BUILD_BRANCH` | `main` | branch from the source commit | -| `VELA_BUILD_CHANNEL` | `vela` | queue channel the build was published to | -| `VELA_BUILD_CLONE` | `https://github.com/octocat/hello-world.git` | clone url for the repository the build was triggered from | -| `VELA_BUILD_COMMIT` | `7fd1a60b01f91b314f59955a4e4d4e80d8edf11d` | commit sha from the source commit | -| `VELA_BUILD_CREATED` | `1556720958` | unix timestamp representing build creation time | -| `VELA_BUILD_DISTRIBUTION` | `linux` | distribution where the build was executed | -| `VELA_BUILD_ENQUEUED` | `1556720958` | unix timestamp representing build enqueued time | -| `VELA_BUILD_EVENT` | `push` | webhook event that triggered the build | -| `VELA_BUILD_EVENT_ACTION` | `created` | webhook event action that triggered the build | -| `VELA_BUILD_HOST` | `vela-worker-1` | fully qualified domain name of the worker the build was executed on | -| `VELA_BUILD_LINK` | `https://vela.example.com/octocat/hello-world/1` | link to the build in the UI | -| `VELA_BUILD_MESSAGE` | `Merge pull request #6 from octocat/patch-1` | message from the source commit | -| `VELA_BUILD_NUMBER` | `1` | build number | -| `VELA_BUILD_PARENT` | `1` | previous build number | -| `VELA_BUILD_REF` | `refs/heads/main` | reference from the source commit | -| `VELA_BUILD_RUNTIME` | `docker` | runtime where the build was executed | -| `VELA_BUILD_SENDER` | `NealColeman` | user who triggered the build | -| `VELA_BUILD_STARTED` | `1556730001` | unix timestamp representing build start time | -| `VELA_BUILD_SOURCE` | `https://github.com/octocat/hello-world/commit/7fd1a60b01f91b314f59955a4e4d4e80d8edf11d` | full url for the source commit the build was triggered from | -| `VELA_BUILD_STATUS` | `success` | status of the build | -| `VELA_BUILD_TITLE` | `push received from https://github.com/octocat/hello-world` | title for the build | -| `VELA_BUILD_WORKSPACE` | `/vela/src/github.com/octocat/hello-world` | working directory the build is executed in | - -### `comment` event only - -:::tip -The following table includes variables only available during the **comment** event. -::: - -| Key | Value | Explanation | -| ------------------------- | ----- | ---------------------------------------------------------- | -| `VELA_BUILD_PULL_REQUEST` | `1` | pull request number is populated from the source reference | -| `VELA_PULL_REQUEST` | `1` | pull request number is populated from the source reference | -| `VELA_PULL_REQUEST_SOURCE` | `dev` | pull request branch from the source reference | -| `VELA_PULL_REQUEST_TARGET` | `main` | pull request branch for the target reference | - -### `deployment` event only - -:::tip -The following table includes variables only available during the **deployment** event. - -All custom parameters are passed to the deployment available with a `DEPLOYMENT_PARAMETER_` prefix of the key. -::: - -| Key | Value | Explanation | -| ------------------------ | ----------- | --------------------------------------------- | -| `VELA_BUILD_TARGET` | `production` | name of target environment for the deployment | -| `VELA_DEPLOYMENT` | `production` | name of target environment for the deployment | -| `VELA_DEPLOYMENT_NUMBER` | `12345` | ID of deployment from source | - -### `pull_request` event only - -:::tip -The following table includes variables only available during the **pull_request** event. -::: - -| Key | Value | Explanation | -| -------------------------- | ------ | ---------------------------------------------------------- | -| `VELA_BUILD_PULL_REQUEST` | `1` | pull request number is populated from the source reference | -| `VELA_PULL_REQUEST` | `1` | pull request number is populated from the source reference | -| `VELA_PULL_REQUEST_SOURCE` | `dev` | pull request branch from the source reference | -| `VELA_PULL_REQUEST_TARGET` | `main` | pull request branch for the target reference | - -### `tag` event only - -:::tip -The following table includes variables only available during the **tag** event. -::: - -| Key | Value | Explanation | -| ---------------- | -------- | ------------------------------------------ | -| `VELA_BUILD_TAG` | `v1.0.0` | tag is populated from the source reference | - -### OpenID Connect only - -:::tip -The following table includes variables only available when the step `id_request` field has a value. -::: - -| Key | Value | Explanation | -| ------------------------------ | ----------------------------------------------------------------------- | ------------------------------------- | -| `VELA_ID_TOKEN_REQUEST_URL` | `/api/v1/repos///builds//id_token` | URL to request an ID token | -| `VELA_ID_TOKEN_REQUEST_TOKEN` | `ey123abc...` | bearer token for requesting ID token | - - -#### Vela Environment Variables - -| Key | Value | Explanation | -| ---------------------- |---------------------------------------------------|---------------------------------------------------------------------| -| `VELA` | `true` | environment is Vela | -| `VELA_ADDR` | `vela.example.com` | fully qualified domain name of the Vela server | -| `VELA_CHANNEL` | `vela` | queue channel the build was published to | -| `VELA_DATABASE` | `postgres` | database Vela is connected to | -| `VELA_HOST` | `vela-worker-1` | fully qualified domain name of the worker the build was executed on | -| `VELA_QUEUE` | `redis` | queue build was published to | -| `VELA_RUNTIME` | `docker` | runtime environment build was executed in | -| `VELA_SOURCE` | `github` | queue channel the build was published to | -| `VELA_VERSION` | `v0.1.0` | Vela version | -| `VELA_WORKSPACE` | `/vela/src/github.com/github/octocat/hello-world` | working directory the build is executed in | -| `CI` | `true` | Indicates this is a CI environment | -| `VELA_OUTPUTS` | `/vela/outputs/.env` | file path for dynamic environment | -| `VELA_MASKED_OUTPUTS` | `/vela/outputs/masked.env` | file path for dynamic environment for sensitive values | - -#### Repository Environment Variables - -| Key | Value | Explanation | -| ------------------------- | -------------------------------------------- | --------------------------------------------- | -| `VELA_REPO_ACTIVE` | `true` | active setting for the repository | -| `VELA_REPO_ALLOW_COMMENT` | `false` | comment enabled setting for the repository | -| `VELA_REPO_ALLOW_DEPLOY` | `false` | deploy enabled setting for the repository | -| `VELA_REPO_ALLOW_PULL` | `true` | pull enabled setting for the repository | -| `VELA_REPO_ALLOW_PUSH` | `true` | push enabled setting for the repository | -| `VELA_REPO_ALLOW_TAG` | `false` | tag enabled setting for the repository | -| `VELA_REPO_BRANCH` | `main` | default branch of the repository | -| `VELA_REPO_BUILD_LIMIT` | `10` | limit of concurrent builds for the repository | -| `VELA_REPO_CLONE` | `https://github.com/octocat/hello-world.git` | clone url of the repository | -| `VELA_REPO_FULL_NAME` | `octocat/hello-world` | full name of the repository | -| `VELA_REPO_LINK` | `https://github.com/octocat/hello-world` | direct url of the repository | -| `VELA_REPO_NAME` | `hello-world` | name of the repository | -| `VELA_REPO_ORG` | `octocat` | org of the repository | -| `VELA_REPO_PRIVATE` | `false` | privacy setting for the repository | -| `VELA_REPO_TIMEOUT` | `30` | timeout setting for the repository | -| `VELA_REPO_TOPICS` | `cloud,security` | comma-separated list of repository topics | -| `VELA_REPO_TRUSTED` | `false` | trusted setting for the repository | -| `VELA_REPO_VISIBILITY` | `public` | visibility setting for the repository | - -#### User Environment Variables - -| Key | Value | Explanation | -| ---------------------- | --------------------------- | ---------------------------------- | -| `VELA_USER_ACTIVE` | `true` | active setting for the user | -| `VELA_USER_NAME` | `Octocat` | user handle setting for the user | - -## Step Only Defaults - -The following environment variables are **only** injected into every step container. - -| Key | Value | Explanation | -| ------------------------ | ------------------------ | ------------------------------------------------------------------- | -| `VELA_STEP_CREATED` | `1556720958` | unix timestamp representing step creation time | -| `VELA_STEP_DISTRIBUTION` | `linux` | distribution where the step was executed | -| `VELA_STEP_EXIT_CODE` | `0` | exit code of the step when container starts | -| `VELA_STEP_HOST` | `vela-worker-1` | fully qualified domain name of the worker the step was executed on | -| `VELA_STEP_IMAGE` | `target/vela-git:latest` | name of the image executed | -| `VELA_STEP_NAME` | `clone` | name of the step | -| `VELA_STEP_NUMBER` | `1` | number of the step executed within the pipeline | -| `VELA_STEP_REPORT_AS` | `cypress tests` | context to which to publish for the commit that reflects step status | -| `VELA_STEP_RUNTIME` | `docker` | runtime where the step was executed | -| `VELA_STEP_STAGE` | `clone` | name of the stage the step belongs to within the pipeline | -| `VELA_STEP_STARTED` | `1556730001` | unix timestamp representing step start time | -| `VELA_STEP_STATUS` | `success` | status of the step | - -## Service Only Defaults - -The following environment variables are **only** injected into every step container. - -| Key | Value | Explanation | -| --------------------------- | ------------------------ | --------------------------------------------------------------------- | -| `VELA_SERVICE_CREATED` | `1556720958` | unix timestamp representing service creation time | -| `VELA_SERVICE_DISTRIBUTION` | `linux` | distribution where the service was executed | -| `VELA_SERVICE_EXIT_CODE` | `0` | exit code of the service when container starts | -| `VELA_SERVICE_HOST` | `vela-worker-1` | fully qualified domain name of the worker the service was executed on | -| `VELA_SERVICE_IMAGE` | `target/vela-git:latest` | name of the image executed | -| `VELA_SERVICE_NAME` | `clone` | name of the service | -| `VELA_SERVICE_NUMBER` | `1` | number of the service executed within the pipeline | -| `VELA_SERVICE_RUNTIME` | `docker` | runtime where the service was executed | -| `VELA_SERVICE_STARTED` | `1556730001` | unix timestamp representing service start time | -| `VELA_SERVICE_STATUS` | `success` | status of the service | - -## Using Substitution For Platform Variables - -There are a few default environment variables that need to be [escaped](/reference/environment/substitution/#escaping) when attempting to substitute, as they are not available or not accurate at compile time. - -| Key | Compile Time | Build Time Example | -| -------------------------- | ------------- | ------------------- | -| `VELA_BUILD_STARTED` | `0` | `1556730001` | -| `VELA_BUILD_STATUS` | `pending` | `running` | -| `VELA_BUILD_APPROVED_AT` | `0` | `1556730001` | -| `VELA_BUILD_APPROVED_BY` | `''` | `Octocat` | -| `VELA_BUILD_ENQUEUED` | `0` | `1556730001` | -| `VELA_BUILD_RUNTIME` | `''` | `docker` | -| `VELA_BUILD_DISTRIBUTION` | `''` | `linux` | -| `VELA_BUILD_HOST` | `''` | `vela-worker-42` | diff --git a/versioned_docs/version-0.26/reference/installation/_category_.json b/versioned_docs/version-0.26/reference/installation/_category_.json deleted file mode 100644 index 0d527f1..0000000 --- a/versioned_docs/version-0.26/reference/installation/_category_.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "label": "Installation", - "position": 3, - "link": { - "type": "generated-index" - } -} diff --git a/versioned_docs/version-0.26/reference/installation/server/compiler.md b/versioned_docs/version-0.26/reference/installation/server/compiler.md deleted file mode 100644 index bdfb211..0000000 --- a/versioned_docs/version-0.26/reference/installation/server/compiler.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: "Compiler" -linkTitle: "Compiler" -weight: 2 -description: > - This section contains information on the compiler component for the Vela server. ---- - -:::note -The compiler is embedded directly in the server and can only be accessed through the server. -::: - -This component is responsible for transforming a [pipeline](/docs/usage/tour/tour.md) into an executable representation for the [worker](/docs/installation/worker/worker.md). - -During the transformation, it will retrieve [templates](/docs/usage/tour/templates.md) from one or more registries depending on the pipeline configuration. - -By default, Vela will use [GitHub](https://github.com/) as a registry for fetching templates, but you can configure additional registries as well. - -However, to fetch templates from a private organization or repository on GitHub, you need to provide a token to the compiler. - -Additionally, the compiler can send pipelines to an external endpoint, to be modified, based off custom configuration. - -This modification endpoint can be used to perform any number of customizations to all workloads created by the system. - -Some examples of what the modification endpoint can do include, but are not limited to: - -* injecting or updating the configuration for [secrets](/docs/usage/tour/secrets.md) in the pipeline -* injecting or updating the configuration for [services](/docs/usage/tour/services.md) in the pipeline -* injecting or updating the configuration for [stages](/docs/usage/tour/stages.md) in the pipeline -* injecting or updating the configuration for [steps](/docs/usage/tour/steps.md) in the pipeline - -## Configuration - -The following options are used to configure the component: - -| Name | Description | Required | Default | Environment Variables | -| ------------------------------ | ---------------------------------------------------------------------------- | -------- | --------------------- | --------------------------------------------------------------------- | -| `clone-image` | default clone image to use for Vela injected clone step | `true` | `target/vela-git` (1) | `VELA_CLONE_IMAGE` | -| `github-driver` | enables using Github or GitHub Enterprise Server as a registry for templates | `false` | `false` | `COMPILER_GITHUB`\`VELA_COMPILER_GITHUB` | -| `github-url` | fully qualified url to GitHub or GitHub Enterprise Server for templates | `false` | `N/A` | `COMPILER_GITHUB_URL`\`VELA_COMPILER_GITHUB_URL` | -| `github-token` | token used for authentication when fetching registry templates | `false` | `N/A` | `COMPILER_GITHUB_TOKEN`\`VELA_COMPILER_GITHUB_TOKEN` | -| `modification-addr` | fully qualified url to endpoint for modifying pipelines | `false` | `N/A` | `MODIFICATION_ADDR`\`VELA_MODIFICATION_ADDR` | -| `modification-retries` | number of times to resend failed requests to the modification endpoint | `false` | `5` | `MODIFICATION_RETRIES`\`VELA_MODIFICATION_RETRIES` | -| `modification-secret` | authenticates communication between compiler and the modification endpoint | `false` | `N/A` | `MODIFICATION_SECRET`\`VELA_MODIFICATION_SECRET` | -| `modification-timeout` | timeout for requests sent to the modification endpoint | `false` | `8s` | `MODIFICATION_TIMEOUT`\`VELA_MODIFICATION_TIMEOUT` | -| `max-template-depth` | max depth for calling nested templates during compilation | `true` | `3` | `MAX_TEMPLATE_DEPTH`\`VELA_MAX_TEMPLATE_DEPTH` | -| `compiler-starlark-exec-limit` | execution step limit for compiling starlark pipelines | `true` | `7500` | `COMPILER_STARLARK_EXEC_LIMIT`\`VELA_COMPILER_STARLARK_EXEC_LIMIT` | - -_(1) this will be the latest available, tagged release of `target/vela-git` at the time the server component is released_ - -:::note -For more information on these configuration options, please see the [server reference](/docs/reference/installation/server/server.md). -::: - -## Drivers - -The following drivers are available to configure the component: - -| Name | Description | Documentation | -| -------- | -------------------------------------------------------------- | --------------------------------------------------------------------------- | -| `github` | uses GitHub or GitHug Enterprise Server as a template registry | https://docs.github.com/en/enterprise-server/admin/overview/system-overview | - -### GitHub - -From the [GitHub official website](https://github.com/about/): - -> GitHub is where the world builds software. Millions of developers and companies build, ship, and maintain their software on GitHub—the largest and most advanced development platform in the world. - -The below configuration displays an example of starting the Vela server that will use a GitHub Server as a template registry: - -```diff -$ docker run \ - --detach=true \ - --env=VELA_ADDR=https://vela-server.example.com \ -+ --env=VELA_COMPILER_GITHUB=true \ -+ --env=VELA_COMPILER_TOKEN= \ -+ --env=VELA_COMPILER_URL=https://github.com \ - --env=VELA_DATABASE_ENCRYPTION_KEY= \ - --env=VELA_QUEUE_DRIVER=redis \ - --env=VELA_QUEUE_ADDR=redis://@:/ \ - --env=VELA_PORT=443 \ - --env=VELA_SECRET= \ - --env=VELA_SERVER_PRIVATE_KEY= \ - --env=VELA_SCM_CLIENT= \ - --env=VELA_SCM_SECRET= \ - --env=VELA_WEBUI_ADDR=https://vela.example.com \ - --name=server \ - --publish=80:80 \ - --publish=443:443 \ - --restart=always \ - target/vela-server:latest -``` - -:::note -This GitHub configuration is enabled by default and is not necessary to provide in order for Vela to operate. - -However, this configuration will enable you to fetch templates from a private organization or repository on GitHub. -::: - -### GitHub Enterprise Server - -From the [GitHub Enterprise official website](https://docs.github.com/en/enterprise-server/admin/overview/system-overview): - -> GitHub Enterprise Server is your organization's private copy of GitHub contained within a virtual appliance, hosted on premises or in the cloud, that you configure and control. - -The below configuration displays an example of starting the Vela server that will use a GitHub Enterprise Server as a template registry: - -```diff -$ docker run \ - --detach=true \ - --env=VELA_ADDR=https://vela-server.example.com \ -+ --env=VELA_COMPILER_GITHUB=true \ -+ --env=VELA_COMPILER_TOKEN= \ -+ --env=VELA_COMPILER_URL=https://git.example.com \ - --env=VELA_DATABASE_ENCRYPTION_KEY= \ - --env=VELA_QUEUE_DRIVER=redis \ - --env=VELA_QUEUE_ADDR=redis://@:/ \ - --env=VELA_PORT=443 \ - --env=VELA_SECRET= \ - --env=VELA_SERVER_PRIVATE_KEY= \ - --env=VELA_SCM_CLIENT= \ - --env=VELA_SCM_SECRET= \ - --env=VELA_WEBUI_ADDR=https://vela.example.com \ - --name=server \ - --publish=80:80 \ - --publish=443:443 \ - --restart=always \ - target/vela-server:latest -``` diff --git a/versioned_docs/version-0.26/reference/installation/server/database.md b/versioned_docs/version-0.26/reference/installation/server/database.md deleted file mode 100644 index 587cdad..0000000 --- a/versioned_docs/version-0.26/reference/installation/server/database.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: "Database" -linkTitle: "Database" -weight: 3 -description: > - This section contains information on the database component for the Vela server. ---- - -This component is responsible for integrating with a database system based off the configuration provided. - -The database system is used by Vela for storing application [data at rest](https://en.wikipedia.org/wiki/Data_at_rest). - -This data is an organized collection of information necessary for the platform to operate. - -:::note -Any sensitive data stored in the database will be encrypted using the [Advanced Encryption Standard (AES)](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard). -::: - -## Configuration - -The following options are used to configure the component: - -| Name | Description | Required | Default | Environment Variables | -| ----------------------------- | ---------------------------------------------------------------- | -------- | ------------- | --------------------------------------------------------------------- | -| `database.addr` | full connection string to the database | `true` | `sqlite3` | `DATABASE_ADDR`\`VELA_DATABASE_ADDR` | -| `database.driver` | type of client to control and operate the database | `true` | `vela.sqlite` | `DATABASE_DRIVER`\`VELA_DATABASE_DRIVER` | -| `database.compression.level` | level of compression for logs stored in the database | `true` | `3` | `DATABASE_COMPRESSION_LEVEL`\`VELA_DATABASE_COMPRESSION_LEVEL` | -| `database.connection.idle` | maximum number of idle connections to the database | `true` | `2` | `DATABASE_CONNECTION_IDLE`\`VELA_DATABASE_CONNECTION_IDLE` | -| `database.connection.life` | duration of time a connection is reusable | `true` | `30m` | `DATABASE_CONNECTION_LIFE`\`VELA_DATABASE_CONNECTION_LIFE` | -| `database.connection.open` | maximum number of open connections to the database | `true` | `0` | `DATABASE_CONNECTION_OPEN`\`VELA_DATABASE_CONNECTION_OPEN` | -| `database.encryption.key` | AES-256 key for encrypting/decrypting values in the database | `true` | `N/A` | `DATABASE_ENCRYPTION_KEY`\`VELA_DATABASE_ENCRYPTION_KEY` | -| `database.skip_creation` | skips the creation of tables and indexes in the database | `false` | `false` | `DATABASE_SKIP_CREATION`\`VELA_DATABASE_SKIP_CREATION` | -| `database.log.level` | log level for database | `false` | `warn` | `DATABASE_LOG_LEVEL` \ `VELA_DATABASE_LOG_LEVEL` | -| `database.log.show_sql` | show sql query in logs | `false` | `false` | `DATABASE_LOG_SHOW_SQL` \ `VELA_DATABASE_LOG_SHOW_SQL` | -| `database.log.skip_notfound` | skip logging not found errors | `false` | `true` | `DATABASE_LOG_SKIP_NOTFOUND` \ `VELA_DATABASE_LOG_SKIP_NOTFOUND` | -| `database.log.slow_threshold` | queries higher than this value are considered slow and logged | `false` | `200ms` | `DATABASE_LOG_SLOW_THRESHOLD` \ `VELA_DATABASE_LOG_SLOW_THRESHOLD` | - -:::note -For more information on these configuration options, please see the [server reference](/docs/reference/installation/server/server.md). -::: - -## Drivers - -The following drivers are available to configure the component: - -| Name | Description | Documentation | -| ---------- | --------------------------------------------------- | --------------------------- | -| `postgres` | uses a PostgreSQL database for storing data at rest | https://www.postgresql.org/ | -| `sqlite3` | uses a SQLite database for storing data at rest | https://www.sqlite.org/ | - -### Postgres - -From the [PostgreSQL official website](https://www.postgresql.org/): - -> PostgreSQL is a powerful, open source object-relational database system with over 30 years of active development that has earned it a strong reputation for reliability, feature robustness, and performance. - -The below configuration displays an example of starting the Vela server that will connect to a Postgres database: - -```diff -$ docker run \ - --detach=true \ - --env=VELA_ADDR=https://vela-server.example.com \ -+ --env=VELA_DATABASE_DRIVER=postgres \ -+ --env=VELA_DATABASE_ADDR=postgres://:@:/ \ - --env=VELA_DATABASE_ENCRYPTION_KEY= \ - --env=VELA_QUEUE_DRIVER=redis \ - --env=VELA_QUEUE_ADDR=redis://@:/ \ - --env=VELA_PORT=443 \ - --env=VELA_SECRET= \ - --env=VELA_SERVER_PRIVATE_KEY= \ - --env=VELA_SCM_CLIENT= \ - --env=VELA_SCM_SECRET= \ - --env=VELA_WEBUI_ADDR=https://vela.example.com \ - --name=server \ - --publish=80:80 \ - --publish=443:443 \ - --restart=always \ - target/vela-server:latest -``` - -### Sqlite3 - -From the [Sqlite official website](https://www.sqlite.org/): - -> SQLite is a C-language library that implements a small, fast, self-contained, high-reliability, full-featured, SQL database engine. SQLite is the most used database engine in the world. SQLite is built into all mobile phones and most computers and comes bundled inside countless other applications that people use every day. - -The below configuration displays an example of starting the Vela server that will connect to a Sqlite database: - -```diff -$ docker run \ - --detach=true \ - --env=VELA_ADDR=https://vela-server.example.com \ -+ --env=VELA_DATABASE_DRIVER=sqlite3 \ -+ --env=VELA_DATABASE_ADDR=vela.sqlite \ - --env=VELA_DATABASE_ENCRYPTION_KEY= \ - --env=VELA_QUEUE_DRIVER=redis \ - --env=VELA_QUEUE_ADDR=redis://@:/ \ - --env=VELA_PORT=443 \ - --env=VELA_SECRET= \ - --env=VELA_SERVER_PRIVATE_KEY= \ - --env=VELA_SCM_CLIENT= \ - --env=VELA_SCM_SECRET= \ - --env=VELA_WEBUI_ADDR=https://vela.example.com \ - --name=server \ - --publish=80:80 \ - --publish=443:443 \ - --restart=always \ - target/vela-server:latest -``` - -:::note -This Sqlite configuration is enabled by default and is not necessary to provide in order for Vela to operate. -::: \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/installation/server/queue.md b/versioned_docs/version-0.26/reference/installation/server/queue.md deleted file mode 100644 index c498e98..0000000 --- a/versioned_docs/version-0.26/reference/installation/server/queue.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: "Queue" -linkTitle: "Queue" -weight: 4 -description: > - This section contains information on the queue component for the Vela server. ---- - -This component is responsible for integrating with a queue system based off the configuration provided. - -The queue system is used by the Vela server for pushing workloads that will be run by a [worker](/docs/installation/worker/worker.md). - -Workloads published to the queue are managed with a [first in, first out (FIFO)](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics)) strategy. - -## Configuration - -The following options are used to configure the component: - -| Name | Description | Required | Default | Environment Variables | -| ------------------- | ------------------------------------------------------------- | -------- | ---------- | ----------------------------------------------- | -| `queue.addr` | full connection string to the queue | `true` | `N/A` | `QUEUE_ADDR`\`VELA_QUEUE_ADDR` | -| `queue.cluster` | configures the client for a queue cluster | `false` | `false` | `QUEUE_CLUSTER`\`VELA_QUEUE_CLUSTER` | -| `queue.driver` | type of client to control and operate queue | `true` | `N/A` | `QUEUE_DRIVER`\`VELA_QUEUE_DRIVER` | -| `queue.pop.timeout` | timeout for requests that pop items off the queue | `true` | `60s` | `QUEUE_POP_TIMEOUT`\`VELA_QUEUE_POP_TIMEOUT` | -| `queue.routes` | unique channels or topics for pushing workloads | `true` | `[ vela ]` | `QUEUE_ROUTES`\`VELA_QUEUE_ROUTES` | -| `queue.private-key` | private key for signing items prior to push | `false` | `N/A` | `QUEUE_PRIVATE_KEY`\`VELA_QUEUE_PRIVATE_KEY` | -| `queue.public-key` | public key for opening items after popping them off the queue | `false` | `N/A` | `QUEUE_PUBLIC_KEY`\`VELA_QUEUE_PUBLIC_KEY` | - -:::note -For more information on these configuration options, please see the [server reference](/docs/reference/installation/server/server.md). -::: - -## Drivers - -The following drivers are available to configure the component: - -| Name | Description | Documentation | -| ------- | ----------------------------------------- | ----------------- | -| `redis` | uses a Redis queue for managing workloads | https://redis.io/ | - -### Redis - -From the [Redis official website](https://redis.io/): - -> Redis is an open source (BSD licensed), in-memory data structure store, used as a database, cache, and message broker. Redis provides data structures such as strings, hashes, lists, sets, sorted sets with range queries, bitmaps, hyperloglogs, geospatial indexes, and streams. Redis has built-in replication, Lua scripting, LRU eviction, transactions, and different levels of on-disk persistence, and provides high availability via Redis Sentinel and automatic partitioning with Redis Cluster. - -The below configuration displays an example of starting the Vela server that will connect to a Redis queue: - -```diff -$ docker run \ - --detach=true \ - --env=VELA_ADDR=https://vela-server.example.com \ - --env=VELA_DATABASE_ENCRYPTION_KEY= \ -+ --env=VELA_QUEUE_DRIVER=redis \ -+ --env=VELA_QUEUE_ADDR=redis://@:/ \ -+ --env=VELA_QUEUE_PRIVATE_KEY= \ -+ --env=VELA_QUEUE_PUBLIC_KEY= \ - --env=VELA_PORT=443 \ - --env=VELA_SECRET= \ - --env=VELA_SERVER_PRIVATE_KEY= \ - --env=VELA_SCM_CLIENT= \ - --env=VELA_SCM_SECRET= \ - --env=VELA_WEBUI_ADDR=https://vela.example.com \ - --name=server \ - --publish=80:80 \ - --publish=443:443 \ - --restart=always \ - target/vela-server:latest -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/installation/server/scm.md b/versioned_docs/version-0.26/reference/installation/server/scm.md deleted file mode 100644 index 0ff523c..0000000 --- a/versioned_docs/version-0.26/reference/installation/server/scm.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: "SCM" -linkTitle: "SCM" -weight: 6 -description: > - This section contains information on the scm component for the Vela server. ---- - -This component is responsible for integrating with a source control management (SCM) system based off the configuration provided. - -The SCM system is used by Vela for both authentication and authorization of interactions performed within the application. - -![Authentication Workflow](/img/reference/authentication_workflow.png) - -## Configuration - -The following options are used to configure the component: - -| Name | Description | Required | Default | Environment Variables | -| ------------------ | --------------------------------------------------------------- | -------- | -------------------------------------------------------- | --------------------------------------------- | -| `scm.addr` | fully qualified url for the SCM | `true` | `https://github.com` | `SCM_ADDR`\`VELA_SCM_ADDR` | -| `scm.client` | client ID from the generated OAuth application on the SCM | `true` | `N/A` | `SCM_CLIENT`\`VELA_SCM_CLIENT` | -| `scm.context` | message to set in commit status on the SCM | `true` | `continuous-integration/vela` | `SCM_CONTEXT`\`VELA_SCM_CONTEXT` | -| `scm.driver` | type of client to control and operate SCM | `true` | `github` | `SCM_DRIVER`\`VELA_SCM_DRIVER` | -| `scm.scopes` | permission scopes to apply for the OAuth credentials on the SCM | `true` | `[ repo, repo:status, user:email, read:user, read:org ]` | `SCM_SCOPES`\`VELA_SCM_SCOPES` | -| `scm.secret` | client secret from the generated OAuth application on the SCM | `true` | `N/A` | `SCM_SECRET`\`VELA_SCM_SECRET` | -| `scm.webhook.addr` | url for webhooks on the SCM to send requests to | `false` | the address of the Vela server (`$VELA_ADDR`) | `SCM_WEBHOOK_ADDR`\`VELA_SCM_WEBHOOK_ADDR` | - -:::note -For more information on these configuration options, please see the [server reference](/docs/reference/installation/server/server.md). -::: - -## Drivers - -The following drivers are available to configure the component: - -| Name | Description | Documentation | -| -------- | ----------------------------------------------------- | ------------------------- | -| `github` | uses a GitHub or GitHug Enterprise Server for the SCM | https://github.com/about/ | - -### GitHub - -From the [GitHub official website](https://github.com/about/): - -> GitHub is where the world builds software. Millions of developers and companies build, ship, and maintain their software on GitHub—the largest and most advanced development platform in the world. - -The below configuration displays an example of creating a [GitHub OAuth application](https://docs.github.com/developers/apps/building-oauth-apps/creating-an-oauth-app): - -![OAuth Application](/img/reference/github_oauth.png) - -:::warning -The `Homepage URL` should match [the `VELA_ADDR` environment variable](/reference/installation/server#vela_addr) provided to the server for clusters without a UI. - -Otherwise, the `Homepage URL` should match [the `VELA_WEBUI_ADDR` environment variable](/reference/installation/server#vela_webui_addr) provided to the server. - -The `Authorization callback URL` should contain [the `VELA_ADDR` environment variable](/reference/installation/server#vela_addr) with a `/authenticate` suffix. -::: - -### GitHub Enterprise Server - -From the [GitHub Enterprise official website](https://docs.github.com/en/enterprise-server/admin/overview/system-overview): - -> GitHub Enterprise Server is your organization's private copy of GitHub contained within a virtual appliance, hosted on premises or in the cloud, that you configure and control. - -The below configuration displays an example of creating a [GitHub Enterprise Server OAuth application](https://docs.github.com/enterprise-server@3.3/developers/apps/building-oauth-apps/creating-an-oauth-app): - -![OAuth Application](/img/reference/github_enterprise_oauth.png) - -:::warning -The `Homepage URL` should match [the `VELA_ADDR` environment variable](/reference/installation/server#vela_addr) provided to the server for clusters without a UI. - -Otherwise, the `Homepage URL` should match [the `VELA_WEBUI_ADDR` environment variable](/reference/installation/server#vela_webui_addr) provided to the server. - -The `Authorization callback URL` should contain [the `VELA_ADDR` environment variable](/reference/installation/server#vela_addr) with a `/authenticate` suffix. -::: \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/installation/server/secret.md b/versioned_docs/version-0.26/reference/installation/server/secret.md deleted file mode 100644 index 74f3ae6..0000000 --- a/versioned_docs/version-0.26/reference/installation/server/secret.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: "Secret" -linkTitle: "Secret" -weight: 5 -description: > - This section contains information on the secret component for the Vela server. ---- - -This component is optional and is responsible for integrating with an external secret system based off the configuration provided. - -The secret system is used by Vela for storing sensitive application [data at rest](https://en.wikipedia.org/wiki/Data_at_rest). - -By default, Vela will use [the database](docs/reference/installation/server/database.md) to store the sensitive data if no other secret system is configured. - -:::note -Any sensitive data stored in the database will be encrypted using the [Advanced Encryption Standard (AES)](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard). -::: - -## Configuration - -The following options are used to configure the component: - -| Name | Description | Required | Default | Environment Variables | -| -------------------------- | ---------------------------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------- | -| `secret.vault.addr` | fully qualified url to the HashiCorp Vault instance | `true` | `N/A` | `SECRET_VAULT_ADDR`\`VELA_SECRET_VAULT_ADDR` | -| `secret.vault.auth-method` | authentication method used to obtain token from the HashiCorp Vault instance | `false` | `N/A` | `SECRET_VAULT_AUTH_METHOD`\`VELA_SECRET_VAULT_AUTH_METHOD` | -| `secret.vault.aws-role` | HashiCorp Vault role used to connect to the auth/aws/login endpoint | `false` | `N/A` | `SECRET_VAULT_AWS_ROLE`\`VELA_SECRET_VAULT_AWS_ROLE` | -| `secret.vault.driver` | enables HashiCorp Vault as a secret engine | `true` | `false` | `SECRET_VAULT`\`VELA_SECRET_VAULT` | -| `secret.vault.prefix` | prefix for k/v secrets in the HashiCorp Vault instance | `false` | `N/A` | `SECRET_VAULT_PREFIX`\`VELA_SECRET_VAULT_PREFIX` | -| `secret.vault.renewal` | frequency to renew the token for the HashiCorp Vault instance | `false` | `30m` | `SECRET_VAULT_RENEWAL`\`VELA_SECRET_VAULT_RENEWAL` | -| `secret.vault.token` | token required to access the HashiCorp Vault instance | `true` | `N/A` | `SECRET_VAULT_TOKEN`\`VELA_SECRET_VAULT_TOKEN` | -| `secret.vault.version` | version for the k/v backend for the HashiCorp Vault instance | `true` | `2` | `SECRET_VAULT_VERSION`\`VELA_SECRET_VAULT_VERSION` | - -:::note -For more information on these configuration options, please see the [server reference](/docs/reference/installation/server/server.md). -::: - -## Drivers - -The following drivers are available to configure the component: - -| Name | Description | Documentation | -| ------- | ------------------------------------------------------------------ | ---------------------------- | -| `vault` | uses a HashiCorp Vault instance for storing sensitive data at rest | https://www.vaultproject.io/ | - -### HashiCorp Vault - -From the [HashiCorp Vault official website](https://www.vaultproject.io/): - -> HashiCorp Vault enables you to secure, store and tightly control access to tokens, passwords, certificates, encryption keys for protecting secrets and other sensitive data using a UI, CLI, or HTTP API. - -The below configuration displays an example of starting the Vela server that will connect to a HashiCorp Vault instance: - -```diff -$ docker run \ - --detach=true \ - --env=VELA_ADDR=https://vela-server.example.com \ - --env=VELA_DATABASE_ENCRYPTION_KEY= \ - --env=VELA_QUEUE_DRIVER=redis \ - --env=VELA_QUEUE_ADDR=redis://@:/ \ - --env=VELA_PORT=443 \ - --env=VELA_SECRET= \ - --env=VELA_SERVER_PRIVATE_KEY= \ -+ --env=VELA_SECRET_VAULT=true \ -+ --env=VELA_SECRET_VAULT_ADDR=https://vault.example.com \ -+ --env=VELA_SECRET_VAULT_TOKEN= - --env=VELA_SCM_CLIENT= \ - --env=VELA_SCM_SECRET= \ - --env=VELA_WEBUI_ADDR=https://vela.example.com \ - --name=server \ - --publish=80:80 \ - --publish=443:443 \ - --restart=always \ - target/vela-server:latest -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/installation/server/server.md b/versioned_docs/version-0.26/reference/installation/server/server.md deleted file mode 100644 index 30153bf..0000000 --- a/versioned_docs/version-0.26/reference/installation/server/server.md +++ /dev/null @@ -1,907 +0,0 @@ ---- -no_list: true -title: "Server" -sidebar_position: 1 -weight: 4 -description: > - This section contains a reference of configuration options for the Vela server service. ---- - -## Components - -The server is made up of several components, responsible for specific tasks, necessary for the service to operate: - -| Name | Description | -| ---------- | ----------------------------------------------------------------------------------------------------------------- | -| `settings` | keeps track of updated runtime properties for the [server](/docs/installation/server/server.md) | -| `compiler` | transforms a [pipeline](/docs/usage/tour/tour.md) into an executable workload for the [worker](/docs/installation/worker/worker.md) | -| `database` | integrates with a database provider for storing application data at rest | -| `queue` | integrates with a queue provider for pushing workloads that will be run by a [worker](/docs/installation/worker/worker.md) | -| `secret` | integrates with a secret provider for storing sensitive application data at rest | -| `source` | integrates with a source control management (SCM) provider for authentication and authorization | -| `tracing` | implements OpenTelemetry tracing instrumentation for the [server](/docs/installation/server/server.md) | - -## Required - -This section contains a list of all variables that must be provided to the server. - -Some properties can be updated while the server is running using the [settings component](/docs/reference/installation/server/settings.md). - -### VELA_ADDR - -This variable sets a fully qualified URL to the Vela [server](/docs/installation/server/server.md) address. - -The variable should be provided as a `string`. - -### VELA_DATABASE_ENCRYPTION_KEY - -This configuration variable is used by the [database component](/docs/reference/installation/server/database.md) for the server. - -Examples using this configuration variable are provided in the above reference documentation. - -This variable sets the AES key for encrypting/decrypting values for data stored in the database. - -The variable should be provided as an `string`. - -### VELA_QUEUE_ADDR - -This configuration variable is used by the [queue component](/docs/reference/installation/server/queue.md) for the server. - -Examples using this configuration variable are provided in the above reference documentation. - -This variable sets a fully qualified URL to the queue instance for pushing workloads that will be run by a [worker](/docs/installation/worker/worker.md). - -The variable should be provided as a `string`. - -### VELA_QUEUE_DRIVER - -This configuration variable is used by the [queue component](/docs/reference/installation/server/queue.md) for the server. - -Examples using this configuration variable are provided in the above reference documentation. - -This variable sets the driver to use for the queue functionality for the server. - -The variable should be provided as a `string`. - -:::note -This variable should match [the `VELA_QUEUE_DRIVER` variable](/reference/installation/worker/#vela_queue_driver) provided to the worker. - -The possible options to provide for this variable are: - -* `redis` -::: - -### VELA_SCM_CLIENT - -This configuration variable is used by the [SCM component](/docs/reference/installation/server/scm.md) for the server. - -This variable sets the client ID from the OAuth application created on the SCM system. - -The variable should be provided as a `string`. - -### VELA_SCM_SECRET - -This configuration variable is used by the [SCM component](/docs/reference/installation/server/scm.md) for the server. - -This variable sets the client secret from the OAuth application created on the SCM system. - -The variable should be provided as a `string`. - -### VELA_SERVER_PRIVATE_KEY - -This variable sets the private key that will be used to sign all JWT tokens within Vela. Please be sure to follow [guidelines](https://www.rfc-editor.org/rfc/rfc2104#section-3) related to generating a private key. - -The variable should be provided as a `string`. - -## Optional - -This section contains a list of all variables that can be provided to the server. - -Some properties can be updated while the server is running using the [settings component](/docs/reference/installation/server/settings.md). - -### VELA_CLONE_IMAGE - -This configuration variable is used by the [compiler component](/docs/reference/installation/server/compiler.md) for the server. - -The clone image sets the clone image to use for the Vela injected clone step in a pipeline. - -By default, Vela will use the latest available release of the clone image at the time of a server release. - -This variable should be provided as a `string`. - -This property can be updated while the server is running using the [settings component](/docs/reference/installation/server/settings.md). - -### VELA_COMPILER_GITHUB - -This configuration variable is used by the [compiler component](/docs/reference/installation/server/compiler.md) for the server. - -Examples using this configuration variable are provided in the above reference documentation. - -This variable enables using GitHub or GitHub Enterprise Server as a registry for fetching pipeline [templates](docs/usage/tour/templates.md) from. - -By default, Vela will use [GitHub](https://github.com/) as a registry for fetching templates. - -However, to fetch templates from a private organization or repository on GitHub, you need to provide this configuration. - -The variable can be provided as a `boolean`. - -:::note -This variable has a default value of `false`. -::: - -### VELA_COMPILER_GITHUB_TOKEN - -This configuration variable is used by the [compiler component](/docs/reference/installation/server/compiler.md) for the server. - -Examples using this configuration variable are provided in the above reference documentation. - -This variable sets a [Personal Access Token (PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) for fetching pipeline [templates](docs/usage/tour/templates.md) from GitHub or GitHub Enterprise Server. - -By default, Vela will use [GitHub](https://github.com/) as a registry for fetching templates. - -However, to fetch templates from a private organization or repository on GitHub, you need to provide this configuration. - -The variable can be provided as a `string`. - -### VELA_COMPILER_GITHUB_URL - -This configuration variable is used by the [compiler component](/docs/reference/installation/server/compiler.md) for the server. - -Examples using this configuration variable are provided in the above reference documentation. - -This variable sets a fully qualified URL to GitHub or GitHub Enterprise Server used for fetching pipeline [templates](docs/usage/tour/templates.md) from. - -By default, Vela will use [GitHub](https://github.com/) as a registry for fetching templates. - -However, to fetch templates from a private organization or repository on GitHub, you need to provide this configuration. - -The variable can be provided as a `string`. - -### VELA_DATABASE_ADDR - -This configuration variable is used by the [database component](/docs/reference/installation/server/database.md) for the server. - -Examples using this configuration variable are provided in the above reference documentation. - -This variable sets a fully qualified URL to the database instance for storing data at rest. - -The variable can be provided as a `string`. - -:::note -This variable has a default value of `vela.sqlite`. -::: - -### VELA_DATABASE_COMPRESSION_LEVEL - -This configuration variable is used by the [database component](/docs/reference/installation/server/database.md) for the server. - -This variable sets the level of compression for workload logs, uploaded by the Vela [worker](/docs/installation/worker/worker.md), which are stored in the database. - -The variable can be provided as an `integer`. - -:::note -This variable has a default value of `3`. - -The possible options to provide for this variable are: - -* `-1` -* `0` - produces no compression for the log data -* `1` - produces compression for the log data the fastest and with the largest size of data -* `2` -* `3` -* `4` -* `5` - produces compression for the log data with an even balance of speed and size of data -* `6` -* `7` -* `8` -* `9` - produces compression for the log data the slowest and with the smallest size of data -::: - -### VELA_DATABASE_CONNECTION_IDLE - -This configuration variable is used by the [database component](/docs/reference/installation/server/database.md) for the server. - -This variable sets the maximum number of [idle connections](https://pkg.go.dev/database/sql#DB.SetMaxIdleConns) allowed for the database client. - -The variable can be provided as an `integer`. - -:::note -This variable has a default value of `2`. -::: - -### VELA_DATABASE_CONNECTION_LIFE - -This configuration variable is used by the [database component](/docs/reference/installation/server/database.md) for the server. - -This variable sets the maximum duration of time [a connection is reusable](https://pkg.go.dev/database/sql#DB.SetConnMaxLifetime) for the database client. - -The variable can be provided as a `duration` (i.e. `5s`, `10m`). - -:::note -This variable has a default value of `30m`. -::: - -### VELA_DATABASE_CONNECTION_OPEN - -This configuration variable is used by the [database component](/docs/reference/installation/server/database.md) for the server. - -This variable sets the maximum number of [open connections](https://pkg.go.dev/database/sql#DB.SetMaxOpenConns) allowed for the database client. - -The variable can be provided as an `integer`. - -:::note -This variable has a default value of `0` (meaning no limit is set). -::: - -### VELA_DATABASE_DRIVER - -This configuration variable is used by the [database component](/docs/reference/installation/server/database.md) for the server. - -Examples using this configuration variable are provided in the above reference documentation. - -This variable sets the driver to use for the database functionality for the server. - -The variable can be provided as a `string`. - -:::note -This variable has a default value of `sqlite3`. - -The possible options to provide for this variable are: - -* `postgres` -* `sqlite3` -::: - -### VELA_DATABASE_SKIP_CREATION - -This configuration variable is used by the [database component](/docs/reference/installation/server/database.md) for the server. - -This variable enables skipping the creation of tables and indexes in the database system. - -The variable can be provided as a `boolean`. - -:::note -This variable has a default value of `false`. -::: - -### VELA_DATABASE_LOG_LEVEL - -This configuration variable is used by the [database component](/docs/reference/installation/server/database.md) for the server. - -This variable controls the log level to use in the database system. This can be different than the log level for the rest of the application. - -The variable can be provided as a `string` (trace, debug, info, warn, error, fatal, panic). - -:::note -This variable has a default value of `warn`. -::: - -### VELA_DATABASE_LOG_SHOW_SQL - -This configuration variable is used by the [database component](/docs/reference/installation/server/database.md) for the server. - -This variable controls whether to show the SQL query in the logs for the database system. - -The variable can be provided as a `boolean`. - -:::note -This variable has a default value of `false`. -::: - -### VELA_DATABASE_LOG_SKIP_NOTFOUND - -This configuration variable is used by the [database component](/docs/reference/installation/server/database.md) for the server. - -This variable controls whether to skip showing record not found errors in the logs for the in the database system. - -The variable can be provided as a `boolean`. - -:::note -This variable has a default value of `true`. -::: - -### VELA_DATABASE_LOG_SLOW_THRESHOLD - -This configuration variable is used by the [database component](/docs/reference/installation/server/database.md) for the server. - -This variable controls the threshold that determines which queries are considered slow and logged in the database system. - -The variable can be provided as a `duration`. - -:::note -This variable has a default value of `200ms`. -::: - -### VELA_DEFAULT_BUILD_LIMIT - -This variable sets the default amount of concurrent builds a repo is allowed to run. - -In this context, concurrent builds refers to any `pending` or `running` builds for that repo. - -If the amount of concurrent builds for a repo matches the limit, then any new builds will be blocked from being created. - -The variable can be provided as an `integer`. - -:::note -This variable has a default value of `10`. -::: - -### VELA_DEFAULT_BUILD_TIMEOUT - -This variable sets the default duration of time a build is allowed to run on a worker. - -The variable can be provided as an `integer`. - -:::note -This variable has a default value of `30`. -::: - -### VELA_DEFAULT_REPO_EVENTS - -This variable sets the default active events for newly activated repositories. - -The variable can be provided as a comma-separated `list` (i.e. `push,tag,deployment`). - -:::note -By default, the `push` event is enabled. Valid values are: `push`, `pull_request`, `tag`, `deployment`, and `comment`. -::: - -### VELA_DISABLE_WEBHOOK_VALIDATION - -This variable disables validation of webhooks sent by the SCM to the server. - -The variable can be provided as a `boolean`. - -:::note -This variable should only be used for local development. - -This variable has a default value of `false`. -::: - -### VELA_ENABLE_SECURE_COOKIE - -This enables using cookies with the secure flag set by the server. - -The variable can be provided as a `boolean`. - -:::note -This variable should only be used for local development. - -This variable has a default value of `true`. -::: - -### VELA_LOG_FORMATTER - -This variable sets whether the logging formatter used for structured server logs is a standard JSON logger, or a custom Elasticsearch Common Schema (ECS) compatible JSON formatter. - -The variable can be provided as a `string`. - -:::note -This variable has a default value of `json`. Valid values are: `json`, and `ecs`. -::: - -### VELA_MAX_BUILD_LIMIT - -This variable sets the maximum amount of concurrent builds a repo is allowed to run. - -In this context, concurrent builds refers to any `pending` or `running` builds for that repo. - -If the amount of concurrent builds for a repo matches the limit, then any new builds will be blocked from being created. - -The variable can be provided as an `integer`. - -:::note -This variable has a default value of `30`. - -This variable should match [the `VELA_MAX_BUILD_LIMIT` variable](/reference/installation/ui/#vela_max_build_limit) provided to the UI. -::: - -### VELA_MODIFICATION_ADDR - -This configuration variable is used by the [compiler component](/docs/reference/installation/server/compiler.md) for the server. - -This variable sets a fully qualified URL to the modification endpoint used for the compiler. - -The variable can be provided as a `string`. - -### VELA_MODIFICATION_RETRIES - -This configuration variable is used by the [compiler component](/docs/reference/installation/server/compiler.md) for the server. - -This variable sets the maximum number of times to resend failed requests to the modification endpoint for the compiler. - -The variable can be provided as an `integer`. - -:::note -This variable has a default value of `5`. -::: - -### VELA_MODIFICATION_SECRET - -This configuration variable is used by the [compiler component](/docs/reference/installation/server/compiler.md) for the server. - -This variable sets a shared secret for authenticating communication between the compiler and the modification endpoint. - -The variable can be provided as a `string`. - -### VELA_MODIFICATION_TIMEOUT - -This configuration variable is used by the [compiler component](/docs/reference/installation/server/compiler.md) for the server. - -This variable sets the maximum duration of time the compiler will wait before timing out requests sent to the modification endpoint. - -The variable can be provided as a `duration` (i.e. `5s`, `10m`). - -:::note -This variable has a default value of `8s`. -::: - -### VELA_MAX_TEMPLATE_DEPTH - -This configuration variable is used by the [compiler component](/docs/reference/installation/server/compiler.md) for the server. - -This variable sets the maximum depth of nested templates that can be called during compilation. - -The variable can be provided as an `integer`. - -:::note -This variable has a default value of `3`. -::: - -This property can be updated while the server is running using the [settings component](/docs/reference/installation/server/settings.md). - -### VELA_COMPILER_STARLARK_EXEC_LIMIT - -This configuration variable is used by the [compiler component](/docs/reference/installation/server/compiler.md) for the server. - -This variable sets the starlark execution step limit for compiling starlark pipelines. - -The variable can be provided as an `integer`. - -:::note -This variable has a default value of `7500`. -::: - -This property can be updated while the server is running using the [settings component](/docs/reference/installation/server/settings.md). - -### VELA_PORT - -This variable sets the port the server API responds on for HTTP requests. - -The variable can be provided as a `string`. - -:::note -This variable has a default value of `8080`. -::: - -### VELA_QUEUE_CLUSTER - -This configuration variable is used by the [queue component](/docs/reference/installation/server/queue.md) for the server. - -This variable enables the server to connect to a queue cluster rather than a standalone instance. - -The variable can be provided as a `boolean`. - -:::note -This variable should match [the `VELA_QUEUE_CLUSTER` variable](/reference/installation/worker/#vela_queue_cluster) provided to the worker. -::: - -### VELA_QUEUE_POP_TIMEOUT - -This configuration variable is unused by the [queue component](/docs/reference/installation/server/queue.md) for the server. - -This variable sets the maximum duration of time the worker will wait before timing out requests sent for pushing workloads. - -The variable can be provided as a `duration` (i.e. `5s`, `10m`). - -:::note -This variable has a default value of `60s`. -::: - -### VELA_QUEUE_ROUTES - -This configuration variable is used by the [queue component](/docs/reference/installation/server/queue.md) for the server. - -This variable sets the unique channels or topics to push workloads to. - -The variable can be provided as a comma-separated `list` (i.e. `myRoute1,myRoute2`). - -:::note -This variable has a default value of `vela`. -::: - -This property can be updated while the server is running using the [settings component](/docs/reference/installation/server/settings.md). - -### VELA_QUEUE_PRIVATE_KEY - -This variable sets a private key secret for signing queue items that will be opened by the worker's \. - -The variable should be provided as a base64 encoded `string`. - -### VELA_QUEUE_PUBLIC_KEY - -This variable sets a public key secret for opening queue items that have been signed by the server's \. - -The variable should be provided as a base64 encoded `string`. - -### VELA_REPO_ALLOWLIST - -This variable sets a group of repositories, from the SCM, that can be enabled on the server. - -The variable can be provided as a comma-separated `list` (i.e. `myOrg1/myRepo1,myOrg1/myRepo2,myOrg2/*`). - -:::note -By default, no repositories are allowed to be enabled. To allow any repository to be enabled, provide a single value of `*`. -::: - -This property can be updated while the server is running using the [settings component](/docs/reference/installation/server/settings.md). - -### VELA_SCHEDULE_ALLOWLIST - -This variable sets a group of repositories, from the SCM, that can create a schedule for a repo on the server. - -The variable can be provided as a comma-separated `list` (i.e. `myOrg1/myRepo1,myOrg1/myRepo2,myOrg2/*`). - -:::note -By default, no repositories are allowed to create a schedule. To allow any repository to create a schedule, provide a single value of `*`. -::: - -This property can be updated while the server is running using the [settings component](/docs/reference/installation/server/settings.md). - -### VELA_SCHEDULE_MINIMUM_FREQUENCY - -This variable sets the minimum frequency allowed to be set for a schedule. - -The variable can be provided as a `duration` (i.e. `5s`, `10m`). - -:::note -This variable has a default value of `1h`. -::: - -### VELA_SCM_ADDR - -This configuration variable is used by the [SCM component](/docs/reference/installation/server/scm.md) for the server. - -This variable sets a fully qualified URL to the source control management (SCM) system. - -The variable can be provided as a `string`. - -:::note -This variable has a default value of `https://github.com`. -::: - -### VELA_SCM_CONTEXT - -This configuration variable is used by the [SCM component](/docs/reference/installation/server/scm.md) for the server. - -This variable sets the message to set in the commit status on the SCM system. - -The variable can be provided as a `string`. - -:::note -This variable has a default value of `continuous-integration/vela`. -::: - -### VELA_SCM_DRIVER - -This configuration variable is used by the [SCM component](/docs/reference/installation/server/scm.md) for the server. - -This variable sets the driver to use for the SCM functionality for the server. - -The variable can be provided as a `string`. - -:::note -This variable has a default value of `github`. - -The possible options to provide for this variable are: - -* `github` -::: - -### VELA_SCM_SCOPES - -This configuration variable is used by the [SCM component](/docs/reference/installation/server/scm.md) for the server. - -This variable sets the permission scopes to apply for OAuth credentials captured from the SCM system. - -The variable can be provided as a comma-separated `list` (i.e. `myScope1,myScope2`). - -:::note -This variable has a default value of `read:org,read:user,repo,repo:status,user:email`. -::: - -### VELA_SCM_WEBHOOK_ADDR - -This configuration variable is used by the [SCM component](/docs/reference/installation/server/scm.md) for the server. - -This variable sets a fully qualified URL on the SCM system to send webhooks to the server. - -The variable can be provided as a `string`. - -:::note -This variable has a default value of [the `VELA_ADDR` variable](/reference/installation/server#vela_addr) provided to the server. -::: - -### VELA_SECRET - -This variable sets a shared secret with the Vela [worker](/docs/installation/worker/worker.md) for authenticating communication between workers and the server. - -Only necessary to provide if utilizing the [server-worker trusted symmetric worker authentication method](/installation/worker/docker/#worker-server-trusted-symmetric-token). - -The variable should be provided as a `string`. - -:::note -This variable should match [the `VELA_SERVER_SECRET` variable](/reference/installation/worker/#vela_server_secret) provided to the worker. -::: - -### VELA_SECRET_VAULT - -This configuration variable is used by the [secret component](/docs/reference/installation/server/secret.md) for the server. - -Examples using this configuration variable are provided in the above reference documentation. - -This variable enables using HashiCorp Vault as a secret engine. - -The variable can be provided as a `boolean`. - -:::note -This variable has a default value of `false`. -::: - -### VELA_SECRET_VAULT_ADDR - -This configuration variable is used by the [secret component](/docs/reference/installation/server/secret.md) for the server. - -Examples using this configuration variable are provided in the above reference documentation. - -This variable sets a fully qualified URL to the HashiCorp Vault instance. - -The variable can be provided as a `string`. - -### VELA_SECRET_VAULT_AUTH_METHOD - -This configuration variable is used by the [secret component](/docs/reference/installation/server/secret.md) for the server. - -This variable sets the authentication method to obtain a token from the HashiCorp Vault instance. - -The variable can be provided as a `string`. - -### VELA_SECRET_VAULT_AWS_ROLE - -This configuration variable is used by the [secret component](/docs/reference/installation/server/secret.md) for the server. - -This variable sets the HashiCorp Vault role to connect to the `auth/aws/login` endpoint. - -The variable can be provided as a `string`. - -### VELA_SECRET_VAULT_PREFIX - -This configuration variable is used by the [secret component](/docs/reference/installation/server/secret.md) for the server. - -This variable sets the prefix for k/v secrets in the HashiCorp Vault instance. - -The variable can be provided as a `string`. - -### VELA_SECRET_VAULT_RENEWAL - -This configuration variable is used by the [secret component](/docs/reference/installation/server/secret.md) for the server. - -This variable sets the frequency to renew the token for the HashiCorp Vault instance. - -The variable can be provided as a `duration` (i.e. `5s`, `10m`). - -:::note -This variable has a default value of `30m`. -::: - -### VELA_SECRET_VAULT_TOKEN - -This configuration variable is used by the [secret component](/docs/reference/installation/server/secret.md) for the server. - -Examples using this configuration variable are provided in the above reference documentation. - -This variable sets the token for accessing the HashiCorp Vault instance. - -The variable can be provided as a `string`. - -### VELA_SECRET_VAULT_VERSION - -This configuration variable is used by the [secret component](/docs/reference/installation/server/secret.md) for the server. - -This variable sets the version for the k/v backend for the HashiCorp Vault instance. - -The variable can be provided as a `string`. - -:::note -This variable has a default value of `2`. -::: - -### VELA_USER_ACCESS_TOKEN_DURATION - -This variable sets the maximum duration of time a Vela access token for a user is valid on the server. - -The access token is used for authenticating user's requests to the server. - -The variable can be provided as a `duration` (i.e. `5s`, `10m`). - -:::note -This variable has a default value of `15m`. -::: - -### VELA_USER_REFRESH_TOKEN_DURATION - -This variable sets the maximum duration of time a Vela refresh token for a user is valid on the server. - -The refresh token is used for refreshing a user's access token on the server. - -The variable can be provided as a `duration` (i.e. `5s`, `10m`). - -:::note -This variable has a default value of `8h`. -::: - -### VELA_BUILD_TOKEN_BUFFER_DURATION - -This variable sets the maximum duration of time a Vela build token for a build extends beyond the repo build limit to maintain validity on the server. - -The build token is used for authenticating a worker's access to the server to update build resources. - -The variable can be provided as a `duration` (i.e. `5s`, `10m`). - -:::note -This variable has a default value of `5m`. -::: - -### VELA_WEBUI_ADDR - -This variable sets a fully qualified URL to the Vela [UI](/docs/installation/ui/ui.md) address. - -The variable can be provided as a `string`. - -### VELA_WEBUI_OAUTH_CALLBACK_PATH - -This variable sets the endpoint to use for the OAuth callback path for the Vela [UI](/docs/installation/ui/ui.md). - -The variable can be provided as a `string`. - -:::note -This variable has a default value of `/account/authenticate`. -::: - -### VELA_WORKER_AUTH_TOKEN_DURATION - -This variable sets the maximum duration of time a Vela auth token for a worker is valid on the server. - -The worker auth token is used for authenticating a worker's access to the server to check-in and request build tokens. - -The variable can be provided as a `duration` (i.e. `5s`, `10m`). - -:::note -This variable should be _longer_ than the [VELA_CHECK_IN](/reference/installation/worker/#vela_check_in) in order to be able to refresh the auth token. - -This variable has a default value of `20m`. -::: - -### VELA_WORKER_REGISTER_TOKEN_DURATION - -This variable sets the maximum duration of time a Vela registration token for a worker is valid on the server. - -The worker register token is used for onboarding a worker onto the server and beginning its auth refresh routine. - -The variable can be provided as a `duration` (i.e. `5s`, `10m`). - -:::note -This variable should be relatively short-lived. There is a [CLI Command](/docs/reference/cli/worker/add.md) to quicken the registration process for admins. - -This variable has a default value of `1m`. -::: - -### VELA_WORKER_ACTIVE_INTERVAL - -This variable sets the interval of time the workers will be considered active. A worker is considered active if it has registered with the server inside the give duration. - -The variable can be provided as a `duration` (i.e. `5s`, `10m`). - -:::note -This variable has a default value of `5m`.\ -\ -The value should coordinate with the [`VELA_CHECK_IN`](/reference/installation/worker/#vela_check_in) setting provided to the [worker](/docs/installation/worker/worker.md). -::: - -### VELA_OTEL_TRACING_ENABLE - -This variable enables [OpenTelemetry tracing](https://opentelemetry.io/docs/concepts/signals/traces/) for the Vela server. You must provide `VELA_OTEL_EXPORTER_OTLP_ENDPOINT` **when tracing is enabled**. - -:::note -This variable has a default value of `false`. -::: - -### VELA_OTEL_TRACING_SERVICE_NAME - -This variable sets the [service name](https://opentelemetry.io/docs/languages/sdk-configuration/general/) applied to [traces](https://opentelemetry.io/docs/concepts/signals/traces/). - -:::note -This variable has a default value of `vela-server`. -::: - -### VELA_OTEL_EXPORTER_OTLP_ENDPOINT - -This variable sets the [OTel exporter](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/) endpoint (ex. scheme://host:port). - -:::note -This variable has no default value.\ -\ -When tracing is enabled this variable is **required**. -::: - -### VELA_OTEL_TRACING_EXPORTER_SSL_CERT_PATH - -This variable sets the path to certs used for communicating with the [OTel exporter](https://opentelemetry.io/docs/specs/OTel/protocol/exporter/). If nothing is provided, will use insecure communication. - -:::note -This variable has no default value.\ -\ -Providing no value for this variable instructs the server to export traces insecurely (no SSL). -::: - -### VELA_OTEL_TRACING_TLS_MIN_VERSION - -This optional variable sets a TLS minimum version used when exporting traces to the [OTel exporter](https://opentelemetry.io/docs/specs/OTel/protocol/exporter/). - -:::note -This variable has a default value of `1.2`. -::: - -### VELA_OTEL_TRACING_SAMPLER_RATELIMIT_PER_SECOND - -This variable sets OTel [tracing head-sampler](https://opentelemetry.io/docs/concepts/sampling/) rate-limiting to N per second. - -:::note -This variable has a default value of `100`, meaning the server can record a maximum of `100 traces per second`. -::: - -### VELA_OTEL_TRACING_SAMPLER_TASKS_CONFIG_FILEPATH - -This variable sets an (optional) filepath to the OTel tracing head-sampler configurations json to alter how certain tasks (endpoints, queries, etc) are sampled. - -A `task` is basically the "span name" based on the work being performed. A `task` can be an API endpoint interaction, a gorm query, etc. - -See: https://opentelemetry.io/docs/specs/OTel/trace/api/#span - -:::note -This variable has no default value.\ -\ -When no path is provided all tasks are recorded using provided shared parameters. -::: - -### VELA_OTEL_TRACING_RESOURCE_ATTRIBUTES - -This variable sets OTel resource [(span) attributes](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a list of key=value pairs. each one will be attached to each span as a 'process' attribute. - -:::note -This variable has no default value. -::: - -### VELA_OTEL_TRACING_RESOURCE_ENV_ATTRIBUTES - -This variable sets OTel resource [(span) attributes](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a list of key=env_variable_key pairs. each one will be attached to each [span](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a 'process' attribute where the value is retrieved from the environment using the pair value. - -:::note -This variable has no default value. -::: - -### VELA_OTEL_TRACING_SPAN_ATTRIBUTES - -This variable sets trace [span attributes](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a list of key=value pairs. Each pair will be attached to each [span](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a 'tag' attribute. - -:::note -This variable has no default value. -::: - -### VELA_OTEL_TRACING_TRACESTATE_ATTRIBUTES - -This variable sets OTel tracestate [(span) attributes](https://www.w3.org/TR/trace-context) as a list of key=value pairs. Each pair will be inserted into the tracestate for each sampled span. - -:::note -This variable has no default value. -::: diff --git a/versioned_docs/version-0.26/reference/installation/server/settings.md b/versioned_docs/version-0.26/reference/installation/server/settings.md deleted file mode 100644 index 2b80c92..0000000 --- a/versioned_docs/version-0.26/reference/installation/server/settings.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "Settings" -linkTitle: "Settings" -weight: 1 -description: > - This section contains information on using dynamic platform settings for the Vela server. ---- - -Platform Administrators can update certain properties during runtime to change how the platform behaves in real time. - -The following properties are available to be updated: - -* [`VELA_REPO_ALLOWLIST`](/reference/installation/server/#vela_repo_allowlist) -* [`VELA_SCHEDULE_ALLOWLIST`](/reference/installation/server/#vela_schedule_allowlist) -* [`VELA_MAX_TEMPLATE_DEPTH`](/reference/installation/server/#vela_max_template_depth) -* [`VELA_COMPILER_STARLARK_EXEC_LIMIT`](/reference/installation/server/#vela_compiler_starlark_exec_limit) -* [`VELA_CLONE_IMAGE`](/reference/installation/server/#vela_clone_image) - - -## Configuration - -The following options are used to configure the component: - -| Name | Description | Required | Default | Environment Variables | -| --------------------------- | -------------------------------------------------------- | -------- | ------- | --------------------------------------------------------------------------- | -| `settings-refresh-interval` | the interval at which the server syncs with the database | `true` | `5s` | `VELA_PLATFORM_SETTINGS_REFRESH_INTERVAL`, `VELA_SETTINGS_REFRESH_INTERVAL` | - -:::note -For more information on how the runtime properties are consumed, please see the [server reference](/docs/reference/installation/server/server.md). -::: - -## Permissions - -This functionality only exists for [Platform Administrators](/docs/usage/roles.md). - -## Usage - -### Initializing - -The server will ensure shared settings are first initialized using the variables provided in the environment. For more information on how the runtime properties are configured, please see the [server reference](/docs/reference/installation/server/server.md). - -On subsequent server startups, the properties controlled by the `settings` component will be retrieved from the database. - -If the database settings record is deleted then the server will fail. On the next startup the server will re-initialize the settings record using the values provided in the environment. - -### Server Synchronization - -The server will keep its own `settings` in sync with the database according to the `settings-refresh-interval` set in the environment. - -### Viewing and Updating Properties - -To view or update settings via the user interface, log into your Vela instance and click the `site admin` link in the top right corner or navigate to `https://vela-server.example.com/admin/settings`. - -Check the [CLI docs](/docs/reference/cli/settings/settings.md) for instructions on modifying runtime properties via the command line. - -Updated properties will propagate to all server instances depending on the `settings-refresh-interval` set in the environment on startup. - -### Restoring Default Properties - -The [`DELETE /api/v1/admin/settings`](/docs/reference/api/admin/settings/restore.md) API endpoint can be used to "restore" the server to its original environment-provided configurations. Acting as a way for platform admins to undo any current modifications to the platform without restarting or modifying the database. diff --git a/versioned_docs/version-0.26/reference/installation/server/token_manager.md b/versioned_docs/version-0.26/reference/installation/server/token_manager.md deleted file mode 100644 index bef81d4..0000000 --- a/versioned_docs/version-0.26/reference/installation/server/token_manager.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: "Token Manager" -linkTitle: "Token Manager" -weight: 6 -description: > - This section contains information on the token manager component for the Vela server. ---- - -This component is responsible for generating and validating JWT tokens shared between the Vela server, workers, and users based off the configuration provided. - -The token manager is designed to ensure secure interactions with the server and protect build resources. - - -## Configuration - -The following options are used to configure the component: - -| Name | Description | Required | Default | Environment Variables | -| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- | --------------------------------------------- | -| `vela-server-private-key` | private key used for signing and validating all JWT tokens | `true` | `N/A` | `VELA_SERVER_PRIVATE_KEY` | -| `user-access-token-duration` | maximum duration of time a Vela access token for a user is valid on the server | `true` | `15m` | `VELA_USER_ACCESS_TOKEN_DURATION`\`USER_ACCESS_TOKEN_DURATION` | -| `user-refresh-token-duration` | maximum duration of time a Vela refresh token for a user is valid on the server | `true` | `8h` | `VELA_USER_ACCESS_TOKEN_DURATION`\`USER_ACCESS_TOKEN_DURATION` | -| `build-token-buffer-duration` | maximum duration of time a Vela build token for a build extends beyond the repo build limit to maintain validity on the server | `true` | `5m` | `VELA_BUILD_TOKEN_BUFFER_DURATION`\`BUILD_TOKEN_BUFFER_DURATION` | -| `worker-auth-token-duration` | maximum duration of time an auth token for a worker is valid on the server | `false`* | `20m` | `VELA_WORKER_AUTH_TOKEN_DURATION`\`WORKER_AUTH_TOKEN_DURATION` | -| `worker-register-token-duration` | maximum duration of time a registration token for a worker is valid on the server | `false`* | `1m` | `VELA_WORKER_REGISTER_TOKEN_DURATION`\`WORKER_REGISTER_TOKEN_DURATION` | - - - -:::note -\* `worker-auth-token-duration` and `worker-register-token-duration` are required if you intend to register workers. - -For more information on these configuration options, please see the [server reference](/docs/reference/installation/server/server.md). -::: diff --git a/versioned_docs/version-0.26/reference/installation/server/tracing.md b/versioned_docs/version-0.26/reference/installation/server/tracing.md deleted file mode 100644 index de9eccb..0000000 --- a/versioned_docs/version-0.26/reference/installation/server/tracing.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: "Tracing" -linkTitle: "Tracing" -weight: 7 -description: > - This section contains information on configuring OpenTelemetry instrumentation for the Vela server. ---- - -This component is responsible for instrumenting [OpenTelemetry traces](https://opentelemetry.io/docs/concepts/signals/traces/) based off the configuration provided. - -## Configuration - -The following options are used to configure the component: - -| Name | Description | Required | Default | Environment Variables | -| --------------------------- | -------------------------------------------------------- | -------- | ------- | --------------------------------------------------------------------------- | -| `tracing.enable` | This variable enables [OpenTelemetry tracing](https://opentelemetry.io/docs/concepts/signals/traces/) for the Vela server. You must provide `VELA_OTEL_EXPORTER_OTLP_ENDPOINT` **when tracing is enabled**. | `false` | `false` | `VELA_OTEL_TRACING_ENABLE` | -| `tracing.service.name` | This variable sets the [service name](https://opentelemetry.io/docs/languages/sdk-configuration/general/) applied to [traces](https://opentelemetry.io/docs/concepts/signals/traces/). | `false` | `vela-server` | `VELA_OTEL_TRACING_SERVICE_NAME` | -| `tracing.exporter.endpoint` | This variable sets the [OTel exporter](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/) endpoint (ex. scheme://host:port). | `false` | `N/A` | `VELA_OTEL_EXPORTER_OTLP_ENDPOINT` | -| `tracing.exporter.cert_path` | This variable sets the path to certs used for communicating with the [OTel exporter](https://opentelemetry.io/docs/specs/OTel/protocol/exporter/). If nothing is provided the server will use insecure communication. | `false` | `N/A` | `VELA_OTEL_TRACING_EXPORTER_SSL_CERT_PATH` | -| `tracing.exporter.tls-min-version` | This optional variable sets a TLS minimum version used when exporting traces to the [OTel exporter](https://opentelemetry.io/docs/specs/OTel/protocol/exporter/). | `false` | `1.2` | `VELA_OTEL_TRACING_TLS_MIN_VERSION` | -| `tracing.sampler.persecond` | This variable sets OTel [tracing head-sampler](https://opentelemetry.io/docs/concepts/sampling/) rate-limiting to N per second. | `false` | `100` | `VELA_OTEL_TRACING_SAMPLER_RATELIMIT_PER_SECOND` | -| `tracing.sampler.tasks` | This variable sets an (optional) filepath to the OTel tracing head-sampler configurations json to alter how certain tasks (API endpoints, queries, etc) are sampled. | `false` | `N/A` | `VELA_OTEL_TRACING_SAMPLER_TASKS_CONFIG_FILEPATH` | -| `tracing.resource.attributes` | This variable sets OTel resource [(span) attributes](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a list of `key=value` pairs. each one will be attached to each span as a 'process' attribute. | `false` | `N/A` | `VELA_OTEL_TRACING_RESOURCE_ATTRIBUTES` | -| `tracing.resource.env_attributes` | This variable sets OTel resource [(span) attributes](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a list of `key=env_variable_key` pairs. each one will be attached to each [span](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a 'process' attribute where the value is retrieved from the environment using the pair value. | `false` | `N/A` | `VELA_OTEL_TRACING_RESOURCE_ENV_ATTRIBUTES` | -| `tracing.span.attributes` | This variable sets trace [span attributes](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a list of `key=value` pairs. Each pair will be attached to each [span](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a 'tag' attribute. | `false` | `N/A` | `VELA_OTEL_TRACING_SPAN_ATTRIBUTES` | -| `tracing.tracestate.attributes` | This variable sets OTel tracestate [(span) attributes](https://www.w3.org/TR/trace-context) as a list of `key=value` pairs. Each pair will be inserted into the tracestate for each sampled span. | `false` | `N/A` | `VELA_OTEL_TRACING_TRACESTATE_ATTRIBUTES` | - -:::note -For more information on how the runtime properties are consumed, please see the [server reference](/docs/reference/installation/server/server.md). -::: - -## Exporter - -To start using tracing you first need to set `VELA_OTEL_TRACING_ENABLE=true` in the runtime environment. - -Enabling tracing requires that `VELA_OTEL_EXPORTER_OTLP_ENDPOINT` be set to an [exporter](https://opentelemetry.io/docs/specs/OTel/protocol/exporter/) host that is reachable over HTTP. - -If the exporter requires SSL then `VELA_OTEL_TRACING_EXPORTER_SSL_CERT_PATH` must be set to a filepath that contains valid certificates. If no certificate filepath is set, then the server will communicate with the exporter over HTTP (insecure). - -The Vela local stack is configured to export traces to Jaeger using their "all-in-one" Docker image, making it easy to view traces out of the box. - -```diff -+ jaeger: -+ image: jaegertracing/all-in-one:latest -... - -$ docker run \ - --detach=true \ - --env=VELA_ADDR=https://vela-server.example.com \ -+ --env=VELA_OTEL_TRACING_ENABLE: true \ -+ --env=VELA_OTEL_EXPORTER_OTLP_ENDPOINT: http://jaeger:4318 \ -... -``` - -From the [Jaeger official website](https://www.jaegertracing.io/docs/1.6/getting-started/): -> This image, designed for quick local testing, launches the Jaeger UI, collector, query, and agent, with an in memory storage component. - -## Sampling - -The server uses a combination of "shared" and "per-task" [head sampling](https://opentelemetry.io/docs/concepts/sampling/) to control how traces are recorded or dropped. - -### "Shared" Samplers - -The following samplers are utilized by all traces produced by the server. - -#### Global Rate-limiting - -All traces share a global rate limit controlled by `VELA_OTEL_TRACING_SAMPLER_RATELIMIT_PER_SECOND`. - -Use `VELA_OTEL_TRACING_SAMPLER_RATELIMIT_PER_SECOND` to set a maximum threshold of "N traces per second". The default is `100` traces per second. - -### "Task" Samplers - -Set `VELA_OTEL_TRACING_SAMPLER_TASKS_CONFIG_FILEPATH` to point to a JSON filepath to control sampler configurations on a per-task basis. - -```json -tracing.json -{ - "task-name": { - "active": bool - } -} -``` - -A `task` is basically the "span name" based on the work being performed. A `task` can be an API endpoint interaction, a [Gorm](https://gorm.io/docs/index.html) query, etc. See [OTel span docs](https://opentelemetry.io/docs/specs/otel/trace/api/#span) for more information. - -If a `task` is **not** represented in the configuration file then the task will be treated normally, **with tracing enabled** using the "shared" samplers. - -| Field | Type | Description | -| ----- | ----------- | ----------- | -| `active` | bool | Set to `false` to completely disable traces for a particular task. | - -Examples of trace tasks include API endpoints, gorm queries, etc. The list of tasks will change as functionality is added to the server. - -> See the configuration file examples below. - -#### Example - No Tasks - -```json -{} -``` - -Because tasks that do not exist in the configuration file will be treated as enabled, this file will **enable all tracing**. - -#### Example - Disable /health Endpoint - -```json -{ - "/health": { - "active": false - } -} -``` - -Because `active` can be used to disable tracing, this configuration file will enable tracing for all tasks **except for the `/health` endpoint**. - -#### Example - Mixed Tasks - -```json -{ - "/health": { - "active": false - }, - "/api/v1/deployments/:org/:repo": { - "active": false - }, - "/api/v1/:worker": { - "active": true - }, - "gorm.query": { - "active": false - } -} -``` - -The task `/health` with `active: false` will **disable** tracing on `/health`. - -`/api/v1/deployments/:org/:repo` with `active: false` will **disable** tracing on `/api/v1/deployments/:org/:repo` for **ALL** `:org` and `:repo` parameters. - -`/api/v1/:worker` with `active: true` **will do nothing** at this point, because any tasks that are not present in the configuration file will automatically be sampled normally. For now this is slightly confusing, but in the future there will be more configuration fields that will determine how an `active: true` task is sampled. - -The task `gorm.query` with `active: false` would disable tracing for raw gorm queries. This is meant to show that the config applies to **all trace tasks** and not just API endpoints. - -**All other tasks** will be sampled as normal using the global shared samplers (like rate limiting)! This includes all API endpoints and gorm queries. diff --git a/versioned_docs/version-0.26/reference/installation/ui.md b/versioned_docs/version-0.26/reference/installation/ui.md deleted file mode 100644 index a679cc3..0000000 --- a/versioned_docs/version-0.26/reference/installation/ui.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: "UI" -sidebar_position: 3 ---- - -## Required - -This section contains a list of all variables that must be provided to the UI. - -### VELA_API - -This variable sets a fully qualified URL to the Vela [server](/docs/installation/server/server.md) address. - -The variable should be provided as a `string`. - -:::note -This variable should match [the `VELA_ADDR` variable](/reference/installation/server#vela_addr) provided to the server. -::: - -## Optional - -This section contains a list of all variables that can be provided to the UI. - -### NODE_ENV - -This variable sets the targeted deployment environment for [node.js](https://nodejs.org/). - -Setting this variable to `development` will enable development mode for the service and output verbose logging. - -The variable can be provided as a `string`. - -:::note -This variable has a default value of `production`. -::: - -### VELA_DOCS_URL - -This variable sets a fully qualified URL to the documentation website for Vela. - -The variable can be provided as a `string`. - -:::note -This variable has a default value of `https://go-vela.github.io/docs/`. - -Please note that this variable is used in deep links throughout the UI. Customizing this value assumes the target location utilizes the same URL structure as the official docs at the default location. -::: - -### VELA_FEEDBACK_URL - -This variable sets a fully qualified URL to the feedback website for Vela. - -The variable can be provided as a `string`. - -:::note -This variable has a default value of `https://github.com/go-vela/ui/issues/new/`. -::: - -### VELA_LOG_BYTES_LIMIT - -This variable sets the maximum amount of bytes for logs the UI will attempt to render. - -The variable can be provided as an `integer`. - -:::note -This variable has a default value of `20000` (2 MB). -::: - -### VELA_MAX_BUILD_LIMIT - -This variable sets the maximum amount of concurrent builds a repo is allowed to run. - -In this context, concurrent builds refers to any `pending` or `running` builds for that repo. - -If the amount of concurrent builds for a repo matches the limit, then any new builds will be blocked from being created. - -The variable can be provided as an `integer`. - -:::note -This variable has a default value of `30`. - -This variable should match [the `VELA_MAX_BUILD_LIMIT` variable](/reference/installation/server#vela_max_build_limit) provided to the server. -::: \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/installation/worker/executor.md b/versioned_docs/version-0.26/reference/installation/worker/executor.md deleted file mode 100644 index 89fac46..0000000 --- a/versioned_docs/version-0.26/reference/installation/worker/executor.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: "Executor" -linkTitle: "Executor" -description: > - This section contains information on the executor component for the worker. ---- - -This component is responsible for coordinating with the runtime to manage workload resources. - -Throughout the lifecycle of these resources, this component will track and report results back to the [server](/docs/installation/server/server.md). - -## Configuration - -The following options are used to configure the component: - -| Name | Description | Required | Default | Environment Variables | -| -------------------------------- | -------------------------------------------------------------------------- | -------- | -------------- | ------------------------------------------------------------------------- | -| `executor.driver` | type of client to control and operate executor | `true` | `linux` | `EXECUTOR_DRIVER`\`VELA_EXECUTOR_DRIVER` | -| `executor.max_log_size` | maximum log size (in bytes) | `false` | `0` (no limit) | `EXECUTOR_MAX_LOG_SIZE`\`VELA_EXECUTOR_MAX_LOG_SIZE` | -| `executor.log_streaming_timeout` | maximum time to wait, after build completion, for logs to finish streaming | `false` | `5m` | `EXECUTOR_LOG_STREAMING_TIMEOUT`\`VELA_EXECUTOR_LOG_STREAMING_TIMEOUT` | - -:::note -For more information on these configuration options, please see the [worker reference](/docs/reference/installation/worker/worker.md). -::: - -## Drivers - -The following drivers are available to configure the component: - -| Name | Description | Documentation | -| ------- | ------------------------------------------------------ | ---------------------- | -| `linux` | uses a Linux executor for running workloads | https://www.linux.com/ | -| `local` | uses a Local executor for running workloads (CLI only) | `N/A` | - -### Linux - -From the [Linux official website](https://www.linux.com/what-is-linux/): - -> Linux has been around since the mid-1990s and has since reached a user-base that spans the globe. Just like Windows, iOS, and Mac OS, Linux is an operating system. In fact, one of the most popular platforms on the planet, Android, is powered by the Linux operating system. - -The below configuration displays an example of starting the Vela worker that will use a Linux executor: - -```diff -$ docker run \ - --detach=true \ -+ --env=VELA_EXECUTOR_DRIVER=linux \ - --env=VELA_QUEUE_DRIVER=redis \ - --env=VELA_SERVER_ADDR=https://vela-server.example.com \ - --env=VELA_SERVER_SECRET= \ - --env=VELA_WORKER_ADDR=https://vela-worker.example.com \ - --name=worker \ - --publish=80:80 \ - --publish=443:443 \ - --restart=always \ - --volume=/var/run/docker.sock:/var/run/docker.sock \ - target/vela-worker:latest -``` - -:::note -This Linux configuration is enabled by default and is not necessary to provide in order for Vela to operate. -::: - -### Local - -The `local` executor driver is only intended for use with the Vela CLI. - -It's not recommended to run any workloads on a worker configured with this driver. diff --git a/versioned_docs/version-0.26/reference/installation/worker/queue.md b/versioned_docs/version-0.26/reference/installation/worker/queue.md deleted file mode 100644 index 57349e4..0000000 --- a/versioned_docs/version-0.26/reference/installation/worker/queue.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: "Queue" -linkTitle: "Queue" -description: > - This section contains information on the queue component for the worker. ---- - -This component is responsible for integrating with a queue system based off the configuration provided. - -The queue system is used by Vela for pulling workloads, provided by the [server](/docs/installation/server/server.md), that will be run. - -Workloads fetched from the queue are managed with a [first in, first out (FIFO)](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics)) strategy. - -## Configuration - -The following options are used to configure the component: - -| Name | Description | Required | Default | Environment Variables | -| ------------------- | ------------------------------------------------- | -------- | ---------- | ----------------------------------------------- | -| `queue.cluster` | configures the client for a queue cluster | `false` | `false` | `QUEUE_CLUSTER`\`VELA_QUEUE_CLUSTER` | -| `queue.driver` | type of client to control and operate queue | `true` | `N/A` | `QUEUE_DRIVER`\`VELA_QUEUE_DRIVER` | -| `queue.pop.timeout` | timeout for requests that pop items off the queue | `true` | `60s` | `QUEUE_POP_TIMEOUT`\`VELA_QUEUE_POP_TIMEOUT` | -| `queue.routes` | unique channels or topics for pulling workloads | `true` | `[ vela ]` | `QUEUE_ROUTES`\`VELA_QUEUE_ROUTES` | - -:::note -For more information on these configuration options, please see the [worker reference](/docs/reference/installation/worker/worker.md). -::: - -## Drivers - -The following drivers are available to configure the component: - -| Name | Description | Documentation | -| ------- | ----------------------------------------- | ----------------- | -| `redis` | uses a Redis queue for managing workloads | https://redis.io/ | - -### Redis - -From the [Redis official website](https://redis.io/): - -> Redis is an open source (BSD licensed), in-memory data structure store, used as a database, cache, and message broker. Redis provides data structures such as strings, hashes, lists, sets, sorted sets with range queries, bitmaps, hyperloglogs, geospatial indexes, and streams. Redis has built-in replication, Lua scripting, LRU eviction, transactions, and different levels of on-disk persistence, and provides high availability via Redis Sentinel and automatic partitioning with Redis Cluster. - -The below configuration displays an example of starting the Vela worker that will connect to a Redis queue: - -```diff -$ docker run \ - --detach=true \ -+ --env=VELA_QUEUE_DRIVER=redis \ - --env=VELA_SERVER_ADDR=https://vela-server.example.com \ - --env=VELA_SERVER_SECRET= \ - --env=VELA_WORKER_ADDR=https://vela-worker.example.com \ - --name=worker \ - --publish=80:80 \ - --publish=443:443 \ - --restart=always \ - --volume=/var/run/docker.sock:/var/run/docker.sock \ - target/vela-worker:latest -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/installation/worker/runtime.md b/versioned_docs/version-0.26/reference/installation/worker/runtime.md deleted file mode 100644 index 20efbba..0000000 --- a/versioned_docs/version-0.26/reference/installation/worker/runtime.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: "Runtime" -linkTitle: "Runtime" -description: > - This section contains information on the runtime component for the worker. ---- - -This component is responsible for integrating with a runtime environment based off the configuration provided. - -The runtime environment is used by Vela for executing workload resources and managing their lifecycle. - -## Configuration - -The following options are used to configure the component: - -| Name | Description | Required | Default | Environment Variables | -|------------------------------|-------------------------------------------------------------------------------------------------|----------|--------------------------|-------------------------------------------------------------------| -| `runtime.config` | path to configuration file for the runtime | `false` | `N/A` | `RUNTIME_CONFIG`\`VELA_RUNTIME_CONFIG` | -| `runtime.driver` | type of client to control and operate runtime | `true` | `docker` | `RUNTIME_DRIVER`\`VELA_RUNTIME_DRIVER` | -| `runtime.namespace` | namespace to use for the runtime (only for kubernetes) | `false` | `N/A` | `RUNTIME_NAMESPACE`\`VELA_RUNTIME_NAMESPACE` | -| `runtime.pods-template-name` | name of the PipelinePodsTemplate to retrieve from the `runtime.namespace` (only for kubernetes) | `false` | `N/A` | `RUNTIME_PODS_TEMPLATE_NAME`\`VELA_RUNTIME_PODS_TEMPLATE_NAME` | -| `runtime.pods-template-file` | path to local fallback file containing a PipelinePodsTemplate in YAML (only for kubernetes) | `false` | `N/A` | `RUNTIME_PODS_TEMPLATE_FILE`\`VELA_RUNTIME_PODS_TEMPLATE_FILE` | -| `runtime.privileged-images` | images allowed to run in privileged mode for the runtime | `false` | `[ ]` | `RUNTIME_PRIVILEGED_IMAGES`\`VELA_RUNTIME_PRIVILEGED_IMAGES` | -| `runtime.drop-capabilities` | kernel capabilities to be dropped from each running container | `false` | `N/A` | `RUNTIME_DROP_CAPABILITIES`\`VELA_RUNTIME_DROP_CAPABILITIES` | -| `runtime.volumes` | path to host volumes to mount into resources for the runtime | `false` | `N/A` | `RUNTIME_VOLUMES`\`VELA_RUNTIME_VOLUMES` | - -:::note -For more information on these configuration options, please see the [worker reference](/docs/reference/installation/worker/worker.md). -::: - -## Drivers - -The following drivers are available to configure the component: - -| Name | Description | Documentation | -| ------------ | --------------------------------------------------------------------- | ---------------------- | -| `docker` | uses a Docker daemon for creating and managing runtime resources | https://docker.io/ | -| `kubernetes` | uses a Kubernetes cluster for creating and managing runtime resources | https://kubernetes.io/ | - -### Docker - -From the [Docker official website](https://docker.io/): - -> Docker takes away repetitive, mundane configuration tasks and is used throughout the development lifecycle for fast, easy and portable application development - desktop and cloud. Docker’s comprehensive end to end platform includes UIs, CLIs, APIs and security that are engineered to work together across the entire application delivery lifecycle. - -The below configuration displays an example of starting the Vela worker that will use a Docker runtime: - -```diff -$ docker run \ - --detach=true \ - --env=VELA_QUEUE_DRIVER=redis \ -+ --env=VELA_RUNTIME_DRIVER=docker \ - --env=VELA_SERVER_ADDR=https://vela-server.example.com \ - --env=VELA_SERVER_SECRET= \ - --env=VELA_WORKER_ADDR=https://vela-worker.example.com \ - --name=worker \ - --publish=80:80 \ - --publish=443:443 \ - --restart=always \ - --volume=/var/run/docker.sock:/var/run/docker.sock - target/vela-worker:latest -``` - -:::note -This Docker configuration is enabled by default and is not necessary to provide in order for Vela to operate. -::: - -### Kubernetes - -From the [Kubernetes official website](https://kubernetes.io/): - -> Kubernetes, also known as K8s, is an open-source system for automating deployment, scaling, and management of containerized applications. - -The below configuration displays an example of starting the Vela worker that will use a Kubernetes runtime: - -```diff -$ docker run \ - --detach=true \ - --env=VELA_QUEUE_DRIVER=redis \ -+ --env=VELA_RUNTIME_DRIVER=kubernetes \ -+ --env=VELA_RUNTIME_CONFIG=/root/.kube/config \ -+ --env=VELA_RUNTIME_NAMESPACE=vela \ - --env=VELA_SERVER_ADDR=https://vela-server.example.com \ - --env=VELA_SERVER_SECRET= \ - --env=VELA_WORKER_ADDR=https://vela-worker.example.com \ - --name=worker \ - --publish=80:80 \ - --publish=443:443 \ - --restart=always \ - --volume=/var/run/docker.sock:/var/run/docker.sock \ -+ --volume=/root/.kube/config:/root/.kube/config \ - target/vela-worker:latest -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/installation/worker/worker.md b/versioned_docs/version-0.26/reference/installation/worker/worker.md deleted file mode 100644 index 35e31fd..0000000 --- a/versioned_docs/version-0.26/reference/installation/worker/worker.md +++ /dev/null @@ -1,304 +0,0 @@ ---- -no_list: true -title: "Worker" -sidebar_position: 2 ---- - -## Components - -The worker is made up of several components, responsible for specific tasks, necessary for the service to operate: - -| Name | Description | -| ---------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `executor` | coordinates with the runtime to manage workload resources and reports results back to the [server](/docs/installation/server/server.md) | -| `queue` | integrates with a queue provider for pulling workloads, provided by the [server](/docs/installation/server/server.md), that will be run | -| `runtime` | integrates with a runtime environment for executing workload resources | - -## Required - -This section contains a list of all variables that must be provided to the worker. - -### VELA_QUEUE_DRIVER - -This configuration variable is used by the [queue component](/docs/reference/installation/server/queue.md) for the worker. - -Examples using this configuration variable are provided in the above reference documentation. - -This variable sets the driver to use for the queue functionality for the worker. - -The variable should be provided as a `string`. - -:::note -This variable should match [the `VELA_QUEUE_DRIVER` variable](/reference/installation/server#vela_queue_driver) provided to the server. - -The possible options to provide for this variable are: - -* `redis` -::: - -### VELA_SERVER_ADDR - -This variable sets a fully qualified URL to the Vela [server](/docs/installation/server/server.md) address. - -The variable should be provided as a `string`. - -:::note -This variable should match [the `VELA_ADDR` variable](/reference/installation/server#vela_addr) provided to the server. -::: - -### VELA_WORKER_ADDR - -This variable sets a fully qualified URL to the Vela [worker](/docs/installation/worker/worker.md) address. - -The variable should be provided as a `string`. - -## Optional - -This section contains a list of all variables that can be provided to the worker. - -### VELA_SERVER_SECRET - -This variable sets a shared secret for authenticating communication between workers and the server. - -Only necessary to provide if utilizing the [server-worker trusted symmetric worker authentication method](/installation/worker/docker/#worker-server-trusted-symmetric-token). - -The variable should be provided as a `string`. - -:::note -This variable should match [the `VELA_SECRET` variable](/reference/installation/server#vela_secret) provided to the server. -::: - -### VELA_BUILD_LIMIT - -This variable sets a number to control the maximum amount of builds that are allowed to run concurrently on the worker. - -The variable can be provided as an `integer`. - -:::note -This variable has a default value of `1`. -::: - -### VELA_BUILD_TIMEOUT - -This variable sets the maximum duration of time a build can run for on the worker before being terminated. - -The variable can be provided as a `duration` (i.e. `5s`, `10m`). - -:::note -This variable has a default value of `30m`. -::: - -### VELA_CHECK_IN - -This variable sets the maximum duration of time a worker will wait before registering with the Vela [server](/docs/installation/server/server.md). - -The variable can be provided as a `duration` (i.e. `5s`, `10m`). - -:::note -This variable has a default value of `15m`.\ -\ -The value should coordinate with the [`VELA_WORKER_ACTIVE_INTERVAL`](/reference/installation/server/#vela_worker_active_interval) setting provided to the [server](/docs/installation/server/server.md). -::: - -### VELA_EXECUTOR_DRIVER - -This configuration variable is used by the [executor component](/docs/reference/installation/worker/executor.md) for the worker. - -Examples using this configuration variable are provided in the above reference documentation. - -This variable sets the driver to use for the executor functionality for the worker. - -The variable can be provided as a `string`. - -:::note -This variable has a default value of `linux`. - -The possible options to provide for this variable are: - -* `linux` -* `local` -::: - -### VELA_EXECUTOR_MAX_LOG_SIZE - -This configuration variable is used by the [executor component](/docs/reference/installation/worker/executor.md) for the worker. - -This variable sets the maximum number of bytes for logs allowed to be uploaded per step. - -The variable can be provided as an `integer`. - -:::note -This variable has a default value of `0`. No limit. -::: - -### VELA_EXECUTOR_ENFORCE_TRUSTED_REPOS - -This configuration variable is used by the [executor component](/docs/reference/installation/worker/executor.md) for the worker. - -This variable sets whether or not the executor will verify a repository is `trusted` before executing a build that contains privileged images (see [runtime privileged images](/reference/installation/worker/#vela_runtime_privileged_images)). - -The variable can be provided as a `boolean`. - -:::note -This variable has a default value of `true`. -::: - -### VELA_QUEUE_CLUSTER - -This configuration variable is used by the [queue component](/docs/reference/installation/server/queue.md) for the worker. - -This variable enables the worker to connect to a queue cluster rather than a standalone instance. - -The variable can be provided as a `boolean`. - -:::note -This variable should match [the `VELA_QUEUE_CLUSTER` variable](/reference/installation/server#vela_queue_cluster) provided to the server. -::: - -### VELA_QUEUE_POP_TIMEOUT - -This configuration variable is used by the [queue component](/docs/reference/installation/server/queue.md) for the worker. - -This variable sets the maximum duration of time the worker will wait before timing out requests sent for pulling workloads. - -The variable can be provided as a `duration` (i.e. `5s`, `10m`). - -:::note -This variable has a default value of `60s`. -::: - -### VELA_QUEUE_ROUTES - -This configuration variable is used by the [queue component](/docs/reference/installation/server/queue.md) for the worker. - -This variable sets the unique channels or topics to pull workloads from. - -The variable can be provided as a comma-separated `list` (i.e. `myRoute1,myRoute2`). - -The worker will update its own database record using the provided queue routes. If you wish to control worker routes solely using API / Database, supply `""` or `"/docs/usage/tour/"`. - -:::note -This variable has a default value of `vela`. -::: - -### VELA_RUNTIME_CONFIG - -This configuration variable is used by the [runtime component](/docs/reference/installation/worker/runtime.md) for the worker. - -Examples using this configuration variable are provided in the above reference documentation. - -This variable sets a fully qualified system path to a configuration file for the worker. - -The variable can be provided as a `string`. - -### VELA_RUNTIME_DRIVER - -This configuration variable is used by the [runtime component](/docs/reference/installation/worker/runtime.md) for the worker. - -Examples using this configuration variable are provided in the above reference documentation. - -This variable sets the driver to use for the runtime functionality for the worker. - -The variable can be provided as a `string`. - -:::note -This variable has a default value of `docker`. - -The possible options to provide for this variable are: - -* `docker` -* `kubernetes` -::: - -### VELA_RUNTIME_NAMESPACE - -This configuration variable is used by the [runtime component](/docs/reference/installation/worker/runtime.md) for the worker. - -Examples using this configuration variable are provided in the above reference documentation. - -This variable sets a namespace (for Kubernetes only) to use for runtime workloads. - -The variable can be provided as a `string`. - -### VELA_RUNTIME_PODS_TEMPLATE_NAME - -This configuration variable is used by the [runtime component](/docs/reference/installation/worker/runtime.md) for the worker. - -Examples using this configuration variable are provided in the [kubernetes runtime documentation](/docs/installation/worker/kubernetes.md). - -This variable sets a `PipelinePodsTemplate` name (for Kubernetes only) to use for runtime workloads. -The named template must be in the `VELA_RUNTIME_NAMESPACE`. - -The variable can be provided as a `string`. - -### VELA_RUNTIME_PODS_TEMPLATE_FILE - -This configuration variable is used by the [runtime component](/docs/reference/installation/worker/runtime.md) for the worker. - -This variable sets the path to a `PipelinePodsTemplate` YAML file (for Kubernetes only) to use for runtime workloads. -This file is only used if `VELA_RUNTIME_PODS_TEMPLATE_NAME` is empty. - -An example file is provided in the [kubernetes runtime documentation](/docs/installation/worker/kubernetes.md). - -This is useful for Kubernetes clusters that do not allow loading CRDs. It is also used for testing Vela. - -The variable can be provided as a `string`. - -### VELA_RUNTIME_PRIVILEGED_IMAGES - -This configuration variable is used by the [runtime component](/docs/reference/installation/worker/runtime.md) for the worker. - -This variable sets the [Docker image(s)](https://docs.docker.com/get-started/overview/#images) that are allowed to have privileged access on the worker. - -The variable can be provided as a comma-separated `list` (i.e. `myImage1,myImage2`). - -:::note -Please use with caution. This setting essentially grants any defined image root access to the host machine. -::: - -### VELA_RUNTIME_DROP_CAPABILITIES - -This configuration variable is used by the [runtime component](/docs/reference/installation/worker/runtime.md) for the worker. - -This variable leverages the [`--cap-drop` Docker run flag](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) to disable certain kernel capabilities given to the container by default. - -This variable can be provided as a comma-separated `list` (e.g. `CAP_CHOWN,CAP_DAC_OVERRIDE`). There is some validation in place to ensure accurate capabilities are provided. - -### VELA_RUNTIME_VOLUMES - -This configuration variable is used by the [runtime component](/docs/reference/installation/worker/runtime.md) for the worker. - -This variable sets the fully qualified system path(s) to file(s) on the host machine that will be mounted into workloads executed on that worker. - -The variable can be provided as a comma-separated `list` (i.e. `myVolume1,myVolume2`). - -### VELA_SERVER_CERT - -This variable sets a fully qualified system path to the TLS certificate used for HTTPS for the worker. - -The variable can be provided as a `string`. - -### VELA_SERVER_CERT_KEY - -This variable sets a fully qualified system path to the TLS certificate key used for HTTPS for the worker. - -The variable can be provided as a `string`. - -### VELA_SERVER_TLS_MIN_VERSION - -This variable sets the minimum TLS version that the worker API will accept. - -The variable can be provided as a `string`. - -:::note -This variable has a default value of `1.2`. - -The possible options to provide for this variable are: - -* `1.0` -* `1.1` -* `1.2` -* `1.3` -::: - - diff --git a/versioned_docs/version-0.26/reference/sdk/go.md b/versioned_docs/version-0.26/reference/sdk/go.md deleted file mode 100644 index 0d5aee1..0000000 --- a/versioned_docs/version-0.26/reference/sdk/go.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "Go" -linkTitle: "Go" -description: > - Learn how the find the documentation for the Go sdk ---- - -## Overview - -Vela Go SDK is a client to perform operations on Vela objects or view content in a new way to integrate into applications. - -For a complete list of APIs and examples, please take a look at the [Godoc Reference documentation](https://pkg.go.dev/github.com/go-vela/sdk-go/vela). - -## Minimum requirements - -Go 1.13 or above - -## Get build info example - -Below is a sample Go program demonstrating how to authenticate and get a build with the Go SDK: - -```go -package main - -import ( - "fmt" - "github.com/go-vela/sdk-go/vela" -) - -func main() { - // full URI to the Vela server - url := "https://your-vela-server.example.com" - - token := "someToken" - accessToken := "someAccessToken" - refreshToken := "someRefreshToken" - - // instantiate a new Vela client - client, err := vela.NewClient(url, nil) - if err != nil { - fmt.Println(err) - } - - // set the Authentication mechanisms for the client - client.Authentication.SetTokenAuth(token) - client.Authentication.SetAccessAndRefreshAuth(accessToken, refreshToken) - - // Get a build from the server - build, resp, err := c.Build.Get("go-vela", "sdk-go", 1) - if err != nil { - fmt.Println(err) - } - - fmt.Printf("Received response code %d, for build %+v", resp.StatusCode, build) -} -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/reference/sdk/python.md b/versioned_docs/version-0.26/reference/sdk/python.md deleted file mode 100644 index 716edb6..0000000 --- a/versioned_docs/version-0.26/reference/sdk/python.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: "Python" -linkTitle: "Python" -description: > - Learn how the find the documentation for the Python sdk ---- - -## Overview - -Vela Python SDK is a client to perform operations on Vela objects or view content in a new way to integrate into applications. - -For a complete list of APIs and examples, please take a look at the [Python Reference documentation](https://github.com/go-vela/sdk-python#documentation-for-api-endpoints). - -## Requirements. - -Python 2.7 and 3.4+ - -## Get build info example - -Below is a sample Go program demonstrating how to authenticate and get a build with the Python SDK: - -```python -from __future__ import print_function -import time -import vela -from vela.rest import ApiException -from pprint import pprint - -# Configure API key authorization: ApiKeyAuth -configuration = vela.Configuration() -configuration.api_key['Authorization'] = 'YOUR_API_KEY' -configuration.api_key_prefix['Authorization'] = 'Bearer' - -# Configure API endpoint -configuration.host = 'https://your-vela-server.example.com' - -# create an instance of the API class -api_instance = vela.BuildsApi(vela.ApiClient(configuration)) - -try: - api_response = api_instance.get_builds(org="go-vela",repo="sdk-python") - pprint(api_response) -except ApiException as e: - print("Exception when calling BuildsApi->get_builds: %s\n" % e) -``` diff --git a/versioned_docs/version-0.26/reference/sdk/sdk.md b/versioned_docs/version-0.26/reference/sdk/sdk.md deleted file mode 100644 index abc6ed6..0000000 --- a/versioned_docs/version-0.26/reference/sdk/sdk.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: "SDK" -linkTitle: "SDK" -layout: SDK -description: > - This section contains information on how to use the Vela SDKs. ---- - -:::tip -Sdk repos can be found in the Vela GitHub org with an [`sdk-` prefix](https://github.com/go-vela/?q=sdk&type=&language=) -::: diff --git a/versioned_docs/version-0.26/reference/yaml/environment.md b/versioned_docs/version-0.26/reference/yaml/environment.md deleted file mode 100644 index 158469c..0000000 --- a/versioned_docs/version-0.26/reference/yaml/environment.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: "Environment" -linkTitle: "Environment" -weight: 1 -description: > - YAML keys for environment block ---- - -The environment key is intended to be used to inject a global environment configuration into steps, services and secret containers. Control of which container types get the injected environment settings is available via the metadata block. - -```yaml ---- -# This document is displaying using the environment key with a map syntax. -# Additionally, you can also use array syntax where the items in -# they array are of pattern HELLO="Hello, Vela!" -environment: - HELLO: "Hello, Vela!" -``` - diff --git a/versioned_docs/version-0.26/reference/yaml/metadata.md b/versioned_docs/version-0.26/reference/yaml/metadata.md deleted file mode 100644 index e525a66..0000000 --- a/versioned_docs/version-0.26/reference/yaml/metadata.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: "Metadata" -linkTitle: "Metadata" -weight: 2 -description: > - YAML keys for metadata block ---- - -The metadata key is intended to be used during the compile phase to signal how to treat the YAML document. - -```yaml ---- -# This document is displaying all the available keys -# in their default state for the compile process. -metadata: - template: false - clone: true -``` - -## Keys - -| Key | Required | Type | Description | -| --------------- | -------- | ----------- | ----------------------------------------------------------------- | -| `template` | Y | bool | Enables compiling the pipeline as a template. | -| `clone` | N | bool | Enables injecting the default clone process. | -| `render_inline` | N | bool | Enables rendering without explicitly calling within the pipeline. | -| `auto_cancel` | N | (see below) | Auto canceling settings for pipelines. | - -### Usage - -#### The `template:` key - -:::tip -To learn how to write templates, see the [template documentation](/docs/usage/templates/templates.md). -::: - -```yaml ---- -metadata: - # Enables compiling the pipeline as a template. This value - # is defaulted during the compile phase to "false" if not - # explicitly provided by the user. - template: true -``` - -#### The `clone:` key - -```yaml ---- -metadata: - # Enables injecting the default clone process - clone: true -``` - -#### The `environment:` key - -```yaml ---- -metadata: - # By default, the below is populated into every pipeline with - # services, steps, and secrets. But, when the block exists the - # configuration specified is used during compile phase. - environment: [steps, services, secrets] -``` - -#### The `render_inline:` key - -```yaml ---- -metadata: - # By default, the below is populated into every pipeline with - # false. But, when set to "true" a user can render a template - # in the resulting pipeline without referencing it in stages - # or steps. - render_inline: false -``` - -#### The `auto_cancel` key - -| Key | Default | Type | Description | -| ---------------- | ------- | ---- | ------------------------------------------------------------------------------------------- | -| `pending` | True | bool | Pending builds will be auto canceled if qualifying build is triggered | -| `running` | False | bool | Currently running builds will be auto canceled if qualifying build is triggered | -| `default_branch` | False | bool | Pushes to the default branch will also be auto canceled if a qualifying build is triggered. | - -A **qualifying build** is defined as either: - -- a _push_ build with the same _branch_ as another running/pending _push_ build -- a _pull request_ build with the same _head ref_ as another running/pending _pull request_ build - -These builds most often happen when a user pushes a commit to a branch and quickly pushes another commit, both of which kick off new builds. Using the `auto_cancel` block can help free up build space and eliminate pointless builds. - -By default, auto canceling is disabled altogether. However, if `running` or `default_branch` are specified, `pending` has a default value of `true` unless specified otherwise. - -```yaml ---- -# pending & running will auto cancel, but not pushes to the default branch. -metadata: - auto_cancel: - running: true -``` - -```yaml ---- -# running builds will auto cancel even if they are targeting the default branch, but pending builds will not. -metadata: - auto_cancel: - pending: false - default_branch: true - running: true -``` diff --git a/versioned_docs/version-0.26/reference/yaml/secrets.md b/versioned_docs/version-0.26/reference/yaml/secrets.md deleted file mode 100644 index 2d6993e..0000000 --- a/versioned_docs/version-0.26/reference/yaml/secrets.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -title: "Secrets" -linkTitle: "Secrets" -weight: 8 -description: > - YAML keys for secret block ---- - -The secret key is intended to be used to pull secrets from the Vela server or execute plugins to write the external secrets to the build volume. - -```yaml ---- -# This document is displaying all the required keys -# to pull various secret types. -secrets: - # Below is displaying the declarative secret definitions. - - name: foo1 - key: go-vela/docs/foo1 - engine: native - type: repo - - name: foo2 - key: go-vela/foo2 - engine: native - type: org - - name: foo3 - key: go-vela/admins/foo3 - engine: native - type: shared - - name: vault_token - key: go-vela/vault_token - engine: native - type: org - - # Below is displaying executing a secret plugin. - - origin: - name: External Vault Secret - image: target/secret-vault:latest - secrets: [ vault_token ] - parameters: - addr: vault.company.com - auth_method: token - username: vela - token: sometoken - items: - - source: secret/vela - path: user -``` - -## Keys - -| Key | Required | Type | Description | -| -------- | -------- | ------ | --------------------------------------------------------------- | -| `name` | Y | string | Name of secret to reference in the pipeline. | -| `key` | N | string | Path to secret to fetch from storage backend. | -| `engine` | N | string | Name of storage backend to fetch secret from. | -| `type` | N | string | Type of secret to fetch from storage backend. | -| `pull` | N | string | When to pull in secrets from storage backend. | -| `origin` | N | struct | Declaration to pull secrets from non-internal secret providers. | - -#### The `name:` key - -```yaml ---- -secrets: - # Name of secret to reference in the pipeline. - - name: postgres -``` - -#### The `key:` key - -:::tip -The key is unique - # to the type of secret you need to pull and follows a pattern - # to ensure the repo has the proper authorization to use the secret. - # Pattern by type: - # repo - \/\/\ - # org - \/\ - # shared - \/\/\ -::: - -```yaml ---- -secrets: - # Path to secret to fetch from storage backend. Displaying a - # repo type secret. - - key: go-vela/docs/foo1 - - # Path to secret to fetch from storage backend. Displaying a - # org type secret. - - key: go-vela/foo1 - - # Path to secret to fetch from storage backend. Displaying a - # shared type secret. - - key: go-vela/admins/foo1 -``` - -#### The `engine:` key - -:::tip -To know what engines are available for your Vela installation, we recommend consulting your system administrators. -::: - -```yaml ---- -secrets: - # Name of storage backend to fetch secret from, "native" signifies - # the backend provider is the Vela database. - - engine: native -``` - -#### The `type:` key - -```yaml ---- -secrets: - # Type of secret to fetch from storage backend. - # By default, Vela can pull repo but type accepts the - # following values: repo, org, and shared - - type: repo -``` - -#### The `pull:` key - -```yaml ---- -secrets: - # When to pull in secrets from storage backend. - # By default, Vela will pull at the beginning of a build but - # accepts the following values: build_start, step_start - - pull: step_start -``` - -:::warning `step_start` or lazy loading secrets -is not currently available for the [Kubernetes-based workers](/docs/installation/worker/kubernetes.md) and does not work with secrets -originating from plugins loaded via [`origin:`](/reference/yaml/secrets/#the-pull-key) (see below). -::: - -#### The `origin:` key - -| Key | Required | Type | Description | -| ------------- | -------- | -------- | ---------------------------------------------------------------- | -| `name` | Y | string | Unique identifier for the container in the pipeline. | -| `image` | Y | []string | Docker image used to create an ephemeral container. | -| `pull` | N | string | Declaration to configure if and when the Docker image is pulled. | -| `secrets` | N | struct | Sensitive variables injected into the container environment. | -| `environment` | N | map | | -| `ruleset` | N | struct | Conditions to limit the execution of the container. | -| `parameters` | N | map | Extra configuration variables specific to a plugin. | - -:::tip The `pull:` option under `origin:` -allows for different values than the -[Secrets `pull:` key](/reference/yaml/secrets/#the-pull-key). It mimics the -[Steps version of the `pull:` key](/reference/yaml/steps/#the-pull-key). -::: - -:::tip In an effort to reduce duplicate -documentation, see the comparable -[step keys documentation](/reference/yaml/steps/#keys) to learn how keys -can be set and details on behavior. ::: diff --git a/versioned_docs/version-0.26/reference/yaml/services.md b/versioned_docs/version-0.26/reference/yaml/services.md deleted file mode 100644 index d588521..0000000 --- a/versioned_docs/version-0.26/reference/yaml/services.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -title: "Services" -linkTitle: "Services" -weight: 5 -description: > - YAML keys for services block ---- - -The `services` key is intended to be used to run applications alongside the pipeline. - -```yaml ---- -# This document is displaying all the required keys -# to run a postgres database for the duration of a pipeline. -services: - - name: postgres - image: postgres:latest -``` - -## Keys - -| Key | Required | Type | Description | -|---------------|----------|-----------------|-----------------------------------------------------------------| -| `name` | Y | string | Unique identifier for the container in the pipeline | -| `image` | Y | string | Docker image used to create an ephemeral container | -| `pull` | N | string | Declaration to configure if and when the Docker image is pulled | -| `environment` | N | map || []string | Variables to inject into the container environment | -| `entrypoint` | N | []string | Commands to execute inside the container | -| `ports` | N | string | List of ports to map for the container in the pipeline | -| `ulimits` | N | []string | Set the user limits for the container | -| `user` | N | string | Set the user for the container. | - -### Usage - -#### The `name:` key - -```yaml ---- -services: - # Unique identifier for the container in the pipeline. - - name: postgres -``` - -#### The `image:` key - -```yaml ---- -services: - # Docker image used to create ephemeral container. - - image: postgres:latest -``` - -#### The `pull:` key - -```yaml ---- -services: - # Declaration to configure if and when the Docker image is pulled. - # By default, the compiler will inject pull but accepts the - # following values: always, never, no_present, on_start, - - pull: always -``` - -#### The `environment:` key - -```yaml ---- -services: - # Variables to injected into the container environment - # using a map style syntax. - - environment: - DB_NAME: vela -``` - -```yaml ---- -services: - # Variables to injected into the container environment - # using an array style syntax. - - environment: - - DB_NAME=vela -``` - -#### The `entrypoint:` key - -```yaml ---- -services: - # Commands to execute inside the container. - - entrypoint: - - some/path/sql-init.sql - - /some/binary/postgres -``` - -#### The `ports:` key - -```yaml ---- -services: - # List of ports to map for the container in the pipeline. - - ports: - - "8080:5432" -``` - -#### The `ulimits:` key - -```yaml ---- -services: - # Set the user limits for the container. - - ulimits: - - name: foo - soft: 1024 - - name: bar - soft: 1024 - hard: 2048 -``` - -#### The `user:` key - -```yaml ---- -services: - # Run the container with the foo user. - - user: foo -``` diff --git a/versioned_docs/version-0.26/reference/yaml/stages.md b/versioned_docs/version-0.26/reference/yaml/stages.md deleted file mode 100644 index f40bcbb..0000000 --- a/versioned_docs/version-0.26/reference/yaml/stages.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: "Stages" -linkTitle: "Stages" -weight: 7 -description: > - YAML keys for stages block ---- - -The `stages` key is intended to be used to parallelize one-to-many sets of step tasks. - -```yaml ---- -# This document is displaying all the required keys -# to run two stages with one step task in parallel. -stages: - hello: - steps: - - name: Hello World - image: alpine:latest - commands: - - echo "Hello, Vela User" - - welcome: - steps: - - name: Welcome to Vela - image: alpine:latest - commands: - - echo "Welcome to Vela!" -``` - -## Keys - -| Key | Required | Type | Description | -|---------------|----------|----------|---------------------------------------------------------------------------| -| `name` | Y | string | Unique identifier for the stage in the pipeline | -| `steps` | Y | []string | Sequential execution instructions for the stage | -| `needs` | N | []string | Stages that must complete before starting the current one | -| `independent` | N | bool | Stage will execute its steps and ignore failures from other stages' steps | - -### Usage - -#### The `name:` key - -```yaml ---- -stages: - # Unique identifier for the stage in the pipeline. - welcome: -``` - -#### The `steps:` key - -```yaml ---- -stages: - # Unique identifier for the stage in the pipeline. - welcome: - # Sequential execution instructions for the stage. - steps: -``` - -:::tip -For more details on steps keys, see the [step keys documentation](/reference/yaml/steps/#keys) -::: - -#### The `needs:` key - -```yaml ---- -stages: - greeting: - - # Unique identifier for the stage in the pipeline. - welcome: - # Stages that must complete before starting the current one. - needs: [ greeting ] -``` - -#### The `independent:` key - -```yaml ---- -stages: - greeting: - - # Unique identifier for the stage in the pipeline. - welcome: - # If the greeting stage fails at any point, the welcome stage will continue its execution. - independent: true -``` diff --git a/versioned_docs/version-0.26/reference/yaml/steps.md b/versioned_docs/version-0.26/reference/yaml/steps.md deleted file mode 100644 index dcfcc85..0000000 --- a/versioned_docs/version-0.26/reference/yaml/steps.md +++ /dev/null @@ -1,452 +0,0 @@ ---- -title: "Steps" -linkTitle: "Steps" -weight: 6 -description: > - YAML keys for steps block ---- - -The steps key is intended to be used to run sequential tasks in a pipeline. - -```yaml ---- -# This document is displaying all the required keys -# to run a postgres database for the duration of a pipeline. -steps: - - name: Hello World - image: alpine:latest - commands: - - echo "Hello, Vela User" -``` - -## Keys - -| Key | Required | Type | Description | -|---------------|----------|-----------------|------------------------------------------------------------------| -| `name` | Y | string | Unique identifier for the container in the pipeline. | -| `image` | Y | string | Docker image used to create ephemeral container. | -| `pull` | N | string | Declaration to configure if and when the Docker image is pulled. | -| `secrets` | N | struct | Sensitive variables injected into the container environment. | -| `environment` | N | map OR []string | Variables to inject into the container environment. | -| `ruleset` | N | struct | Conditions to limit the execution of the container. | -| `parameters` | N | map | Extra configuration variables specific to a plugin. | -| `commands` | N | []string | Execution instructions to run inside the container. | -| `template` | N | struct | Name of a template to expand in the pipeline. | -| `id_request` | N | string | Injects `VELA_ID_TOKEN_REQUEST_TOKEN` into step environment. | -| `entrypoint` | N | []string | Commands to execute inside the container. | -| `detach` | N | []string | Run the container in a detached (headless) state. | -| `ulimits` | N | string | Set the user limits for the container. | -| `user` | N | string | Set the user for the container. | - -### Usage - -#### The `name:` key - -```yaml ---- -steps: - # Unique identifier for the container in the pipeline. - - name: Hello World -``` - -#### The `image:` key - -```yaml ---- -steps: - # Docker image used to create ephemeral container. - - image: alpine:latest -``` - -#### The `pull:` key - -```yaml ---- -steps: - # Declaration to configure if and when the Docker image is pulled. - # By default, the compiler will inject pull with value not_present but - # accepts the following values: always, never, not_present, on_start - - pull: always -``` - -#### The `secrets:` key - -```yaml ---- -steps: - # Sensitive variables to injected into the container - # environment as upper case env. i.e. GIT_USERNAME=vela - - secrets: [ git_username ] -``` - -```yaml ---- -steps: - # Sensitive variables to injected into the container - # environment as upper case env. i.e. GIT_USERNAME= - - secrets: - # The source is the "name:" of a secret within the - # parent "secrets:" yaml key - - source: username - # The target is the desired environment key accessible during - # the container runtime. - target: git_username -``` - -#### The `environment:` key - -```yaml ---- -steps: - # Variables to injected into the container environment - # using a map style syntax. - - environment: - DB_NAME: vela -``` - -```yaml ---- -steps: - # Variables to injected into the container environment - # using an array style syntax. - - environment: - - DB_NAME=vela -``` - -#### The `ruleset:` key - -The following rules can be used to configure a ruleset: - -| Name | Description | -|------------|----------------------------------------------------| -| `branch` | name of branch for a build. | -| `comment` | pull request comment body. | -| `event` | name of an event for a build. | -| `instance` | FQDN of backend server instance. | -| `label` | pull request label. | -| `path` | path to workspace files for a build. | -| `repo` | name of the repo for a build. | -| `status` | name of status for a build. | -| `tag` | name of reference for a build. | -| `target` | name of deployment or schedule target for a build. | - -```yaml ---- -steps: - - ruleset: - # As shown below this step will execute if the build - # branch is stage or main. - branch: [ stage, main ] -``` - -```yaml ---- -steps: - - ruleset: - # This extends the ability to start new builds through interactions - # within a pull request. As shown below this will run a step if a “run build” - # comment is added to the bottom of a pull request. - comment: [ "run build" ] -``` - -```yaml ---- -steps: - - name: Event Ruleset - ruleset: - # As shown below this step will execute if the build - # event is push or pull_request. The available events are: - # comment, push, pull_request, tag, and deployment. - event: [ push, pull_request ] - - name: Scope Events - ruleset: - # For pull_request and comment events, specifying an action will - # further scope when the step is executed. These actions include - # opened, synchronized, and edited for pull_request; created and - # edited for comment. To specify an action, use a ":" as shown below. - event: [pull_request:opened, comment:created] - - # Note: specifying pull_request is the same as - # [pull_request:opened, pull_request:synchronized, pull_request:reopened]. - # Specifying comment is the same as [comment:created, comment:edited]. -``` - -:::tip -Event scoping (`event:action`) was included in Vela release `v0.23.0`. As such, general `event` rulesets in pipelines are mapped as following: - -- `pull_request` -> [ `pull_request:opened`, `pull_request:synchronize`, `pull_request:reopened` ] -- `comment` -> [ `comment:created`, `comment:edited` ] -- `deployment` -> [ `deployment:created` ] - -If you wish to include _all_ event types from an event, you can specify a wildcard at the end: - -```yaml - ruleset: - event: pull_request* # will run on opened, reopened, synchronize, edited, labeled, and unlabeled -``` - -::: - -```yaml ---- -steps: - - name: Limiting execution to an instance - ruleset: - # This step will execute if the FQDN of the - # server backend instance matches the supplied value. - instance: https://vela-server.example.com -``` - -:::tip -Ensure you are supplying the address of the configured backend server and not the web UI. -::: - -```yaml ---- -steps: - - name: Labeling a pull request - ruleset: - # This step will execute if a pull request has been labeled enhancement. - event: [ 'pull_request:labeled' ] - label: [ 'enhancement' ] - - name: Editing a pull request with labels - ruleset: - # This step will execute if a pull request has been edited AND - # has the labels enhancement or documentation. - event: [ 'pull_request:edited' ] - label: [ 'enhancement', 'documentation' ] -``` - -```yaml ---- -steps: - - ruleset: - # As shown below this step will execute if file README.md, any file of type *.md - # in the root directory or any file in the test/* directory has changed. - path: [ README.md, "*.md", "test/*" ] -``` - -```yaml ---- -steps: - - ruleset: - # As shown below this step will execute if repo exists within the target GitHub - # organization or the repo is the go-vela/docs repository. - repo: [ "target/*", "go-vela/docs" ] -``` - -```yaml ---- -steps: - - ruleset: - # As shown below this step will execute if the build status is failure or success. - status: [ failure, success ] -``` - -```yaml ---- -steps: - - ruleset: - # As shown below this step will execute if the build ref is dev/* or test/*. - tag: [ dev/*, test/* ] -``` - -```yaml ---- -steps: - - ruleset: - # As shown below this step will execute if the build target is stage or production. - # This key is only compatible with deployment and schedule events. - target: [ dev/*, test/* ] -``` - -The following controls can be used to modify the behavior of the ruleset evaluation: - -| Name | Description | Options | -|------------|----------------------------------------------------| ----------------------------------------------------------------------- | -| `continue` | enables continuing the build if the step fails. | `true`, `false` | -| `matcher` | matcher to use when evaluating the ruleset. | `filepath`, `regexp` | -| `operator` | operator to use when evaluating the ruleset. | `and`, `or` | -| `if` | limits the step execution to all rules must match. | `branch`, `comment`, `event`, `path`, `repo`, `status`, `tag`, `target` | -| `unless` | limits the step execution to no rules can match. | `branch`, `comment`, `event`, `path`, `repo`, `status`, `tag`, `target` | - -```yaml ---- -steps: - - ruleset: - # As shown below this will overwrite Vela's default behavior to - # allow the build to continue the sequential step pipeline when this step fails. - continue: true -``` - -```yaml ---- -steps: - - ruleset: - # As shown below this will overwrite Vela's default behavior to use a - # filepath matcher and instead evaluate all rules with regex. The available - # matchers are: filepath, and regexp. - # Note: The regexp matcher uses Go's regexp package. You can find documentation - # at https://golang.org/pkg/regexp/syntax/ - matcher: regexp - branch: foo-\\d -``` - -```yaml ---- -steps: - - ruleset: - # As shown below this will overwrite Vela's default behavior to use an - # "or" behavior when comparing all ruleset rules. - # The available operators are: and, and or. - operator: or -``` - -```yaml ---- -steps: - - ruleset: - # As shown below this will tell the ruleset to only execute - # this step when the branch is main and event is push. - if: - branch: main - event: push -``` - -```yaml ---- -steps: - - ruleset: - # As shown below this will overwrite Vela's default behavior to tell the ruleset - # to only execute this step when the branch is not main and event is not push. - unless: - branch: main - event: push -``` - -#### The `parameters:` key - -```yaml ---- -steps: - # Extra configuration variables specific to a plugin. All keys within the - # parameters key are injected environment variables into the - # container as PARAMETER_. - # As shown below this step will execute a plugin that needs two fields: - # PARAMETER_REGISTRY=index.docker.io - # PARAMETER_REPO=octocat/hello-world,go-vela/docs - - parameters: - registry: index.docker.io - repo: [ go-vela/hello-world, go-vela/docs ] -``` - -#### The `commands:` key - -```yaml ---- -steps: - # Execution instructions to run inside the container. - - entrypoint: - - echo "Hello, World" -``` - -#### The `template:` key - -The following keys can be used to configure a template injection: - -| Name | Description | -|--------| ---------------------------------------| -| `name` | Name of template to inject in the step | -| `vars` | Variables injected into the template | - -```yaml ---- -steps: - - template: - # Name of template to inject in the step. The name must map - # to an existing template in the parent "template" key. - name: example -``` - -```yaml ---- -steps: - - template: - # Variables injected into the template. Variables can be any - # primitive or complex YAML types but the corresponding template - # needs to understand how those templates are to be used. - vars: - tags: [ latest, "1.14", "1.15" ] - pull_policy: always - commands: - test: "go test ./..." - build: "go build ./..." -``` - -#### The `report_as` key - -```yaml ---- -steps: - # publish custom status for commit with `test suite` as the context - - report_as: test suite -``` - -:::tip -A pipeline can have up to 10 steps that report their own status. -::: - -#### The `id_request` key - -```yaml -steps: - # inject $VELA_ID_TOKEN_REQUEST_TOKEN into step environment. Value of `id_request` becomes one of the claims in the token. - - name: OIDC - id_request: write -``` - -#### The `entrypoint:` key - -```yaml ---- -steps: - # Commands to execute inside the container. - - entrypoint: - - /bin/pwd - - /bin/ls -``` - -#### The `detach:` key - -```yaml ---- -steps: - # Run the container in a detached (headless) state. Similar to the - # "services:" key this will create a container that can be used throughout - # the duration of the pipeline. - - detach: true -``` - -#### The `ulimits:` key - -```yaml ---- -steps: - # Set the user limits for the container. - - ulimits: - - name: foo - soft: 1024 - - name: bar - soft: 1024 - hard: 2048 -``` - -#### The `user:` key - -```yaml ---- -steps: - # Run the container with the foo user. - - user: foo -``` - diff --git a/versioned_docs/version-0.26/reference/yaml/templates.md b/versioned_docs/version-0.26/reference/yaml/templates.md deleted file mode 100644 index c0dbace..0000000 --- a/versioned_docs/version-0.26/reference/yaml/templates.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: "Templates" -linkTitle: "Templates" -weight: 4 -description: > - YAML keys for templates block ---- - -The template key is intended to be used to identify where to retrieve templates during the compiler phase of the pipeline. - -```yaml ---- -# This document is displaying all the required keys -# to pull a template from a remote system. -templates: - - name: example - source: github.com/go-vela/templates/example.yml - type: github -``` - -## Keys - -| Key | Required | Type | Description | -|----------|----------|--------|-------------------------------------------------------| -| `name` | Y | string | indicates a unique identifier for the template. | -| `source` | Y | string | indicates a path to a template in remote system. | -| `type` | Y | string | indicates to the compiler which version to use. | -| `format` | N | string | indicates the language used within the template file. | - -### Usage - -:::tip -To learn how to write templates, see the [template documentation](/docs/usage/templates/templates.md) -::: - -#### The `name:` key - -```yaml -templates: - # Indicates a unique identifier for the template. This identifier - # then can be used within a step to expand the template. - - name: example -``` - -#### The `source:` key - -```yaml -templates: - # Indicates a path to a template in remote system. This path - # should always be the raw path within a repository. By default - # the template is pulled from the default branch on the repository. - # It can be overwritten by adding a suffix of `@branch`, `@tag`, or - # `@commit`. - source: github.com/go-vela/templates/example.yml@testbranch -``` - -```yaml -templates: - # As an alternative, if the template is within the same repository, - # the source can be the path to the template in the Vela workspace. - # This is used in conjunction with `type: file`. - source: path/to/template.yml -``` - -#### The `type:` key - -```yaml -templates: - # Indicates to the compiler which version to use. - type: github -``` - -```yaml -templates: - # The 'file' type will grab a template from the repository on a commit. - type: file -``` - -#### The `format:` key - -```yaml -templates: - - name: example - source: github.com/go-vela/templates/example.yml - type: github - # Indicates the language used within the template file. By default - # the template will be "go" but accepts the following values: go, golang, starlark - format: starlark -``` diff --git a/versioned_docs/version-0.26/reference/yaml/version.md b/versioned_docs/version-0.26/reference/yaml/version.md deleted file mode 100644 index d9c1367..0000000 --- a/versioned_docs/version-0.26/reference/yaml/version.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Version" -linkTitle: "Version" -weight: 1 -description: > - YAML keys for version block ---- - -The version key is intended to be used in order to issue warnings for deprecated features or breaking changes within the YAML document. - -```yaml ---- -# This document is displaying using the version key within a yaml file. -version: "1" -``` - diff --git a/versioned_docs/version-0.26/reference/yaml/worker.md b/versioned_docs/version-0.26/reference/yaml/worker.md deleted file mode 100644 index 45072fb..0000000 --- a/versioned_docs/version-0.26/reference/yaml/worker.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "Worker" -linkTitle: "Worker" -weight: 3 -description: > - YAML keys for worker block ---- - -The worker key is intended to be used to route a build to a specific worker pool of workers available with the Vela queue. - -```yaml ---- -# This document is displaying all the available keys -# and routing the build to a specific worker "sm:docker". -worker: - flavor: sm - platform: docker -``` - -:::warning -Routes are defined by the Vela system administrators during installation. To know what routes are available for your Vela installation, we recommend consulting your system administrators. -::: - -## Keys - -| Key | Required | Type | Description | -|------------|----------|--------|------------------------------------------------------| -| `flavor` | N | string | Indicates what flavor of a worker. (i.e. sm, m, lg) | -| `platform` | N | string | Indicates the platform of a worker. (i.e. docker, k8s) | - -### Usage - -:::tip -See an [example](/docs/usage/examples/route.md) on how to route a build. -::: - -#### The `flavor:` key - -```yaml ---- -worker: - # indicates what flavor of worker (i.e. sm, m, lg). If not specified - # will be scheduled in the generic "vela" queue. - flavor: sm -``` - -#### The `platform:` key - -```yaml ---- -worker: - # Indicates the platform of worker (i.e. docker, k8s). If not specified - # will be scheduled in the generic "vela" queue. - platform: docker -``` - diff --git a/versioned_docs/version-0.26/reference/yaml/yaml.md b/versioned_docs/version-0.26/reference/yaml/yaml.md deleted file mode 100644 index 74615ba..0000000 --- a/versioned_docs/version-0.26/reference/yaml/yaml.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: "YAML" -linkTitle: "YAML" -layout: reference -description: > - reference information for creating Vela pipelines ---- - -Steps and Stages Pipeline use "YAML Ain’t Markup Language" (YAML) which is a data serialization language designed to be human friendly. Vela accepts YAML files with either a `.yml` or `.yaml` extension. If you'd like to learn more about the YAML language, we recommend you see, "[Learn YAML in five minutes.](https://www.codeproject.com/Articles/1214409/Learn-YAML-in-five-minutes)". - -:::tip -The design goals for YAML are, in decreasing priority: - -1. YAML is easily readable by humans. -2. YAML data is portable between programming languages. -3. YAML matches the native data structures of agile languages. -4. YAML has a consistent model to support generic tools. -5. YAML supports one-pass processing. -6. YAML is expressive and extensible. -7. YAML is easy to implement and use. - -See YAML [design goals](https://yaml.org/spec/1.2/spec.html#Introduction) from spec. -::: - -## Terminology Check - -Whether you are a YAML expert or a novice, here is some quick terminology that you should be aware of: - -:::tip -You can get feedback directly on your `.vela.yml` or `.vela.yaml` pipelines in your IDE with the available [JSON Schema](/docs/usage/json-schema-support.md). -::: - -### Document - -A file ending with `.yml` or `.yaml` that contains contents following the YAML spec is called a document, see [YAML 1.2 spec for full details](https://yaml.org/spec/1.2/spec.html#id2800132). - -Example: - -```yml ---- -key: value -``` - -### Keys - -A YAML document is compose of one to many key-value pairs where the value is evaluated to an explicit type (Int, Float, string, bool, etc), see [YAML 1.2 spec for full details](https://yaml.org/spec/1.2/spec.html#id2761292). - -Example: - -```yml ---- -# an integer -canonical: 12345 - -# a float -canonical: 3.14159e+3 - -# a string -canonical: "Hello, World" - -# a bool -canonical: true -``` - diff --git a/versioned_docs/version-0.26/usage/_category_.json b/versioned_docs/version-0.26/usage/_category_.json deleted file mode 100644 index 621c21d..0000000 --- a/versioned_docs/version-0.26/usage/_category_.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "label": "Usage", - "position": 1, - "link": { - "type": "generated-index" - } -} diff --git a/versioned_docs/version-0.26/usage/authenticate.md b/versioned_docs/version-0.26/usage/authenticate.md deleted file mode 100644 index 50ffcb4..0000000 --- a/versioned_docs/version-0.26/usage/authenticate.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: "Authenticate" ---- - -:::warning -These docs assume you have Vela running. -::: - -## UI - -Navigate to your deployed instance and follow the OAuth workflow presented on the web interface. - -## CLI - -Please see authentication in the [CLI reference](/docs/reference/cli/authentication.md). - -_If you have not yet installed the CLI, see [CLI install reference](/docs/reference/cli/install.md) first._ - -## API - -Please see authentication in the [API reference](/docs/reference/api/authentication.md). - -## SDK - -Please see authentication in the [sdk reference](/docs/reference/sdk/go.md). diff --git a/versioned_docs/version-0.26/usage/badge.md b/versioned_docs/version-0.26/usage/badge.md deleted file mode 100644 index cd48f4e..0000000 --- a/versioned_docs/version-0.26/usage/badge.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: "Badges" -description: > - Show off your build status. ---- - -:::note -These docs assume you have Vela running. -::: - -### How to get your badge - -The server has an endpoint that will return an SVG badge for the default branch of your repo. The badge represents the current status for the most recent build for that branch. The most recent build refers to any build produced by the repo that is attached to that branch, which includes any event (push, pull request, etc). - -```sh -# Syntax -https:///badge///status.svg - -# Example -https://vela.example.com/badge/octocat/Hello-World/status.svg -``` - -In addition you can specify which branch you want to get a badge for by supplying a `?branch=` query parameter in the URL. - -```sh -# Syntax -https:///badge///status.svg?branch= - -# Example -https://vela.example.com/badge/octocat/Hello-World/status.svg?branch=not_default -``` - -### Embedding in Markdown - -To embed your badge in your markdown formatted file, follow this example: - -```sh -# Syntax -[![Build Status](https:///badge///status.svg)](https:////) - -# Example -[![Build Status](https://vela.example.com/badge/octocat/Hello-World/status.svg)](https://vela.example.com/octocat/Hello-World) -``` diff --git a/versioned_docs/version-0.26/usage/docker.md b/versioned_docs/version-0.26/usage/docker.md deleted file mode 100644 index 5c236e4..0000000 --- a/versioned_docs/version-0.26/usage/docker.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: "Building Docker Images" ---- - -We assume you understand how to build and run Docker images. If you need assistance on how to get started with Docker; we recommend you see their documentation for [getting set up](https://docs.docker.com/get-started/). - -Vela runs all workloads within Docker containers. Which essentially gives us two core different ways to build Docker images: - -* Without elevated daemon access -* With elevated daemon access - -Both options have disadvantages and advantages, so we encourage all Vela administrators to weigh the pros/cons of how they want to build Docker images for their cluster. Here are some resources you can use while researching available tools: - -* [What is Docker BuildKit and What can I use it for?](https://brianchristner.io/what-is-docker-buildkit/) -* [Kaniko tools comparison](https://github.com/GoogleContainerTools/kaniko#comparison-with-other-tools) - -## Without elevated daemon access - -Building an image without elevated access gives administrators the most secure pattern for not allowing any elevated access to the workers within the cluster. There are two plugin options for building those images: - -* [vela-kaniko](/docs/usage/plugins/registry/Kaniko.md) - -We recommend customers read the [tool comparisons](/usage/docker/#additional-resources) before picking a technology for building their images. In-depth examples for building with either utility are available within their respective plugin documentation pages. A simple example is provided below: - -```yaml -version: "1" -steps: - - name: build and publish with kaniko - image: target/vela-kaniko:latest - pull: always - parameters: - registry: index.docker.io - repo: index.docker.io/octocat/hello-world -``` - -## With elevated daemon access - -Building an image with elevated access is a allowed pattern as long as the administrators have set the required allow list of images on the worker. It's *important to work with your administrator* to understand stand which pattern you instances was deployed to support. The supported plugin for building those images: - -* [vela-docker](/docs/usage/plugins/registry/docker.md) - -```yaml -version: "1" -steps: - - name: build and publish with Docker's BuildKit - image: target/vela-docker:latest - pull: always - parameters: - registry: index.docker.io - tags: [ index.docker.io/octocat/hello-world ] - - - name: build and publish without Docker's BuildKit - image: target/vela-docker:latest - environment: - DOCKER_BUILDKIT=0 - pull: always - parameters: - registry: index.docker.io - tags: [ index.docker.io/octocat/hello-world ] -``` - -## Additional Resources - -* [Building Container Images Securely on Kubernetes](https://blog.jessfraz.com/post/building-container-images-securely-on-kubernetes/) -* [Why is building rootless so hard?](https://github.com/opencontainers/runc/pull/1692) diff --git a/versioned_docs/version-0.26/usage/enable_repo.md b/versioned_docs/version-0.26/usage/enable_repo.md deleted file mode 100644 index ccfa3ad..0000000 --- a/versioned_docs/version-0.26/usage/enable_repo.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: "Enable a Repo" ---- - -:::note -You will need **Admin** access to the repo to be able to activate it in Vela. This is because you need **Admin** access to be able to add webhooks -to the repo. -::: - -### Via the UI - -For this example, we'll go over using the UI to add the repo. You can always head over to the [CLI docs](/docs/reference/cli/repo/add.md) for docs on how to add a repo via CLI. - -1. Log into your Vela instance. -1. Click "Add Repositories". -1. Select the Org from the available list. -1. Click "Add" next to the repo you would like to add. - 1. Alternatively you can "Add All" repos in an org. - 1. If your repo doesn't exist, try clicking "Refresh List" in the top right. - -Your repo now has the necessary web hook to Vela. - -:::tip -If you're coming from another CI platform you can set a starting build number by updating the counter field on the repo via the UI, [CLI](/docs/reference/cli/repo/repo.md), or [API](/docs/reference/api/repo/repo.md). -::: diff --git a/versioned_docs/version-0.26/usage/environment.md b/versioned_docs/version-0.26/usage/environment.md deleted file mode 100644 index b685e55..0000000 --- a/versioned_docs/version-0.26/usage/environment.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: "Using the Environment" -toc: true -description: > - Learn about how to leverage the environment within your builds. ---- - -Vela provides the ability to define environment variables scoped to individual steps, services and secrets. Additionally, if you need global environment variables you can set it at the parent and have it injected to all containers. - -Please note the environment is designed to be unique per container. Vela does inject a variety of default values from build, repo and user information. - -Defaults: - -* [Container](/reference/environment/variables/#container-defaults) -* [Steps only](/reference/environment/variables/#step-only-defaults) -* [Services only](/reference/environment/variables/#service-only-defaults) - -## Usage - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Services](docs/usage/tour/services.md) - * [Environment](docs/usage/tour/environment.md) -* [Stages](docs/usage/tour/stages.md) - * [Environment](docs/usage/tour/environment.md) -* [Steps](docs/usage/tour/steps.md) - * [Environment](docs/usage/tour/environment.md) -* [Secrets](docs/usage/tour/secrets.md) - * [Origin](docs/usage/tour/secrets.md) - -:::note -Please be warned that `${variable}` expressions are subject to pre-processing. - -If you do not want the pre-processor to evaluate your expression it must be escaped. -::: - -```diff -version: "1" -+ environment: -+ GLOBAL_EXAMPLE: Hello, World Globally! - -services: - - name: redis -+ environment: -+ LOCAL_EXAMPLE: Hello, World! - image: redis:latest - -stages: - first_stage: -+ environment: -+ STAGE_EXAMPLE: "All the World's a Stage!" - steps: - - name: check status - image: redis:latest -+ environment: -+ LOCAL_EXAMPLE: Hello, World! - commands: - # you can use bash commands in-line to set or override variables - - export EXAMPLE="Hello World From Vela Team" - - echo ${EXAMPLE} - - echo ${STAGE_EXAMPLE} - - echo ${GLOBAL_EXAMPLE} - -secrets: - - origin: - name: private vault - image: target/secret-vault:latest -+ environment: -+ EXAMPLE: Hello, World! - secrets: [ vault_token ] - parameters: - addr: vault.example.com - auth_method: token - username: octocat - items: - - source: secret/docker - path: docker -``` - -## Global Usage - -By default global injection affects all containers ran within the pipeline. However, if you only want some container types to receive the configuration you can limit which types get them by adding the `environment` declaration into the metadata. - -:::note -Valid values for metadata `environment:` YAML key are `steps`, `services` and `secrets`. -::: - -```diff -version: "1" - environment: - GLOBAL_EXAMPLE: Hello, World Globally! - -+ metadata: -+ environment: [ steps, services ] - -services: - # Global configuration is no longer available in services - - name: redis - environment: - LOCAL_EXAMPLE: Hello, World! - image: redis:latest - -stages: - first_stage: - environment: - STAGE_EXAMPLE: "All the World's a Stage!" - steps: - - name: check status - image: redis:latest - environment: - LOCAL_EXAMPLE: Hello, World! - commands: - # you can use bash commands in-line to set or override variables - - export EXAMPLE="Hello World From Vela Team" - - echo ${EXAMPLE} - - echo ${STAGE_EXAMPLE} - - echo ${GLOBAL_EXAMPLE} - -secrets: -+ # Global configuration is no longer available in secrets since "secrets" -+ # was removed as a value in the metadata.environment block. - - origin: - name: private vault - image: target/secret-vault:latest - environment: - EXAMPLE: Hello, World! - secrets: [ vault_token ] - parameters: - addr: vault.example.com - auth_method: token - username: octocat - items: - - source: secret/docker - path: docker -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/usage/examples/_category_.json b/versioned_docs/version-0.26/usage/examples/_category_.json deleted file mode 100644 index c543bc0..0000000 --- a/versioned_docs/version-0.26/usage/examples/_category_.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "label": "Examples", - "position": 3, - "link": { - "type": "generated-index" - } -} diff --git a/versioned_docs/version-0.26/usage/examples/go_modules.md b/versioned_docs/version-0.26/usage/examples/go_modules.md deleted file mode 100644 index abcdac4..0000000 --- a/versioned_docs/version-0.26/usage/examples/go_modules.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: "Go (With Modules)" -toc: true -weight: 1 -description: > - Example Go (With Modules) Pipeline ---- - -Example [Yaml](https://yaml.org/spec/) configuration for a project building a [Go](https://golang.org/) binary with [Go modules](https://github.com/golang/go/wiki/Modules). - -## Scenario - -User is looking to create a pipeline that builds an artifact on any event or branch pushed to source control. - -### Steps - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Steps](docs/usage/tour/steps.md) - * [image](docs/usage/tour/image.md) - * [Environment](docs/usage/tour/environment.md) - * [Pull](docs/usage/tour/image.md) - * [Commands](docs/usage/tour/steps.md) - -:::tip -Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` - -It is recommended to pin `image:` versions for production pipelines -::: - -```yaml -version: "1" - -steps: - - name: install - image: golang:latest - pull: always - environment: - CGO_ENABLED: '0' - GOOS: linux - commands: - - go get ./... - - - name: test - image: golang:latest - pull: always - environment: - CGO_ENABLED: '0' - GOOS: linux - commands: - - go test ./... - - - name: build - image: golang:latest - pull: always - environment: - CGO_ENABLED: '0' - GOOS: linux - commands: - - go build -``` - -### Stages - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Stages](docs/usage/tour/stages.md) - * [Needs](docs/usage/tour/stages.md) - * [Steps](docs/usage/tour/steps.md) - * [image](docs/usage/tour/image.md) - * [Environment](docs/usage/tour/environment.md) - * [Pull](docs/usage/tour/image.md) - * [Commands](docs/usage/tour/steps.md) - -:::tip -Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` - -It is recommended to pin `image:` versions for production pipelines -::: - -```yaml -version: "1" - -stages: - install: - steps: - - name: install - image: golang:latest - pull: always - environment: - CGO_ENABLED: '0' - GOOS: linux - commands: - - go get ./... - - test: - needs: [ install ] - steps: - - name: test - image: golang:latest - pull: always - environment: - CGO_ENABLED: '0' - GOOS: linux - commands: - - go test ./... - - build: - needs: [ install ] - steps: - - name: build - image: golang:latest - pull: always - environment: - CGO_ENABLED: '0' - GOOS: linux - commands: - - go build -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/usage/examples/java_gradle.md b/versioned_docs/version-0.26/usage/examples/java_gradle.md deleted file mode 100644 index ac41539..0000000 --- a/versioned_docs/version-0.26/usage/examples/java_gradle.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: "Java (With Gradle)" -toc: true -weight: 2 -description: > - Example Java (With Gradle) Pipeline ---- - -Example [Yaml](https://yaml.org/spec/) configuration for a project building a [Java](https://docs.oracle.com/en/java/) application with [Gradle](https://docs.gradle.org/current/userguide/userguide.html). - -## Scenario - -User is looking to create a pipeline that builds an artifact on any event or branch pushed to source control. - -### Steps - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Steps](docs/usage/tour/steps.md) - * [image](docs/usage/tour/image.md) - * [Environment](docs/usage/tour/environment.md) - * [Pull](docs/usage/tour/image.md) - * [Commands](docs/usage/tour/steps.md) - -:::tip -Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` - -It is recommended to pin `image:` versions for production pipelines -::: - -```yaml -version: "1" - -steps: - - name: install - image: gradle:latest - pull: always - environment: - GRADLE_USER_HOME: .gradle - GRADLE_OPTS: -Dorg.gradle.daemon=false -Dorg.gradle.workers.max=1 -Dorg.gradle.parallel=false - commands: - - gradle downloadDependencies - - - name: test - image: gradle:latest - pull: always - environment: - GRADLE_USER_HOME: .gradle - GRADLE_OPTS: -Dorg.gradle.daemon=false -Dorg.gradle.workers.max=1 -Dorg.gradle.parallel=false - commands: - - gradle test - - - name: build - image: gradle:latest - pull: always - environment: - GRADLE_USER_HOME: .gradle - GRADLE_OPTS: -Dorg.gradle.daemon=false -Dorg.gradle.workers.max=1 -Dorg.gradle.parallel=false - commands: - - gradle build -``` - -### Stages - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Stages](/docs/usage/tour/stages.md) - * [Needs](/docs/usage/tour/stages.md) - * [Steps](/docs/usage/tour/steps.md) - * [image](/docs/usage/tour/image.md) - * [Environment](/docs/usage/tour/environment.md) - * [Pull](/docs/usage/tour/image.md) - * [Commands](/docs/usage/tour/steps.md) - -:::tip -Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` - -It is recommended to pin `image:` versions for production pipelines -::: - -```yaml -version: "1" -stages: - install: - steps: - - name: install - image: gradle:latest - pull: always - environment: - GRADLE_USER_HOME: .gradle - GRADLE_OPTS: -Dorg.gradle.daemon=false -Dorg.gradle.workers.max=1 -Dorg.gradle.parallel=false - commands: - - gradle downloadDependencies - test: - needs: [ install ] - steps: - - name: test - image: gradle:latest - pull: always - environment: - GRADLE_USER_HOME: .gradle - GRADLE_OPTS: -Dorg.gradle.daemon=false -Dorg.gradle.workers.max=1 -Dorg.gradle.parallel=false - commands: - - gradle test - - build: - needs: [ install ] - steps: - - name: build - image: gradle:latest - pull: always - environment: - GRADLE_USER_HOME: .gradle - GRADLE_OPTS: -Dorg.gradle.daemon=false -Dorg.gradle.workers.max=1 -Dorg.gradle.parallel=false - commands: - - gradle build -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/usage/examples/java_maven.md b/versioned_docs/version-0.26/usage/examples/java_maven.md deleted file mode 100644 index aa3838f..0000000 --- a/versioned_docs/version-0.26/usage/examples/java_maven.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: "Java (With Maven)" -toc: true -weight: 2 -description: > - Example Java (With Maven) Pipeline ---- - -Example [Yaml](https://yaml.org/spec/) configuration for a project building a [Java](https://docs.oracle.com/en/java/) application with [Maven](https://maven.apache.org/guides/index.html). - -## Scenario - -User is looking to create a pipeline that builds an artifact on any event or branch pushed to source control. - -### Steps - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Steps](docs/usage/tour/steps.md) - * [image](docs/usage/tour/image.md) - * [Environment](docs/usage/tour/environment.md) - * [Pull](docs/usage/tour/image.md) - * [Commands](docs/usage/tour/steps.md) - -:::tip -Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` - -It is recommended to pin `image:` versions for production pipelines -::: - -```yaml -version: "1" - -steps: - - name: install - image: maven:latest - pull: always - commands: - - mvn install - - - name: test - image: maven:latest - pull: always - commands: - - mvn test - - - name: build - image: maven:latest - pull: always - commands: - - mvn package -``` - -### Stages - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Stages](docs/usage/tour/stages.md) - * [Needs](docs/usage/tour/stages.md) - * [Steps](docs/usage/tour/steps.md) - * [image](docs/usage/tour/image.md) - * [Environment](docs/usage/tour/environment.md) - * [Pull](docs/usage/tour/image.md) - * [Commands](docs/usage/tour/steps.md) - -:::tip -Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` - -It is recommended to pin `image:` versions for production pipelines -::: - -```yaml -version: "1" -stages: - install: - steps: - - name: install - image: maven:latest - pull: always - commands: - - mvn install - test: - needs: [ install ] - steps: - - name: test - image: maven:latest - pull: always - environment: - GRADLE_USER_HOME: .gradle - GRADLE_OPTS: -Dorg.gradle.daemon=false -Dorg.gradle.workers.max=1 -Dorg.gradle.parallel=false - commands: - - mvn test - - build: - needs: [ install ] - steps: - - name: build - image: maven:latest - pull: always - environment: - GRADLE_USER_HOME: .gradle - GRADLE_OPTS: -Dorg.gradle.daemon=false -Dorg.gradle.workers.max=1 -Dorg.gradle.parallel=false - commands: - - mvn package -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/usage/examples/mongo.md b/versioned_docs/version-0.26/usage/examples/mongo.md deleted file mode 100644 index 1e330c6..0000000 --- a/versioned_docs/version-0.26/usage/examples/mongo.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: "Mongo" -toc: true -weight: 1 -description: > - Example Pipeline with Mongo ---- - -Example [Yaml](https://yaml.org/spec/) configuration for a project requiring a [Mongo](https://www.mongodb.com/) as a pipeline dependency. - -## Scenario - -User is looking to create a pipeline that can integrate with an ephemeral Mongo instance. - -### Services - -Services Yaml block can be used with stages and steps pipelines. This example uses a basic steps configuration. - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Services](docs/usage/tour/services.md) - * [Image](docs/usage/tour/image.md) -* [Steps](docs/usage/tour/steps.md) - * [Image](docs/usage/tour/image.md) - * [Pull](docs/usage/tour/image.md) - * [Commands](docs/usage/tour/steps.md) - -:::tip -Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` - -It is recommended to pin `image:` versions for production pipelines -::: - -```diff -version: "1" -services: - - name: mongo - image: mongo:latest - pull: always - -steps: - - name: check status - image: mongo:latest - pull: always - commands: - # sleeping can help ensure the service adequate time to start -+ - sleep 15 - - /bin/mongosh --host mongo --eval 'db.runCommand("ping")' -``` - -### Detach - -If you're looking for more granular start time for the container you can add a detach flag within stages and steps pipelines. - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Steps](docs/usage/tour/steps.md) - * [Image](docs/usage/tour/image.md) - * [Pull](docs/usage/tour/image.md) - * [Commands](docs/usage/tour/steps.md) - -:::tip -Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` - -It is recommended to pin `image:` versions for production pipelines -::: - -```diff -version: "1" - -steps: - - name: mongo - image: mongo:latest - detach: true - - - name: check status - image: mongo:latest - commands: - # sleeping can help ensure the service adequate time to start -+ - sleep 15 - - /bin/mongosh --host mongo --eval 'db.runCommand("ping")' -``` diff --git a/versioned_docs/version-0.26/usage/examples/node.md b/versioned_docs/version-0.26/usage/examples/node.md deleted file mode 100644 index a0b547c..0000000 --- a/versioned_docs/version-0.26/usage/examples/node.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: "Node" -toc: true -weight: 3 -description: > - Example Node Pipeline ---- - -Example [Yaml](https://yaml.org/spec/) configuration for a project building a [Node](https://nodejs.org/en/docs/) application. - -## Scenario - -User is looking to create a pipeline that builds an artifact on any event or branch pushed to source control. - -### Steps - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Steps](docs/usage/tour/steps.md) - * [image](docs/usage/tour/image.md) - * [Pull](docs/usage/tour/image.md) - * [Commands](docs/usage/tour/steps.md) - -:::tip -Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` - -It is recommended to pin `image:` versions for production pipelines -::: - -```yaml -version: "1" - -steps: - - name: install - image: node:latest - pull: always - commands: - - node install - - - name: lint - image: node:latest - pull: always - commands: - - node test - - - name: build - image: node:latest - pull: always - commands: - - node build -``` - -### Stages - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Stages](docs/usage/tour/stages.md) - * [Needs](docs/usage/tour/stages.md) - * [Steps](docs/usage/tour/steps.md) - * [image](docs/usage/tour/image.md) - * [Pull](docs/usage/tour/image.md) - * [Commands](docs/usage/tour/steps.md) - -:::tip -Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` - -It is recommended to pin `image:` versions for production pipelines -::: - -```yaml -version: "1" - -stages: - install: - steps: - - name: install - image: node:latest - pull: always - commands: - - node install - - test: - needs: [ install ] - steps: - - name: test - image: node:latest - pull: always - commands: - - node test - - build: - needs: [ install ] - steps: - - name: build - image: node:latest - pull: always - commands: - - node build -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/usage/examples/postgres.md b/versioned_docs/version-0.26/usage/examples/postgres.md deleted file mode 100644 index 4377081..0000000 --- a/versioned_docs/version-0.26/usage/examples/postgres.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: "Postgres" -toc: true -weight: 1 -description: > - Example Pipeline with Postgres ---- - -Example [Yaml](https://yaml.org/spec/) configuration for a project requiring a [Postgres](https://www.postgresql.org/) as a pipeline dependency. - -## Scenario - -User is looking to create a pipeline that can integrate with an ephemeral Postgres instance. - -### Services - -Services Yaml block can be used with stages and steps pipelines. This example uses a basic steps configuration. - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Services](docs/usage/tour/services.md) - * [Image](docs/usage/tour/image.md) -* [Steps](docs/usage/tour/steps.md) - * [Image](docs/usage/tour/image.md) - * [Pull](docs/usage/tour/image.md) - * [Commands](docs/usage/tour/steps.md) - -:::tip -Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` - -It is recommended to pin `image:` versions for production pipelines -::: - -```diff -version: "1" -services: - - name: postgres - image: postgres:latest - pull: always - environment: - POSTGRES_USER: admin - POSTGRES_PASSWORD: password - POSTGRES_DB: vela - -steps: - - name: check status - image: postgres:latest - pull: always - environment: - PGPASSWORD=password - commands: - # sleeping can help ensure the service adequate time to start - - sleep 15 - - psql -U admin -d vela -h postgres -p 5432 -``` - -### Detach - -If you're looking for more granular start time for the container you can add a detach flag within stages and steps pipelines. - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Steps](docs/usage/tour/steps.md) - * [Image](docs/usage/tour/image.md) - * [Pull](docs/usage/tour/image.md) - * [Commands](docs/usage/tour/steps.md) - -:::tip -Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` - -It is recommended to pin `image:` versions for production pipelines -::: - -```diff -version: "1" - -steps: - - name: postgres - image: postgres:latest - pull: always - environment: - POSTGRES_USER: admin - POSTGRES_PASSWORD: password - POSTGRES_DB: vela - detach: true - - - name: check status - image: postgres:latest - pull: always - environment: - PGPASSWORD=password - commands: - # sleeping can help ensure the service adequate time to start - - sleep 15 - - psql -U admin -d vela -h postgres -p 5432 -``` diff --git a/versioned_docs/version-0.26/usage/examples/redis.md b/versioned_docs/version-0.26/usage/examples/redis.md deleted file mode 100644 index 75b5479..0000000 --- a/versioned_docs/version-0.26/usage/examples/redis.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: "Redis" -toc: true -weight: 1 -description: > - Example Pipeline with Redis ---- - -Example [Yaml](https://yaml.org/spec/) configuration for a project requiring a [Redis](https://redis.io/) as a pipeline dependency. - -## Scenario - -User is looking to create a pipeline that can integrate with an ephemeral Redis instance. - -### Services - -Services Yaml block can be used with stages and steps pipelines. This example uses a basic steps configuration. - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Services](docs/usage/tour/services.md) - * [Image](docs/usage/tour/image.md) -* [Steps](docs/usage/tour/steps.md) - * [Image](docs/usage/tour/image.md) - * [Pull](docs/usage/tour/image.md) - * [Commands](docs/usage/tour/steps.md) - -:::tip -Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` - -It is recommended to pin `image:` versions for production pipelines -::: - -```diff -version: "1" -services: - - name: redis - image: redis:latest - pull: always - -steps: - - name: check status - image: redis:latest - pull: always - commands: - # sleeping can help ensure the service adequate time to start -+ - sleep 15 - - redis-cli -h redis ping -``` - -### Detach - -If you're looking for more granular start time for the container you can add a detach flag within stages and steps pipelines. - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Steps](docs/usage/tour/steps.md) - * [image](docs/usage/tour/image.md) - * [Pull](docs/usage/tour/image.md) - * [Commands](docs/usage/tour/steps.md) - -:::tip -Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` - -It is recommended to pin `image:` versions for production pipelines -::: - -```diff -version: "1" - -steps: - - name: redis - image: redis:latest - pull: always - detach: true - - - name: check status - image: redis:latest - pull: always - commands: - # sleeping can help ensure the service adequate time to start -+ - sleep 15 - - redis-cli -h redis ping -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/usage/examples/route.md b/versioned_docs/version-0.26/usage/examples/route.md deleted file mode 100644 index 4ab7708..0000000 --- a/versioned_docs/version-0.26/usage/examples/route.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: "Route" -toc: true -weight: 1 -description: > - Example Pipeline with build routing ---- - -Example [Yaml](https://yaml.org/spec/) configuration for a project requiring a specific runtime or platform. - -## Scenario - -User is looking to create a pipeline that can only run within a Docker runtime. - -:::tip -Work with your server administer to understand what routes are available for your installation -::: - -### Steps - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* *Worker* - * *Platform* -* [Steps](docs/usage/tour/steps.md) - * [Image](docs/usage/tour/image.md) - * [Pull](docs/usage/tour/image.md) - * [Commands](docs/usage/tour/steps.md) - -:::tip -Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` - -It is recommended to pin `image:` versions for production pipelines -::: - -```yaml -version: "1" - -worker: - platform: docker - -steps: - - name: view worker name - image: alpine:latest - pull: always - commands: - - echo "Hello ${BUILD_HOST} Worker!!" -``` - -### Stages - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* *Worker* - * *Platform* -* [Stages](docs/usage/tour/stages.md) - * [Steps](docs/usage/tour/steps.md) - * [Image](docs/usage/tour/image.md) - * [Environment](docs/usage/tour/environment.md) - * [Pull](docs/usage/tour/image.md) - * [Commands](docs/usage/tour/steps.md) - -:::tip -Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` - -It is recommended to pin `image:` versions for production pipelines -::: - -```yaml -version: "1" - -worker: - platform: docker - -stages: - docker: - steps: - - name: view worker name - image: alpine:latest - pull: always - commands: - - echo "Hello ${BUILD_HOST} Worker!!" -``` diff --git a/versioned_docs/version-0.26/usage/examples/rust_cargo.md b/versioned_docs/version-0.26/usage/examples/rust_cargo.md deleted file mode 100644 index 97b3e67..0000000 --- a/versioned_docs/version-0.26/usage/examples/rust_cargo.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: "Rust (With Cargo)" -toc: true -weight: 1 -description: > - Example Rust (With Cargo) Pipeline ---- - -Example [Yaml](https://yaml.org/spec/) configuration for a project building a [Rust](https://www.rust-lang.org/) binary with [Cargo](https://doc.rust-lang.org/cargo/commands/cargo-doc.html). - -## Scenario - -User is looking to create a pipeline that builds an artifact on any event or branch pushed to source control. - -### Steps - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Steps](docs/usage/tour/steps.md) - * [image](docs/usage/tour/image.md) - * [Pull](docs/usage/tour/image.md) - * [Commands](docs/usage/tour/steps.md) - -:::tip -Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` - -It is recommended to pin `image:` versions for production pipelines -::: - -```yaml -version: "1" - -steps: - - name: fetch - image: rust:latest - pull: always - commands: - - cargo fetch --verbose --all - - - name: test - image: rust:latest - pull: always - environment: - CGO_ENABLED: '0' - GOOS: linux - commands: - - cargo test --verbose --all - - - name: build - image: rust:latest - pull: always - environment: - CGO_ENABLED: '0' - GOOS: linux - commands: - - cargo build --verbose --all -``` - -### Stages - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Stages](docs/usage/tour/stages.md) - * [Needs](docs/usage/tour/stages.md) - * [Steps](docs/usage/tour/steps.md) - * [image](docs/usage/tour/image.md) - * [Pull](docs/usage/tour/image.md) - * [Commands](docs/usage/tour/steps.md) - -:::tip -Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` - -It is recommended to pin `image:` versions for production pipelines -::: - -```yaml -version: "1" - -stages: - fetch: - steps: - - name: fetch - image: rust:latest - pull: always - commands: - - cargo fetch --verbose --all - - test: - needs: [ fetch ] - steps: - - name: test - image: rust:latest - pull: always - commands: - - cargo test --verbose --all - - build: - needs: [ fetch ] - steps: - - name: build - image: rust:latest - pull: always - commands: - - cargo build --verbose --all -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/usage/examples/secrets_external.md b/versioned_docs/version-0.26/usage/examples/secrets_external.md deleted file mode 100644 index 11c0877..0000000 --- a/versioned_docs/version-0.26/usage/examples/secrets_external.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: "External Secrets" -toc: true -weight: 1 -description: > - Example pipeline with external secrets ---- - -Example [Yaml](https://yaml.org/spec/) configuration for a project requiring a secrets to be used within a step - -## Scenario - -User is looking to create a pipeline that can integrate with a private Vault to inject secrets that can not be used with pushing a Docker image to a registry. - -:::tip -It is assumed you have created secret `vault_token` in the web interface or [CLI](/docs/usage/tour/tour.md). -::: - -The examples show a pipeline using repository secrets. Vela contains three secret types: repository, organization, and shared. For examples on organization and shared, please see the [secret concepts](docs/usage/tour/secrets.md) documentation. - -### Steps - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Steps](docs/usage/tour/steps.md) - * [Image](docs/usage/tour/image.md) - * [Pull](docs/usage/tour/image.md) - * [Secrets](docs/usage/tour/secrets.md) - * [Parameters](docs/usage/tour/plugins.md) -* [Secrets](docs/usage/tour/secrets.md) - -The following [Vela plugins](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Docker](/docs/usage/plugins/registry/docker.md) - -:::tip -Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` - -It is recommended to pin `image:` versions for production pipelines -::: - -```yaml -version: "1" - -steps: - - name: publish hello world - image: target/vela-docker:latest - pull: always - parameters: - registry: index.docker.io - repo: index.docker.io/vela/hello-world - - -secrets: - # Note here how this pipeline uses an internal secret vault_token - # in the origin secret below to get additional secrets from an - # external service. - - name: vault_token - key: go-vela/vault_token - engine: native - type: org - - - origin: - name: private vault - image: target/secret-vault:latest - pull: always - secrets: [ vault_token ] - parameters: - addr: vault.example.com - auth_method: token - username: octocat - items: - - source: secret/docker - path: docker -``` - -### Stages - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Stages](docs/usage/tour/stages.md) - * [Steps](docs/usage/tour/steps.md) - * [Image](docs/usage/tour/image.md) - * [Pull](docs/usage/tour/image.md) - * [Secrets](docs/usage/tour/secrets.md) - * [Parameters](docs/usage/tour/plugins.md) -* [Secrets](docs/usage/tour/secrets.md) - -The following [Vela plugins](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Docker](/docs/usage/plugins/registry/docker.md) - -:::tip -Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` - -It is recommended to pin `image:` versions for production pipelines -::: - -```yaml -version: "1" - -worker: - runtime: docker - -stages: - docker: - steps: - - name: publish hello world - image: target/vela-docker:latest - pull: always - secrets: [ docker_username, docker_password ] - parameters: - registry: index.docker.io - repo: index.docker.io/vela/hello-world - -secrets: - - name: vault_token - key: go-vela/vault_token - engine: native - type: org - - - origin: - name: private vault - image: target/secret-vault:latest - pull: always - secrets: [ vault_token ] - parameters: - addr: vault.example.com - auth_method: token - username: octocat - items: - - source: secret/docker - path: docker -``` diff --git a/versioned_docs/version-0.26/usage/examples/secrets_internal.md b/versioned_docs/version-0.26/usage/examples/secrets_internal.md deleted file mode 100644 index f2eefae..0000000 --- a/versioned_docs/version-0.26/usage/examples/secrets_internal.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: "Internal Secrets" -toc: true -weight: 1 -description: > - Example Pipeline with internal secrets ---- - -Example [Yaml](https://yaml.org/spec/) configuration for a project requiring a secrets to be used within a step - -## Scenario - -User is looking to create a pipeline that can inject configuration that can not be placed into a Yaml file. A simple example would be producing a Docker image with username and password. - -:::tip -It is assumed you have created secrets `docker_username` and `docker_password` in the web interface or [CLI](/docs/reference/cli/secret/secret.md). -::: - -:::warning -Internal secrets do NOT have the `pull_request` event enabled by default. This is intentional to help mitigate exposure via a pull request against the repo. You can override this behavior, at your own risk, for each secret. -::: - -The examples show a pipeline using repo secrets. Vela contains three secret types: repo, org, and shared. Please see the [secret concepts](docs/usage/tour/secrets.md) documentation. - -### Steps - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Steps](docs/usage/tour/steps.md) - * [Image](docs/usage/tour/image.md) - * [Pull](docs/usage/tour/image.md) - * [Secrets](docs/usage/tour/secrets.md) - * [Parameters](docs/usage/tour/plugins.md) -* [Secrets](docs/usage/tour/secrets.md) - -The following [Vela plugins](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Docker](/docs/usage/plugins/registry/docker.md) - -:::tip -Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` - -It is recommended to pin `image:` versions for production pipelines -::: - -```yaml -version: "1" - -steps: - - name: publish hello world - image: target/vela-docker:latest - pull: always - secrets: [ docker_username, docker_password ] - parameters: - registry: index.docker.io - repo: index.docker.io/vela/hello-world - - -secrets: - - name: docker_username - key: vela/hello-world/docker_username - engine: native - type: repo - - - name: docker_password - key: vela/hello-world/docker_password - engine: native - type: repo -``` - -### Stages - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Stages](docs/usage/tour/stages.md) - * [Steps](docs/usage/tour/steps.md) - * [Image](docs/usage/tour/image.md) - * [Pull](docs/usage/tour/image.md) - * [Secrets](docs/usage/tour/secrets.md) - * [Parameters](docs/usage/tour/plugins.md) -* [Secrets](docs/usage/tour/secrets.md) - -The following [Vela plugins](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Docker](/docs/usage/plugins/registry/docker.md) - -:::tip -Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` - -It is recommended to pin `image:` versions for production pipelines -::: - -```yaml -version: "1" - -stages: - docker: - steps: - - name: publish hello world - image: target/vela-docker:latest - pull: always - secrets: [ docker_username, docker_password ] - parameters: - registry: index.docker.io - repo: index.docker.io/vela/hello-world - -secrets: - - name: docker_username - key: vela/hello-world/docker_username - engine: native - type: repo - - - name: docker_password - key: vela/hello-world/docker_password - engine: native - type: repo -``` diff --git a/versioned_docs/version-0.26/usage/json-schema-support.md b/versioned_docs/version-0.26/usage/json-schema-support.md deleted file mode 100644 index 06fde76..0000000 --- a/versioned_docs/version-0.26/usage/json-schema-support.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: "JSON Schema Support" ---- - -The schema gets published and updated via https://github.com/go-vela/types where it ends up as a release artifact. The latest schema is available for download from https://github.com/go-vela/types/releases/latest/download/schema.json. - -In addition, the schema is available in the JSON Schema Store project at https://www.schemastore.org. -[Supported editors](https://www.schemastore.org/json#editors) automatically use schemas that this project provides, including Vela's schema. diff --git a/versioned_docs/version-0.26/usage/managing-deployments.md b/versioned_docs/version-0.26/usage/managing-deployments.md deleted file mode 100644 index bb7fd22..0000000 --- a/versioned_docs/version-0.26/usage/managing-deployments.md +++ /dev/null @@ -1,88 +0,0 @@ - -# Managing Deployments - -Pipelines can be written with your specific branching methodology in mind but when it comes to deployments you often want to be very intentional with triggering a change. For this reason, Vela has deployments, a unique build event that is triggered directly via Vela on a specific ref (branch, SHA, tag). - -Vela leverages a deep integration with [GitHub Deployments](https://docs.github.com/en/rest/reference/repos#deployments) which will not only trigger your build but create a system of record on GitHub for your deployment action. You can leverage a deployment in your steps like: - -:::info -Make sure you have the `deployment` event enabled within repo settings - -Additionally, any secret you may need for the event must also have `deployments` allowed for events. -::: - -```yaml -# A step triggering on "all" deployment events -- name: All deployments - image: alpine - commands: - - echo "Running your deployment!" - ruleset: - event: [ deployment ] - -# A step triggering deployment to a specific target. -# Targets can be any value i.e. dev, stage, eng, prod, etc -- name: Targeted deployments - image: alpine - commands: - - echo "Running deployment for ${VELA_DEPLOYMENT}!" - ruleset: - event: [ deployment ] - target: [ dev, eng ] -``` - -## Usage - -Let us look at an example workflow for executing a deployment on your repo. You should understand the following concepts before proceeding: - -* [Steps](docs/usage/tour/steps.md) - * [image](docs/usage/tour/image.md) - * [Commands](docs/usage/tour/environment.md) - * [Ruleset](docs/usage/tour/rulesets.md) - -```yaml -version: "1" -steps: - # A step triggering on "all" deployment events - - name: All deployments - image: alpine - commands: - - echo "Running your deployment!" - ruleset: - event: [ deployment ] - - # A step triggering deployment to a specific target. - # Targets can be any value i.e. dev, stage, eng, prod, etc - - name: Targeted deployments - image: alpine - commands: - - echo "Running deployment for ${VELA_DEPLOYMENT}!" - ruleset: - event: [ deployment ] - target: [ dev, eng ] - - # Now that we know how to control a deployment, lets look - # at adding custom parameters. Sometimes not only do you need - # control of the target but you want custom data available - # when your pipeline runs. - - name: Custom parameters deployments - image: alpine - commands: - - echo "Custom parameter message, ${DEPLOYMENT_PARAMETER_MESSAGE}" - ruleset: - event: [ deployment ] - target: [ dev, eng ] -``` - -The following CLI commands will trigger the pipeline and produce different permutations of the pipeline executing: - -```sh -# Trigger deployment with no additional configuration -$ vela add deployment --org github --repo octocat - -# Trigger deployment for a repository with a specific target environment. -$ vela add deployment --org github --repo octocat --target stage - -# Add a deployment for a repository with two parameters. -$ vela add deployment --org github --repo octocat --parameter 'message=Hello, custom var!' -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/usage/open_id_connect.md b/versioned_docs/version-0.26/usage/open_id_connect.md deleted file mode 100644 index 05cd745..0000000 --- a/versioned_docs/version-0.26/usage/open_id_connect.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: "OpenID Connect" -toc: true -description: > - Learn how to leverage OpenID Connect for cloud services. ---- - -### OpenID in Vela - -Oftentimes, Vela builds interact with cloud providers to deploy software, update configurations, or more generally use the cloud's services. In order for this process to work securely, users create or retrieve credentials from the cloud provider and duplicate their values into Vela as secrets, which are injected into build steps. As an example, below is a pipeline which uploads a docker image to Artifactory: - -```yaml -version: "1" - -secrets: - # password for user Vela-Arti-User - - name: docker_password - key: VelaOrg/vela-repo - type: repo - engine: native - -steps: - - name: build & publish - image: target/vela-kaniko:latest - secrets: [ docker_password ] - parameters: - username: Vela-Arti-User - registry: my-arti-registry.com - repo: my-arti-registry.com/VelaOrg/vela-repo - tags: - - latest -``` - -The above pipeline will work and be suitable for many cloud-related CI builds. However, there are potential issues with this method. As stricter rotation policies for credentials becomes more common place, developing processes wherein Vela secrets are updated in tandem with these rotations is introducing unneccessary tech debt and is antithetical to continuous integration. - -In comes [OpenID Connect](https://openid.net/developers/how-connect-works/). - -With OpenID Connect (OIDC), you can configure your pipeline to request a short-lived access token directly from the cloud provider. This requires that the cloud provider supports OIDC processing for Vela ID tokens and properly validates the token using Vela's OpenID configuration and JWKs. - -Let's take a look at the same pipeline but using OpenID Connect. - -```yaml -version: "1" - -steps: - - name: get credentials - image: alpine - id_request: yes - commands: - - > - AUTH_TOKEN=$(curl -H "Authorization: Bearer $VELA_ID_TOKEN_REQUEST_TOKEN" - "$VELA_ID_TOKEN_REQUEST_URL?audience=artifactory" | - jq -r '.value') - - > - REQ=$(curl -s -X POST -H "Token: $AUTH_TOKEN" - "https://cloud-service-open-id-validator.com/get-token") - - echo "${REQ}" | jq -r .username > /vela/secrets/kaniko/username - - echo "${REQ}" | jq -r .token > /vela/secrets/kaniko/password - - - name: build & publish - image: target/vela-kaniko:latest - parameters: - registry: my-arti-registry.com - repo: my-arti-registry.com/VelaOrg/vela-repo - tags: - - latest -``` - -In this example, the `get credentials` step is using the Vela environment values of `VELA_ID_TOKEN_REQUEST_TOKEN` and `VELA_ID_TOKEN_REQUEST_URL` to retrieve a short-lived ID token that can be used to authenticate with the cloud service, so long as that service has an OpenID processing layer. - -The `id_request` key being set to _anything_ will result in the injection of the request environment variables. The value of `id_request` becomes a claim in the eventual ID token. - -### ID Token Claims - -```json -{ - "build_number": 42, - "build_id": 100, - "actor": "Octocat", - "actor_scm_id": "1", - "repo": "Octocat/vela-testing", - "token_type": "ID", - "image": "golang:1.22.4", - "request": "yes", - "commands": true, - "event": "pull_request:opened", - "ref": "refs/heads/main", - "sha": "15b17a5751dd2fd04a7b4ca056063dc876984073", - "iss": "https://vela-server.com/_services/token", - "sub": "repo:Octocat/vela-testing:ref:refs/heads/main:event:pull_request", - "aud": [ - "artifactory" - ], - "exp": 1717699924, - "iat": 1717699624 -} -``` - -### Validating an ID Token - -There are many resources on validating OpenID tokens. Some of the high level requirements: - -- Can the token be validated using the JWKs located at the well-known path of the issuer? -- Do the claims of the ID token match the cloud service expectations? -- Are the claims all members of the `supported_claims` field located at the well-known OpenID configuration? \ No newline at end of file diff --git a/versioned_docs/version-0.26/usage/outputs.md b/versioned_docs/version-0.26/usage/outputs.md deleted file mode 100644 index 33a4c89..0000000 --- a/versioned_docs/version-0.26/usage/outputs.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: "Outputs" -toc: true -description: > - Learn how to configure outputs for steps. ---- - -:::tip -Outputs functionality is only available in the Docker runtime. -::: - -### What are outputs and why are they useful? - -While the workspace [is shared](/docs/usage/workspace.md) for all steps in a build, the environment is not. This is because changes to a container environment are not exported after the completion of a step. - -For example, take the following pipeline: - -```yaml -version: "1" - -steps: - - name: parse image for testing - image: alpine:latest - commands: - # image to use is the first part of the source branch (inventory-updates -> my-organization/inventory:latest) - - image=$(echo ${VELA_PULL_REQUEST_SOURCE} | sed 's/[_.-].*//') - - - name: test - image: my-organization/${image}:latest - pull: on_start - commands: - - go test ./... - -``` - -This is not a valid pipeline configuration because `image` will not persist from the first step to the second. However, being able to dynamically update environment variables for substitution or for plugin parameters can be an important part of a CI build. - -This is where `outputs` can improve your pipeline configurations. - -Let's take the same pipeline but make it valid using outputs: - -```yaml -version: "1" - -steps: - - name: parse image for testing - image: alpine:latest - commands: - # image to use is the first part of the source branch (inventory-updates -> my-organization/inventory:latest) - - echo "image=$(echo ${VELA_PULL_REQUEST_SOURCE} | sed 's/[_.-].*//')" > $VELA_OUTPUTS - - - name: test - image: my-organization/${image}:latest - pull: on_start - commands: - - go test ./... -``` - -Writing to `$VELA_OUTPUTS` in environment file format ensures that those key-value pairs persist for the entirety of the build. - -Not only is this more convenient than storing information in the shared workspace, it can also be safer. Vela secrets are masked in logs, but any sensitive value captured during a build has the potential to be leaked in logs if steps or plugins are not configured correctly. - -This can be remedied with masked outputs: - -```yaml -version: "1" - -steps: - - name: capture API key for testing - image: alpine:latest - commands: - - apk add jq - - echo "API_KEY=$(curl http://my-test-endpoint/token | jq .token)" > $VELA_MASKED_OUTPUTS - - - name: test - image: golang:latest - commands: - - echo $API_KEY # will print *** - - go test ./... -``` - -After the first step is complete, the logs will mask any mention of the `$API_KEY`. - -### Limitations - -- Outputs can only be used as environment variables (`$VAR`) or substitution variables (`${VAR}`). Inline Go templating (`{{ .VAR }}`) is done at compile time and will not dynamically be evaluated. - -- Masking will only be applied to variables in `$VELA_MASKED_OUTPUTS` in steps that run _after_ the variable has been written. In other words, if `Step A` writes a token to `$VELA_MASKED_OUTPUTS`, `Step A` logs will _not_ mask the value. Only subsequent steps will have the masking applied. \ No newline at end of file diff --git a/versioned_docs/version-0.26/usage/plugin.md b/versioned_docs/version-0.26/usage/plugin.md deleted file mode 100644 index 406f07c..0000000 --- a/versioned_docs/version-0.26/usage/plugin.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: "Working with plugins" -toc: true -description: > - Walkthrough of an example using pipeline and secret plugins working together ---- - -:::note -The following plugins are used within the example - -* [Kaniko](/docs/usage/plugins/registry/Kaniko.md) -* [Vault](/docs/usage/tour/vault secrets.md) -::: - -Typically, plugins are configured as a step in a pipeline and should accept their configuration via environment variables. The below example shows a pipeline and secret plugin working together to publish an image to a registry: - -```yaml -version: "1" - -steps: - - name: plugin - image: target/vela-kaniko - pull: always - parameters: - registry: index.docker.io - repo: index.docker.io/octocat/hello-world - -secrets: - - name: vault_token - key: go-vela/vault_token - engine: native - type: org - - - origin: - name: plugin - image: target/secret-vault - pull: always - secrets: [ vault_token ] - parameters: - addr: vault.example.com - auth_method: token - items: - - source: secret/docker - path: docker -``` - -We pass these variables in Vela using the `parameters` block. Any variable passed to this block, will be injected into the step as `PARAMETER_`: - -```diff -version: "1" - -steps: - - name: docker - image: target/vela-kaniko - pull: always -+ parameters: -+ registry: index.docker.io -+ repo: index.docker.io/octocat/hello-world - -secrets: - - name: vault_token - key: go-vela/vault_token - engine: native - type: org - - - origin: - name: vault - image: target/secret-vault - pull: always - secrets: [ vault_token ] -+ parameters: -+ addr: vault.example.com -+ auth_method: token -+ items: -+ - source: secret/docker -+ path: docker -``` - -From the above example, the following environment variables would be added to the containers: - -**Docker:** - -* `PARAMETER_REGISTRY=index.docker.io` -* `PARAMETER_REPO=index.docker.io/octocat/hello-world` - -**Vault:** - -* `PARAMETER_ADDR=index.docker.io` -* `PARAMETER_AUTH_METHOD=index.docker.io/octocat/hello-world` -* `PARAMETER_ITEMS={"items": [{"source": "secret/docker"}],"path": "docker"}` diff --git a/versioned_docs/version-0.26/usage/plugins/index.md b/versioned_docs/version-0.26/usage/plugins/index.md deleted file mode 100644 index 25848a9..0000000 --- a/versioned_docs/version-0.26/usage/plugins/index.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: "Plugins" -sidebar_position: 4 ---- - -Vela contains two plugin types: - -* pipeline - designed to be used within steps, stages, and template pipelines -* secret - designed to be used within the secrets Yaml block of pipelines - -Both accept configuration via environment variables but should be used within their specific location of the Yaml pipeline. - -:::info -Before you begin your plugin journey we recommend the following pre-requisites: - -* [Steps](docs/usage/tour/steps.md) -* [Stages](docs/usage/tour/stages.md) -* [Templates](docs/usage/tour/templates.md) -::: - -## Pipeline - -Pipeline plugins are designed to automate, customize, and execute your software development workflows. A pipeline plugin is a Docker container that is designed to perform a set of pre-defined actions. - -These actions can be for any number of general tasks, including: - -* deploying code -* publishing artifacts -* sending notifications -* much, much more... - -### Example - -The example we have shown is publishing an image to a registry. Pipeline plugins configuration works via environment variables that pass data from pipeline to the container at runtime. - -_Not a runnable pipeline_ -```diff -version: "1" - -steps: - - name: docker - image: target/vela-docker - pull: always -+ parameters: -+ registry: index.docker.io -+ repo: index.docker.io/octocat/hello-world -``` - -## Secret - -:::warning -Secret plugins are configured with an allow list of available images via an administator on installation. To know which secret plugins are available for your Vela installation, we recommend consulting your system administrators. -::: - -Secret plugins are designed to be used to read secrets in volumes within the Vela workspace. When a secret plugin runs the plugin should write data to the custom Vela mount (`/vela/secrets/`) as key/value pairs. Secret plugins configuration works via environment variables that pass data from pipeline to the container at runtime. - -A secret plugin works in tandem with the Vela workspace to read data from a provider and write them into an available location (`/vela/secrets`) within a pipeline. - -### Sample - -_Not a runnable pipeline_ -```diff -secrets: - - name: vault_token - key: go-vela/vault_token - engine: native - type: org - - - origin: - name: vault - image: target/secret-vault - pull: always - secrets: [ vault_token ] -+ parameters: -+ addr: vault.company.com -+ auth_method: token -+ username: octocat -+ items: -+ - source: secret/docker -+ path: docker -``` - -From the above example, will have written the following available secrets to: - -* `/vela/secrets/docker// **NOTE:** -> -> Users should refrain from using latest as the tag for the Docker image. -> -> It is recommended to use a semantically versioned tag instead. - -More information for ansible-lint can be found at: [ansible-lint docs](https://ansible-lint.readthedocs.io/en/latest/). \ -More information for ansible-playbook can be found at: [ansible-playbook docs](https://ansible-lint.readthedocs.io/en/latest/). - -### Sample for .vela.yml - -```yaml -steps: - - name: ansible-lint - image: target/vela-ansible:latest - parameters: - action: lint - playbook: "abox/main.yml" - lint_skip: - - no-changed-when - - key-order - - - name: ansible-playbook - image: target/vela-ansible:latest - parameters: - action: playbook - playbook: "abox/main.yml" - options_inventory: "abox/inventory/hosts.yml" - connection_user: root -``` - -## Parameters - -The following parameters are used to configure the image: - -| Parameter | Description | Required | Default | -| ----------- | -------------------------------------------------------------------------- | -------- | ------- | -| `log_level` | set the log level for the plugin (valid options: `info`, `debug`, `trace`) | true | info | -| `action ` | set plugin action (valid options: `lint`, `playbook` | true | lint | - -> Note: `action` parameter will determine whether to run ansible-lint or ansible-playbook. The default is set to ansible-lint. - -### Ansible-Lint - -| Parameter | Description | Required | Default | -| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------- | -| `playbook` | playbook to be ran by ansible-lint | true | false | -| `lint_version` | returns ansible-lint version and exits the program. | false | false | -| `lint_list` | lists all the rules. | false | false | -| `lint_format` | format used rules output `{rich,plain,rst,codeclimate,quiet,pep8}` | false | rich | -| `lint_quieter` | quieter, although not silent output. | false | false | -| `lint_parseable` | parseable output in the format of pep8. | false | false | -| `lint_parseableseverity` | parseable output including severity of rule. | false | false | -| `lint_progressive` | return success if it detects a reduction in number of violations compared with previous git commit. This feature works only in git repositories. | false | false | -| `lint_projectdir` | location of project/repository, autodetected based on location of configuration file. | false | N/A | -| `lint_rule` | specify one or more rules directories. -r flag (lint_rule) overrides the default rules in /path/to/ansible-lint/lib/ansiblelint/rules, unless -R (lint_rulesdefault) is also used. | false | N/A | -| `lint_rulesdefault` | use default rules in /path/to/ansible-lint/lib/ansiblelint/rules in addition to any extra rules directories specified with -r (lint_rule). There is no need to specify this if no -r (lint_rule) flag/s is/are used. | false | false | -| `lint_showrelativepath` | display path relative to CWD. | false | false | -| `lint_tags` | only check rules whose id/tags match these values. | false | N/A | -| `lint_tagslist` | list all the tags. | false | false | -| `lint_verbose` | increase verbosity level. | false | false | -| `lint_skip` | only check rules whose id/tags does not match these values. | false | N/A | -| `lint_warn` | only warn about these rules, unless overridden in config file defaults to 'experimental' | false | experimental | -| `lint_enable` | activate optional rules by their tag name | false | N/A | -| `lint_nocolor` | disable colored output. | false | false | -| `lint_forcecolor` | try force colored output. | false | false | -| `lint_exclude` | path to directories or files to skip. | false | N/A | -| `lint_config` | specify a configuration file to use. | false | .ansible-lint | -| `lint_offline` | disable installation of requirements.yml | false | false | - -### Ansible-Playbook - -| Parameter | Description | Required | Default | -| ---------- | --------------------------------------- | -------- | ------- | -| `playbook` | playbook to be ran by ansible-playbook. | true | N/A | - -### ansible-playbook options - -| Parameter | Description | Required | Default | -| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------- | -| `options_askvaultpass` | ask for vault password. | false | false | -| `options_flushcache` | clear the fact cache for every host in inventory. | false | false | -| `options_forcehandlers` | run handlers even if a task fails. | false | false | -| `options_listhosts` | outputs a list of matching hosts and exits program. | false | false | -| `options_listtags` | list all available tags | false | false | -| `options_listtasks` | list all tasks to be executed. | false | false | -| `options_skiptags` | only run plays and tasks whose tags does not match these values. | false | N/A | -| `options_startattask` | start the playbook at the task matching this name. | false | N/A | -| `options_step` | one-set-at-a-time: confirm each task before running. | false | false | -| `options_syntaxcheck` | perform a syntax check on the playbook and exits program. | false | false | -| `options_vaultid` | the vault identity to use. | false | N/A | -| `options_vaultpasswordfile` | vault password file. | false | N/A | -| `options_version` | returns ansible-playbook version number, configuration file location, configured module search path, module location, executable location and exits program. | false | false | -| `options_check` | dry-run, does not make any changes; instead, tries to predict some of the changes that may occur. | false | false | -| `options_difference` | when changing (small) files and template, shows the difference in those files. | false | false | -| `options_modulepath` | prepend colon-separated path(s) to module library | false | ~/.ansible/plugins/modules:/usr/share/ansible/plugins/modules | -| `options_extravars` | set additional variables as key=value or YAML/JSON, if filename is prepend with @ | false | N/A | -| `options_forks` | specify number of parallel processes to use. | false | 5 | -| `options_inventory` | specify inventory host path or comma separated host list. | true | N/A | -| `options_limit` | further limit selected hosts to additional pattern. | false | false | -| `options_tags` | only run plays and task whose tags matches these values. | false | N/A | -| `options_verbose` | verbose mode. | false | false | -| `options_verbosemore` | verbose mode: more verbose. | false | false | -| `options_verbosedebug` | verbose mode: connection debugging | false | false | - -### ansible-playbook connection - -| Parameter | Description | Required | Default | -| -------------------------- | ------------------------------------------------- | -------- | ------- | -| `connection_privatekey` | use this file to authenticate the connection. | false | N/A | -| `connection_scpextraargs` | specify extra arguments to pass to scp only. | false | N/A | -| `connection_sftpextraargs` | specify extra arguments to pass to sftp only. | false | N/A | -| `connection_sshextraargs` | specify extra arguments to pass to ssh only. | false | N/A | -| `connection_sshcommonargs` | specify common arguments to pass to scp/sftp/ssh. | false | N/A | -| `connection_timeout` | override the connection timeout in seconds. | false | 10 | -| `connection_connection` | connection type to use. | false | smart | -| `connection_user` | connect as this user. | false | none | -| `connection_passwordfile` | connection password file | false | N/A | - -### ansible-playbook privilege escalation - -| Parameter | Description | Required | Default | -| -------------------------- | -------------------------------------------------------------- | -------- | ------- | -| `privilege_becomemethod` | privilege escalation method to use. | false | sudo | -| `privilege_becomeuser` | run operation as this user. | false | root | -| `privilege_askbecomepass` | ask for privilege escalation password. | false | false | -| `privilege_become` | run operations with become (does not imply password prompting) | false | false | -| `privilege_becomepassfile` | become password file | false | N/A | - -## Template - -COMING SOON! - -## Troubleshooting - -You can start troubleshooting this plugin by tuning the level of logs being displayed: - -```diff -steps: - - name: ansible-lint - image: target/vela-ansible:latest - parameters: -+ log_level: trace - action: lint - playbook: "abox/main.yml" - -``` - -Below are a list of common problems and how to solve them: diff --git a/versioned_docs/version-0.26/usage/plugins/registry/Artifactory.md b/versioned_docs/version-0.26/usage/plugins/registry/Artifactory.md deleted file mode 100644 index 920b360..0000000 --- a/versioned_docs/version-0.26/usage/plugins/registry/Artifactory.md +++ /dev/null @@ -1,320 +0,0 @@ -## Description - -This plugin enables you to manage artifacts in [Artifactory](https://jfrog.com/artifactory/) in a Vela pipeline. - -Source Code: https://github.com/go-vela/vela-artifactory - -Registry: https://hub.docker.com/r/target/vela-artifactory - -## Usage - -> **NOTE:** -> -> Users should refrain from using latest as the tag for the Docker image. -> -> It is recommended to use a semantically versioned tag instead. - -Sample of copying an artifact: - -```yaml -steps: - - name: copy_artifacts - image: target/vela-artifactory:latest - pull: always - parameters: - action: copy - path: libs-snapshot-local/foo.txt - target: libs-snapshot-local/bar.txt - url: http://localhost:8081/artifactory -``` - -Sample of deleting an artifact: - -```yaml -steps: - - name: delete_artifacts - image: target/vela-artifactory:latest - pull: always - parameters: - action: delete - path: libs-snapshot-local/foo.txt - url: http://localhost:8081/artifactory -``` - -Sample of setting properties on an artifact: - -```yaml -steps: - - name: set_properties_artifacts - image: target/vela-artifactory:latest - pull: always - parameters: - action: set-prop - path: libs-snapshot-local/foo.txt - props: - - name: single - value: foo - - name: multiple - values: - - bar - - baz - url: http://localhost:8081/artifactory -``` - -Sample of uploading an artifact: - -```yaml -steps: - - name: upload_artifacts - image: target/vela-artifactory:latest - pull: always - parameters: - action: upload - path: libs-snapshot-local/ - sources: - - foo.txt - - target/*.jar - - dist/**/*.js - url: http://localhost:8081/artifactory -``` - -Sample of uploading an artifact using regexp: - -```yaml -steps: - - name: upload_artifacts - image: target/vela-artifactory:latest - pull: always - parameters: - action: upload - path: libs-snapshot-local/ - regexp: true - sources: - - dist/([a-z]+).js - url: http://localhost:8081/artifactory -``` - -> [!IMPORTANT] -> As the [JFrog docs](https://docs.jfrog-applications.jfrog.io/jfrog-applications/jfrog-cli/cli-for-jfrog-artifactory/generic-files) call out: If you have specified that you are using regular expressions, then the beginning of the expression must be enclosed in parenthesis. For example: a/b/c/(.*)/file.zip - -Sample of uploading an artifact using build props (matrix parameters): - -```yaml -steps: - - name: upload_artifacts - image: target/vela-artifactory:latest - pull: always - parameters: - action: upload - path: libs-snapshot-local/file - sources: - - file.txt - build_props: build.name=buildName;build.number=17;build.timestamp=1600856623553 - url: http://localhost:8081/artifactory -``` - -Sample of pretending to upload an artifact: - -```diff -steps: - - name: upload_artifacts - image: target/vela-artifactory:latest - pull: always - parameters: - action: upload -+ dry_run: true - path: libs-snapshot-local/ - sources: - - foo.txt - - target/*.jar - - dist/**/*.js - url: http://localhost:8081/artifactory -``` - -Sample of using docker-promote on an artifact: - -```yaml -steps: - - name: docker_promote_artifacts - image: target/vela-artifactory:latest - pull: always - parameters: - action: docker-promote - target_repo: libs-snapshot-local - docker_registry: octocat/hello-world - tag: latest - target_docker_registry: octocat/hello-world - target_tags: "${VELA_BUILD_COMMIT:0:8}" -``` - -## Secrets - -> **NOTE:** Users should refrain from configuring sensitive information in your pipeline in plain text. - -### Internal - -The plugin accepts the following `parameters` for authentication: - -| Parameter | Environment Variable Configuration | -| ----------- | -------------------------------------------- | -| `api_key` | `PARAMETER_API_KEY`, `ARTIFACTORY_API_KEY` | -| `password` | `PARAMETER_PASSWORD`, `ARTIFACTORY_PASSWORD` | -| `username` | `PARAMETER_USERNAME`, `ARTIFACTORY_USERNAME` | - -Users can use [Vela internal secrets](https://go-vela.github.io/docs/tour/secrets/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: copy_artifacts - image: target/vela-artifactory:latest - pull: always -+ secrets: [ artifactory_username, artifactory_password ] - parameters: - action: copy - path: libs-snapshot-local/foo.txt - target: libs-snapshot-local/bar.txt - url: http://localhost:8081/artifactory -- username: octocat -- password: superSecretPassword -``` - -> This example will add the secrets to the `copy_artifacts` step as environment variables: -> -> * `ARTIFACTORY_USERNAME=` -> * `ARTIFACTORY_PASSWORD=` - -### External - -The plugin accepts the following files for authentication: - -| Parameter | File Configuration | -| ---------- | ----------------------------------------------------------------------------- | -| `api_key` | `/vela/parameters/artifactory/api_key`, `/vela/secrets/artifactory/api_key`, `/vela/secrets/managed-auth/api_key` | -| `password` | `/vela/parameters/artifactory/password`, `/vela/secrets/artifactory/password`, `/vela/secrets/managed-auth/password` | -| `username` | `/vela/parameters/artifactory/username`, `/vela/secrets/artifactory/username`, `/vela/secrets/managed-auth/username` | - -Users can use [Vela external secrets](https://go-vela.github.io/docs/tour/secrets/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: copy_artifacts - image: target/vela-artifactory:latest - pull: always - parameters: - action: copy - path: libs-snapshot-local/foo.txt - target: libs-snapshot-local/bar.txt - url: http://localhost:8081/artifactory -- username: octocat -- password: superSecretPassword -``` - -> This example will read the secret values in the build workspace stored at `/vela/secrets/artifactory/*` - -## Parameters - -> **NOTE:** -> -> The plugin supports reading all parameters via: -> -> * environment variables - `PARAMETER_*` OR `ARTIFACTORY_*` -> * files - `/vela/parameters/artifactory/*` OR `/vela/secrets/artifactory/*` -> -> Any values set from a file takes precedence over values set from the environment. - -The following parameters are used to configure the image: - -| Name | Description | Required | Default | Environment Variables | -| ----------- | -------------------------------------------- | -------- | ------- | ------------------------------------------------ | -| `action` | action to perform against Artifactory | `true` | `N/A` | `PARAMETER_ACTION`
`ARTIFACTORY_ACTION` | -| `api_key` | API key for communication with Artifactory | `false` | `N/A` | `PARAMETER_API_KEY`
`ARTIFACTORY_API_KEY` | -| `dry_run` | enables pretending to perform the action | `false` | `false` | `PARAMETER_DRY_RUN`
`ARTIFACTORY_DRY_RUN` | -| `log_level` | set the log level for the plugin | `true` | `info` | `PARAMETER_LOG_LEVEL`
`ARTIFACTORY_LOG_LEVEL` | -| `password` | password for communication with Artifactory | `false` | `N/A` | `PARAMETER_PASSWORD`
`ARTIFACTORY_PASSWORD` | -| `url` | Artifactory instance to communicate with | `true` | `N/A` | `PARAMETER_URL`
`ARTIFACTORY_URL` | -| `username` | user name for communication with Artifactory | `false` | `N/A` | `PARAMETER_USERNAME`
`ARTIFACTORY_USERNAME` | -| `http_client_retries` | number of times to retry failed http attempts | `false` | `3` | `PARAMETER_HTTP_CLIENT_RETRIES`
`ARTIFACTORY_HTTP_CLIENT_RETRIES` | -| `http_client_retry_wait` | amount of milliseconds to wait between failed http attempts | `false` | `500` | `PARAMETER_HTTP_CLIENT_RETRY_WAIT_MILLISECONDS`
`ARTIFACTORY_HTTP_CLIENT_RETRY_WAIT_MILLISECONDS` | -| `http_client_cert` | file path to the client certificate to use for TLS communication | `false` | `N/A` | `PARAMETER_HTTP_CLIENT_CERT`
`ARTIFACTORY_HTTP_CLIENT_CERT` | -| `http_client_cert_key` | file path to the client certificate key to use for TLS communication | `false` | `N/A` | `PARAMETER_HTTP_CLIENT_CERT_KEY`
`ARTIFACTORY_HTTP_CLIENT_CERT_KEY` | -| `http_client_insecure_tls` | enable insecure TLS communication | `false` | `false` | `PARAMETER_HTTP_CLIENT_INSECURE_TLS`
`ARTIFACTORY_HTTP_CLIENT_INSECURE_TLS` | - -### Copy - -The following parameters are used to configure the `copy` action: - -| Name | Description | Required | Default | Environment Variables | -| ----------- | --------------------------------------------------- | -------- | ------- | ------------------------------------------------ | -| `flat` | enables removing source directory hierarchy | `false` | `false` | `PARAMETER_FLAT`
`ARTIFACTORY_FLAT` | -| `path` | source path to copy artifact(s) from | `true` | `N/A` | `PARAMETER_PATH`
`ARTIFACTORY_PATH` | -| `recursive` | enables copying sub-directories for the artifact(s) | `false` | `false` | `PARAMETER_RECURSIVE`
`ARTIFACTORY_RECURSIVE` | -| `target` | target path to copy artifact(s) to | `true` | `N/A` | `PARAMETER_TARGET`
`ARTIFACTORY_TARGET` | - -### Delete - -The following parameters are used to configure the `delete` action: - -| Name | Description | Required | Default | Environment Variables | -| ----------- | ---------------------------------------------------- | -------- | ------- | ------------------------------------------------ | -| `path` | target path to delete artifact(s) from | `true` | `N/A` | `PARAMETER_PATH`
`ARTIFACTORY_PATH` | -| `recursive` | enables removing sub-directories for the artifact(s) | `false` | `false` | `PARAMETER_RECURSIVE`
`ARTIFACTORY_RECURSIVE` | - -### Docker-Promote - -The following parameters are used to configure the `docker-promote` action: - -| Name | Description | Required | Default | Environment Variables | -| ------------------------ | --------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------- | -| `copy` | set to copy instead of moving the image | `false` | `true` | `PARAMETER_COPY`
`ARTIFACTORY_COPY` | -| `docker_registry` | path to image in docker registry | `true` | `N/A` | `PARAMETER_DOCKER_REGISTRY`
`ARTIFACTORY_DOCKER_REGISTRY` | -| `promote_props` | enables setting properties on the promoted artifact | `false` | `false` | `PARAMETER_PROMOTE_PROPS`
`ARTIFACTORY_PROMOTE_PROPS` | -| `tag` | name of the tag for promoting | `true` | `N/A` | `PARAMETER_TAG`
`ARTIFACTORY_TAG` | -| `target_docker_registry` | path for target image in docker registry | `true` | `N/A` | `PARAMETER_TARGET_DOCKER_REGISTRY`
`ARTIFACTORY_TARGET_DOCKER_REGISTRY` | -| `target_repo` | name of the docker registry containing the image | `true` | `N/A` | `PARAMETER_TARGET_REPO`
`ARTIFACTORY_TARGET_REPO` | -| `target_tags` | name of the final tags after promotion | `true` | `N/A` | `PARAMETER_TARGET_TAGS`
`ARTIFACTORY_TARGET_TAGS` | - -### Set-Prop - -The following parameters are used to configure the `set-prop` action: - -| Name | Description | Required | Default | Environment Variables | -| ------- | ------------------------------------ | -------- | ------- | ---------------------------------------- | -| `path` | target path to artifact(s) | `true` | `N/A` | `PARAMETER_PATH`
`ARTIFACTORY_PATH` | -| `props` | properties to set on the artifact(s) | `true` | `N/A` | `PARAMETER_PROPS`
`ARTIFACTORY_PROPS` | - -### Upload - -The following parameters are used to configure the `upload` action: - -| Name | Description | Required | Default | Environment Variables | -| -------------- | ----------------------------------------------------- | -------- | ------- | ------------------------------------------------------ | -| `build_props` | build props (matrix parameters) to apply | `false` | `N/A` | `PARAMETER_BUILD_PROPS`
`ARTIFACTORY_BUILD_PROPS` | -| `flat` | enables removing source directory hierarchy | `false` | `false` | `PARAMETER_FLAT`
`ARTIFACTORY_FLAT` | -| `include_dirs` | enables including sub-directories for the artifact(s) | `false` | `false` | `PARAMETER_INCLUDE_DIRS`
`ARTIFACTORY_INCLUDE_DIRS` | -| `path` | target path to upload artifact(s) to | `true` | `N/A` | `PARAMETER_PATH`
`ARTIFACTORY_PATH` | -| `recursive` | enables uploading sub-directories for the artifact(s) | `false` | `false` | `PARAMETER_RECURSIVE`
`ARTIFACTORY_RECURSIVE` | -| `regexp` | enables reading the sources as a regular expression | `false` | `false` | `PARAMETER_REGEXP`
`ARTIFACTORY_REGEXP` | -| `sources` | list of artifact(s) to upload | `true` | `N/A` | `PARAMETER_SOURCES`
`ARTIFACTORY_SOURCES` | - -## Template - -COMING SOON! - -## Troubleshooting - -You can start troubleshooting this plugin by tuning the level of logs being displayed: - -```diff -steps: - - name: copy_artifacts - image: target/vela-artifactory:latest - pull: always - parameters: - action: copy -+ log_level: trace - path: libs-snapshot-local/foo.txt - target: libs-snapshot-local/bar.txt - url: http://localhost:8081/artifactory -``` - -Below are a list of common problems and how to solve them: diff --git a/versioned_docs/version-0.26/usage/plugins/registry/Aws Credentials.md b/versioned_docs/version-0.26/usage/plugins/registry/Aws Credentials.md deleted file mode 100644 index 333d8ac..0000000 --- a/versioned_docs/version-0.26/usage/plugins/registry/Aws Credentials.md +++ /dev/null @@ -1,205 +0,0 @@ -## Description - -With OpenID Connect (OIDC), you can configure your pipeline to request a short-lived set of credentials from AWS. - -Source Code: https://github.com/Cargill/vela-aws-credentials - -Registry: https://hub.docker.com/r/cargill/vela-aws-credentials - -## Prerequisites - -### Adding the identity provider to AWS - -To add the Vela OIDC provider to IAM, see the [AWS docs](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html). - -- Provider URL: `https:///_services/token`. -- Audience: `sts.amazonaws.com`. - -Terraform example: - -```terraform -data "tls_certificate" "vela" { - url = "https://vela-server.com/_services/token" -} - -resource "aws_iam_openid_connect_provider" "vela" { - url = "https://vela-server.com/_services/token" - client_id_list = ["sts.amazonaws.com"] - thumbprint_list = [data.tls_certificate.vela.certificates[0].sha1_fingerprint] -} -``` - -### Configuring the IAM role - -Review the [official AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html) for IAM roles with OIDC. - -> **NOTE:** It is critical that the IAM trust policy has conditions to limit which Vela pipelines/steps are able to assume the IAM role. - -The example below includes several conditions that limit the ability to assume the IAM role: - -1. The `StringLike` condition on the `sub` claim with a wildcard operator (*) allows any branch or pull request merge branch from the `octo-org/octo-repo` organization and repository to assume the IAM role in AWS. -2. The `StringLike` condition on the `image` claim with a wildcard operator (*) permits only steps that use the `golang:` image to assume the IAM role in AWS. -3. The `StringEquals` condition on the `aud` claim ensures that only tokens with the audience of `sts.amazonaws.com` can assume the IAM role in AWS. `sts.amazonaws.com` is the default audience when utilizing this plugin. -4. The `StringEquals` condition on the `commands` claim ensures that only steps without a `commands` section can assume the IAM role in AWS. - -> **NOTE:** AWS requires that all conditions must be met for the role assumption to succeed. If any condition is not met, the role assumption will fail. - -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Principal": { - "Federated": "arn:aws:iam::123456123456:oidc-provider/vela-server.com/_services/token" - }, - "Action": "sts:AssumeRoleWithWebIdentity", - "Condition": { - "StringLike": { - "vela-server.com/_services/token:sub": "repo:octo-org/octo-repo:*", - "vela-server.com/_services/token:image": "golang:*" - }, - "StringEquals": { - "vela-server.com/_services/token:aud": "sts.amazonaws.com", - "vela-server.com/_services/token:commands": false - } - } - } - ] -} -``` - -The full list of claims that Vela exposes to AWS can be found within [the Vela docs](https://go-vela.github.io/docs/usage/open_id_connect/#id-token-claims). - -Terraform example: - -```terraform -data "aws_iam_policy_document" "assume_role_policy" { - statement { - actions = [ "sts:AssumeRoleWithWebIdentity" ] - principals { - identifiers = [ aws_iam_openid_connect_provider.vela.arn ] - type = "Federated" - } - - condition { - test = "StringLike" - variable = "vela-server.com/_services/token:sub" - values = ["repo:octo-org/octo-repo:*"] - } - - condition { - test = "StringLike" - variable = "vela-server.com/_services/token:image" - values = ["golang:*"] - } - - condition { - test = "StringEquals" - variable = "vela-server.com/_services/token:aud" - values = ["sts.amazonaws.com"] - } - - condition { - test = "StringEquals" - variable = "vela-server.com/_services/token:commands" - values = [false] - } - } -} - -resource "aws_iam_role" "test_role" { - name = "test_role" - - assume_role_policy = data.aws_iam_policy_document.assume_role_policy.json -} -``` - -## Usage - -> **NOTE:** -> -> Users should refrain from using latest as the tag for the Docker image. -> -> It is recommended to use a semantically versioned tag instead. - -Example of generating credentials: - -```yaml -steps: - - name: generate_aws - image: cargill/vela-aws-credentials:latest - id_request: yes - parameters: - role: "arn:aws:iam::123456123456:role/test" -``` - -Example of generating credentials with a different region: - -```diff -steps: - - name: generate_aws - image: cargill/vela-aws-credentials:latest - id_request: yes - parameters: - role: "arn:aws:iam::123456123456:role/test" -+ region: "us-west-2" -``` - -Sample of generating credentials, writing credentials script, and utilizing them with the AWS CLI: - -```yaml -steps: - - name: generate_aws - image: cargill/vela-aws-credentials:latest - id_request: yes - parameters: - role: "arn:aws:iam::123456123456:role/test" - script_write: true - - - name: test_aws - image: amazon/aws-cli:latest - commands: - - source /vela/secrets/aws/setup.sh - - aws sts get-caller-identity -``` - -## Parameters - -> **NOTE:** -> -> The plugin supports reading all parameters via environment variables or files. -> -> Any values set from a file take precedence over values set from the environment. - -The following parameters are used to configure the image: - -| Name | Description | Required | Default | Environment Variables | -|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------| -| `role` | AWS IAM Role ARN for which to generate credentials | `true` | `N/A` | `PARAMETER_ROLE`
`AWS_CREDENTIALS_ROLE` | -| `region` | AWS region where you want to obtain credentials. | `false` | `us-east-1` | `PARAMETER_REGION`
`AWS_CREDENTIALS_REGION` | -| `role_duration_seconds` | Assumed role duration in seconds. | `false` | `3600` | `PARAMETER_ROLE_DURATION_SECONDS`
`AWS_CREDENTIALS_ROLE_DURATION_SECONDS` | -| `role_session_name` | Session name to use when assuming the role. | `false` | `vela` | `PARAMETER_ROLE_SESSION_NAME`
`AWS_CREDENTIALS_ROLE_SESSION_NAME` | -| `log_level` | Log level for the plugin. | `false` | `info` | `PARAMETER_LOG_LEVEL`
`AWS_CREDENTIALS_LOG_LEVEL` | -| `audience` | Audience to use for the OIDC provider. | `false` | `sts.amazonaws.com` | `PARAMETER_AUDIENCE`
`AWS_CREDENTIALS_AUDIENCE` | -| `verify` | If the AWS credentials should be verified. | `false` | `false` | `PARAMETER_VERIFY`
`AWS_CREDENTIALS_VERIFY` | -| `script_path` | Path where to write script that contains AWS credentials | `false` | `/vela/secrets/aws/setup.sh` (shell) or `/vela/secrets/aws/creds` (credential_file) | `PARAMETER_SCRIPT_PATH`
`AWS_CREDENTIALS_SCRIPT_PATH` | -| `script_write` | If the credentials script should be created. | `false` | `false` | `PARAMETER_SCRIPT_WRITE`
`AWS_CREDENTIALS_SCRIPT_WRITE` | -| `script_format` | Format of file to write (shell or credential_file) | `false` | `N/A` | `PARAMETER_SCRIPT_FORMAT`
`AWS_CREDENTIALS_SCRIPT_FORMAT` | -| `inline_session_policy` | An IAM policy in JSON format that you want to use as an inline session policy when assuming the IAM role. | `false` | `N/A` | `PARAMETER_INLINE_SESSION_POLICY`
`AWS_CREDENTIALS_INLINE_SESSION_POLICY` | -| `managed_session_policies` | List of ARNs of the IAM managed policies that you want to use as managed session policies when assuming the IAM role. The policies must exist in the same account as the role. | `false` | `N/A` | `PARAMETER_MANAGED_SESSION_POLICIES`
`AWS_CREDENTIALS_MANAGED_SESSION_POLICIES` | - -## Troubleshooting - -You can start troubleshooting this plugin by tuning the level of logs being displayed: - -```diff -steps: - - name: message - image: cargill/vela-aws-credentials:latest - pull: always - id_request: yes - parameters: -+ log_level: trace - role: "arn:aws:iam::123456123456:role/test" -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/usage/plugins/registry/Build Summary.md b/versioned_docs/version-0.26/usage/plugins/registry/Build Summary.md deleted file mode 100644 index 9b0a452..0000000 --- a/versioned_docs/version-0.26/usage/plugins/registry/Build Summary.md +++ /dev/null @@ -1,138 +0,0 @@ -## Description - -This plugin enables you to provide a summary of a build in a pipeline. - -Source Code: https://github.com/go-vela/vela-build-summary - -Registry: https://hub.docker.com/r/target/vela-build-summary - -## Usage - -> **NOTE:** -> -> Users should refrain from using latest as the tag for the Docker image. -> -> It is recommended to use a semantically versioned tag instead. - -Sample of outputting a summary for the current build: - -```yaml -steps: - - name: build-summary - image: target/vela-build-summary:latest - pull: always - secrets: [ build_summary_token ] -``` - -Sample of outputting a summary for an existing build: - -```diff -steps: - - name: build-summary - image: target/vela-build-summary:latest - pull: always - secrets: [ build_summary_token ] - parameters: -+ number: 1 -``` - -Sample of outputting a summary for an existing build in a different repo: - -```diff -steps: - - name: build-summary - image: target/vela-build-summary:latest - pull: always - secrets: [ build_summary_token ] - parameters: - number: 1 -+ org: octocat -+ repo: hello-world -``` - -## Secrets - -> **NOTE:** Users should refrain from configuring sensitive information in your pipeline in plain text. - -### Internal - -The plugin accepts the following `parameters` for authentication: - -| Parameter | Environment Variable Configuration | -| --------- | --------------------------------------------------------------------- | -| `token` | `PARAMETER_TOKEN`, `BUILD_SUMMARY_TOKEN` | - -Users can use [Vela internal secrets](https://go-vela.github.io/docs/tour/secrets/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: build-summary - image: target/vela-build-summary:latest - pull: always -+ secrets: [ build_summary_token ] -- parameters: -- token: superSecretToken -``` - -> This example will add the secret to the `build-summary` step as an environment variable: -> -> * `BUILD_SUMMARY_TOKEN=` - -### External - -The plugin accepts the following files for authentication: - -| Parameter | Volume Configuration | -| --------- | --------------------------------------------------------------------------- | -| `token` | `/vela/parameters/build-summary/token`, `/vela/secrets/build-summary/token` | - -Users can use [Vela external secrets](https://go-vela.github.io/docs/concepts/pipeline/secrets/origin/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: build-summary - image: target/vela-build-summary:latest - pull: always -- parameters: -- token: superSecretToken -``` - -> This example will read the secret values in the volume stored at `/vela/secrets/` - -## Parameters - -> **NOTE:** -> -> The plugin supports reading all parameters via environment variables or files. -> -> Any values set from a file take precedence over values set from the environment. - -The following parameters are used to configure the image: - -| Name | Description | Required | Default | Environment Variables | -| ----------- | --------------------------------------- | -------- | ----------------- | ------------------------------------------------------------------- | -| `log_level` | set the log level for the plugin | `true` | `info` | `PARAMETER_LOG_LEVEL`
`BUILD_SUMMARY_LOG_LEVEL` | -| `number` | set the number for the build | `true` | **set by Vela** | `PARAMETER_NUMBER`
`BUILD_SUMMARY_NUMBER`
`VELA_BUILD_NUMBER` | -| `org` | set the organization name for the build | `true` | **set by Vela** | `PARAMETER_ORG`
`BUILD_SUMMARY_ORG`
`VELA_REPO_ORG` | -| `repo` | set the repository name for the build | `true` | **set by Vela** | `PARAMETER_REPO`
`BUILD_SUMMARY_REPO`
`VELA_REPO_NAME` | -| `server` | Vela server to communicate with | `true` | **set by Vela** | `PARAMETER_SERVER`
`BUILD_SUMMARY_SERVER`
`VELA_ADDR` | -| `token` | token for communication with Vela | `true` | **set by Vela** | `PARAMETER_TOKEN`
`BUILD_SUMMARY_TOKEN`
`VELA_NETRC_PASSWORD` | -## Template - -COMING SOON! - -## Troubleshooting - -You can start troubleshooting this plugin by tuning the level of logs being displayed: - -```diff -steps: - - name: build-summary - image: target/vela-build-summary:latest - pull: always - secrets: [ build_summary_token ] -+ parameters: -+ log_level: trace -``` - -Below are a list of common problems and how to solve them: \ No newline at end of file diff --git a/versioned_docs/version-0.26/usage/plugins/registry/Cache.md b/versioned_docs/version-0.26/usage/plugins/registry/Cache.md deleted file mode 100644 index 8ef7f15..0000000 --- a/versioned_docs/version-0.26/usage/plugins/registry/Cache.md +++ /dev/null @@ -1,215 +0,0 @@ -## Description - -This plugin enables you to cache build resources in an [s3](https://aws.amazon.com/s3/) compatible store for a Vela pipeline. - -Source Code: https://github.com/go-vela/vela-s3-cache - -Registry: https://hub.docker.com/r/target/vela-s3-cache - -## Usage - -> **NOTE:** -> -> Users should refrain from using latest as the tag for the Docker image. -> -> It is recommended to use a semantically versioned tag instead. - -Sample of restoring a cache: - -```yaml -steps: - - name: restore_cache - image: target/vela-s3-cache:latest - pull: always - parameters: - action: restore - bucket: mybucket - server: mybucket.s3-us-west-2.amazonaws.com -``` - -Sample of rebuilding a cache: - -```yaml -steps: - - name: rebuild_cache - image: target/vela-s3-cache:latest - pull: always - parameters: - action: rebuild - bucket: mybucket - server: mybucket.s3-us-west-2.amazonaws.com - mount: - - .gradle -``` - -Sample of rebuilding a cache while preserving the directory structure: - -```yaml -steps: - - name: rebuild_cache - image: target/vela-s3-cache:latest - pull: always - parameters: - action: rebuild - bucket: mybucket - server: mybucket.s3-us-west-2.amazonaws.com - preserve_path: true - mount: - - foo/test1 - - bar/test2 -``` - -Sample of flushing a cache: - -```yaml -steps: - - name: flushing_cache - image: target/vela-s3-cache:latest - pull: always - parameters: - action: flush - bucket: mybucket - server: mybucket.s3-us-west-2.amazonaws.com -``` - -## Secrets - -> **NOTE:** Users should refrain from configuring sensitive information in your pipeline in plain text. - -### Internal - -Users can use [Vela internal secrets](https://go-vela.github.io/docs/tour/secrets/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: restore_cache - image: target/vela-s3-cache:latest - pull: always -+ secrets: [ s3_cache_access_key, s3_cache_secret_key ] - parameters: - action: restore - bucket: mybucket - server: mybucket.s3-us-west-2.amazonaws.com -- access_key: AKIAIOSFODNN7EXAMPLE -- secret_key: 123456789QWERTYEXAMPLE -``` - -> This example will add the secrets to the `restore_cache` step as environment variables: -> -> * `S3_CACHE_ACCESS_KEY=` -> * `S3_CACHE_SECRET_KEY=` - -### External - -The plugin accepts the following files for authentication: - -| Parameter | Volume Configuration | -| --------------- | --------------------------------------------------------------------------------- | -| `access_key` | `/vela/parameters/s3-cache/access_key`, `/vela/secrets/s3-cache/access_key` | -| `secret_key` | `/vela/parameters/s3-cache/secret_key`, `/vela/secrets/s3-cache/secret_key` | -| `session_token` | `/vela/parameters/s3-cache/session_token`, `/vela/secrets/s3-cache/session_token` | - -Users can use [Vela external secrets](https://go-vela.github.io/docs/concepts/pipeline/secrets/origin/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: restore_cache - image: target/vela-s3-cache:latest - pull: always -+ secrets: [ s3_cache_access_key, s3_cache_secret_key ] - parameters: - action: restore - bucket: mybucket - server: mybucket.s3-us-west-2.amazonaws.com -- access_key: AKIAIOSFODNN7EXAMPLE -- secret_key: 123456789QWERTYEXAMPLE -``` - -> This example will read the secret values in the volume stored at `/vela/secrets/` - -## Parameters - -> **NOTE:** -> -> The plugin supports reading all parameters via environment variables or files. -> -> Any values set from a file take precedence over values set from the environment. -> -> The s3 bucket set with the `bucket` parameter is expected to be created beforehand. - -The following parameters can used to configure all image actions: - -| Name | Description | Required | Default | Environment Variables | -| ---------------------- | ------------------------------------------- | -------- | --------------- | ---------------------------------------------------------------------------- | -| `accelerated_endpoint` | s3 accelerated instance to communicate with | `false` | `N/A` | `PARAMETER_ACCELERATED_ENDPOINT`
`S3_CACHE_ACCELERATED_ENDPOINT` | -| `access_key` | access key for communication with s3 | `true` | `N/A` | `PARAMETER_ACCESS_KEY`
`S3_CACHE_ACCESS_KEY`
`AWS_ACCESS_KEY_ID` | -| `action` | action to perform against s3 | `true` | `N/A` | `PARAMETER_ACTION`
`S3_CACHE_ACTION` | -| `build_branch` | branch name from build for the repository | `false` | **set by Vela** | `PARAMETER_BUILD_BRANCH`
`VELA_BUILD_BRANCH` | -| `bucket` | name of the s3 bucket | `true` | `N/A` | `PARAMETER_BUCKET`
`S3_CACHE_BUCKET` | -| `log_level` | set the log level for the plugin | `false` | `info` | `PARAMETER_LOG_LEVEL`
`S3_CACHE_LOG_LEVEL` | -| `org` | name of the org for the repository | `true` | **set by Vela** | `PARAMETER_ORG`
`VELA_REPO_ORG` | -| `path` | custom path for the object(s) | `false` | `N/A` | `PARAMETER_PATH`
`S3_CACHE_PATH` | -| `prefix` | path prefix for the object(s) | `false` | `N/A` | `PARAMETER_PREFIX`
`S3_CACHE_PREFIX` | -| `repo` | name of the repository | `true` | **set by Vela** | `PARAMETER_REPO`
`VELA_REPO_NAME` | -| `repo_branch` | default branch for the Vela repository | `false` | **set by Vela** | `PARAMETER_REPO_BRANCH`
`VELA_REPO_BRANCH` | -| `secret_key` | secret key for communication with s3 | `true` | `N/A` | `PARAMETER_SECRET_KEY`
`S3_CACHE_SECRET_KEY`
`AWS_SECRET_ACCESS_KEY` | -| `server` | s3 instance to communicate with | `true` | `N/A` | `PARAMETER_SERVER`
`S3_CACHE_SERVER` | -| `session_token` | session token for communication with s3 | `true` | `N/A` | `PARAMETER_SESSION_TOKEN`
`S3_CACHE_SESSION_TOKEN`
`AWS_SESSION_TOKEN` | - -### Restore - -The following parameters are used to configure the `restore` action: - -| Name | Description | Required | Default | Environment Variables | -| ---------- | ---------------------------------------------------------- | -------- | ------------- | ------------------------------------------- | -| `filename` | the name of the cache object | `true` | `archive.tgz` | `PARAMETER_FILENAME`
`S3_CACHE_FILENAME` | -| `timeout` | the timeout for the call to s3 | `false` | `10m` | `PARAMETER_TIMEOUT`
`S3_CACHE_TIMEOUT` | - -### Rebuild - -The following parameters are used to configure the `rebuild` action: - -| Name | Description | Required | Default | Environment Variables | -| --------------- | --------------------------------------------------------------------------- | -------- | ------------- | ----------------------------------------------- | -| `filename` | the name of the cache object | `true` | `archive.tgz` | `PARAMETER_FILENAME`
`S3_CACHE_FILENAME` | -| `timeout` | the timeout for the call to s3 | `false` | `10m` | `PARAMETER_TIMEOUT`
`S3_CACHE_TIMEOUT` | -| `preserve_path` | whether to preserve the relative directory structure during the tar process | `false` | `false` | `PARAMETER_PRESERVE_PATH`
`S3_PRESERVE_PATH` | -| `mount` | the file or directories locations to build your cache from | `true` | `N/A` | `PARAMETER_MOUNT`
`S3_CACHE_MOUNT` | - -### Flush - -The following parameters are used to configure the `flush` action: - -| Name | Description | Required | Default | Environment Variables | -| ----- | ------------------------------------------------------- | -------- | ------- | --------------------------------- | -| `age` | delete the objects past a specific age (i.e. 60m, 8h) | `false` | `336h` | `PARAMETER_AGE`
`S3_CACHE_AGE` | - -## Template - -COMING SOON! - -## Troubleshooting - -You can start troubleshooting this plugin by tuning the level of logs being displayed: - -```diff -steps: - - name: restore_cache - image: target/vela-s3-cache:latest - pull: always - parameters: - action: restore - bucket: mybucket -+ log_level: trace - server: mybucket.s3-us-west-2.amazonaws.com -``` - -Below are a list of common problems and how to solve them: - -### Invalid duration value - -The error may look like this: - - could not parse \"14d\" as duration value for flag flush.age: time: unknown unit \"d\" in duration \"14d\" - -Values for rebuild and restore `timeout` and flushing `age` are parsed using Go's [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration) function. Only `h` for hours, `m` for minutes, and so on for smaller time units are supported; `d` for days will cause an error unless added in subsequent versions of Go after v1.16, which is [unlikely](https://github.com/golang/go/issues/11473). diff --git a/versioned_docs/version-0.26/usage/plugins/registry/Downstream.md b/versioned_docs/version-0.26/usage/plugins/registry/Downstream.md deleted file mode 100644 index f224ec7..0000000 --- a/versioned_docs/version-0.26/usage/plugins/registry/Downstream.md +++ /dev/null @@ -1,226 +0,0 @@ -## Description - -This plugin enables you to trigger builds for other repos for [Vela](https://go-vela.github.io/docs/) in a pipeline. - -Source Code: https://github.com/go-vela/vela-downstream - -Registry: https://hub.docker.com/r/target/vela-downstream - -## Usage - -> **NOTE:** -> -> Users should refrain from using latest as the tag for the Docker image. -> -> It is recommended to use a semantically versioned tag instead. - -Sample of triggering a downstream build: - -```yaml -steps: - - name: trigger_hello-world - image: target/vela-downstream:latest - pull: always - parameters: - repos: - - octocat/hello-world - server: https://vela-server.localhost -``` - -Sample of triggering a downstream build for a specific branch: - -```diff -steps: - - name: trigger_hello-world - image: target/vela-downstream:latest - pull: always - parameters: -+ branch: main - repos: - - octocat/hello-world - server: https://vela-server.localhost -``` - -Sample of triggering a downstream build for a specific event: - -```diff -steps: - - name: trigger_hello-world - image: target/vela-downstream:latest - pull: always - parameters: -+ event: tag - repos: - - octocat/hello-world - server: https://vela-server.localhost -``` - -Sample of triggering a downstream build for a specific status: - -> **NOTE:** -> -> You can provide a list of statuses to the plugin. -> -> The first build found matching either of the statuses will be triggered. - -```diff -steps: - - name: trigger_hello-world - image: target/vela-downstream:latest - pull: always - parameters: - repos: - - octocat/hello-world - server: https://vela-server.localhost -+ status: [ success, failure ] -``` - -Sample of triggering a downstream build for multiple repos: - -```diff -steps: - - name: trigger_multiple - image: target/vela-downstream:latest - pull: always - parameters: - repos: - - octocat/hello-world -+ - go-vela/hello-world - server: https://vela-server.localhost -``` - -Sample of triggering a downstream build for multiple repos with different branches: - -> **NOTE:** -> -> Use the @ symbol at the end of the org/repo to provide a unique branch per repo. -> -> This will override the value set for the `branch` parameter. - -```diff -steps: - - name: trigger_multiple - image: target/vela-downstream:latest - pull: always - parameters: - repos: -- - octocat/hello-world -+ - octocat/hello-world@test -- - go-vela/hello-world -+ - go-vela/hello-world@stage - server: https://vela-server.localhost -``` - -## Secrets - -> **NOTE:** Users should refrain from configuring sensitive information in your pipeline in plain text. - -A personal access token for the related source control manager (GitHub, GitLab, etc.) is required. - -The token must be tied to a user that exists in Vela, that is, the user has logged into Vela at least once. -Additionally, the user must have `write` access to both the origin repo as well as any downstream repos. - -### Internal - -Users can use [Vela internal secrets](https://go-vela.github.io/docs/tour/secrets/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: trigger_hello-world - image: target/vela-downstream:latest - pull: always -+ secrets: [ downstream_token ] - parameters: - repos: - - octocat/hello-world - server: https://vela-server.localhost -- token: superSecretVelaToken -``` - -> This example will add the secret to the `trigger_hello-world` step as environment variables: -> -> * `DOWNSTREAM_TOKEN=` - -### External - -The plugin accepts the following files for authentication: - -| Parameter | Volume Configuration | -| --------- | --------------------------------------------------------------------- | -| `token` | `/vela/parameters/downstream/token`, `/vela/secrets/downstream/token` | - -Users can use [Vela external secrets](https://go-vela.github.io/docs/concepts/pipeline/secrets/origin/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: trigger_hello-world - image: target/vela-downstream:latest - pull: always - parameters: - repos: - - octocat/hello-world - server: https://vela-server.localhost -- token: superSecretVelaToken -``` - -> This example will read the secret value in the volume stored at `/vela/secrets/` - -## Parameters - -> **NOTE:** -> -> The plugin supports reading all parameters via environment variables or files. -> -> Any values set from a file take precedence over values set from the environment. - -The following parameters are used to configure the image: - -| Name | Description | Required | Default | Environment Variables | -| ----------------------- | ----------------------------------------------------- | -------- | ------------- | ----------------------------------------------------------------------- | -| `branch` | branch to trigger a build on | `false` | `N/A` | `PARAMETER_BRANCH`
`DOWNSTREAM_BRANCH` | -| `event` | event to trigger a build on | `true` | `push` | `PARAMETER_EVENT`
`DOWNSTREAM_EVENT` | -| `log_level` | set the log level for the plugin | `true` | `info` | `PARAMETER_LOG_LEVEL`
`DOWNSTREAM_LOG_LEVEL` | -| `repos` | list of |org|/|repo| names to trigger a build on | `true` | `N/A` | `PARAMETER_REPOS`
`DOWNSTREAM_REPOS` | -| `server` | Vela server to communicate with | `true` | `N/A` | `PARAMETER_SERVER`
`DOWNSTREAM_SERVER` | -| `status` | list of statuses to trigger a build on | `true` | `[ success ]` | `PARAMETER_STATUS`
`DOWNSTREAM_STATUS` | -| `token` | SCM (GitHub, GitLab, etc.) personal access token of an existing Vela user | `true` | `N/A` | `PARAMETER_TOKEN`
`DOWNSTREAM_TOKEN` | -| `report_back` | whether or not to track downstream build status | `false` | `false` | `PARAMETER_REPORT_BACK`
`DOWNSTREAM_REPORT_BACK` | -| `target_status` | list of statuses to look for from downstream builds | `false` | `[ success ]` | `PARAMETER_TARGET_STATUS`
`DOWNSTREAM_TARGET_STATUS` | -| `timeout` | how long should the plugin wait for downstream builds | `false` | `30m` | `PARAMETER_TIMEOUT`
`DOWNSTREAM_TIMEOUT` | -| `continue_on_not_found` | continue triggering builds on failure to find one | `false` | `false` | `PARAMETER_CONTINUE_ON_NOT_FOUND`
`DOWNSTREAM_CONTINUE_ON_NOT_FOUND` | - -## Template - -COMING SOON! - -## Troubleshooting - -You can start troubleshooting this plugin by tuning the level of logs being displayed: - -```diff -steps: - - name: trigger_hello-world - image: target/vela-downstream:latest - pull: always - parameters: -+ log_level: trace - repos: - - octocat/hello-world - server: https://vela-server.localhost -``` - -Below are a list of common problems and how to solve them: - -### `unable to authenticate: user not found` - -Vela does not have a record of the user that owns the token, even if the user exists in the source control management system and the token may be valid. - -Log into Vela as this user once to fix the issue. - -### `unable to restart build myorg/myrepo/1234` - -Vela does not have permission to restart the build with the given token. - -Make sure the user that owns the token has write access to the repo that this .vela.yml is inside as well as any repos you want to trigger builds for. - -Admin access on these repos is not required. diff --git a/versioned_docs/version-0.26/usage/plugins/registry/Email.md b/versioned_docs/version-0.26/usage/plugins/registry/Email.md deleted file mode 100644 index 47dfdb2..0000000 --- a/versioned_docs/version-0.26/usage/plugins/registry/Email.md +++ /dev/null @@ -1,376 +0,0 @@ -## Description - -This plugin enables you to send data to an email. - -Source Code: https://github.com/go-vela/vela-email - -Registry: https://hub.docker.com/r/target/vela-email - -## Usage - -> **NOTE:** -> -> Users should refrain from using latest as the tag for the Docker image. -> -> It is recommended to use a semantically versioned tag instead. - -### Sample for .vela.yml - -```yaml -secrets: - - name: username - engine: native - key: vela/noreply/username - type: shared - - - name: password - engine: native - key: vela/noreply/password - type: shared - -steps: - - name: email on success - image: target/vela-email:latest - pull: not_present - secrets: [username, password] - ruleset: - status: success - parameters: - from: vela-noreply@fakemail.com - to: [one@email.com, two@email.com] - sendtype: StartTLS - auth: LoginAuth - host: smtp.youremailserver.com - port: 587 - subject: "{{ .VELA_BUILD_COMMIT }}" - text: "Author: {{ .VELA_BUILD_AUTHOR }} - Branch: {{ .VELA_BUILD_BRANCH }}" - - - name: email on failure - image: target/vela-email:latest - pull: not_present - secrets: [username, password] - ruleset: - status: failure - parameters: - from: vela-noreply@fakemail.com - to: [one@email.com, two@email.com] - sendtype: StartTLS - auth: LoginAuth - host: smtp.youremailserver.com - port: 587 - subject: "{{ .VELA_BUILD_COMMIT }}" - text: "Author: {{ .VELA_BUILD_AUTHOR }} - Branch: {{ .VELA_BUILD_BRANCH }}" -``` - -### Sample for .vela.yml with attachment - -```yaml -secrets: - - name: username - engine: native - key: vela/noreply/username - type: shared - - - name: password - engine: native - key: vela/noreply/password - type: shared - -steps: - - name: email on success - image: target/vela-email:latest - pull: not_present - secrets: [username, password] - ruleset: - status: success - parameters: - filename: - sendtype: StartTLS - auth: LoginAuth - host: smtp.youremailserver.com - port: 587 - - - name: email on failure - image: target/vela-email:latest - pull: not_present - secrets: [username, password] - ruleset: - status: failure - parameters: - filename: - sendtype: StartTLS - auth: LoginAuth - host: smtp.youremailserver.com - port: 587 -``` - -### Sample for email attachment - -```text -From: vela-noreply@fakemail.com -To: emailone@email.com, emailtwo@email.com -Subject: Vela Pipeline for {{ .VELA_REPO_FULL_NAME }} {{ .VELA_BUILD_BRANCH }} -Content-Type: text/plain - -BuildAuthor: {{ .VELA_BUILD_AUTHOR }} -BuildAuthorEmail: {{ .VELA_BUILD_AUTHOR_EMAIL }} -BuildBranch: {{ .VELA_BUILD_BRANCH }} -BuildCommit: {{ .VELA_BUILD_COMMIT }} -BuildCreated: {{ .BuildCreated }} -BuildMessage: {{ .VELA_BUILD_MESSAGE }} -BuildNumber: {{ .VELA_BUILD_NUMBER }} -RepositoryFullName: {{ .VELA_REPO_FULL_NAME }} -RepositoryLink: {{ .VELA_REPO_LINK }} -``` - -## Secrets - -> **NOTE:** Users should refrain from configuring sensitive information in your pipeline in plain text. - -### Internal - -The plugin accepts the following `parameters` for authentication: - -| Parameter | Environment Variable Configuration | -| ---------- | ---------------------------------- | -| `username` | `PARAMETER_USERNAME`, `USERNAME` | -| `password` | `PARAMETER_PASSWORD`, `PASSWORD` | - -Users can use [Vela internal secrets](https://go-vela.github.io/docs/tour/secrets/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: email - image: target/vela-email:latest - pull: always -+ secrets: [ username, password ] - parameters: -- username: usernameexample@email.com -``` - -> This example will add the secret to the `email` step as environment variables: -> -> - `USERNAME=value` - -### External - -The plugin accepts the following files for authentication: - -| Parameter | Volume Configuration | -| ---------- | ----------------------------------------------------------------- | -| `username` | `/vela/parameters/email/username`, `/vela/secrets/email/username` | -| `password` | `/vela/parameters/email/password`, `/vela/secrets/email/password` | - -Users can use [Vela external secrets](https://go-vela.github.io/docs/concepts/pipeline/secrets/origin/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: email - image: target/vela-email:latest - pull: always - parameters: -- username: usernameexample@email.com -``` - -> This example will read the secret value in the volume stored at `/vela/secrets/` - -## Parameters - -> **NOTE:** -> -> Any values set from a file take precedence over values set from the environment. -> -> VELA environments can be found at [VELA Environments](https://go-vela.github.io/docs/reference/environment/) -> -> All environment variables are wrapped in sprig template. More information on sprig can be found at [sprig docs](http://masterminds.github.io/sprig/) - -The following parameters are used to configure the image: - -### Logging - -| Parameter | Description | Required | Default | Environment Variables | -| ----------- | -------------------------------------------------------------------------- | -------- | ------- | ------------------------------------------ | -| `log_level` | set the log level for the plugin (valid options: `info`, `debug`, `trace`) | `true` | `info` | `PARAMETER_LOG_LEVEL`
`EMAIL_LOG_LEVEL` | - -### Email - -| Parameter | Description | Required | Default | Environment Variables | -| ------------- | ----------------------------------------------------------------- | -------- | ----------------- | ---------------------------------------------- | -| `from` | who the email is being sent from | true | N/A | `PARAMETER_FROM`
`EMAIL_FROM` | -| `to` | who the email is being sent to | true | N/A | `PARAMETER_TO`
`EMAIL_TO` | -| `cc` | carbon copy of the email to be sent to | false | N/A | `PARAMETER_CC`
`EMAIL_CC` | -| `bcc` | blind carbon copy of the email to be sent to | false | N/A | `PARAMETER_BCC`
`EMAIL_BCC` | -| `sender` | who the email being sent from (will overwrite from) | false | N/A | `PARAMETER_SENDER`
`EMAIL_SENDER` | -| `replyto` | email address that will be used for replies | false | N/A | `PARAMETER_REPLYTO`
`EMAIL_REPLYTO` | -| `subject` | subject of the email | false | default subject | `PARAMETER_SUBJECT`
`EMAIL_SUBJECT` | -| `text` | body of the email in plain text format (HTML will overwrite TEXT) | false | N/A | `PARAMETER_TEXT`
`EMAIL_TEXT` | -| `html` | body of the email in hmtl format (HTML will overwrite TEXT) | false | default html body | `PARAMETER_HTML`
`EMAIL_HTML` | -| `readreceipt` | delivery confirmation | false | N/A | `PARAMETER_READRECEIPT`
`EMAIL_READRECEIPT` | - -> **NOTE:** -> -> The parameters To, CC, BCC and ReplyTo accepts an array of emails in the format of: -> -> - [ one@email.com, two@email.com ] or -> -> - [ firstname lastname one@email.com, firstname lastname two@email.com ] -> -> Subject, Text body, and HTML body will accept VELA environments with the use of `{{ }}` such as: -> -> - `{{ .VELA_REPO_FULL_NAME }}` - -### Attachment - -| Parameter | Description | Required | Default | Environment Variables | -| ------------ | ------------------------------ | -------- | ------- | -------------------------------------------- | -| `attachment` | file will be attached to email | false | N/A | `PARAMETER_ATTACHMENT`
`EMAIL_ATTACHMENT` | - -### Email Filename - -| Parameter | Description | Required | Default | Environment Variables | -| ---------- | --------------------------------------------------------- | -------- | ------- | ---------------------------------------- | -| `filename` | data in attached file will be used to populate the email. | false | N/A | `PARAMETER_FILENAME`
`EMAIL_FILENAME` | - -### SMTP - -| Parameter | Description | Required | Default | Environment Variables | -| ---------- | ------------- | -------- | ------- | ---------------------------------------- | -| `host` | SMTP host | true | N/A | `PARAMETER_HOST`
`EMAIL_HOST` | -| `port` | SMTP port | true | N/A | `PARAMETER_PORT`
`EMAIL_PORT` | -| `username` | SMTP username | true | N/A | `PARAMETER_USERNAME`
`EMAIL_USERNAME` | -| `password` | SMTP password | true | N/A | `PARAMETER_PASSWORD`
`EMAIL_PASSWORD` | - -### TLS - -| Parameter | Description | Required | Default | Environment Variables | -| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- | -------------------------------------------- | -| `servername` | default is set to host address of SMTP server | false | SMTP host | `PARAMETER_SERVERNAME`
`EMAIL_SERVERNAME` | -| `insecureskipverify` | verification of the server's certificate chain and host name. Only use true for testing purposes as this makes TLS susceptible to man-in-middle attacks. | false | false | `PARAMETER_SKIPVERIFY`
`EMAIL_SKIPVERIFY` | - -### Encryption - -| Parameter | Description | Required | Default | Environment Variables | -| ---------- | ----------------------------------------------------------------- | -------- | -------- | ---------------------------------------- | -| `sendtype` | security to send email (valid option: `Plain`, `StartTLS`, `TLS`) | true | StartTLS | `PARAMETER_SENDTYPE`
`EMAIL_SENDTYPE` | - -### Authentication - -| Parameter | Description | Required | Default | Environment Variables | -| --------- | ------------------------------------------------------------- | -------- | --------- | -------------------------------- | -| `auth` | login authentication (valid option: `PlainAuth`, `LoginAuth`) | true | LoginAuth | `PARAMETER_AUTH`
`EMAIL_AUTH` | - -> **NOTE:** -> -> PlainAuth using smtp/auth login for SMTP server. -> -> LoginAuth using a custom login for Office 365/Exchange SMTP server. - -## Variables - -The Plugin provides the following User friendly timestamp variables that can be used in a subject, text, HTML template. -These timestamps are converted to Unix timestamps in UTC. - -- BuildCreated -- BuildEnqueued -- BuildFinished -- BuildStarted - -## Defaults - -> **NOTE:** -> Context-Type options are as follow: -> -> - text/html for HTML based body of message. -> - text/plain for TEXT based body of message. - -### Default subject - -```text -{{ .VELA_REPO_FULL_NAME }} {{ .VELA_BUILD_BRANCH }} - {{ .VELA_BUILD_COMMIT }} -``` - -### Default body in HTML - -```html - - - - - - -
-
- - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - -
Build Number: - - {{ .VELA_BUILD_NUMBER }} - -
Repo:{{ .VELA_REPO_FULL_NAME }}
Author: - {{ .VELA_BUILD_AUTHOR }} ({{ .VELA_BUILD_AUTHOR_EMAIL - }}) -
Branch:{{ .VELA_BUILD_BRANCH }}
Commit:{{ .VELA_BUILD_COMMIT }}
Started at:{{ .BuildCreated }}
-
- - - - - - -
{{ .VELA_BUILD_MESSAGE }}
-
-
-
-``` - -## Template - -COMING SOON! - -## Troubleshooting - -You can start troubleshooting this plugin by tuning the level of logs being displayed: - -```diff -steps: - - name: send email - image: target/vela-email:latest - pull: always - parameters: -+ log_level: trace - ... -``` - -Below are a list of common problems and how to solve them: diff --git a/versioned_docs/version-0.26/usage/plugins/registry/Git.md b/versioned_docs/version-0.26/usage/plugins/registry/Git.md deleted file mode 100644 index d186611..0000000 --- a/versioned_docs/version-0.26/usage/plugins/registry/Git.md +++ /dev/null @@ -1,185 +0,0 @@ -## Description - -> **NOTE:** This plugin is automatically injected into your pipeline for the source repository. - -This plugin enables you to clone repositories in a Vela pipeline to your build workspace. - -Source Code: https://github.com/go-vela/vela-git - -Registry: - -- https://hub.docker.com/r/target/vela-git-slim -- https://hub.docker.com/r/target/vela-git - -## Usage - -> **NOTE:** -> -> Users should refrain from using latest as the tag for the Docker image. -> -> It is recommended to use a semantically versioned tag instead. - -Sample of cloning a repository: - -```yaml -steps: - - name: clone_vela-git-test - image: target/vela-git-slim:latest - pull: always - parameters: - path: vela-git-test - ref: refs/heads/main - remote: https://github.com/go-vela/vela-git-test.git - sha: ee1e671529ad86a11ed628a04b37829e71783682 -``` - -Sample of cloning a repository with submodules: - -```diff -steps: - - name: clone_vela-git-test - image: target/vela-git-slim:latest - pull: always - parameters: - path: vela-git-test - ref: refs/heads/main - remote: https://github.com/go-vela/vela-git-test.git - sha: ee1e671529ad86a11ed628a04b37829e71783682 -+ submodules: true -``` - -Sample of cloning a repository with tags: - -```diff -steps: - - name: clone_vela-git-test - image: target/vela-git-slim:latest - pull: always - parameters: - path: vela-git-test - ref: refs/heads/main - remote: https://github.com/go-vela/vela-git-test.git - sha: ee1e671529ad86a11ed628a04b37829e71783682 -+ tags: true -``` - -Sample of cloning a repository and resolving LFS objects with the `vela-git` plugin: - -```diff -steps: - - name: clone_vela-git-test - image: target/vela-git:latest - pull: always - parameters: - path: vela-git-test - ref: refs/heads/main - remote: https://github.com/go-vela/vela-git-test.git - sha: ee1e671529ad86a11ed628a04b37829e71783682 -+ lfs: true -``` - -## Secrets - -> **NOTE:** Users should refrain from configuring sensitive information in your pipeline in plain text. - -### Internal - -Users can use [Vela internal secrets](https://go-vela.github.io/docs/tour/secrets/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: clone_vela-git-test - image: target/vela-git-slim:latest - pull: always -+ secrets: [ git_username, git_password ] - parameters: -- username: octocat -- password: superSecretPassword - path: /home/go-vela_vela-git-test_1 - ref: refs/heads/main - remote: https://github.com/go-vela/vela-git-test.git - sha: ee1e671529ad86a11ed628a04b37829e71783682 -``` - -> This example will add the secrets to the `clone_vela-git-test` step as environment variables: -> -> * `GIT_USERNAME=` -> * `GIT_PASSWORD=` - -### External - -The plugin accepts the following files for authentication: - -| Parameter | Volume Configuration | -| ---------- | ------------------------------------------------------------- | -| `password` | `/vela/parameters/git/password`, `/vela/secrets/git/password` | -| `username` | `/vela/parameters/git/username`, `/vela/secrets/git/username` | - -Users can use [Vela external secrets](https://go-vela.github.io/docs/concepts/pipeline/secrets/origin/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: clone_vela-git-test - image: target/vela-git-slim:latest - pull: always - parameters: -- username: octocat -- password: superSecretPassword - path: /home/go-vela_vela-git-test_1 - ref: refs/heads/main - remote: https://github.com/go-vela/vela-git-test.git - sha: ee1e671529ad86a11ed628a04b37829e71783682 -``` - -> This example will read the secret values in the volume stored at `/vela/secrets/` - -## Parameters - -> **NOTE:** -> -> The plugin supports reading all parameters via environment variables or files. -> -> Any values set from a file take precedence over values set from the environment. - -The following parameters are used to configure the image: - -| Name | Description | Required | Default | Environment Variables | -|--------------|-----------------------------------------| -------- |---------------------|-----------------------------------------------------------------------------------------| -| `branch` | initial branch to clone from repository | `true` | `master` | `PARAMETER_BRANCH`
`GIT_BRANCH`
`VELA_PULL_REQUEST_SOURCE`
`VELA_BUILD_BRANCH` | -| `log_level` | set the log level for the plugin | `true` | `info` | `PARAMETER_LOG_LEVEL`
`GIT_LOG_LEVEL` | -| `machine` | machine name to communicate with | `true` | `github.com` | `PARAMETER_MACHINE`
`GIT_MACHINE`
`VELA_NETRC_MACHINE` | -| `password` | password for authentication | `true` | **set by Vela** | `PARAMETER_PASSWORD`
`GIT_PASSWORD`
`VELA_NETRC_PASSWORD` | -| `username` | user name for authentication | `true` | **set by Vela** | `PARAMETER_USERNAME`
`GIT_USERNAME`
`VELA_NETRC_USERNAME` | -| `path` | local path to clone repository to | `true` | **set by Vela** | `PARAMETER_PATH`
`GIT_PATH`
`VELA_BUILD_WORKSPACE` | -| `ref` | reference generated for commit | `true` | `refs/heads/master` | `PARAMETER_REF`
`GIT_REF`
`VELA_BUILD_REF` | -| `remote` | full url for cloning repository | `true` | **set by Vela** | `PARAMETER_REMOTE`
`GIT_REMOTE`
`VELA_REPO_CLONE` | -| `sha` | SHA-1 hash generated for commit | `true` | **set by Vela** | `PARAMETER_SHA`
`GIT_SHA`
`VELA_BUILD_COMMIT` | -| `submodules` | enables fetching of submodules | `false` | `false` | `PARAMETER_SUBMODULES`
`GIT_SUBMODULES` | -| `tags` | enables fetching of tags | `false` | `false` | `PARAMETER_TAGS`
`GIT_TAGS` | -| `depth` | enables fetching with a specific depth | `false` | `100` | `PARAMETER_DEPTH`
`GIT_DEPTH` | -| `lfs`[^1] | enables resolving LFS objects | `false` | `false` | `PARAMETER_LFS`
`GIT_LFS` | - -[^1]: only functional in the `target/vela-git` plugin. - -## Template - -COMING SOON! - -## Troubleshooting - -You can start troubleshooting this plugin by tuning the level of logs being displayed: - -```diff -steps: - - name: clone_vela-git-test - image: target/vela-git-slim:latest - pull: always - parameters: -+ log_level: trace - path: vela-git-test - ref: refs/heads/main - remote: https://github.com/go-vela/vela-git-test.git - sha: ee1e671529ad86a11ed628a04b37829e71783682 -``` - -Below are a list of common problems and how to solve them: diff --git a/versioned_docs/version-0.26/usage/plugins/registry/Github Release.md b/versioned_docs/version-0.26/usage/plugins/registry/Github Release.md deleted file mode 100644 index 4b31f33..0000000 --- a/versioned_docs/version-0.26/usage/plugins/registry/Github Release.md +++ /dev/null @@ -1,269 +0,0 @@ -## Description - -This plugin enables the ability to manage GitHub releases [GitHub CLI](https://cli.github.com/manual/) in a Vela pipeline. - -Source Code: https://github.com/go-vela/vela-github-release - -Registry: https://hub.docker.com/r/target/vela-github-release - -## Usage - -> **NOTE:** -> -> Users should refrain from using **latest** as the tag for the Docker image. -> -> It is recommended to use a semantically versioned tag instead. - -Sample of creating a GitHub release: - -```yaml -steps: - - name: gh - image: target/vela-github-release:latest - pull: always - parameters: - action: create - files: [ gh/common, gh/dev/deploy.yml ] - tag: v0.1.0 -``` - -Sample of creating a GitHub release, attaching all `.pdf` files in the current directory: - -```yaml -steps: - - name: gh - image: target/vela-github-release:latest - pull: always - parameters: - action: create - files: [ "*.pdf" ] - tag: v0.1.0 -``` - -> [!IMPORTANT] -> This uses [Go's implementation of glob patterns](https://pkg.go.dev/path/filepath#Match) - -Sample of deleting release files: - -```yaml -steps: - - name: gh - image: target/vela-github-release:latest - pull: always - parameters: - action: delete - tag: v0.1.0 -``` - -Sample of downloading assets from a release in a project: - -```yaml -steps: - - name: gh - image: target/vela-github-release:latest - pull: always - parameters: - action: download - tag: v0.1.0 -``` - -Sample of listing releases in a repository: - -```yaml -steps: - - name: gh - image: target/vela-github-release:latest - pull: always - parameters: - action: list -``` - -Sample of uploading assets to a gh release: - -```yaml -steps: - - name: gh - image: target/vela-github-release:latest - pull: always - parameters: - action: upload - files: [ changelog.md ] - tag: v0.1.0 -``` - -Sample of uploading assets using glob pattern to a gh release: - -```yaml -steps: - - name: gh - image: target/vela-github-release:latest - pull: always - parameters: - action: upload - files: [ "*.pdf" ] - tag: v0.1.0 -``` - -> [!IMPORTANT] -> This uses [Go's implementation of glob patterns](https://pkg.go.dev/path/filepath#Match) - -Sample of viewing information about a gh release: - -```yaml -steps: - - name: gh - image: target/vela-github-release:latest - pull: always - parameters: - action: view - tag: v0.1.0 -``` - -## Secrets - -> **NOTE:** Users should refrain from configuring sensitive information in your pipeline in plain text. - -### Internal - -The plugin accepts the following `parameters` for authentication: - -| Parameter | Environment Variable Configuration | -| ----------| -------------------------------------------------------------- | -| `token` | `PARAMETER_TOKEN`, `CONFIG_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` | - -Users can use [Vela internal secrets](https://go-vela.github.io/docs/concepts/pipeline/secrets/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: gh - image: target/vela-github-release:latest - pull: always -+ secrets: [github_token] - parameters: - action: create - files: [ gh/common, gh/dev/deploy.yml ] -``` - -> This example will add the secrets to the `gh` step as environment variables: -> -> * `GITHUB_TOKEN=` - -### External - -The plugin accepts the following files for authentication: - -| Parameter | Volume Configuration | -| ---------- | ------------------------------------------------------------------------------------------- | -| `token` | `/vela/parameters/github-release/config/token`, `/vela/secrets/github-release/config/token` | - -Users can use [Vela external secrets](https://go-vela.github.io/docs/concepts/pipeline/secrets/origin/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: gh - image: target/vela-github-release:latest - pull: always -+ secrets: [github_token] - parameters: - config: -- github_token: somepersonalaccesstoken -``` - -> This example will read the secret value in the volume stored at `/vela/secrets/` - -## Parameters - -> **NOTE:** -> -> The plugin supports reading all parameters via environment variables or files. -> -> VELA environments can be found at [VELA Environments](https://go-vela.github.io/docs/reference/environment/) -> -> Any values set from a file take precedence over values set from the environment. - -The following parameters are used to configure the image: - -| Name | Description | Required | Default | Environment Variables | -| ----------- | ------------------------------------------------ | -------- | ------------ | ----------------------------------------------------------------------- | -| `action` | action to perform against gh | `true` | `N/A` | `PARAMETER_ACTION`
`CONFIG_ACTION` | -| `hostname` | hostname to set for GitHub instance | `true` | `github.com` | `PARAMETER_HOSTNAME`
`GH_HOST`
`GITHUB_HOST` | -| `token` | token to set to authenticate to GitHub instance | `true` | `N/A` | `PARAMETER_TOKEN`
`CONFIG_TOKEN`
`GH_TOKEN`
`GITHUB_TOKEN` | -| `log_level` | set the log level for the plugin | `true` | `info` | `PARAMETER_LOG_LEVEL`
`VELA_LOG_LEVEL`
`GITHUB_RELEASE_LOG_LEVEL` | -| `version` | version of the `gh` CLI to install | `false` | `v2.14.4` | `PARAMETER_VERSION`
`VELA_GH_VERSION`
`GH_VERSION` | - -#### Create - -The following parameters are used to configure the `create` action: - -| Name | Description | Required | Default | Environment Variables | -| ------------ | ---------------------------------------------------- | -------- | ------- | ---------------------------------------------- | -| `draft` | save the release as a draft instead of publishing it | `false` | `false` | `PARAMETER_DRAFT`
`CREATE_DRAFT` | -| `notes` | create release notes | `false` | `N/A` | `PARAMETER_NOTES`
`CREATE_NOTES` | -| `notes_file` | read release notes from file | `false` | `N/A` | `PARAMETER_NOTES_FILE`
`CREATE_NOTES_FILE` | -| `files` | file(s) name used to create | `false` | `N/A` | `PARAMETER_FILES`
`GITHUB_RELEASE_FILES` | -| `prerelease` | mark the release as a prerelease | `false` | `false` | `PARAMETER_PRERELEASE`
`CREATE_PRERELEASE` | -| `tag` | github tag name to create | `true` | `N/A` | `PARAMETER_TAG`
`GITHUB_RELEASE_TAG` | -| `target` | target branch or commit SHA | `true` | `main` | `PARAMETER_TARGET`
`CREATE_TARGET` | -| `title` | Release title | `false` | `N/A` | `PARAMETER_TITLE`
`CREATE_TITLE` | - -#### Delete - -The following parameters are used to configure the `delete` action: - -| Name | Description | Required | Default | Environment Variables | -| --------- | -------------------------------------- | -------- | ------- | ----------------------------------------- | -| `yes` | skip the delete confirmation prompt | `false` | `false` | `PARAMETER_YES`
`DELETE_YES` | -| `tag` | github tag name to delete | `true` | `N/A` | `PARAMETER_TAG`
`GITHUB_RELEASE_TAG` | - -#### Download - -The following parameters are used to configure the `download` action: - -| Name | Description | Required | Default | Environment Variables | -| ----------- | --------------------------------------------- | -------- | ------- | --------------------------------------------- | -| `directory` | the directory to download files | `true` | `"."` | `PARAMETER_DIR`
`DOWNLOAD_DIR` | -| `patterns` | download only assets that match glob patterns | `false` | `N/A` | `PARAMETER_PATTERNS`
`DOWNLOAD_PATTERNS` | -| `tag` | github tag name to download | `true` | `N/A` | `PARAMETER_TAG`
`GITHUB_RELEASE_TAG` | - -#### List - -The following parameters are used to configure the `list` action: - -| Name | Description | Required | Default | Environment Variables | -| ---------- | ------------------------------------------------ | -------- | ------- | --------------------------------------------- | -| `limit` | maximum number of items to fetch for list action | `true` | `30` | `PARAMETER_LIMIT`
`LIST_LIMIT` | - -#### Upload - -The following parameters are used to configure the `upload` action: - -| Name | Description | Required | Default | Environment Variables | -| --------- | ------------------------------------------- | -------- | ------- | --------------------------------------------- | -| `clobber` | overwrite existing assets of the same name | `false` | `false` | `PARAMETER_CLOBBER`
`UPLOAD_CLOBBER` | -| `files` | file(s) name used to upload | `true` | `N/A` | `PARAMETER_FILES`
`GITHUB_RELEASE_FILES` | -| `tag` | github tag name to upload | `true` | `N/A` | `PARAMETER_TAG`
`GITHUB_RELEASE_TAG` | - -#### View - -The following parameters are used to configure the `view` action: - -| Name | Description | Required | Default | Environment Variables | -| ------- | --------------------------------- | -------- | ------- | ---------------------------------------- | -| `tag` | github tag name to view | `true` | `N/A` | `PARAMETER_TAG`
`GITHUB_RELEASE_TAG` | -| `web` | open the release in the browser | `true` | `false` | `PARAMETER_WEB`
`VIEW_WEB` | - - -## Troubleshooting - -You can start troubleshooting this plugin by tuning the level of logs being displayed: - -```diff -steps: - - name: github-release - image: target/vela-github-release:latest - pull: always - parameters: - action: create - files: [ gh/common, gh/dev/deploy.yml ] -+ log_level: trace -``` diff --git a/versioned_docs/version-0.26/usage/plugins/registry/Hugo.md b/versioned_docs/version-0.26/usage/plugins/registry/Hugo.md deleted file mode 100644 index 3b6ed94..0000000 --- a/versioned_docs/version-0.26/usage/plugins/registry/Hugo.md +++ /dev/null @@ -1,141 +0,0 @@ -## Description - -This plugin enables you generate a static website using [Hugo](https://gohugo.io/) in a pipeline. - -Source Code: https://github.com/go-vela/vela-hugo - -Registry: https://hub.docker.com/r/target/vela-hugo - -## Usage - -> **NOTE:** -> -> Users should refrain from using latest as the tag for the Docker image. -> -> It is recommended to use a semantically versioned tag instead. - -Sample of building a site: - -```yaml -steps: - - name: hugo - image: target/vela-hugo:latest - pull: always - parameters: - theme_name: hugo-theme-learn -``` - -Sample of building a site using the `docsy` theme: - -```diff -steps: - - name: hugo - image: target/vela-hugo:latest - pull: always - parameters: -- theme_name: hugo-theme-learn -+ theme_name: docsy -``` - -Sample of building a site using a custom version of Hugo: - -```diff -steps: - - name: hugo - image: target/vela-hugo:latest - pull: always - parameters: - theme_name: hugo-theme-learn -+ version: 0.101.0 -``` - -Sample of building a site using the extended `hugo` binary: - -> **NOTE:** Some themes may require the extended binary for additional functionality. - -```diff -steps: - - name: hugo - image: target/vela-hugo:latest - pull: always - parameters: - theme_name: hugo-theme-learn -+ extended: true -``` - -Sample of using an environment to build the site differently depending on configuration: - -> **NOTE:** Please see [Hugo documentation](https://gohugo.io/getting-started/configuration/) for how to configure this properly. - -```diff -steps: - - name: hugo - image: target/vela-hugo:latest - pull: always - parameters: - theme_name: hugo-theme-learn -+ environment: dev -``` - -Sample of using multiple themes via configuration file: - -> **NOTE:** Please see [Hugo documentation](https://gohugo.io/hugo-modules/theme-components/#readout) for how to configure this properly. - -```yaml -steps: - - name: hugo - image: target/vela-hugo:latest - pull: always - parameters: - config_file: config.toml -``` - -## Parameters - -> **NOTE:** -> -> The plugin supports reading all parameters via environment variables or files. -> -> Any values set from a file take precedence over values set from the environment. - -The following parameters are used to configure the image: - -| Name | Description | Required | Default | Environment Variables | -| ------------------- | ------------------------------------------------------------------------- | -------- | --------- | --------------------------------------------------------- | -| `base_url` | hostname (and path) to the root, e.g. http://spf13.com/ | `false` | `N/A` | `PARAMETER_BASE_URL`
`HUGO_BASE_URL` | -| `cache_directory` | filesystem path to cache directory | `false` | `N/A` | `PARAMETER_CACHE_DIRECTORY`
`HUGO_CACHE_DIRECTORY` | -| `content_directory` | filesystem path to content directory | `false` | `N/A` | `PARAMETER_CONTENT_DIRECTORY`
`HUGO_CONTENT_DIRECTORY` | -| `config_directory` | filesystem path to config directory | `false` | `config` | `PARAMETER_CONFIG_DIRECTORY`
`HUGO_CONFIG_DIRECTORY` | -| `config_file` | config file to use from config directory (supports: `json`,`toml`,`yaml`) | `false` | `N/A` | `PARAMETER_CONFIG_FILE`
`HUGO_CONFIG_FILE` | -| `draft` | include content marked as draft | `false` | `false` | `PARAMETER_DRAFT`
`HUGO_DRAFT` | -| `environment` | target build environment, located in the config directory | `false` | `N/A` | `PARAMETER_ENVIRONMENT`
`HUGO_ENVIRONMENT` | -| `expired` | include expired content | `false` | `false` | `PARAMETER_EXPIRED`
`HUGO_EXPIRED` | -| `extended` | whether to use the extended hugo binary | `false` | `false` | `PARAMETER_EXTENDED`
`HUGO_EXTENDED` | -| `future` | include content with publish date in the future | `false` | `false` | `PARAMETER_FUTURE`
`HUGO_FUTURE` | -| `layout_directory` | filesystem path to layout directory | `false` | `N/A` | `PARAMETER_LAYOUT_DIRECTORY`
`HUGO_LAYOUT_DIRECTORY` | -| `log_level` | set the log level for the plugin | `true` | `info` | `PARAMETER_LOG_LEVEL`
`HUGO_LOG_LEVEL` | -| `output_directory` | filesystem path to write files to | `false` | `N/A` | `PARAMETER_OUTPUT_DIRECTORY`
`HUGO_OUTPUT_DIRECTORY` | -| `source_directory` | filesystem path to read files relative from | `false` | `N/A` | `PARAMETER_SOURCE_DIRECTORY`
`HUGO_SOURCE_DIRECTORY` | -| `theme_name` | theme to use from theme directory | `false` | `N/A` | `PARAMETER_THEME_NAME`
`HUGO_THEME_NAME` | -| `theme_directory` | filesystem path to themes directory | `false` | `themes` | `PARAMETER_THEME_DIRECTORY`
`HUGO_THEME_DIRECTORY` | -| `version` | the version of hugo the plugin should use | `false` | `0.101.0` | `PARAMETER_VERSION`
`HUGO_VERSION` | - -## Template - -COMING SOON! - -## Troubleshooting - -You can start troubleshooting this plugin by tuning the level of logs being displayed: - -```diff -steps: - - name: hugo - image: target/vela-hugo:latest - pull: always - parameters: -+ log_level: trace - theme_name: hugo-theme-learn -``` - -Below are a list of common problems and how to solve them: diff --git a/versioned_docs/version-0.26/usage/plugins/registry/Influx.md b/versioned_docs/version-0.26/usage/plugins/registry/Influx.md deleted file mode 100644 index fa8b638..0000000 --- a/versioned_docs/version-0.26/usage/plugins/registry/Influx.md +++ /dev/null @@ -1,156 +0,0 @@ -## Description - -This plugin enables you to send data to an [InfluxDB](https://www.influxdata.com/) in a pipeline. - -Source Code: https://github.com/go-vela/vela-influx - -Registry: https://hub.docker.com/r/target/vela-influx - -## Usage - -> **NOTE:** -> -> Users should refrain from using latest as the tag for the Docker image. -> -> It is recommended to use a semantically versioned tag instead. - -Sample of emitting a pass/fail build metric: - -```yaml -steps: - - name: write - image: target/vela-influx:latest - pull: always - parameters: - addr: https://influx.example.com - database: vela - name: build_report - fields: - build_status: ${VELA_BUILD_STATUS} -``` - -Sample of emitting a pass/fail build metric with custom tags: - -```diff -steps: - - name: write - image: target/vela-influx:latest - pull: always - parameters: - addr: https://influx.example.com - database: vela - name: build_report - fields: - build_status: ${BUILD_STATUS} -+ tags: -+ repo_name: ${VELA_REPO_FULL_NAME} -+ build_number: "${VELA_BUILD_NUMBER}" -``` - -## Secrets - -> **NOTE:** Users should refrain from configuring sensitive information in your pipeline in plain text. - -### Internal - -The plugin accepts the following `parameters` for authentication: - -| Parameter | Environment Variable Configuration | -| ---------- | --------------------------------------- | -| `password` | `PARAMETER_PASSWORD`, `INFLUX_PASSWORD` | -| `username` | `PARAMETER_USERNAME`, `INFLUX_USERNAME` | - -Users can use [Vela internal secrets](https://go-vela.github.io/docs/tour/secrets/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: write - image: target/vela-influx:latest - pull: always -+ secrets: [ influx_username, influx_password ] - parameters: -- username: superSecretUsername -- password: superSecretPassword - addr: https://influx.example.com - database: vela - name: build_report - fields: - build_status: ${VELA_BUILD_STATUS} -``` - -> This example will add the secret to the `trigger_hello-world` step as environment variables: -> -> * `DOWNSTREAM_TOKEN=` - -### External - -The plugin accepts the following files for authentication: - -| Parameter | Volume Configuration | -| ---------- | ------------------------------------------------------------------- | -| `password` | `/vela/parameters/influx/password`, `/vela/secrets/influx/password` | -| `username` | `/vela/parameters/influx/username`, `/vela/secrets/influx/username` | - -Users can use [Vela external secrets](https://go-vela.github.io/docs/concepts/pipeline/secrets/origin/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: write - image: target/vela-influx:latest - pull: always - parameters: -- username: superSecretUsername -- password: superSecretPassword - addr: https://influx.example.com - database: vela - name: build_report - fields: - build_status: ${VELA_BUILD_STATUS} -``` - -> This example will read the secret value in the volume stored at `/vela/secrets/` - -## Parameters - -> **NOTE:** -> -> The plugin supports reading all parameters via environment variables or files. -> -> Any values set from a file take precedence over values set from the environment. - -The following parameters are used to configure the image: - -| Name | Description | Required | Default | Environment Variables | -| ----------- | ---------------------------------------------------- | -------- | --------------- | ------------------------------------------- | -| `addr` | Influx instance to communicate with | `true` | `N/A` | `PARAMETER_ADDR`
`INFLUX_ADDR` | -| `database` | database name on Influx instance to communicate with | `true` | `N/A` | `PARAMETER_DATABASE`
`INFLUX_DATABASE` | -| `fields` | data fields to send along with the metric | `true` | `N/A` | `PARAMETER_FIELDS`
`INFLUX_FIELDS` | -| `log_level` | set the log level for the plugin | `true` | `info` | `PARAMETER_LOG_LEVEL`
`INFLUX_LOG_LEVEL` | -| `name` | name of metric sent to database on Influx instance | `true` | `build_metrics` | `PARAMETER_NAME`
`INFLUX_NAME` | -| `password` | password for communication with Influx | `false` | `N/A` | `PARAMETER_PASSWORD`
`INFLUX_PASSWORD` | -| `tags` | extra metadata to send along with the metric | `false` | `N/A` | `PARAMETER_TAGS`
`INFLUX_TAGS` | -| `username` | user name for communication with Influx | `false` | `N/A` | `PARAMETER_USERNAME`
`INFLUX_USERNAME` | - -## Template - -COMING SOON! - -## Troubleshooting - -You can start troubleshooting this plugin by tuning the level of logs being displayed: - -```diff -steps: - - name: write - image: target/vela-influx:latest - pull: always - parameters: -+ log_level: trace - addr: https://influx.example.com - database: vela - name: build_report - fields: - build_status: ${VELA_BUILD_STATUS} -``` - -Below are a list of common problems and how to solve them: diff --git a/versioned_docs/version-0.26/usage/plugins/registry/K6.md b/versioned_docs/version-0.26/usage/plugins/registry/K6.md deleted file mode 100644 index eb1ffb3..0000000 --- a/versioned_docs/version-0.26/usage/plugins/registry/K6.md +++ /dev/null @@ -1,77 +0,0 @@ -## Description - -This plugin uses [Grafana k6](https://k6.io/) to run performance tests in a Vela pipeline. - -Source Code: https://github.com/go-vela/vela-k6 - -Registry: https://hub.docker.com/r/target/vela-k6 - -## Usage - -Below is a simple example using the plugin. In this hypothetical repository, the k6 test script is located at `./k6-test/script.js`. In this step, a file named `test-results.json` will be created in the current directory with the test results. - -```yaml -- name: k6-performance-test - image: target/vela-k6:v0.1.0 - ruleset: - event: [tag] - pull: true - parameters: - script_path: ./k6-test/script.js - output_path: ./test-results.json -``` - -Example using `projektor_compat_mode` parameter, which generates output with the `--summary-export` flag instead of the recommended `--out` flag. This ensures compatibility with [Projektor](https://projektor.dev/) test result visualization: - -```yaml -- name: k6-performance-test - image: target/vela-k6:v0.1.0 - ruleset: - event: [tag] - pull: true - parameters: - script_path: ./k6-test/script.js - output_path: ./test-results.json - projektor_compat_mode: true - -- name: projektor-publish - image: node:alpine - ruleset: - event: [tag] - pull: true - commands: - - npm install -g projektor-publish - - npx projektor-publish --serverUrl=https://my-projektor-server.dev --performance="./test-results.json" -``` - -> **NOTE:** -> -> Projektor will not accept performance test results unless the below stats are included - -For your results to be accepted by your Projektor server, the k6 script's `options.summaryTrendStats` MUST include the following: - -```js -export const options = { - summaryTrendStats: ["p(95)", "p(90)", "avg", "min", "max", "med"], - ... -}; -``` - -## Parameters - -> **NOTE:** -> -> The plugin supports reading all parameters via environment variables or files. -> -> Any values set from a file take precedence over values set from the environment. - -The following parameters are used to configure the image: - -| Name | Description | Required | Default | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------- | -| `script_path` | path to the k6 script file. must be a JavaScript file satisfying the pattern `^(\./\|(\.\./)+)?[a-zA-Z0-9-_/]*[a-zA-Z0-9]\.js$`. | `true` | `N/A` | -| `output_path` | path to the output file that will be created. directories will be created as necessary. if empty, no output file will be generated. must be a JSON file satisfying the pattern `^(\./\|(\.\./)+)?[a-zA-Z0-9-_/]*[a-zA-Z0-9]\.json$`. | `false` | `N/A` | -| `setup_script_path` | path to an optional setup script file to be run before tests. must be a shell script (sh or bash) with execute permissions matching the pattern `^(\./\|(\.\./)+)?[a-zA-Z0-9-_/]*[a-zA-Z0-9]\.sh$`. | `false` | `N/A` | -| `fail_on_threshold_breach` | if `false`, the pipeline step will not fail even if thresholds are breached. | `false` | `true` | -| `projektor_compat_mode` | if `true`, output will be generated with the `--summary-output` flag instead of the `--out` flag. this is necessary for results uploaded to a [Projektor](https://projektor.dev/) server. | `false` | `false` | -| `log_progress` | if `true`, k6 progress bar output will print to the Vela pipeline. Not recommended for numerous or long-running tests, as logging becomes excessive. | `false` | `false` | diff --git a/versioned_docs/version-0.26/usage/plugins/registry/Kaniko.md b/versioned_docs/version-0.26/usage/plugins/registry/Kaniko.md deleted file mode 100644 index 4f61005..0000000 --- a/versioned_docs/version-0.26/usage/plugins/registry/Kaniko.md +++ /dev/null @@ -1,302 +0,0 @@ -## Description - -This plugin enables you to build and publish [Docker](https://www.docker.com/) images in a Vela pipeline. - -Source Code: https://github.com/go-vela/vela-kaniko - -Registry: https://hub.docker.com/r/target/vela-kaniko - -## Usage - -> **NOTE:** -> -> Users should refrain from using latest as the tag for the Docker image. -> -> It is recommended to use a semantically versioned tag instead. - -Sample of building and publishing an image: - -```yaml -steps: - - name: publish_hello-world - image: target/vela-kaniko:latest - pull: always - parameters: - registry: index.docker.io - repo: index.docker.io/octocat/hello-world -``` - -Sample of building an image without publishing: - -```diff -steps: - - name: publish_hello-world - image: target/vela-kaniko:latest - pull: always - parameters: -+ dry_run: true - registry: index.docker.io - repo: index.docker.io/octocat/hello-world -``` - -Sample of attempting the publishing of an image three times: - -```diff -steps: - - name: publish_hello-world - image: target/vela-kaniko:latest - pull: always - parameters: -+ push_retry: 3 - registry: index.docker.io - repo: index.docker.io/octocat/hello-world -``` - -Sample of building and publishing an image with custom tags: - -```diff -steps: - - name: publish_hello-world - image: target/vela-kaniko:latest - pull: always - parameters: - registry: index.docker.io - repo: index.docker.io/octocat/hello-world -+ tags: -+ - latest -+ - foobar -``` - -Sample of building and publishing an image with automatic tags: - - -```diff -steps: - - name: publish_hello-world - image: target/vela-kaniko:latest - pull: always - parameters: -+ auto_tag: true - registry: index.docker.io - repo: index.docker.io/octocat/hello-world -``` - -Depending on the type of event, the image will be tagged as follows: - -* tag event (using `v1.0.0` as an example): - * `index.docker.io/octocat/hello-world:latest` - * `index.docker.io/octocat/hello-world:v1.0.0` - -* all other events: - * `index.docker.io/octocat/hello-world:latest` - * `index.docker.io/octocat/hello-world:eeea105fed7fc11bda4b43a00edfc49a5c982968` - - -Sample of building and publishing an image with build arguments: - -```diff -steps: - - name: publish_hello-world - image: target/vela-kaniko:latest - pull: always - parameters: -+ build_args: -+ - FOO=bar - registry: index.docker.io - repo: index.docker.io/octocat/hello-world -``` - -Sample of building and publishing an image with caching: - -```diff -steps: - - name: publish_hello-world - image: target/vela-kaniko:latest - pull: always - parameters: -+ cache: true -+ cache_repo: index.docker.io/octocat/hello-world - registry: index.docker.io - repo: index.docker.io/octocat/hello-world -``` - -Sample of building using a snapshot mode and publishing an image with caching: - -```diff -steps: - - name: publish_hello-world - image: target/vela-kaniko:latest - pull: always - parameters: -+ snapshot_mode: redo - registry: index.docker.io - repo: index.docker.io/octocat/hello-world -``` - -Sample of building using a custom platform: - -```diff -steps: - - name: publish_hello-world - image: target/vela-kaniko:latest - pull: always - parameters: - registry: index.docker.io - repo: index.docker.io/octocat/hello-world -+ custom_platform: linux/arm64/v8 -``` - -> **NOTE:** This option will only work if your Vela worker is configured appropriately. - -Sample of only including repository topics starting with "id" as a value in the "io.vela.build.topics" that gets applied to the built image: - -```diff -steps: - - name: publish_hello-world - image: target/vela-kaniko:latest - pull: always - parameters: -+ repo_topics_filter: "^id" - registry: index.docker.io - repo: index.docker.io/octocat/hello-world -``` - -Sample of using `zstd` layer compression: - -```diff -steps: - - name: publish_hello-world - image: target/vela-kaniko:latest - pull: always - parameters: - registry: index.docker.io - repo: index.docker.io/octocat/hello-world -+ compression: zstd -+ compression_level: 3 -``` - -> **NOTE:** Be aware that while this may yield better compression and/or performance, many common container tools are not yet compatible with this type of compression. Use at your own risk. - -## Secrets - -> **NOTE:** Users should refrain from configuring sensitive information in your pipeline in plain text. - -### Internal - -Users can use [Vela internal secrets](https://go-vela.github.io/docs/tour/secrets/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: publish_hello-world - image: target/vela-kaniko:latest - pull: always -+ secrets: [ kaniko_username, kaniko_password ] - parameters: - registry: index.docker.io - repo: index.docker.io/octocat/hello-world -- username: octocat -- password: superSecretPassword -``` - -> This example will add the secrets to the `publish_hello-world` step as environment variables: -> -> * `KANIKO_USERNAME=` -> * `KANIKO_PASSWORD=` - -### External - -The plugin accepts the following files for authentication: - -| Parameter | Volume Configuration | -| ---------- | ---------------------------------------------------------------------------------------------------------- | -| `password` | `/vela/parameters/kaniko/password`, `/vela/secrets/kaniko/password`, `/vela/secrets/managed-auth/password` | -| `username` | `/vela/parameters/kaniko/username`, `/vela/secrets/kaniko/username`, `/vela/secrets/managed-auth/username` | - -Users can use [Vela external secrets](https://go-vela.github.io/docs/concepts/pipeline/secrets/origin/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: publish_hello-world - image: target/vela-kaniko:latest - pull: always -+ secrets: [ kaniko_username, kaniko_password ] - parameters: - registry: index.docker.io - repo: index.docker.io/octocat/hello-world -- username: octocat -- password: superSecretPassword -``` - -> This example will read the secret values in the volume stored at `/vela/secrets/` - -## Parameters - -> **NOTE:** -> -> The plugin supports reading all parameters via environment variables or files. -> -> Any values set from a file take precedence over values set from the environment. -> -> The [Snapshot mode](https://github.com/GoogleContainerTools/kaniko/releases/tag/v1.0.0) can help improve performance but it is recommend to follow Kaniko's guidelines for picking the mode. - -The following parameters are used to configure the image: - -| Name | Description | Required | Default | Environment Variables | -|------------------------|-------------------------------------------------------------------------------------------------------------------------| -------- |-------------------|---------------------------------------------------------------------------------| -| `auto_tag` | enables automatic tagging of images (tag or sha, and `latest`) | `false` | `false` | `PARAMETER_AUTO_TAG`
`KANIKO_AUTO_TAG` | -| `build_args` | variables passed to image at build-time | `false` | `N/A` | `PARAMETER_BUILD_ARGS`
`KANIKO_BUILD_ARGS` | -| `cache` | enable caching of image layers | `false` | `false` | `PARAMETER_CACHE`
`KANIKO_CACHE` | -| `cache_repo` | specific repo to enable caching for | `false` | `N/A` | `PARAMETER_CACHE_REPO`
`KANIKO_CACHE_REPO` | -| `compression` | compression to use (`gzip` or `zstd` - kaniko uses `gzip` if not defined) | `false` | `N/A` | `PARAMETER_COMPRESSION`
`KANIKO_COMPRESSION` | -| `compression_level` | compression level to use (1 - 9, inclusive) | `false` | `N/A` | `PARAMETER_COMPRESSION_LEVEL`
`KANIKO_COMPRESSION_LEVEL` | -| `compressed_caching` | set this to false in order to prevent tar compression for cached layers | `false` | `true` | `PARAMETER_COMPRESSED_CACHING`
`KANIKO_COMPRESSED_CACHING` | -| `context` | path to context for building the image | `true` | `.` | `PARAMETER_CONTEXT`
`KANIKO_CONTEXT` | -| `dockerfile` | path to the file for building the image | `true` | `Dockerfile` | `PARAMETER_DOCKERFILE`
`KANIKO_DOCKERFILE` | -| `dry_run` | enable building the image without publishing | `false` | `false` | `PARAMETER_DRY_RUN`
`KANIKO_DRY_RUN` | -| `event` | event generated for build | `true` | **set by Vela** | `PARAMETER_EVENT`
`KANIKO_EVENT`
`VELA_BUILD_EVENT` | -| `force_build_metadata` | enable force adding metadata layers to build image | `false` | `false` | `PARAMETER_FORCE_BUILD_METADATA`
`KANIKO_FORCE_BUILD_METADATA` | -| `repo_topics_filter` | regex expression to filter out repository topics | `false` | `empty slice` | `PARAMETER_REPO_TOPICS_FILTER`
`KANIKO_REPO_TOPICS_FILTER` | -| `ignore_path` | ignore path when taking an image snapshot | `false` | `empty slice` | `PARAMETER_IGNORE_PATH`
`KANIKO_IGNORE_PATH` | -| `ignore_var_run` | sets `--ignore-var-run` kaniko flag to control whether /var/run is included in image snapshot | `false` | `true` | `PARAMETER_IGNORE_VAR_RUN`
`KANIKO_IGNORE_VAR_RUN`
`VELA_IGNORE_VAR_RUN` | -| `labels` | unique labels to add to the image | `false` | `N/A` | `PARAMETER_LABELS`
`KANIKO_LABELS` | -| `log_level` | set the log level for the plugin | `true` | `info` | `PARAMETER_LOG_LEVEL`
`KANIKO_LOG_LEVEL` | -| `log_timestamps` | add timestamps to log lines | `false` | `false` | `PARAMETER_LOG_TIMESTAMPS`
`KANIKO_LOG_TIMESTAMPS` | -| `mirror` | name of the mirror registry to use | `false` | `N/A` | `PARAMETER_MIRROR`
`KANIKO_MIRROR` | -| `password` | password for communication with the registry | `true` | `N/A` | `PARAMETER_PASSWORD`
`KANIKO_PASSWORD`
`DOCKER_PASSWORD` | -| `push_retry` | number of retries for pushing an image to a remote destination | `false` | `0` | `PARAMETER_PUSH_RETRY`
`KANIKO_PUSH_RETRY` | -| `registry` | name of the registry for the repository | `true` | `index.docker.io` | `PARAMETER_REGISTRY`
`KANIKO_REGISTRY` | -| `repo` | name of the repository for the image | `true` | `N/A` | `PARAMETER_REPO`
`KANIKO_REPO` | -| `sha` | SHA-1 hash generated for commit | `true` | **set by Vela** | `PARAMETER_SHA`
`KANIKO_SHA`
`VELA_BUILD_COMMIT` | -| `use_new_run` | use experimental run implementation for detecting changes without requiring file system snapshots | `false` | `false` | `PARAMETER_USE_NEW_RUN`
`KANIKO_USE_NEW_RUN` | -| `single_snapshot` | takes a single snapshot of the filesystem at the end of the build, so only one layer will be appended to the base image | `false` | `false` | `PARAMETER_SINGLE_SNAPSHOT`
`KANIKO_SINGLE_SNAPSHOT` | -| `snapshot_mode` | control how to snapshot the filesystem. - options: `full`, `redo`, or `time` | `false` | `N/A` | `PARAMETER_SNAPSHOT_MODE`
`KANIKO_SNAPSHOT_MODE` | -| `tag` | tag generated for build | `false` | **set by Vela** | `PARAMETER_TAG`
`KANIKO_TAG`
`VELA_BUILD_TAG` | -| `tags` | unique tags of the image | `true` | `latest` | `PARAMETER_TAGS`
`KANIKO_TAGS` | -| `tar_path` | save the image as a tarball at path | `false` | `N/A` | `PARAMETER_TAR_PATH`
`KANIKO_TAR_PATH` | -| `target` | set the target build stage for the image | `false` | `N/A` | `PARAMETER_TARGET`
`KANIKO_TARGET` | -| `username` | user name for communication with the registry | `true` | `N/A` | `PARAMETER_USERNAME`
`KANIKO_USERNAME`
`DOCKER_USERNAME` | -| `custom_platform` | set the custom platform for the image | `false` | `N/A` | `PARAMETER_CUSTOM_PLATFORM`
`KANIKO_CUSTOM_PLATFORM` | -| `insecure_registries` | insecure docker registries to push or pull to/from | `false` | `empty slice` | `PARAMETER_INSECURE_REGISTRIES`
`KANIKO_INSECURE_REGISTRIES` | -| `insecure_pull` | enable pulling from any insecure registry | `false` | `false` | `PARAMETER_INSECURE_PULL`
`KANIKO_INSECURE_PULL` | -| `insecure_push` | enable pushing to any insecure registry | `false` | `false` | `PARAMETER_INSECURE_PUSH`
`KANIKO_INSECURE_PUSH` | - -## Template - -COMING SOON! - -## Troubleshooting - -You can start troubleshooting this plugin by tuning the level of logs being displayed: - -```diff -steps: - - name: publish_hello-world - image: target/vela-kaniko:latest - pull: always - parameters: -+ log_level: trace - registry: index.docker.io - repo: index.docker.io/octocat/hello-world -``` - -Below are a list of common problems and how to solve them: diff --git a/versioned_docs/version-0.26/usage/plugins/registry/Kubernetes.md b/versioned_docs/version-0.26/usage/plugins/registry/Kubernetes.md deleted file mode 100644 index 66e111d..0000000 --- a/versioned_docs/version-0.26/usage/plugins/registry/Kubernetes.md +++ /dev/null @@ -1,387 +0,0 @@ -## Description - -This plugin enables the ability to manage resources in [Kubernetes](https://kubernetes.io/) in a Vela pipeline. - -Source Code: https://github.com/go-vela/vela-kubernetes - -Registry: https://hub.docker.com/r/target/vela-kubernetes - -## Usage - -> **NOTE:** -> -> Users should refrain from using latest as the tag for the Docker image. -> -> It is recommended to use a semantically versioned tag instead. - -Sample of applying Kubernetes files: - -```yaml -steps: - - name: kubernetes - image: target/vela-kubernetes:latest - pull: always - parameters: - action: apply - files: [ kubernetes/common, kubernetes/dev/deploy.yml ] -``` - -Sample of pretending to apply Kubernetes files: - -```diff -steps: - - name: kubernetes - image: target/vela-kubernetes:latest - pull: always - parameters: - action: apply -+ dry_run: true - files: [ kubernetes/common, kubernetes/dev/deploy.yml ] -``` - -Sample of patching containers in Kubernetes files: - -```yaml -steps: - - name: kubernetes - image: target/vela-kubernetes:latest - pull: always - parameters: - action: patch - files: [ kubernetes/common, kubernetes/dev/deploy.yml ] - containers: - - name: sample - image: alpine:latest -``` - -Sample of pretending to patch containers in Kubernetes files: - -```diff -steps: - - name: kubernetes - image: target/vela-kubernetes:latest - pull: always - parameters: - action: patch -+ dry_run: true - files: [ kubernetes/common, kubernetes/dev/deploy.yml ] - containers: - - name: sample - image: alpine:latest -``` - -Sample of watching the status of resources: - -```yaml -steps: - - name: kubernetes - image: target/vela-kubernetes:latest - pull: always - parameters: - action: status - statuses: [ sample ] -``` - -### GKE clusters authentication - -Google Kubernetes Engine (GKE) clusters version 1.26 and up require use of new "gke-gcloud-auth-plugin", see [blog](https://cloud.google.com/blog/products/containers-kubernetes/kubectl-auth-changes-in-gke). - -1. Download Google service account credentials: - -```bash -gcloud beta secrets versions access 1 --secret [Secret Name] --project [Google Project Name] --out-file [Secret Name]-gsa-key.json -``` - -2. Upload Google service account secret to vela native secrets store: - -```bash -vela add secret --secret.engine native --secret.type org --org MYORGNAME --name k8s-gsa-key --value @k8s-gsa-key.json -event deployment --event pull_request --event push --event tag --event comment -``` - -3. Create kubeconfig file and make sure to use user `gke-gcloud-auth-user` for your cluster: - -```yaml -apiVersion: v1 -clusters: -- cluster: - certificate-authority-data: XXXXXXXXXXX - server: https://ip of K8s API Server - name: clustername -contexts: -- context: - cluster: clustername - user: gke-gcloud-auth-user - name: clustername - -current-context: "" -kind: Config -preferences: {} -users: -- name: gke-gcloud-auth-user - user: - exec: - apiVersion: client.authentication.k8s.io/v1beta1 - args: - - --use_application_default_credentials - command: gke-gcloud-auth-plugin - env: null - installHint: Install gke-gcloud-auth-plugin for use with kubectl by following - https://cloud.google.com/blog/products/containers-kubernetes/kubectl-auth-changes-in-gke - interactiveMode: IfAvailable - provideClusterInfo: true - -``` -4. Upload kubeconfig file to vela native secretrs store: - -```bash -vela add secret --secret.engine native --secret.type org --org MYORGNAME --name kube_config_secret --value @kube_config_secret.file -event deployment --event pull_request --event push --event tag --event comment -``` - -5. Configure Vela file: - -```yaml -secrets: - - name: kube_config_secret - key: ORGNAME/kube-config - type: org - - name: gsa_key - key: ORGNAME/k8s-gsa-key - type: org - - k8s-gsa-setup: - steps: - - name: setup-gke-access - image: alpine:latest - ruleset: - branch: master - event: [pull_request, push, deployment] - pull: always - environment: - GOOGLE_APPLICATION_CREDENTIALS: "/vela/secrets/.kube/gsa-key.json" # <== change name as needed - secrets: - - source: gsa_key - target: GSA_KEY_FILE - commands: - - mkdir -p /vela/secrets/.kube/ - - echo "$GSA_KEY_FILE" > $GOOGLE_APPLICATION_CREDENTIALS - - k8s-plugin-dry-run: - needs: [ k8s-gsa-setup ] - steps: - - name: dry-run - image: target/vela-kubernetes:latest - ruleset: - branch: master - event: [ pull_request ] - environment: - GOOGLE_APPLICATION_CREDENTIALS: "/vela/secrets/.kube/gsa-key.json" # <== change name as needed - USE_GKE_GCLOUD_AUTH_PLUGIN: True # <== required - secrets: - - source: kube_config_secret - target: kube_config - parameters: - action: apply - dry_run: true - context: context-name # <== change as needed - files: [ Kubernetes/manifests/service.yaml ] - - k8s-plugin-apply: - needs: [ k8s-gsa-setup ] - steps: - - name: run-apply - image: target/vela-kubernetes:latest - ruleset: - branch: master - event: [ push ] - environment: - GOOGLE_APPLICATION_CREDENTIALS: "/vela/secrets/.kube/gsa-key.json" # <== change name as needed - USE_GKE_GCLOUD_AUTH_PLUGIN: True # <== required - secrets: - - source: kube_config_secret - target: kube_config - parameters: - action: apply - context: context-name # <== change as needed - files: [ Kubernetes/manifests/service.yaml ] -``` - -## Secrets - -> **NOTE:** Users should refrain from configuring sensitive information in your pipeline in plain text. - -### Internal - -Users can use [Vela internal secrets](https://go-vela.github.io/docs/tour/secrets/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: kubernetes - image: target/vela-kubernetes:latest - pull: always -+ secrets: [ kube_config ] - parameters: - action: apply - files: [ kubernetes/common, kubernetes/dev/deploy.yml ] -- config: | -- --- -- apiVersion: v1 -- kind: Config -``` - -> This example will add the secrets to the `kubernetes` step as environment variables: -> -> * `KUBE_CONFIG=` - -### External - -The plugin accepts the following files for authentication: - -| Parameter | Volume Configuration | -| ---------- | ----------------------------------------------------------------------- | -| `config` | `/vela/parameters/kubernetes/config`, `/vela/secrets/kubernetes/config` | - -Users can use [Vela external secrets](https://go-vela.github.io/docs/concepts/pipeline/secrets/origin/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: kubernetes - image: target/vela-kubernetes:latest - pull: always -+ secrets: [ kube_config ] - parameters: - action: apply - files: [ kubernetes/common, kubernetes/dev/deploy.yml ] -- config: | -- --- -- apiVersion: v1 -- kind: Config -``` - -> This example will read the secret values in the volume stored at `/vela/secrets/` - -## Parameters - -> **NOTE:** -> -> The plugin supports reading all parameters via environment variables or files. -> -> Any values set from a file take precedence over values set from the environment. - -The following parameters are used to configure the image: - -| Name | Description | Required | Default | Environment Variables | -| ------------- | --------------------------------------------------------------- | -------- | ----------------- | ---------------------------------------------------------- | -| `action` | action to perform against Kubernetes | `true` | `N/A` | `PARAMETER_ACTION`
`KUBERNETES_ACTION` | -| `cluster` | Kubernetes cluster from the configuration file | `false` | `N/A` | `PARAMETER_CLUSTER`
`KUBERNETES_CLUSTER` | -| `context` | Kubernetes context from the configuration file | `false` | `N/A` | `PARAMETER_CONTEXT`
`KUBERNETES_CONTEXT` | -| `config` | content of configuration file for communication with Kubernetes | `true` | `N/A` | `PARAMETER_CONFIG`
`KUBERNETES_CONFIG`
`KUBE_CONFIG` | -| `log_level` | set the log level for the plugin | `true` | `info` | `PARAMETER_LOG_LEVEL`
`KUBERNETES_LOG_LEVEL` | -| `namespace` | Kubernetes namespace from the configuration file | `false` | `N/A` | `PARAMETER_NAMESPACE`
`KUBERNETES_NAMESPACE` | -| `path` | path to configuration file for communication with Kubernetes | `false` | `N/A` | `PARAMETER_PATH`
`KUBERNETES_PATH` | -| `version` | version of the `kubectl` CLI to install | `false` | `v1.24.0` | `PARAMETER_VERSION`
`KUBERNETES_VERSION` | - -### Config - -The content passed to the `config` parameter is expected to be a full -Kubernetes Config object as would be found in `~/.kube/config`. -Run `kubectl config view` to get an idea of what _could_ be in this config file. - -Consider this a minimal example of step with inline `config`: - -```yaml -name: k8s apply -image: target/vela-kubernetes:latest -ruleset: - event: push - branch: [main] -secrets: [K8S_TOKEN] -parameters: - action: apply - files: - # These may not be necessary, but explicitness is good practice. - cluster: mycluster - context: mycontext - namespace: mynamespace - - k8s/myapp.yaml - config: | - --- - apiVersion: v1 - kind: Config - clusters: - - name: mycluster - cluster: - server: https://kubernetes.example.com:6443 - users: - - name: myuser - user: - token: "${K8S_TOKEN}" - contexts: - - name: mycontext - context: - cluster: mycluster - namespace: mynamespace - user: myuser - current-context: mycontext -``` - -Note the interpolation of the `K8S_TOKEN` secret. -Doing this can ease management of large secrets with multiple "sub-secrets" -even when they don't change very often. - -### Actions - -These next sections define the parameters that must or can be passed when -a particular action is active. - - -#### Apply - -The following parameters are used to configure the `apply` action: - -| Name | Description | Required | Default | Environment Variables | -| --------- | ------------------------------------------------ | -------- | ------- | ------------------------------------------- | -| `dry_run` | enables pretending to perform the apply (`true`/`client`, `false`/`none`, `server`) | `false` | `false` | `PARAMETER_DRY_RUN`
`KUBERNETES_DRY_RUN` | -| `files` | list of Kubernetes files or directories to apply | `true` | `N/A` | `PARAMETER_FILES`
`KUBERNETES_FILES` | -| `output` | set the output for the apply | `false` | `N/A` | `PARAMETER_OUTPUT`
`KUBERNETES_OUTPUT` | - -#### Patch - -The following parameters are used to configure the `patch` action: - -| Name | Description | Required | Default | Environment Variables | -| ------------ | ------------------------------------------------ | -------- | ------- | ------------------------------------------------- | -| `containers` | containers from the files to patch | `true` | `N/A` | `PARAMETER_CONTAINERS`
`KUBERNETES_CONTAINERS` | -| `dry_run` | enables pretending to perform the patch | `false` | `false` | `PARAMETER_DRY_RUN`
`KUBERNETES_DRY_RUN` | -| `files` | list of Kubernetes files or directories to patch | `true` | `N/A` | `PARAMETER_FILES`
`KUBERNETES_FILES` | -| `output` | set the output for the patch | `false` | `N/A` | `PARAMETER_OUTPUT`
`KUBERNETES_OUTPUT` | - -#### Status - -The following parameters are used to configure the `status` action: - -| Name | Description | Required | Default | Environment Variables | -| ---------- | ------------------------------------------------ | -------- | ------- | --------------------------------------------- | -| `statuses` | list of Kubernetes resources to watch status on | `true` | `N/A` | `PARAMETER_STATUSES`
`KUBERNETES_STATUSES` | -| `timeout` | total time allowed to watch Kubernetes resources | `true` | `5m` | `PARAMETER_TIMEOUT`
`KUBERNETES_TIMEOUT` | -| `watch` | enables watching until the resource completes | `false` | `true` | `PARAMETER_WATCH`
`KUBERNETES_WATCH` | - -## Template - -COMING SOON! - -## Troubleshooting - -You can start troubleshooting this plugin by tuning the level of logs being displayed: - -```diff -steps: - - name: kubernetes - image: target/vela-kubernetes:latest - pull: always - parameters: - action: apply - files: [ kubernetes/common, kubernetes/dev/deploy.yml ] -+ log_level: trace -``` - -Below are a list of common problems and how to solve them: diff --git a/versioned_docs/version-0.26/usage/plugins/registry/Manifest Tool.md b/versioned_docs/version-0.26/usage/plugins/registry/Manifest Tool.md deleted file mode 100644 index d7af212..0000000 --- a/versioned_docs/version-0.26/usage/plugins/registry/Manifest Tool.md +++ /dev/null @@ -1,102 +0,0 @@ -## Description - -This plugin enables you to build and publish [Docker Manifest List](https://www.docker.com/) -or [OCI Image Index](https://github.com/opencontainers/image-spec/blob/main/image-index.md) -in a Vela pipeline. - -Source Code: https://github.com/go-vela/vela-manifest-tool - -Registry: https://hub.docker.com/r/target/vela-manifest-tool - -## Usage - -> **NOTE:** -> -> Users should refrain from using latest as the tag for the Docker image. -> -> It is recommended to use a semantically versioned tag instead. - -Sample of building and publishing an image: - -```yaml -steps: - - name: publish_hello-world - image: target/vela-manifest-tool:latest - pull: always - parameters: - registry: index.docker.io - repo: /octocat/hello-world - tags: [ "latest" ] - platforms: - - linux/amd64 - - linux/arm64/v8 - component_template: /octocat/hello-world:latest-{{ .Os }}-{{ .Arch }}{{ if .Variant }}-{{ .Variant }}{{ end }} -``` - -NOTE: For vela-manifest-tool, unlike for vela-kaniko, the `repo` argument excludes the `registry` value. Said another -way, rather than using: - -```yaml -parameters: - registry: index.docker.io - repo: index.docker.io/octocat/hello-world - ... - component_template: index.docker.io/octocat/hello-world:latest-{{ .Os }}-{{ .Arch }}{{ if .Variant }}-{{ .Variant }}{{ end }} -``` - -You must instead use: - -```yaml -parameters: - registry: index.docker.io - repo: /octocat/hello-world - ... - component_template: /octocat/hello-world:latest-{{ .Os }}-{{ .Arch }}{{ if .Variant }}-{{ .Variant }}{{ end }} -``` - -This is because manifest tool requires that all image repos referenced exist within the same registry. Resulting tags will -all be the concatenation of the registry with the repo. - -Sample of building an image without publishing: - -```yaml -steps: - - name: publish_hello-world - image: target/vela-manifest-tool:latest - pull: always - parameters: -+ dry_run: true - registry: index.docker.io - repo: /octocat/hello-world - tags: [ "latest" ] - platforms: - - linux/amd64 - - linux/arm64/v8 - component_template: /octocat/hello-world:latest-{{ .Os }}-{{ .Arch }}{{ if .Variant }}-{{ .Variant }}{{ end }} -``` - -For every element of `tags:`, one spec file will be generated and (unless `dry_run: true`) pushed to the `registry:`. -For each manifest-tool spec file, the tag for the manifest list/image index will be `$registry$repo:$tag`. Then there will -be one element in the `manifests:` list of the spec file for each element of the `platform:` argument. Platform is assumed -to be in `os/architecture/variant` format. Within the `component_template`, you can use Os, Arch, Variant (from the platform), -or Tag (from the top level `tags:`). - -Note: The default component_template of `"{{.Repo}}:{{.Tag}}-{{.Os}}-{{.Arch}}{{if .Variant}}-{{.Variant}}{{end}}"` might -be sufficient for most needs if you follow that tagging convention. For example, if the builds for /octocat/hello-world created -the architecture specific image - -- index.docker.io/octocat/hello-world:latest-linux-amd64 -- index.docker.io/octocat/hello-world:latest-linux-arm64-v8 - -Then the following configuration would be sufficient due to defaults for tags, platforms, and component_template: - -```yaml -steps: - - name: publish_hello-world - image: target/vela-manifest-tool:latest - pull: always - parameters: - registry: index.docker.io - repo: /octocat/hello-world -``` - diff --git a/versioned_docs/version-0.26/usage/plugins/registry/NPM.md b/versioned_docs/version-0.26/usage/plugins/registry/NPM.md deleted file mode 100644 index 4737591..0000000 --- a/versioned_docs/version-0.26/usage/plugins/registry/NPM.md +++ /dev/null @@ -1,207 +0,0 @@ -## Description - -This plugin enables the ability to manage artifacts in [npm](https://www.npmjs.org/) in a Vela pipeline. - -Source Code: https://github.com/go-vela/vela-npm - -Registry: https://hub.docker.com/r/target/vela-npm - -## Usage - -> **NOTE:** -> -> Users should refrain from using latest as the tag for the Docker image. -> -> It is recommended to use a semantically versioned tag instead. - -Sample of publishing package: - -```yaml -steps: - - name: npm_publish - image: target/vela-npm:latest - pull: not_present - secrets: [ npm_password ] - parameters: - username: npmUsername - registry: https://registry.npmjs.org -``` - -Sample of publishing if registry does not support `npm ping`: - -> **NOTE:** -> -> Recommended if you are deploying to a registry inside ***Artifactory*** - -```diff -steps: - - name: npm_publish - image: target/vela-npm:latest - pull: not_present - secrets: [ npm_password ] - parameters: - username: npmUsername - registry: https://registry.npmjs.org -+ skip_ping: true -``` - -Sample of pretending to publish package: - -```diff -steps: - - name: npm_publish - image: target/vela-npm:latest - pull: not_present - secrets: [ npm_password ] - parameters: - username: npmUsername - registry: https://registry.npmjs.org -+ dry_run: true -``` - -Sample of first time publishing package: - -```diff -steps: - - name: npm_publish - image: target/vela-npm:latest - pull: not_present - secrets: [ npm_password ] - parameters: - username: npmUsername - registry: https://registry.npmjs.org -+ first_publish: true -``` - -Sample of publishing with additional dist-tag: - -> **NOTE:** -> -> Tags are used as an alias and cannot be valid semver - -```diff -steps: - - name: npm_publish - image: target/vela-npm:latest - pull: not_present - secrets: [ npm_password ] - parameters: - username: npmUsername - registry: https://registry.npmjs.org -+ tag: beta -``` - -Higher level of tolerance for npm audit: - -```diff -steps: - - name: npm_publish - image: target/vela-npm:latest - pull: not_present - secrets: [ npm_password ] - parameters: - username: npmUsername - registry: https://registry.npmjs.org -+ audit_level: critical -``` - -## Secrets - -> **NOTE:** -> -> Users should refrain from configuring sensitive information in their pipeline in plain text. - -### Internal - -The plugin accepts the following `parameters` for authentication: - -| Parameter | Environment Variable Configuration | -| ---------- | ------------------------------------- | -| `password` | `NPM_PASSWORD`, `PARAMETER_PASSWORD` | -| `username` | `NPM_USERNAME`, `PARAMETER_USERNAME` | -| `registry` | `NPM_REGISTRY`, `PARAMETER_REGISTRY` | -| `email` | `NPM_EMAIL`, `PARAMETER_EMAIL` | - -Users can use [Vela internal secrets](https://go-vela.github.io/docs/tour/secrets/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: npm_publish - image: target/vela-npm:latest - pull: not_present - secrets: [ npm_password ] - parameters: - username: npmUsername - registry: https://registry.npmjs.org -- password: superSecretPassword -``` - - -> This example will add the `secrets` to the `npm_publish` step as environment variables: -> - `NPM_PASSWORD`=value - -### External - - -The plugin accepts the following files for authentication: - -| Parameter | Volume Configuration | -| ---------- | ---------------------------------------------------------------------------------------------------- | -| `password` | `/vela/parameters/npm/password`, `/vela/secrets/npm/password`, `/vela/secrets/managed-auth/password` | -| `username` | `/vela/parameters/npm/username`, `/vela/secrets/npm/username`, `/vela/secrets/managed-auth/username` | -| `registry` | `/vela/parameters/npm/registry`, `/vela/secrets/npm/registry` | -| `email` | `/vela/parameters/npm/email`, `/vela/secrets/npm/email` | - -Users can use [Vela external secrets](https://go-vela.github.io/docs/concepts/pipeline/secrets/origin/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: npm_publish - image: target/vela-npm:latest - pull: not_present - parameters: - registry: https://registry.npmjs.org -- username: npmUsername -- password: superSecretPassword -``` - -## Parameters - -The following parameters are used to configure the image: - -| Name | Description | Required | Default | Environment Variables | -| --------------- | ------------------------------------------------------------------------------------------------------------------ | -------- | ---------------------------- | ---------------------------------------- | -| `username` | username for communication with npm | `true` | `N/A` | `PARAMETER_USERNAME`
`NPM_USERNAME` | -| `password` | password for communication with npm | `false` | `N/A` | `PARAMETER_PASSWORD`
`NPM_PASSWORD` | -| `email` | email for communication with npm | `false` | `N/A` | `PARAMETER_EMAIL`
`NPM_EMAIL` | -| `token` | auth token for communication with npm | `false` | `N/A` | `PARAMETER_TOKEN`
`TOKEN` | -| `registry` | npm instance to communicate with | `false` | `https://registry.npmjs.org` | `PARAMETER_REGISTRY`
`NPM_REGISTRY` | -| `audit_level` | level at which the audit check should fail (valid options: `low`, `moderate`, `high`, `critical`, `none` to skip) | `false` | `none` | `PARAMETER_AUDIT_LEVEL`
`AUDIT_LEVEL` | -| `strict_ssl` | whether or not to do SSL key validation during communication | `false` | `true` | `PARAMETER_STRICT_SSL`
`STRICT_SSL` | -| `always_auth` | force npm to always require authentication | `false` | `false` | `PARAMETER_ALWAYS_AUTH`
`ALWAYS_AUTH` | -| `skip_ping` | whether or not to skip `npm ping` authentication command | `false` | `false` | `PARAMETER_SKIP_PING`
`SKIP_PING` | -| `dry_run` | enables pretending to perform the action | `false` | `false` | `PARAMETER_DRY_RUN`
`DRY_RUN` | -| `tag` | publish package with given alias tag | `false` | `latest` | `PARAMETER_TAG`
`TAG` | -| `log_level` | set the log level for the plugin (valid options: `info`, `debug`, `trace`) | `true` | `info` | `PARAMETER_LOG_LEVEL`
`LOG_LEVEL` | -| `workspaces` | publish all workspaces | `false` | `false` | `PARAMETER_WORKSPACES`
`WORKSPACES` | -| `workspace` | publish a specific workspace by specifying the workspace name or relative path | `false` | `N/A` | `PARAMETER_WORKSPACE`
`WORKSPACE` | -| `access` | Tells the registry whether this package should be published as public or restricted. Only applies to scoped packages, which default to restricted | `false` | `restricted` | `PARAMETER_ACCESS`
`ACCESS` | - -## package.json -This is your module's manifest. There are a few important keys that need to be set in order to publish your module - -* **name** - your package name that will be checked against in the registry -* **version** - your package version that will be used to publish, it must be valid semver and unique to the registry -* **private** - this needs to be set to `false` even if you are publishing it internally. -* **publishConfig** - this should be configured to your registry location and registry parameter should match this value - -For example values, see npm's [documentation](https://docs.npmjs.com/files/package.json) - -## Template - -COMING SOON! - -## Troubleshooting - -Here are the available log levels to assist in troubleshooting: -trace, debug, info, warn, error, fatal, panic diff --git a/versioned_docs/version-0.26/usage/plugins/registry/SCP.md b/versioned_docs/version-0.26/usage/plugins/registry/SCP.md deleted file mode 100644 index b4bce33..0000000 --- a/versioned_docs/version-0.26/usage/plugins/registry/SCP.md +++ /dev/null @@ -1,167 +0,0 @@ -## Description - -This plugin is part of the [OpenSSH](https://www.openssh.com/) suite of plugins which enables you to use the `scp` binary in a Vela pipeline. - -Source Code: https://github.com/go-vela/vela-openssh - -Registry: https://hub.docker.com/r/target/vela-scp - -## Usage - -Because the plugin is a thin wrapper around the [`scp`](https://man.openbsd.org/scp) binary, the syntax and parameters follow from the [OpenSSH manual](https://man.openbsd.org/scp). The plugin will take care of some basic secrets identity management tasks for you, most importantly is that when an identity file is provided as a secret the plugin will place the file into the filesystem and change the permissions to match what the binary expects, and then add it to the list of identity files tried as part of authentication. Additionally, if using a password or passphrase for authentication or for unlocking an identity file, the [`sshpass`](https://linux.die.net/man/1/sshpass) binary will be used to provide those credentials without interactive user input. - -> **NOTE:** -> -> Users should refrain from using latest as the tag for images. -> -> It is recommended to use a semantically versioned tag instead. - -### Basic usage -```yaml -steps: - - name: scp basic usage - image: target/vela-scp:latest - pull: always - parameters: - source: - - ./relative/path/to/file/in/vela/workspace - - a_user_name@some_remote_host_name:/absolute/path/on/remote/system - target: a_different_user@some_other_host:~ -``` - -### Using the `scp://` schema for non-standard ports -```diff -steps: - - name: scp to non-standard port - image: target/vela-scp:latest - pull: always - parameters: - source: - - ./relative/path/to/file/in/vela/workspace - - a_user_name@some_remote_host_name:/absolute/path/on/remote/system -+ target: scp://a_different_user@some_remote_host_name:12345/path -``` - -### Passing additional `scp` flags -```diff -steps: - - name: override default scp flags - image: target/vela-scp:latest - pull: always - parameters: - source: - - ./relative/path/to/folder/in/vela/workspace - target: scp://a_different_user@some_remote_host_name:12345/path -+ scp_flag: -+ - "-r" -+ - "-o StrictHostKeyChecking=yes" -``` - -### Using a password for authentication -```diff -steps: - - name: password for authentication - image: target/vela-scp:latest - pull: always -+ secrets: -+ - source: my_non_user_account_password -+ target: sshpass_password - parameters: - source: - - ./relative/path/to/file/in/vela/workspace - target: scp://a_different_user@some_remote_host_name:12345/path -``` - -### Using an identity file (WITHOUT a passphrase) from an internal secret -```diff -steps: - - name: identity file contents from an internal secret - image: target/vela-scp:latest - pull: always -+ secrets: -+ - source: my_non_user_account_id_rsa_file_contents -+ target: identity_file_contents - parameters: - source: - - ./relative/path/to/file/in/vela/workspace - target: scp://a_different_user@some_remote_host_name:12345/path -``` - -### Using an identity file (WITH a passphrase) from an internal secret -```diff -steps: - - name: identity file contents with passphrase from an internal secret - image: target/vela-scp:latest - pull: always -+ secrets: -+ - source: my_non_user_account_id_rsa_file_contents -+ target: identity_file_contents -+ - source: my_non_user_account_id_rsa_passphrase -+ target: sshpass_passphrase - parameters: - source: - - ./relative/path/to/file/in/vela/workspace - target: scp://a_different_user@some_remote_host_name:12345/path -``` - -### Using an existing identity file from the workspace -```diff -steps: - - name: identity file from the workspace - image: target/vela-scp:latest - pull: always - parameters: - source: - - ./relative/path/to/file/in/vela/workspace - target: scp://a_different_user@some_remote_host_name:12345/path -+ identity_file_path: ./some/workspace/location/id_rsa -``` - -### Using additional secrets in other parameters -```diff -steps: - - name: additional secrets in other parameters - image: target/vela-scp:latest - pull: always -+ secrets: -+ - source: some_secret_user -+ target: secret_user -+ - source: some_secret_host -+ target: secret_host -+ - source: some_secret_port -+ target: secret_port - parameters: - source: - - ./relative/path/to/file/in/vela/workspace -+ target: scp://$SECRET_USER@$SECRET_HOST:$SECRET_PORT/path -``` - -### Using the container without the plugin logic -```diff -steps: - - name: override plugin logic to use scp directly - image: target/vela-scp:latest - pull: always -+ commands: -+ - scp -i ./some/existing/id_rsa ./relative/path/to/file/in/vela/workspace username@hostname:/path/ -``` - -## Parameters & Secrets -> **NOTE:** -> -> The plugin supports reading all parameters via environment variables or files. -> -> Any values set from a file take precedence over values set from the environment. -> -> Don't confuse the source/target syntax of native secrets with the source and target parameters required for the scp binary. - -| Name | Description | Required | Accepts Multiple Values? | Default | Environment Variables | File Paths | -| --- | --- | --- | --- | --- | --- | --- | -| `source` | The source option from the [`scp` manual](https://man.openbsd.org/scp). | :white_check_mark: | :white_check_mark: | | `PARAMETER_SOURCE`
`SOURCE` | `/vela/parameters/vela-scp/source`
`/vela/secrets/vela-scp/source` | -| `target` | The target option from the [`scp` manual](https://man.openbsd.org/scp). | :white_check_mark: | :x: | | `PARAMETER_TARGET`
`TARGET` | `/vela/parameters/vela-scp/target`
`/vela/secrets/vela-scp/target` | -| `identity_file_path` | A path for where the [`scp`](https://man.openbsd.org/scp) binary should look for existing identity files.
These are NOT auto created by the plugin as they must be created and managed by a user and only referenced here. | :x: | :white_check_mark: | | `PARAMETER_IDENTITY_FILE_PATH`
`IDENTITY_FILE_PATH`
`PARAMETER_SSH_KEY_PATH`
`SSH_KEY_PATH` | `/vela/parameters/vela-scp/identity-file.path`
`/vela/secrets/vela-scp/identity-file.path` | -| `identity_file_contents` | The raw contents of an identity file for use with [`scp`](https://man.openbsd.org/scp).
The plugin will take the raw contents and place it in a temporary location in the workspace with the correct permissions and inject it as an identity file to use during execution. | :x: | :x: | | `PARAMETER_IDENTITY_FILE_CONTENTS`
`IDENTITY_FILE_CONTENTS`
`PARAMETER_SSH_KEY`
`SSH_KEY` | `/vela/parameters/vela-scp/identity-file.contents`
`/vela/secrets/vela-scp/identity-file.contents` | -| `scp_flag` | Any additional options from the [`scp` manual](https://man.openbsd.org/scp).
These will override the default options and be placed between the identity file options and the source/target options at the end. | :x: | :white_check_mark: | `-o StrictHostKeyChecking=no`
`-o UserKnownHostsFile=/dev/null` | `PARAMETER_SCP_FLAG`
`SCP_FLAG` | `/vela/parameters/vela-scp/scp.flag`
`/vela/secrets/vela-scp/scp.flag` | -| `sshpass_password` | If any systems require a password for authentication it can be specified here, and the [`sshpass`](https://linux.die.net/man/1/sshpass) binary will be used in conjunction with [`scp`](https://man.openbsd.org/scp). | :x: | :x: | | `PARAMETER_SSHPASS_PASSWORD`
`PARAMETER_PASSWORD`
`SSHPASS_PASSWORD`
`PASSWORD` | `/vela/parameters/vela-scp/sshpass.password`
`/vela/secrets/vela-scp/sshpass.password` | -| `sshpass_passphrase` | If any identity files require a passphrase for authentication it can be specified here, and the [`sshpass`](https://linux.die.net/man/1/sshpass) binary will be used in conjunction with [`scp`](https://man.openbsd.org/scp). | :x: | :x: | | `PARAMETER_SSHPASS_PASSPHRASE`
`SSHPASS_PASSPHRASE` | `/vela/parameters/vela-scp/sshpass.passphrase`
`/vela/secrets/vela-scp/sshpass.passphrase` | -| `sshpass_flag` | Any additional options from the [`sshpass` manual](https://linux.die.net/man/1/sshpass). | :x: | :white_check_mark: | | `PARAMETER_SSHPASS_FLAG`
`SSHPASS_FLAG` | `/vela/parameters/vela-scp/sshpass.flag`
`/vela/secrets/vela-scp/sshpass.flag` | diff --git a/versioned_docs/version-0.26/usage/plugins/registry/SSH.md b/versioned_docs/version-0.26/usage/plugins/registry/SSH.md deleted file mode 100644 index b93af72..0000000 --- a/versioned_docs/version-0.26/usage/plugins/registry/SSH.md +++ /dev/null @@ -1,166 +0,0 @@ -## Description - -This plugin is part of the [OpenSSH](https://www.openssh.com/) suite of plugins which enables you to use the `ssh` binary in a Vela pipeline. - -Source Code: https://github.com/go-vela/vela-openssh - -Registry: https://hub.docker.com/r/target/vela-ssh - -## Usage - -Because the plugin is a thin wrapper around the [`ssh`](https://man.openbsd.org/ssh) binary, the syntax and parameters follow from the [OpenSSH manual](https://man.openbsd.org/ssh). The plugin will take care of some basic secrets identity management tasks for you, most importantly is that when an identity file is provided as a secret the plugin will place the file into the filesystem and change the permissions to match what the binary expects, and then add it to the list of identity files tried as part of authentication. Additionally, if using a password or passphrase for authentication or for unlocking an identity file, the [`sshpass`](https://linux.die.net/man/1/sshpass) binary will be used to provide those credentials without interactive user input. - -> **NOTE:** -> -> Users should refrain from using latest as the tag for images. -> -> It is recommended to use a semantically versioned tag instead. - -### Basic usage with no-auth methods -```yaml -steps: - - name: ssh using no-auth - image: target/vela-ssh:latest - pull: always - parameters: - destination: a_different_user@some_other_host - command: - - echo "Hello Vela!" - - /some/path/to/a/remote/script.sh -``` - -### Using the `ssh://` schema for non-standard ports -```diff -steps: - - name: ssh to non-standard port - image: target/vela-ssh:latest - pull: always - parameters: -+ destination: ssh://a_different_user@some_remote_host_name:12345 - command: - - echo "Hello Vela!" -``` - -### Passing additional `ssh` flags -```diff -steps: - - name: override default ssh flags - image: target/vela-ssh:latest - pull: always - parameters: - destination: ssh://a_different_user@some_remote_host_name:12345 - command: - - echo "Hello Vela!" -+ ssh_flag: -+ - "-o StrictHostKeyChecking=yes" -``` - -### Using a password for authentication -```diff -steps: - - name: password for authentication - image: target/vela-ssh:latest - pull: always -+ secrets: -+ - source: my_non_user_account_password -+ target: sshpass_password - parameters: - destination: ssh://a_different_user@some_remote_host_name:12345 - command: - - echo "Hello Vela!" -``` - -### Using an identity file (WITHOUT a passphrase) from an internal secret -```diff -steps: - - name: identity file contents from an internal secret - image: target/vela-ssh:latest - pull: always -+ secrets: -+ - source: my_non_user_account_id_rsa_file_contents -+ target: identity_file_contents - parameters: - destination: ssh://a_different_user@some_remote_host_name:12345 - command: - - echo "Hello Vela!" -``` - -### Using an identity file (WITH a passphrase) from an internal secret -```diff -steps: - - name: identity file contents with passphrase from an internal secret - image: target/vela-ssh:latest - pull: always -+ secrets: -+ - source: my_non_user_account_id_rsa_file_contents -+ target: identity_file_contents -+ - source: my_non_user_account_id_rsa_passphrase -+ target: sshpass_passphrase - parameters: - destination: ssh://a_different_user@some_remote_host_name:12345 - command: - - echo "Hello Vela!" -``` - -### Using an existing identity file from the workspace -```diff -steps: - - name: identity file from the workspace - image: target/vela-ssh:latest - pull: always - parameters: - destination: ssh://a_different_user@some_remote_host_name:12345 - command: - - echo "Hello Vela!" -+ identity_file_path: ./some/workspace/location/id_rsa -``` - -### Using additional secrets in other parameters -```diff -steps: - - name: additional secrets in other parameters - image: target/vela-ssh:latest - pull: always -+ secrets: -+ - source: some_secret_user -+ target: secret_user -+ - source: some_secret_host -+ target: secret_host -+ - source: some_secret_port -+ target: secret_port - parameters: -+ destination: ssh://$SECRET_USER@$SECRET_HOST:$SECRET_PORT - command: - - echo "Hello Vela!" -``` - -### Using the container without the plugin logic -```diff -steps: - - name: override plugin logic to use ssh directly - image: target/vela-ssh:latest - pull: always - # Note that this ISN'T part of the parameters section. -+ commands: -+ - ssh -i ./some/existing/id_rsa username@hostname some-bin -``` - -## Parameters & Secrets -> **NOTE:** -> -> The plugin supports reading all parameters via environment variables or files. -> -> Any values set from a file take precedence over values set from the environment. -> -> Don't confuse the `commands` parameter in a traditional Vela step with the `command` option required for the ssh binary. - -| Name | Description | Required | Accepts Multiple Values? | Default | Environment Variables | File Paths | -| --- | --- | --- | --- | --- | --- | --- | -| `destination` | The destination option from the [`ssh` manual](https://man.openbsd.org/ssh). | :white_check_mark: | :x: | | `PARAMETER_DESTINATION`
`DESTINATION`
`PARAMETER_HOST` | `/vela/parameters/vela-ssh/destination`
`/vela/secrets/vela-ssh/destination` | -| `command` | The command option from the [`ssh` manual](https://man.openbsd.org/ssh). | :white_check_mark: | :white_check_mark: | | `PARAMETER_COMMAND`
`COMMAND`
`PARAMETER_SCRIPT`
`SCRIPT` | `/vela/parameters/vela-ssh/command`
`/vela/secrets/vela-ssh/command` | -| `identity_file_path` | A path for where the [`ssh`](https://man.openbsd.org/ssh) binary should look for existing identity files.
These are NOT auto created by the plugin as they must be created and managed by a user and only referenced here. | :x: | :white_check_mark: | | `PARAMETER_IDENTITY_FILE_PATH`
`IDENTITY_FILE_PATH`
`PARAMETER_SSH_KEY_PATH`
`SSH_KEY_PATH` | `/vela/parameters/vela-ssh/identity-file.path`
`/vela/secrets/vela-ssh/identity-file.path` | -| `identity_file_contents` | The raw contents of an identity file for use with [`ssh`](https://man.openbsd.org/ssh).
The plugin will take the raw contents and place it in a temporary location in the workspace with the correct permissions and inject it as an identity file to use during execution. | :x: | :x: | | `PARAMETER_IDENTITY_FILE_CONTENTS`
`IDENTITY_FILE_CONTENTS`
`PARAMETER_SSH_KEY`
`SSH_KEY` | `/vela/parameters/vela-ssh/identity-file.contents`
`/vela/secrets/vela-ssh/identity-file.contents` | -| `ssh_flag` | Any additional options from the [`ssh` manual](https://man.openbsd.org/ssh).
These will override the default options and be placed between the identity file options and the destination/command options at the end. | :x: | :white_check_mark: | `-o StrictHostKeyChecking=no`
`-o UserKnownHostsFile=/dev/null` | `PARAMETER_SSH_FLAG`
`SSH_FLAG` | `/vela/parameters/vela-ssh/ssh.flag`
`/vela/secrets/vela-ssh/ssh.flag` | -| `sshpass_password` | If any systems require a password for authentication it can be specified here, and the [`sshpass`](https://linux.die.net/man/1/sshpass) binary will be used in conjunction with [`ssh`](https://man.openbsd.org/ssh). | :x: | :x: | | `PARAMETER_SSHPASS_PASSWORD`
`PARAMETER_PASSWORD`
`SSHPASS_PASSWORD`
`PASSWORD` | `/vela/parameters/vela-ssh/sshpass.password`
`/vela/secrets/vela-ssh/sshpass.password` | -| `sshpass_passphrase` | If any identity files require a passphrase for authentication it can be specified here, and the [`sshpass`](https://linux.die.net/man/1/sshpass) binary will be used in conjunction with [`ssh`](https://man.openbsd.org/ssh). | :x: | :x: | | `PARAMETER_SSHPASS_PASSPHRASE`
`SSHPASS_PASSPHRASE` | `/vela/parameters/vela-ssh/sshpass.passphrase`
`/vela/secrets/vela-ssh/sshpass.passphrase` | -| `sshpass_flag` | Any additional options from the [`sshpass` manual](https://linux.die.net/man/1/sshpass). | :x: | :white_check_mark: | | `PARAMETER_SSHPASS_FLAG`
`SSHPASS_FLAG` | `/vela/parameters/vela-ssh/sshpass.flag`
`/vela/secrets/vela-ssh/sshpass.flag` | diff --git a/versioned_docs/version-0.26/usage/plugins/registry/Slack.md b/versioned_docs/version-0.26/usage/plugins/registry/Slack.md deleted file mode 100644 index 375d3e7..0000000 --- a/versioned_docs/version-0.26/usage/plugins/registry/Slack.md +++ /dev/null @@ -1,195 +0,0 @@ -## Description - -This plugin enables you to send data to a [Slack](https://slack.com/) channel. - -Source Code: https://github.com/go-vela/vela-slack - -Registry: https://hub.docker.com/r/target/vela-slack - -## Usage - -> **NOTE:** -> -> Users should refrain from using latest as the tag for the Docker image. -> -> It is recommended to use a semantically versioned tag instead. - -Sample of sending a message: - -```yaml -steps: - - name: message - image: target/vela-slack:latest - pull: always - parameters: - text: "Hello World!" -``` - -Sample of sending a message with formatting: - -```diff -steps: - - name: message-with-formatting - image: target/vela-slack:latest - pull: not_present - parameters: -- text: "Hello World!" -+ text: "Hello Repo {{ .RepositoryName }}!" -``` - -Sample of sending a message with local attachment file: - -```diff -steps: - - name: message-with-attachment - image: target/vela-slack:latest - secrets: [ webhook ] - parameters: -- text: "Hello World!" - filepath: slack_attachment.json - remote: false -``` - -Sample of sending a message with remote attachment file: - -```diff -steps: - - name: message-with-remote-attachment - image: target/vela-slack:latest - secrets: [ webhook ] - parameters: -- text: "Hello World!" - filepath: slack_attachment.json - remote: true - registry: https://github.com -``` - -content of `slack_attachment.json`: - -```json -{ - "attachments": [ - { - "fallback": "Required plain-text summary of the attachment.", - "color": "#36a64f", - "pretext": "Optional text that appears above the attachment block", - "author_name": "Bobby Tables", - "author_link": "http://flickr.com/bobby/", - "author_icon": "http://flickr.com/icons/bobby.jpg", - "title": "Slack API Documentation", - "title_link": "https://api.slack.com/", - "text": "Build: {{ .BuildNumber }}", - "fields": [ - { - "title": "Priority", - "value": "High", - "short": false - } - ], - "image_url": "http://my-website.com/path/to/image.jpg", - "thumb_url": "http://example.com/path/to/thumb.png", - "footer": "Slack API", - "footer_icon": "https://platform.slack-edge.com/img/default_application_icon.png", - "ts": 123456789 - } - ] -} -``` - -> **NOTE:** -> -> To use any variables within `attachments` the file must be saved in the attachment format and be a JSON file. -> -> The configuration below is pulled almost directly from the Slack [Message Builder](https://api.slack.com/docs/messages/builder) attachments example. - -## Secrets - -> **NOTE:** Users should refrain from configuring sensitive information in your pipeline in plain text. - -### Internal - -The plugin accepts the following `parameters` for authentication: - -| Parameter | Environment Variable Configuration | -| --------- | ------------------------------------ | -| `webhook` | `PARAMETER_WEBHOOK`, `SLACK_WEBHOOK` | - -Users can use [Vela internal secrets](https://go-vela.github.io/docs/tour/secrets/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: message - image: target/vela-slack:latest - pull: always -+ secrets: [ slack_webhook ] - parameters: - text: "Hello World!" -- webhook: http://slack.example.com -``` - -> This example will add the secret to the `message` step as environment variables: -> -> * `SLACK_WEBHOOK=` - -### External - -The plugin accepts the following files for authentication: - -| Parameter | Volume Configuration | -| --------- | --------------------------------------------------------------- | -| `webhook` | `/vela/parameters/slack/webhook`, `/vela/secrets/slack/webhook` | - -Users can use [Vela external secrets](https://go-vela.github.io/docs/concepts/pipeline/secrets/origin/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: message - image: target/vela-slack:latest - pull: always - parameters: - text: "Hello World!" -- webhook: http://slack.example.com -``` - -> This example will read the secret value in the volume stored at `/vela/secrets/` - -## Parameters - -> **NOTE:** -> -> The plugin supports reading all parameters via environment variables or files. -> -> Any values set from a file take precedence over values set from the environment. - -The following parameters are used to configure the image: - -| Name | Description | Required | Default | Environment Variables | -| ------------ | ------------------------------------ | -------- | ------- | -------------------------------------------- | -| `channel` | Slack channel to send data to | `false` | `N/A` | `PARAMETER_CHANNEL`
`SLACK_CHANNEL` | -| `filepath` | file path to attachment JSON file | `false` | `N/A` | `PARAMETER_FILEPATH`
`SLACK_FILEPATH` | -| `icon_emoji` | Slack emoji to use for the icon | `false` | `N/A` | `PARAMETER_ICON_EMOJI`
`SLACK_ICON_EMOJI` | -| `icon_url` | Slack emoji URL to use for the icon | `false` | `N/A` | `PARAMETER_ICON_URL`
`SLACK_ICON_URL` | -| `log_level` | set the log level for the plugin | `true` | `info` | `PARAMETER_LOG_LEVEL`
`SLACK_LOG_LEVEL` | -| `text` | top level text to display in message | `false` | `N/A` | `PARAMETER_TEXT`
`SLACK_TEXT` | -| `thread_ts` | timestamp of the thread post | `false` | `N/A` | `PARAMETER_THREAD_TS`
`SLACK_THREAD_TS` | -| `webhook` | Slack webhook url to send data to | `true` | `N/A` | `PARAMETER_WEBHOOK`
`SLACK_WEBHOOK` | - -## Template - -COMING SOON! - -## Troubleshooting - -You can start troubleshooting this plugin by tuning the level of logs being displayed: - -```diff -steps: - - name: message - image: target/vela-slack:latest - pull: always - parameters: -+ log_level: trace - text: "Hello World!" -``` - -Below are a list of common problems and how to solve them: diff --git a/versioned_docs/version-0.26/usage/plugins/registry/Terraform.md b/versioned_docs/version-0.26/usage/plugins/registry/Terraform.md deleted file mode 100644 index 487d9e4..0000000 --- a/versioned_docs/version-0.26/usage/plugins/registry/Terraform.md +++ /dev/null @@ -1,321 +0,0 @@ -## Description - -This plugin enables you to run [Terraform](https://www.terraform.io/) against [providers](https://www.terraform.io/docs/providers/index.html) in a Vela pipeline. - -Source Code: https://github.com/go-vela/vela-terraform - -Registry: https://hub.docker.com/r/target/vela-terraform - -## Usage - -> **NOTE:** -> -> Users should refrain from using latest as the tag for the Docker image. -> -> It is recommended to use a semantically versioned tag instead. - -Sample of adding installing terraform version: - -```yaml -steps: - - name: apply - image: target/vela-terraform:latest - pull: always - parameters: - action: apply - auto_approve: true # Required for versions of Terraform 0.12.x - version: 0.11.7 -``` - -Sample of adding init options to Terraform configuration: - -```yaml -steps: - - name: apply - image: target/vela-terraform:latest - pull: always - parameters: - action: apply - auto_approve: true # Required for versions of Terraform 0.12.x - init_options: - get_plugins: true -``` - -Sample of applying Terraform configuration: - -```yaml -steps: - - name: apply - image: target/vela-terraform:latest - pull: always - parameters: - action: apply - auto_approve: true # Required for versions of Terraform 0.12.x -``` - -Sample of destroying Terraform configuration: - -```yaml -steps: - - name: destroy - image: target/vela-terraform:latest - pull: always - parameters: - action: destroy - auto_approve: true # Required for versions of Terraform 0.12.x -``` - -Sample of formatting Terraform configuration files: - -```yaml -steps: - - name: fmt - image: target/vela-terraform:latest - pull: always - parameters: - action: fmt -``` - -Sample of planning Terraform configuration: - -```yaml -steps: - - name: plan - image: target/vela-terraform:latest - pull: always - parameters: - action: plan -``` - -Sample of validating Terraform configuration: - -```yaml -steps: - - name: validate - image: target/vela-terraform:latest - pull: always - parameters: - action: validate -``` - -## Secrets - -> **NOTE:** Users should refrain from configuring sensitive information in your pipeline in plain text. - -### Internal - -Users can use [Vela internal secrets](https://go-vela.github.io/docs/tour/secrets/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: apply - image: target/vela-terraform:latest - pull: always -+ secrets: [ terraform_username, terraform_password ] - parameters: - action: apply - auto_approve: true # Required for versions of Terraform 0.12.x -- username: octocat -- password: superSecretPassword -``` - -> This example will add the secrets to the `apply` step as environment variables: -> -> * `TERRAFORM_USERNAME=` -> * `TERRAFORM_PASSWORD=` - -### External - -The plugin accepts the following files for authentication: - -| Parameter | Volume Configuration | -| ---------- | ------------------------------------------------------------------------- | -| `password` | `/vela/parameters/terraform/password`, `/vela/secrets/terraform/password` | -| `username` | `/vela/parameters/terraform/username`, `/vela/secrets/terraform/username` | - -Users can use [Vela external secrets](https://go-vela.github.io/docs/tour/secrets/) to substitute these sensitive values at runtime: - -```diff -steps: - - name: apply - image: target/vela-terraform:latest - pull: always - parameters: - action: apply - auto_approve: true # Required for versions of Terraform 0.12.x -- username: octocat -- password: superSecretPassword -``` - -> This example will read the secret values in the volume stored at `/vela/secrets/` - -## Parameters - -> **NOTE:** -> -> The plugin supports reading all parameters via environment variables or files. -> -> Any values set from a file take precedence over values set from the environment. -> -> Terraform commands will be invoked in the current directory by default. - -The following parameters are used to configure the image: - -| Name | Description | Required | Default | Environment Variables | -| -------------- | ------------------------------------------- | -------- | --------------- | --------------------------------------------------------------------- | -| `action` | action to perform with Terraform | `true` | `N/A` | `PARAMETER_ACTION`
`TERRAFORM_ACTION` | -| `init_options` | options to use for Terraform init operation | `false` | `N/A` | `PARAMETER_INIT_OPTIONS`
`TERRAFORM_INIT_OPTIONS` | -| `log_level` | set the log level for the plugin | `true` | `info` | `PARAMETER_LOG_LEVEL`
`TERRAFORM_LOG_LEVEL` | -| `machine` | netrc machine name to communicate with | `true` | `github.com` | `PARAMETER_MACHINE`
`TERRAFORM_MACHINE`
`VELA_NETRC_MACHINE` | -| `password` | netrc password for authentication | `true` | **set by Vela** | `PARAMETER_PASSWORD`
`TERRAFORM_PASSWORD`
`VELA_NETRC_PASSWORD` | -| `username` | netrc user name for authentication | `true` | **set by Vela** | `PARAMETER_USERNAME`
`TERRAFORM_USERNAME`
`VELA_NETRC_USERNAME` | -| `version` | set the Terraform CLI version | `true` | `1.2.7` | `PARAMETER_VERSION`
`TERRAFORM_VERSION` | - -The following parameters can be used within the `init_options` to configure the image: - -| Name | Description | Required | Default | -| ----------------- | ------------------------------------------------------------------------------------- | -------- | ------- | -| `backend` | configure the backend for this configuration | `true` | `N/A` | -| `backend_configs` | this is merged with what is in the configuration file | `true` | `N/A` | -| `force_copy` | suppress prompts about copying state data | `true` | `N/A` | -| `from_module` | copy the contents of the given module into the target directory before initialization | `true` | `N/A` | -| `get` | download any modules for this configuration | `true` | `N/A` | -| `get_plugins` | download any missing plugins for this configuration | `true` | `N/A` | -| `input` | ask for input for variables if not directly set | `true` | `N/A` | -| `lock` | lock the state file when locking is supported | `false` | `N/A` | -| `lock_timeout` | duration to retry a state lock | `false` | `N/A` | -| `no_color` | disables colors in output | `false` | `N/A` | -| `plugin_dirs` | directory containing plugin binaries; overrides all default search paths for plugins | `false` | `N/A` | -| `reconfigure` | reconfigure the backend, ignoring any saved configuration | `false` | `N/A` | -| `upgrade` | install the latest version allowed within configured constraints | `false` | `N/A` | -| `verify_plugins` | verify the authenticity and integrity of automatically downloaded plugins | `false` | `N/A` | - -#### Apply - -The following parameters are used to configure the `apply` action: - -_Command uses Terraform CLI command defaults if not overridden in config._ - -| Name | Description | Required | Default | Environment Variables | -| -------------- | ------------------------------------------------------------- | -------- | ------- | ---------------------------------------------------- | -| `auto_approve` | skip interactive approval of applying resources | `false` | `false` | `PARAMETER_AUTO_APPROVE`
`TERRAFORM_AUTO_APPROVE` | -| `backup` | path to backup the existing state file | `false` | `N/A` | `PARAMETER_BACKUP`
`TERRAFORM_BACKUP` | -| `directory` | the directory containing Terraform files to apply | `false` | `.` | `PARAMETER_DIRECTORY`
`TERRAFORM_DIRECTORY` | -| `lock` | lock the state file when locking is supported | `false` | `false` | `PARAMETER_LOCK`
`TERRAFORM_LOCK` | -| `lock_timeout` | duration to retry a state lock | `false` | `N/A` | `PARAMETER_LOCK_TIMEOUT`
`TERRAFORM_LOCK_TIMEOUT` | -| `no_color` | disables colors in output | `false` | `false` | `PARAMETER_NO_COLOR`
`TERRAFORM_NO_COLOR` | -| `parallelism` | number of concurrent operations as Terraform walks its graph | `false` | `N/A` | `PARAMETER_PARALLELISM`
`TERRAFORM_PARALLELISM` | -| `refresh` | update state prior to checking for differences | `false` | `false` | `PARAMETER_REFRESH`
`TERRAFORM_REFRESH` | -| `state` | path to read and save state | `false` | `N/A` | `PARAMETER_STATE`
`TERRAFORM_STATE` | -| `state_out` | path to write updated state file | `false` | `N/A` | `PARAMETER_STATE_OUT`
`TERRAFORM_STATE_OUT` | -| `target` | resource to target | `false` | `N/A` | `PARAMETER_TARGET`
`TERRAFORM_TARGET` | -| `vars` | a map of variables to pass to the Terraform (`=`) | `false` | `N/A` | `PARAMETER_VARS`
`TERRAFORM_VARS` | -| `var_files` | a list of var files to use | `false` | `N/A` | `PARAMETER_VAR_FILES`
`TERRAFORM_VAR_FILES` | - -#### Destroy - -The following parameters are used to configure the `destroy` action: - -_Command uses Terraform CLI command defaults if not overridden in config._ - -| Name | Description | Required | Default | Environment Variables | -| -------------- | ------------------------------------------------------------- | -------- | ------- | ---------------------------------------------------- | -| `auto_approve` | skip interactive approval of destroying resources | `false` | `false` | `PARAMETER_AUTO_APPROVE`
`TERRAFORM_AUTO_APPROVE` | -| `backup` | path to backup the existing state file | `false` | `N/A` | `PARAMETER_BACKUP`
`TERRAFORM_BACKUP` | -| `directory` | the directory containing Terraform files to destroy | `false` | `.` | `PARAMETER_DIRECTORY`
`TERRAFORM_DIRECTORY` | -| `lock` | lock the state file when locking is supported | `false` | `false` | `PARAMETER_LOCK`
`TERRAFORM_LOCK` | -| `lock_timeout` | duration to retry a state lock | `false` | `N/A` | `PARAMETER_LOCK_TIMEOUT`
`TERRAFORM_LOCK_TIMEOUT` | -| `no_color` | disables colors in output | `false` | `false` | `PARAMETER_NO_COLOR`
`TERRAFORM_NO_COLOR` | -| `parallelism` | number of concurrent operations as Terraform walks its graph | `false` | `N/A` | `PARAMETER_PARALLELISM`
`TERRAFORM_PARALLELISM` | -| `refresh` | update state prior to checking for differences | `false` | `false` | `PARAMETER_REFRESH`
`TERRAFORM_REFRESH` | -| `state` | path to read and save state | `false` | `N/A` | `PARAMETER_STATE`
`TERRAFORM_STATE` | -| `state_out` | path to write updated state file | `false` | `N/A` | `PARAMETER_STATE_OUT`
`TERRAFORM_STATE_OUT` | -| `target` | resource to target | `false` | `N/A` | `PARAMETER_TARGET`
`TERRAFORM_TARGET` | -| `vars` | a map of variables to pass to the Terraform (`=`) | `false` | `N/A` | `PARAMETER_VARS`
`TERRAFORM_VARS` | -| `var_files` | a list of var files to use | `false` | `N/A` | `PARAMETER_VAR_FILES`
`TERRAFORM_VAR_FILES` | - -#### Format - -The following parameters are used to configure the `fmt` action: - -_Command uses Terraform CLI command defaults if not overridden in config._ - -| Name | Description | Required | Default | Environment Variables | -| ----------- | -------------------------------------------------- | -------- | ------- | ---------------------------------------------- | -| `check` | validate if the input is formatted | `false` | `false` | `PARAMETER_CHECK`
`TERRAFORM_CHECK` | -| `diff` | diffs of formatting changes | `false` | `false` | `PARAMETER_DIFF`
`TERRAFORM_DIFF` | -| `directory` | the directory containing Terraform files to format | `false` | `.` | `PARAMETER_DIRECTORY`
`TERRAFORM_DIRECTORY` | -| `list` | list files whose formatting differs | `false` | `false` | `PARAMETER_LIST`
`TERRAFORM_LIST` | -| `write` | write result to source file instead of STDOUT | `false` | `false` | `PARAMETER_WRITE`
`TERRAFORM_WRITE` | - -#### Plan - -The following parameters are used to configure the `plan` action: - -_Command uses Terraform CLI command defaults if not overridden in config._ - -| Name | Description | Required | Default | Environment Variables | -| -------------------- | ------------------------------------------------------------------ | -------- | ------- | ---------------------------------------------------------------- | -| `destroy` | destroy all resources managed by the given configuration and state | `false` | `false` | `PARAMETER_DESTROY`
`TERRAFORM_DESTROY` | -| `detailed_exit_code` | return detailed exit codes when the command exits | `false` | `false` | `PARAMETER_DETAILED_EXIT_CODE`
`TERRAFORM_DETAILED_EXIT_CODE` | -| `directory` | the directory containing Terraform files to plan | `false` | `.` | `PARAMETER_DIRECTORY`
`TERRAFORM_DIRECTORY` | -| `input` | ask for input for variables if not directly set | `false` | `false` | `PARAMETER_INPUT`
`TERRAFORM_INPUT` | -| `lock` | lock the state file when locking is supported | `false` | `false` | `PARAMETER_LOCK`
`TERRAFORM_LOCK` | -| `lock_timeout` | duration to retry a state lock | `false` | `N/A` | `PARAMETER_LOCK_TIMEOUT`
`TERRAFORM_LOCK_TIMEOUT` | -| `module_depth` | specifies the depth of modules to show in the output | `false` | `N/A` | `PARAMETER_MODULE_DEPTH`
`TERRAFORM_MODULE_DEPTH` | -| `no_color` | disables colors in output | `false` | `false` | `PARAMETER_NO_COLOR`
`TERRAFORM_NO_COLOR` | -| `parallelism` | number of concurrent operations as Terraform walks its graph | `false` | `N/A` | `PARAMETER_PARALLELISM`
`TERRAFORM_PARALLELISM` | -| `refresh` | update state prior to checking for differences | `false` | `false` | `PARAMETER_REFRESH`
`TERRAFORM_REFRESH` | -| `state` | path to read and save state | `false` | `N/A` | `PARAMETER_STATE`
`TERRAFORM_STATE` | -| `target` | resource to target | `false` | `N/A` | `PARAMETER_TARGET`
`TERRAFORM_TARGET` | -| `vars` | a map of variables to pass to the Terraform (`=`) | `false` | `N/A` | `PARAMETER_VARS`
`TERRAFORM_VARS` | -| `var_files` | a list of var files to use | `false` | `N/A` | `PARAMETER_VAR_FILES`
`TERRAFORM_VAR_FILES` | - -#### Validate - -The following parameters are used to configure the `validate` action: - -_Command uses Terraform CLI command defaults if not overridden in config._ - -| Name | Description | Required | Default | Environment Variables | -| ----------------- | --------------------------------------------------------------------- | -------- | ------- | ---------------------------------------------------------- | -| `check_variables` | command will check whether all required variables have been specified | `false` | `false` | `PARAMETER_CHECK_VARIABLES`
`TERRAFORM_CHECK_VARIABLES` | -| `directory` | the directory containing Terraform files to validate | `false` | `.` | `PARAMETER_DIRECTORY`
`TERRAFORM_DIRECTORY` | -| `no_color` | disables colors in output | `false` | `false` | `PARAMETER_NO_COLOR`
`TERRAFORM_NO_COLOR` | -| `vars` | a map of variables to pass to the Terraform (`=`) | `false` | `N/A` | `PARAMETER_VARS`
`TERRAFORM_VARS` | -| `var_files` | a list of var files to use | `false` | `N/A` | `PARAMETER_VAR_FILES`
`TERRAFORM_VAR_FILES` | - -## Template - -COMING SOON! - -## Troubleshooting - -You can start troubleshooting this plugin by tuning the level of logs being displayed: - -```diff -steps: - - name: apply - image: target/vela-terraform:latest - pull: always - parameters: - action: apply - auto_approve: true -+ log_level: trace -``` - -You can also instruct the Terraform CLI to output verbose logging: - -```diff -steps: - - name: apply - image: target/vela-terraform:latest - pull: always -+ environment: -+ TF_LOG: TRACE - parameters: - action: apply - auto_approve: true -``` - -Below are a list of common problems and how to solve them: diff --git a/versioned_docs/version-0.26/usage/plugins/registry/_category_.json b/versioned_docs/version-0.26/usage/plugins/registry/_category_.json deleted file mode 100644 index e08149d..0000000 --- a/versioned_docs/version-0.26/usage/plugins/registry/_category_.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "label": "Registry", - "position": 1, - "link": { - "type": "generated-index", - "description": "A Vela cluster is deployed as a self-hosted solution and consists of two core services, the server and the worker. The relationship between these services is considered many-to-many meaning many workers can connect to many servers. - -The server is considered the brains of the application while the worker is considered the brawn of the application. - -An optional third service, the UI, can also be deployed but is not required for the Vela platform to operate as intended. This service provides a means for utilizing and interacting with the Vela platform." - } -} diff --git a/versioned_docs/version-0.26/usage/plugins/registry/captains_log.md b/versioned_docs/version-0.26/usage/plugins/registry/captains_log.md deleted file mode 100644 index 4a11c25..0000000 --- a/versioned_docs/version-0.26/usage/plugins/registry/captains_log.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: "Captain's Log" ---- - -## Overview - -The [Captain's Log](https://github.com/target/captains-log) plugin enables the ability to manage release logs through slack in a Vela pipeline. - -Source Code: https://github.com/target/captains-log - -Registry: https://hub.docker.com/r/target/captains-log - -## Usage - -Basic Usage - -```yaml -steps: - - name: captains-log - image: target/captains-log:1 - pull: always - secrets: [GITHUB_TOKEN, SLACK_URL] - parameters: - github_owner: target - github_repo: captains-log - github_tag_id: "v([0-9]+-release)$" - enterprise_host: https://git.myteam.com - jira_team_domain: myteamnamespace -``` - -Utilize "teams" organization: - -```yaml -steps: - - name: captains-log - image: target/captains-log:1 - pull: always - secrets: [GITHUB_TOKEN, SLACK_URL] - parameters: - github_owner: target - github_repo: captains-log - github_tag_id: "v([0-9]+-release)$" - enterprise_host: https://git.myteam.com - jira_team_domain: myteamnamespace - teams: - - name: Team1 - color: "#FFDC18" - emoji: "✨" - mentions: "<@person1> <@person2>" - issueTracking: - jira: - projects: - - TEAM1 - - TEAM1SUBGROUP - - name: Team2 - color: "#F48642" - emoji: "🔥" - mentions: "<@person3>" - issueTracking: - jira: - projects: - - TEAM2 -``` - -## Secrets - -:::warning -Users should refrain from configuring sensitive information in their pipeline in plain text. -::: - -The plugin accepts the following `parameters` for authentication: - -| Parameter | Environment Variable Configuration | -| -------------- | ---------------------------------- | -| `github_token` | `GITHUB_TOKEN` | -| `slack_token` | `SLACK_URL` | -| `slack_url` | `SLACK_TOKEN` | - -Users can use [Vela secrets](/docs/usage/tour/secrets.md) to substitute these sensitive values at runtime: - -```diff -steps: - - name: captains-log - image: target/captains-log:1 - pull: always -+ secrets: [ github_token, slack_url ] - parameters: - github_owner: target - github_repo: captains-log - github_tag_id: "v([0-9]+-release)$" - enterprise_host: https://git.myteam.com - jira_team_domain: myteamnamespace -- github_token: superSecretToken -- slack_url: https://hooks.slack.com/services/super/secret/url -``` - -:::info -This example will add the `secrets` to the `captains-log` step as environment variables: - -- `GITHUB_TOKEN`=`` -- `SLACK_URL`=`` -::: - - diff --git a/versioned_docs/version-0.26/usage/plugins/tutorials/_category_.json b/versioned_docs/version-0.26/usage/plugins/tutorials/_category_.json deleted file mode 100644 index e832f79..0000000 --- a/versioned_docs/version-0.26/usage/plugins/tutorials/_category_.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "label": "Tutorials", - "position": 2, - "link": { - "type": "generated-index", - "description": "A Vela cluster is deployed as a self-hosted solution and consists of two core services, the server and the worker. The relationship between these services is considered many-to-many meaning many workers can connect to many servers. - -The server is considered the brains of the application while the worker is considered the brawn of the application. - -An optional third service, the UI, can also be deployed but is not required for the Vela platform to operate as intended. This service provides a means for utilizing and interacting with the Vela platform." - } -} diff --git a/versioned_docs/version-0.26/usage/plugins/tutorials/bash.md b/versioned_docs/version-0.26/usage/plugins/tutorials/bash.md deleted file mode 100644 index 6bb6bdb..0000000 --- a/versioned_docs/version-0.26/usage/plugins/tutorials/bash.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: "Bash" -sidebar_position: 1 ---- - -:::warning -We recommend reviewing [Docker's best practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/) before attempting to create a custom plugin. - -We recommend that all plugins be placed inside a [scratch image](https://hub.docker.com/_/scratch). -::: - -## Overview - -From [Bash documentation](https://www.gnu.org/software/bash/): - -> Bash is the GNU Project's shell. Bash is the Bourne Again SHell. Bash is an sh-compatible shell that incorporates useful features from the Korn shell (ksh) and C shell (csh). -> -> It is intended to conform to the IEEE POSIX P1003.2/ISO 9945.2 Shell and Tools standard. It offers functional improvements over sh for both programming and interactive use. In addition, most sh scripts can be run by Bash without modification. - -## Code - -To create a plugin using Bash, we'll need to first decide what task we want this plugin to accomplish. - -For this example, we're going to create a script that runs a `curl` command from the provided input: - -```sh -#!/usr/bin/env bash - -# import method parameter from environment -method=${PARAMETER_METHOD} -# import body parameter from environment -body=${PARAMETER_BODY} -# import url parameter from environment -url=${PARAMETER_URL} - -# send curl request from provided input -curl \ - -X "${method}" \ - -d "${body}" \ - "${url}" -``` - -:::tip -An example of this code is provided in the [bash section](https://github.com/go-vela/vela-tutorials/tree/main/plugins/bash) of the [go-vela/vela-tutorials](https://github.com/go-vela/vela-tutorials/tree/main/plugins) repository. -::: - -## Image - -Once we have the executable needed to accomplish our plugin's task, we need to create a Dockerfile to produce an image. - -This image should contain the script and be setup to run that script when the plugin is executed: - -```docker -FROM alpine - -RUN apk add --update --no-cache bash ca-certificates curl - -COPY vela-sample.sh /bin/vela-sample.sh - -ENTRYPOINT ["bash", "/bin/vela-sample.sh"] -``` - -:::tip -An example of this image is provided in the [target/vela-sample](https://hub.docker.com/r/target/vela-sample) Docker repository. -::: - -## Publishing - -In order to run the plugin in a pipeline, we'll need to make sure we build and publish it to a Docker registry: - -```sh -# build the image -docker build -t target/vela-sample:bash . - -# publish the image -docker push target/vela-sample:bash -``` - -:::info -This has the added benefit of enabling others in the community to consume your plugin! -::: - -## Troubleshooting - -To verify that the plugin performs the desired task, it can be executed locally via the command line: - -```sh -docker run --rm \ - -e PARAMETER_BODY="This is a sample Vela plugin written with Bash" \ - -e PARAMETER_METHOD="POST" \ - -e PARAMETER_URL="http://vela.localhost.com" \ - target/vela-sample:bash -``` - -## Usage - -After publishing the image to a Docker registry, it can be referenced in a pipeline: - -```yaml -version: "1" - -steps: - - name: sample bash plugin - image: target/vela-sample:bash - pull: always - parameters: - url: http://vela.localhost.com - method: POST - body: | - This is a sample Vela plugin written with Bash -``` \ No newline at end of file diff --git a/versioned_docs/version-0.26/usage/pull_policies.md b/versioned_docs/version-0.26/usage/pull_policies.md deleted file mode 100644 index 1e334ac..0000000 --- a/versioned_docs/version-0.26/usage/pull_policies.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: "Pull Policies" -toc: true -description: > - Learn how to control pulling images in your pipeline. ---- - -Vela provides the ability to define how and when the images for secrets, steps, and services will be retrieved at runtime. - -## Usage - -Below are the options for pull policies for container images - -| Policy | Description | -|--------------- |-----------------------------------------------------------------| -| `always` | Always attempt to pull image from registry, even if it exists locally. Best used when leveraging a mutable tag, such as `latest` | -| `not_present` | Only attempt to pull image from registry if it does not already exist locally. This is the default behavior and is recommended for immutably tagged images. | -| `on_start` | Pull image from registry right before the step is to be executed. Can speed up build times if the step or service does not run on every build (e.g. failed build notifying plugins), can be leveraged when dealing with password rotation mid-build (e.g. Vault plugin), or can be used to pull an image that was created and published earlier in the build. | -| `never` | Only use images that exist locally. | - -:::note -The `pull` declaration is **not required**. - -If you do not provide the `pull` declaration, a default value of `not_present` will be used. -::: - -## Example - -```diff -version: "1" -services: - - name: redis - image: redis:latest -+ pull: always - -steps: - - name: check status - image: alpine:latest -+ pull: not_present - commands: - # you can use bash commands in-line to set or override variables - - export EXAMPLE="Hello World From Vela Team" - - echo ${EXAMPLE} - -secrets: - - origin: - name: private vault - image: target/secret-vault:latest -+ pull: on_start - secrets: [ vault_token ] - parameters: - addr: vault.example.com - auth_method: token - username: octocat - items: - - source: secret/docker - path: docker -``` - -:::note -This pipeline will: - -* always attempt to pull the `redis:latest` image, even if it exists locally -* only pull the `alpine:latest` image if it doesn't already exist locally -* wait to pull the `target/secret-vault:latest` image until right before starting the container -::: - -## References - -The following [pipeline concepts](/docs/usage/tour/tour.md) are being used in the pipeline below: - -* [Services](docs/usage/tour/services.md) - * [Pull](docs/usage/tour/image.md) -* [Steps](docs/usage/tour/steps.md) - * [Pull](docs/usage/tour/image.md) -* [Secrets](docs/usage/tour/secrets.md) - * [Origin](docs/usage/tour/secrets.md) - -* [`Pull` YAML Key](/reference/yaml/steps/#the-pull-key) - diff --git a/versioned_docs/version-0.26/usage/quickstart.md b/versioned_docs/version-0.26/usage/quickstart.md deleted file mode 100644 index 9d82d3e..0000000 --- a/versioned_docs/version-0.26/usage/quickstart.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Quickstart - -## Step 1 - Enable a Repo - -:::warning -You will need **Admin** access to the repo to be able to activate it in Vela. This is because you need **Admin** access to be able to add webhooks -to the repo. -::: - -For this example, we'll go over using the UI to add the repo. You can always head over to the [CLI docs](/docs/reference/cli/repo/add.md) for docs on how to add a repo via CLI. - -1. Log into your Vela instance. -1. Click "Add Repositories". -1. Select the Org from the available list. -1. Click "Add" next to the repo you would like to add. - 1. Alternatively you can "Add All" repos in an org. - 1. If your repo doesn't exist, try clicking "Refresh List" in the top right. - -Your repo now has the necessary web hook to Vela. - -:::info -If you're coming from another CI platform you can set a starting build number by updating the counter field on the repo via the UI, [CLI](/docs/reference/cli/repo/repo.md), or [API](/docs/reference/api/repo/repo.md). -::: - -## Step 2 - Build a Pipeline - -A steps pipeline is designed to run a sequential set of tasks.These pipelines do not have a minimum defined length and steps will always execute in the order defined. - -In this pipeline each step is shown with the minimum required YAML keys to execute a step. Both steps are pulling a [Alpine Linux](https://alpinelinux.org/) image from [Docker Hub](https://hub.docker.com/) and executing echo statements. - -```yaml -version: "1" - -# In this pipeline, commands are executed inside the container as the Entrypoint. -# If any command returns a non-zero exit code, the pipeline fails and exits. -steps: - - - name: Greeting - image: alpine - commands: - - echo "Hello, World" - - - name: Welcome - image: alpine - commands: - - echo "Welcome to the Vela docs" -``` -**See it in action with examples!** - -* [Go](/docs/usage/examples/go_modules.md) -* [Rust](/docs/usage/examples/rust_cargo.md) -* [Gradle](/docs/usage/examples/java_gradle.md) -* [Maven](/docs/usage/examples/java_maven.md) -* [Node](/docs/usage/examples/node.md) - -## Step 3 - Customize the Pipeline with Rulesets - -The ruleset allows you to provide conditions to limit the execution of the container. - -When you push your code to a source control management system a payload is sent to Vela. - -Within that payload contains characteristics about what just happened. Maybe it was a push to the main branch, feature branch or tag on any specific commit. - -The ruleset key gives you the ability to add conditions on the step to tell Vela when this step should be executed. - -```yaml -- name: Welcome - # This ruleset would scope the step to only executing - # under the conditions a push to the main branch occurred - ruleset: - event: push - branch: main - image: alpine - commands: - - echo "Welcome to the Vela docs" -``` - -```yaml -- name: Welcome - # This ruleset would scope the step to never executing - # under the conditions a push to the main branch occurred - ruleset: - unless: - event: push - branch: main - image: alpine - commands: - - echo "Welcome to the Vela docs" -``` -## Step 4 - Select Your Plugins - -A plugin is a Docker container that is designed to perform a set of pre-defined actions. - -These actions can be for any number of general tasks, deploying code, publishing artifacts and more. - -Anyone can create a plugin and use it in their pipeline. - -The registry of existing plugins can be found on this site in the [plugins](docs/usage/plugins/index.md) tab. - -Within the parameters block, keys are injected as upper case environment variables with the pattern of `PARAMETER_`. - -**Expand your knowledge with an example!** - -* [Working with Plugins](/docs/usage/plugin.md) - - - -```yaml -steps: - - - name: publish hello world - image: target/vela-kaniko - # Environment variables injected: - # PARAMETER_REGISTRY=index.docker.io - # PARAMETER_REPO=index.docker.io/go-vela/hello-world - # PARAMETER_USERNAME=moby - # PARAMETER_PASSWORD=mypassword - # PARAMETER_TAGS=latest,v1.0.0 - parameters: - registry: index.docker.io - repo: index.docker.io/go-vela/hello-world - username: moby - password: mypassword - tags: - - latest - - v1.0.0 -``` -## Step 5 - Trigger the Pipeline - -If you've followed the documentation for [enabling a repo](/docs/usage/enable_repo.md) and wrote a pipeline ([here are some example pipelines](/docs/usage/tour/tour.md)), all that should be left is to push your pipeline to your repo. - -If a build does not trigger when your push a change to your repo, check the webhook response to see if there is an error. - -:::tip -Want to run it locally? Install the CLI and "exec" the pipline from your terminal -::: - -```sh -$ vela exec pipeline -... -[stage: ][step: Greeting] $ echo "Hello, World" -[stage: ][step: Greeting] Hello, World -[stage: ][step: Welcome] $ echo "Welcome to the Vela docs" -[stage: ][step: Welcome] Welcome to the Vela docs -``` diff --git a/versioned_docs/version-0.26/usage/repo_settings.md b/versioned_docs/version-0.26/usage/repo_settings.md deleted file mode 100644 index 58e92c3..0000000 --- a/versioned_docs/version-0.26/usage/repo_settings.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: "Repository Settings" -linkTitle: "Repository Settings" -description: > - Learn about Vela repository settings. ---- - -## Permissions - -Before going through all the Vela repository settings, it's important to cover Vela permissions and how they apply to various parts of the Vela application. - -An overview of permissions can be found [here](/docs/usage/roles.md). - -## General Repository Settings - -Below are all settings for repositories that can be changed in the Vela UI / CLI / API. - -### Webhook Events - -Vela can subscribe to any of the following webhook events: - -| Event | Description | -|------------------------------ |--------------------------------------------------------------------------- | -| `push` | a commit pushed to a repository branch | -| `tag` | a commit pushed to a repository branch | -| `pull_request:opened` | a pull request is opened | -| `pull_request:reopened` | a pull request is reopened | -| `pull_request:synchronize` | a pull request source branch has been updated with a new commit | -| `pull_request:edited` | a pull request has been edited (title, description, target branch, etc) | -| `pull_request:labeled` | a pull request has been labeled | -| `pull_request:unlabeled` | a pull request has been unlabeled | -| `deployment:created` | a deployment is created for the repository | -| `comment:created` | a comment has been made on a pull request | -| `comment:edited` | a comment has been edited on a pull request | -| `delete:branch` | a repository branch has been deleted | -| `delete:tag` | a repository tag has been deleted | - -Pipelines can be written to behave differently based on which event triggered the build (see [rulesets](/docs/usage/tour/rulesets.md). - -:::note -Event scoping (`event:action`) was included in Vela release `v0.23.0`. As such, general `event` rulesets in pipelines are mapped as following: - -- `pull_request` -> [ `pull_request:opened`, `pull_request:synchronize`, `pull_request:reopened` ] -- `comment` -> [ `comment:created`, `comment:edited` ] -- `deployment` -> [ `deployment:created` ] - -::: - -Updating webhook events for a Vela repository _must_ be done through Vela (API/CLI/UI) in order to preserve the signature integrity of the webhook. Otherwise, users will experience a [webhook signature error](/usage/troubleshooting/#payload-signature-check-failed). - -### Access - -Vela supports two options for visibility: **private** or **any**. This determines who can view the Vela builds. - -By default, a newly enabled repository will inherit the visibility setting it has with the source control manager. However, if a user wishes for the visbility to differ between the source code repository and the CI repository, they can do so by changing this setting. - -### Outside Contributor Permissions - -This setting allows repository admins to further safeguard their repositories by requiring approval for builds, specifically pull requests from forks. - -The four settings are: - -- **Always Require Approval**: regardless of user, if the webhook event is a pull request from a fork, the build will need to be approved by a repository admin. -- **Require Approval For Read-Only**: some teams prefer the fork contribution workflow even if users have write permission to the repo. This setting allows those users to not need approval, but read-only users will. -- **Require Admin Approval for First Time Contributors**: users that have contributed to the repository before will be able to run pull request builds without admin approval. Note: it may take a few hours for a user to be marked as a prior contributor after they have contributed to the repository. -- **Never Require Approval**: any user will be able to run pull request builds by opening a PR against the repository. - -When a build is awaiting approval, the SCM will be updated with the status `pending` with the description `build needs approval from repo admin to run`. - -Repository admins can approve a build in the UI or by using the [CLI](/docs/reference/cli/build/approve.md). - -PR builds that are marked as `pending approval` will auto cancel any previous PR build from the same source (if one exists). This is to prevent a build up of builds pending approval from the same source. - -### Build Limit - -The default and max build limit is determined by the platform administrators. These values determine how many builds can be run concurrently for any given repository. These limits exist to prevent any single repository from occupying a large amount of worker resources. - -Builds that are triggered from a webhook event that result in exceeding the build limit will have to be re-launched by redelivering the webhook once the concurrent build total dips below the limit. - -### Build Timeout - -The Build Timeout setting determines the time limit for any given build for a repository. If a build lasts longer than the set timeout, the build will [error out](/usage/troubleshooting/#context-deadline-exceeded). - -### Build Counter - -This number is a tally of all builds that have ran for the repository. This number can be adjusted to be larger but _NOT_ smaller. - -Occasionally, due to various compilation errors, this counter can fall behind resulting in a SQL collision error found in the audit page for new builds. To fix this, ensure the counter matches the actual build count. - -### Status Badge - -Check out the [usage documentation](/docs/usage/badge.md) for more details on customizing status badges for Vela repositories. - -### Repository Actions - -**Chown** — every Vela repository requires an owner. This owner is typically the user that first enabled the repository. The owner must have _write_ permissions for the repository at the minimum. The "Chown" button (or [command](/docs/reference/cli/repo/chown.md) will transfer the ownership to the user making the request. - -**Repair** — whenever the connection between Vela and the webhook configured with the source control manager has been invalidated, the Vela repository must be repaired. This involves the deletion and re-creation of the webhook with the source repository. The build history will be preserved, but the ability to redeliver old webhooks will not. - -### Pipeline Type - -The following are the options for the formatting of the base pipeline: - -| Type | Description | -|-------------|---------------------------------------------------------------------------------------------------------| -| `YAML` | Default pipeline syntax ([Reference Documentation](/docs/reference/yaml/yaml.md) | -| `Go` | Standard YAML with Go inline functionality ([Reference Documentation](/docs/usage/templates/go/conditional.md) | -| `Starlark` | YAML generation using Starlark ([Reference Documentation](/docs/usage/templates/starlark/anatomy.md) | - -Note: by default, templates are treated with `Go` syntax. In order to match that behavior for the base pipeline, this setting must be changed to `Go`. - -## Pipeline Settings - -Below are high-level pipeline settings that are pulled directly from the `metadata` key. - -### Auto Cancel - -```yaml -metadata: - auto_cancel: - running: true - default_branch: true -``` - -Auto canceling builds is a build strategy that will prioritize the most recent status of the source code by canceling obsolete running/pending builds. More information can be found [here](/reference/yaml/metadata/#the-auto_cancel-key). - -### Render Inline - -```yaml -metadata: - render_inline: true - -templates: - - name: example - source: github.com/go-vela/templates/inline.yml - type: github -``` - -Render Inline is a template compilation strategy that appends templates to the end of the base pipeline in the order in which they are declared. This is the only viable method of calling templates with `stages` at the top level. More information can be found [here](/usage/templates/#rendering-inline-directly-in-velayml). - -### Clone - -```yaml -metadata: - clone: false -``` - -Setting the `clone` key to `false` will override Vela's default behavior of cloning the repository at the start of the build. More information can be found [here](/docs/usage/tour/cloning.md). diff --git a/versioned_docs/version-0.26/usage/roles.md b/versioned_docs/version-0.26/usage/roles.md deleted file mode 100644 index 5482c49..0000000 --- a/versioned_docs/version-0.26/usage/roles.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: "Roles" -linkTitle: "Roles" -description: > - Learn about the authorization roles. ---- - -:::warning -At this time the only Source Control Provider is GitHub. So this documentation is tailored for those users. -::: - -Vela does not maintain any authentication (AuthN) or authorization (AuthZ) internally, but instead inherits its access from the source (version control) provider. More information on GitHub's access model can be found in their [documentation](https://help.github.com/en/github/getting-started-with-github/access-permissions-on-github). - -Platform Roles: - -- Admin - -Source Provider Roles: - -- Admin -- Write -- Read - -### Platform Roles - -Platform admins have full control when interacting with the CLI, UI, and API. - -### Source Provider Roles: - -Admins within the GitHub organization have the option to use GitHub orgs to allow users to have permissions on all repositories in the org, or to use fine-grained access of adding access for users directly to individual repositories. - -#### Admin - -The **admin** role enables full access to the repository, which grants the following access levels for resources: - -| Access | Repo | Build | Step | Service | Log | Secret | -| :----: | :--: | :---: | :--: | :-----: | :-: | :----: | -| Write | Y | N | N | N | N | Y | -| Read | Y | Y | Y | Y | Y | Y | - -#### Write - -The **write** role enables read and write access to the repository, which grants the following access levels for resources: - -| Access | Repo | Build | Step | Service | Log | Secret | -| :----: | :--: | :---: | :--: | :-----: | :-: | :----: | -| Write | Y | N | N | N | N | N | -| Read | Y | Y | Y | Y | Y | N | - -#### Read - -The **read** role enables read access to the repository, which grants the following access levels for resources: - -| Access | Repo | Build | Step | Service | Log | Secret | -| :----: | :--: | :---: | :--: | :-----: | :-: | :----: | -| Write | N | N | N | N | N | N | -| Read | Y | Y | Y | Y | Y | N | diff --git a/versioned_docs/version-0.26/usage/schedule_build.md b/versioned_docs/version-0.26/usage/schedule_build.md deleted file mode 100644 index 0a2c0f2..0000000 --- a/versioned_docs/version-0.26/usage/schedule_build.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: "Scheduling a Build" -linkTitle: "Scheduling a Build" -description: > - Schedule builds for your repo. ---- - -:::note -Please ensure you've already [started a build](/docs/usage/start_build.md) for your repo before attempting to setup a schedule. -::: - -Vela supports the ability to periodically trigger builds for a repo known as a "schedule". - -Outside of the Vela ecosystem, this is more commonly known as a [cron expression](https://en.wikipedia.org/wiki/Cron). - -Users will be able to manage schedules for a repo via the UI, [API](/docs/reference/api/schedule/schedule.md) and [CLI](/docs/reference/cli/schedule/schedule.md). - -Only users with `admin` access to a repo will be able to manage schedules for that repo. - -:::warning -We make best efforts to support feature parity with `cron` but we may not support every capability. -::: - -## Entry - -Users will be able to customize the cadence or frequency for how often the schedule should trigger a build via the `entry` field. - -By default, Vela sets a frequency limit of `1h` which controls the smallest amount of time a schedule can wait before running. - -i.e. A schedule can't trigger a build more often than every hour but this may be different for the Vela installation you use. - -Here's a small list of examples to demonstrate valid values for this field: - -* `0 * * * *` - setup a schedule to run every hour -* `0 0 * * *` - setup a schedule to run every day at midnight -* `0 0 * * 0` - setup a schedule to run every week on Sunday at midnight - -Vela currently uses [github.com/adhocore/gronx](https://github.com/adhocore/gronx) to parse and validate this field. - -This library also supports a number of "common cron expressions" (a.k.a. "tags") i.e. `@hourly`, `@daily`, `@weekly` etc. - -For more information, please see that library's [official docs for these tags](https://github.com/adhocore/gronx#tags). - -:::tip -We recommend leveraging an official cron expression generator like [Crontab Guru](https://crontab.guru/) to build the `entry` for your schedule. -::: - -## Pipeline - -Uses will be able to customize what [stages](docs/usage/tour/stages.md) or [steps](docs/usage/tour/steps.md) will run in a build for a schedule using a [ruleset](docs/usage/tour/rulesets.md): - -```yaml -version: "1" - -steps: - - name: unit-test - ruleset: - event: [ deployment, schedule ] - target: [ unit_test, integration_test, nightly ] - commands: - - echo "I run when a schedule with the name 'unit_test', 'integration_test' or 'nightly' is executed" - - - name: integration-test - ruleset: - event: [ deployment, schedule ] - target: [ integration_test, nightly ] - commands: - - echo "I run when a schedule with the name 'integration_test' or 'nightly' is executed" - - - name: publish - ruleset: - event: [ deployment, schedule ] - target: [ nightly ] - commands: - - echo "I run when a schedule with the name 'nightly' is executed" - - - name: notification - ruleset: - event: [ deployment, schedule ] - commands: - - echo "I run when any schedule is executed" -``` - -:::tip -We recommend adding the `deployment` event to your `ruleset` for processes that you want to run on a schedule. - -This will enable you to manually trigger a build that replicates the configuration you want to run on a schedule. - -This is especially useful when attempting to initially test and debug your pipeline for a schedule. -::: \ No newline at end of file diff --git a/versioned_docs/version-0.26/usage/secrets.md b/versioned_docs/version-0.26/usage/secrets.md deleted file mode 100644 index aba5513..0000000 --- a/versioned_docs/version-0.26/usage/secrets.md +++ /dev/null @@ -1,265 +0,0 @@ ---- -title: "Secrets" -linkTitle: "Secrets" -description: > - Learn about internal Vela secrets. ---- - -This page will primarily focus on `internal secrets`. If you would like to learn more about `external secrets`, check out the [external secrets examples page](/docs/usage/examples/secrets_external.md). For a broader view of secrets and how to use `internal` or `external` secrets in your pipeline, check out the [secrets tour page](docs/usage/tour/secrets.md). - -:::warning -Internal secrets do NOT have the `pull_request` event enabled by default. This is intentional to help mitigate exposure via a pull request against the repo. You can override this behavior, at your own risk, for each secret. -::: - -## Internal Secrets -Internal secrets are generally managed via the UI or the [CLI](/docs/reference/cli/secret/secret.md). They can also be managed via the [API](/docs/reference/api/secret/secret.md). - -A full pipeline example is available [here](/docs/usage/examples/secrets_internal.md) - -_Example pipeline yaml block for internal secrets_ - -```yaml -secrets: - - name: foo1 - key: github/ocotocat/foo - engine: native - type: repo -``` - -### Name - -The name of your secret. - -### Key - -The key is autogenerated based on the other secret components, following this convention (see [Type](/usage/secrets/#type). - -* Repository: `//` -* Organization: `/` -* Shared: `//` - -### Engine - -The native secret engine is designed to store secrets in the database. This component exists for configuration future-proofing; allowing easier expansion for additional options in the future. - -### Type - -There are three types of internal secrets, with equivalent example paths for the UI: - -* Repository - `https://vela.example.com/-/secrets/native/repo//` -* Organization - `https://vela.example.com/-/secrets/native/org/` -* Shared - `https://vela.example.com/-/secrets/native/shared//` - -#### Repository - -Repository secrets are scoped to only a single repository. In order to create/modify these secrets you must be a repository admin within the source code manager. - -_Example yaml block for repository secret type_ - -```yaml -secrets: - - name: foo1 - key: github/ocotocat/foo1 - engine: native - type: repo -``` - -#### Organization - -Organization secrets are scoped to any repository in the organization. In order to create/modify these secrets you must be an organization admin within the source code manager. - -_Example yaml block for organization secret type_ - -```yaml -secrets: - - name: foo - key: github/foo - engine: native - type: org -``` - -#### Shared - -Shared secrets are scoped to any repository in the source code manager (SCM). Shared secrets are unique in the case they require a team to exist in your SCM org. In order to create/modify these secrets you must be a member of the SCM team. - -_Example yaml block for shared secret type_ - -```yaml -secrets: - - name: foo - key: github/ocotokitties/foo - engine: native - type: shared -``` - -### Protecting Secrets - -Learn the best practices for keeping your Vela secrets safe. - -#### Log Exposure - -Vela implements a masking routine that obfuscates any printing of an internal secret value in step / service logs. For example: - -```yaml -secrets: - - name: foo1 - key: github/ocotocat/foo - engine: native - type: repo - -steps: - - name: example - image: alpine - secrets: foo1 - commands: - - echo $FOO1 # will print *** -``` -:::warning -The masking routine simply looks for logs that exactly match the content of a step secret. It is important to consider this as protection against accidental logging and an opportunity for more verbose logging, NOT protection against bad actors. Those protections are described below. -::: - -#### Pull Request Event + Build Approval - -Secrets by default do not have the `pull request` event enabled, as this event can be triggered by users without `write` access to the repository. Therefore, if users do require secrets for `pull request` events, it is best practice to adopt a [build approval policy](/usage/repo_settings/#outside-contributor-permissions), which will allow repository admins to validate the safety of the pipeline. - -#### Other Secret Settings - -Defaults for various secret types - -| Setting | Repo | Org | Shared | -|--------------------- |----------------------- |----------------------- |----------------------- | -| `Allow Command` | Yes | Yes | No | -| `Allow Substitution` | Yes | Yes | No | -| `Images` | Any | Any | Any | -| `Allow Events` | Push, Tag, Deployment | Push, Tag, Deployment | Push, Tag, Deployment | - -**Allow Command**: - -This setting prevents secrets from being injected into the container environment whenever a `commands` block or custom `entrypoint` is specified. For example: - -```yaml -secrets: - - name: no_commands # 'allow command' set to false - key: vela/no_commands - type: org - engine: native - - - name: yes_commands # 'allow command' set to true - key: vela/yes_commands - type: org - engine: native - -steps: - - name: print secret mask - image: alpine:latest - secrets: [ no_commands, yes_commands ] - commands: - - echo $NO_COMMANDS # will print nothing (not injected) - - echo $YES_COMMANDS # will print secret mask *** -``` - -**Allow Substitution**: - -This setting prevents secrets from being substituted in the pipeline configuration by referencing its key in `${KEY}` format. This setting, in tandem with disallowing commands, prevents users from attempting to bypass Vela's secret masking in logs. Example: - -```yaml -secrets: - - name: no_substitution # 'allow substitution' set to false - key: vela/no_substitution - type: org - engine: native - - - name: yes_substitution # 'allow substitution' set to true - key: vela/yes_substitution - type: org - engine: native - -steps: - - name: docker build - image: target/vela-kaniko - secrets: [ no_substitution, yes_substitution ] - parameters: - build_args: - - FOO=${NO_SUBSTITUTION} # FOO will be empty - - BAR=${YES_SUBSTITUTION} # BAR will be the value of YES_SUBSTITUTION - - - name: command substitution - image: alpine - secrets: [ no_substitution, yes_substitution ] - commands: - # As a caveat to this setting, both the following commands will in fact pull in the secret values. - # This is because Vela converts all commands to a shell script, and these ${KEY} substitutions are - # actually shell environment substitutions rather than Vela runtime substitutions. - - wget --header="X-Auth-Token: ${NO_SUBSTITUTION}" https://www.example.com - - wget --header="X-Auth-Token: ${YES_SUBSTITUTION}" https://www.example.com -``` - -:::note -If you have a secret which a plugin expects as a specific environment variable, you can leverage `target` rather than substitution: - -```diff -steps: - - name: custom plugin - image: docker.company.com/my-org/my-plugin - secrets: -- - github_token -+ - source: github_token -+ target: PARAMETER_API_TOKEN - parameters: -- api_token: ${GITHUB_TOKEN} -``` - -This is a much safer practice. -::: - -**Images**: - -You can further protect a secret by limiting its usage to certain images. This ensures that every time a secret is injected into a container environment, it will be used in an expected way. - -You can specify tag-specific images or base images. - -```yaml -secrets: - - name: any_image # `images` set to "any" - key: vela/any_image - type: org - engine: native - - - name: kaniko_only # `images` set to "target/vela-kaniko" - key: vela/kaniko_only - type: org - engine: native - -steps: - - name: docker build - image: target/vela-kaniko - secrets: - - source: any_image - target: KANIKO_USERNAME # injected as KANIKO_USERNAME - - source: kaniko_only - target: KANIKO_PASSWORD # injected as KANIKO_PASSWORD - parameters: - registry: docker.company.com - repo: docker.company.com/some/repo - tags: - - ${VELA_BUILD_COMMIT:0:8} - - - name: alpine use - image: alpine:latest - secrets: [ any_image, kaniko_only ] - commands: - - echo $ANY_IMAGE # will print ***, signaling its injection to the environment - - echo $KANIKO_ONLY # will print nothing, not injected -``` - -**Allow Events**: - -Secrets can be restricted to only be injected into container environments on certain webhook events. This can be useful to limiting potential exposure opportunities and only using a secret when necessary. - - -:::note -To update any of these settings, you can edit the secret in the UI. - -You may also use the [CLI](/docs/reference/cli/secret/secret.md) or [API](/docs/reference/api/secret/secret.md) -::: - diff --git a/versioned_docs/version-0.26/usage/skipping_build.md b/versioned_docs/version-0.26/usage/skipping_build.md deleted file mode 100644 index 1492fa8..0000000 --- a/versioned_docs/version-0.26/usage/skipping_build.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: "Skipping a Build" -linkTitle: "Skipping a Build" -description: > - Skip builds for certain commits. ---- - -To prevent Vela from running a build for a commit, add one of the following to your commit title or message: - -- `[skip ci]` -- `[ci skip]` -- `[skip vela]` -- `[vela skip]` -- `***no_ci***` - -:::note -You can use upper or lower case. -::: - -Vela will receive the payload from the source control provider and return a 200 response with a reason for why a build was not triggered. \ No newline at end of file diff --git a/versioned_docs/version-0.26/usage/stage_orchestration.md b/versioned_docs/version-0.26/usage/stage_orchestration.md deleted file mode 100644 index 3f13aae..0000000 --- a/versioned_docs/version-0.26/usage/stage_orchestration.md +++ /dev/null @@ -1,267 +0,0 @@ ---- -title: "Stage Orchestration" -linkTitle: "Stage Orchestration" -description: > - Learn how to orchestrate pipelines with stages. ---- - -This page will focus on [`stages`](/docs/usage/tour/stages.md) and how to effectively leverage the orchestration options given to users. These options are: the [`ruleset`](/docs/usage/tour/rulesets.md) key, the [`needs`](/reference/yaml/stages/#the-needs-key) key, and the [`independent`](/reference/yaml/stages/#the-independent-key) key. - -### Step Rulesets in Stages - -To begin, let's focus on the `ruleset` key. While this is not a key at the stages level, each stage has a collection of steps, which can all be given rulesets. There are two kinds of rules within Vela: compile-time rules (path, event, branch, comment, tag, target, and repo) and a runtime rule (status). When Vela compiles a pipeline, it will purge any steps that do not meet the compile-time rules. - -For example, let's consider a pipeline written as such: - -```yaml -version: "1" - -stages: - build: - steps: - - name: Build My Code - image: golang:latest - environment: - CGO_ENABLED: '0' - GOOS: linux - commands: - - go build - - deploy: - steps: - - name: Publish My Docker Image - image: target/vela-kaniko:latest - ruleset: - event: push - branch: main - parameters: - registry: index.docker.io - repo: index.docker.io/octocat/hello-world - dry-run: false - notify: - needs: [ build, deploy ] - steps: - - name: Report Failure - image: target/vela-slack:latest - ruleset: - status: failure - parameters: - text: "Failure!" -``` - -If a Vela build is triggered on a `push` to a branch named `issue-123`, the pipeline will be compiled like this: - -```yaml -version: "1" - -stages: - build: - steps: - - name: Build My Docker Image - image: target/vela-kaniko:latest - parameters: - registry: index.docker.io - repo: index.docker.io/octocat/hello-world - dry-run: true - notify: - needs: [ build ] - steps: - - name: Report Failure - image: target/vela-slack:latest - ruleset: - status: failure - parameters: - text: "Failure!" -``` - -Notice how the `deploy` stage has been pruned completely, rather than being a stage with empty steps. Further, since the `notify` stage normally waits on both `build` and `deploy`, in this situation, it only waits on `build`. The `notify` stage is still part of the build since its ruleset consists of only a runtime rule. - -### Understanding the `needs` key - -While there isn't a sure-fire way of running stages in order, the `needs` key introduces a level of dependency that can be used to order stages. However the `needs` key can become tricky when combined with pruning, as shown in the example above. Let's take a look at a theoretical pipeline: - -```yaml -version: "1" - -stages: - run-first: - steps: - - name: sleep for 10 - image: alpine:latest - commands: - - sleep 10 - - echo "done"" - - runtime-ruleset-stage: - needs: [ run-first ] - steps: - - name: fail - image: alpine:latest - ruleset: - status: failure - commands: - - echo "runtime rule" - - compile-time-ruleset-stage: - needs: [ run-first ] - steps: - - name: pruned - image: alpine:latest - ruleset: - branch: not-main - commands: - - echo "never ran" - - x-stage: - needs: [ runtime-ruleset-stage, compile-time-ruleset-stage ] - steps: - - name: who ran the build - image: alpine:latest - commands: - - sleep 20 - - echo $VELA_BUILD_AUTHOR - - y-stage: - needs: [ compile-time-ruleset-stage ] - steps: - - name: what repo is this - image: alpine:latest - commands: - - sleep 20 - - echo $VELA_REPO_FULL_NAME -``` - -:::tip -Be aware that `needs:` references stages by their name, which can be overridden by the `name` key in the stage definition. -::: - -Consider a Vela build triggered by a `push` to `main`. We know that `run-first` will indeed run first, followed by `runtime-ruleset-stage` since it cannot be pruned due to its runtime rule. However, if we recall from our first example, when the _entirety_ of a stage's step collection is pruned at compile-time, the stage disappears completely: - -```yaml -version: "1" - -stages: - run-first: - steps: - - name: sleep for 10 - image: alpine:latest - commands: - - sleep 10 - - echo "done"" - - runtime-ruleset-stage: - needs: [ run-first ] - steps: - - name: fail - image: alpine:latest - ruleset: - status: failure - commands: - - echo "runtime rule" - - x-stage: - needs: [ runtime-ruleset-stage ] - steps: - - name: who ran the build - image: alpine:latest - commands: - - sleep 20 - - echo $VELA_BUILD_AUTHOR - - y-stage: - needs: [ ] - steps: - - name: what repo is this - image: alpine:latest - commands: - - sleep 20 - - echo $VELA_REPO_FULL_NAME -``` - -So in fact, in this scenario, the `run-first` stage and the `y-stage` begin simultaneously, even though `y-stage` "needed" `compile-time-ruleset-stage` which "needed" `run-first` in the original pipeline. - -### Leveraging Stage independence - -With the increasing popularity of monorepos, some Vela pipelines may want to simultaneously execute very different build flows based on modules within the repository. Since by nature Vela stages will skip the remainder of the build if a single stage fails its pipeline, this could potentially cause issues, such as half-done deployments. - -For example, say we have a repo that has back-end _and_ front-end code written together. Let's assume all the back-end code is in `org/repo/back-end` and the front-end code is in `org/repo/front-end`. We can leverage the [`path`](/reference/yaml/steps/#the-ruleset-key) ruleset with the [`independent`](/reference/yaml/stages/#the-independent-key) stage key to compartmentalize Vela builds: - -```yaml -version: "1" - -stages: - test-and-build-backend: - independent: true - steps: - - name: install go - image: golang:latest - pull: always - ruleset: - matcher: regexp - path: org/repo/back-end/* - environment: - CGO_ENABLED: '0' - GOOS: linux - commands: - - go get ./... - - - name: test go - image: golang:latest - pull: always - ruleset: - matcher: regexp - path: org/repo/back-end/* - environment: - CGO_ENABLED: '0' - GOOS: linux - commands: - - go test ./... - - - name: build go - image: golang:latest - pull: always - ruleset: - matcher: regexp - path: org/repo/back-end/* - environment: - CGO_ENABLED: '0' - GOOS: linux - commands: - - go build - - test-and-build-frontend: - independent: true - steps: - - name: install node - image: node:latest - pull: always - ruleset: - matcher: regexp - path: org/repo/front-end/* - commands: - - node install - - - name: lint node - image: node:latest - pull: always - ruleset: - matcher: regexp - path: org/repo/front-end/* - commands: - - node test - - - name: build node - image: node:latest - pull: always - ruleset: - matcher: regexp - path: org/repo/front-end/* - commands: - - node build -``` - -We can extend this example to deployments, and it's easy to see where a team may want one module to complete its build flow even if there's a failure in another module. - -### In Summary - -Stages are an advanced tool to help with writing powerful and sensible pipelines with parallel execution. While these orchestration tools are helpful, consider just using `steps` to simplify pipelines that don't need the, sometimes surprising, complexity. diff --git a/versioned_docs/version-0.26/usage/start_build.md b/versioned_docs/version-0.26/usage/start_build.md deleted file mode 100644 index 8ee1bca..0000000 --- a/versioned_docs/version-0.26/usage/start_build.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Start a Build" -linkTitle: "Start a Build" -description: > - Start a build for the first time. ---- - -If you've followed the documentation for [enabling a repo](/docs/usage/enable_repo.md) and wrote a pipeline ([here are some example pipelines](/docs/usage/tour/tour.md), all that should be left is to push your pipeline to your repo. - -If a build does not trigger when your push a change to your repo, check the webhook response to see if there is an error. diff --git a/versioned_docs/version-0.26/usage/templates/go/_category_.json b/versioned_docs/version-0.26/usage/templates/go/_category_.json deleted file mode 100644 index 55cadad..0000000 --- a/versioned_docs/version-0.26/usage/templates/go/_category_.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "label": "Go", - "position": 1, - "link": { - "type": "generated-index", - } -} diff --git a/versioned_docs/version-0.26/usage/templates/go/conditional.md b/versioned_docs/version-0.26/usage/templates/go/conditional.md deleted file mode 100644 index 6a5d833..0000000 --- a/versioned_docs/version-0.26/usage/templates/go/conditional.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: "Conditionals" -linkTitle: "Conditionals" -description: > - Example Go template with conditionals. ---- - -:::tip -We recommend reviewing [Go Templates documentation](https://golang.org/pkg/text/template/) before attempting to create a template. - -If you're new to YAML we also recommend reviewing the [YAML 1.2 spec](https://yaml.org/spec/1.2/spec.html) for validation on syntax. -::: - -## Overview - -From [Go template Conditional](https://golang.org/pkg/text/template/#hdr-Actions): - -```text -{{if pipeline}} - T1 -{{end}} -``` - -> If the value of the pipeline is empty, no output is generated; -> otherwise, T1 is executed. The empty values are false, 0, any -> nil pointer or interface value, and any array, slice, map, or -> string of length zero. -> Dot is unaffected. - -:::tip -For information on if/else statements see [conditional docs](https://golang.org/pkg/text/template/#hdr-Actions) -::: - -## Sample - -Let's take a look at using a conditional with a variable in a template: - -```yaml -metadata: - template: true - -{{$br := vela "BUILD_BRANCH"}} - -steps: - - - name: test - commands: - - go test ./... - image: {{ .image }} - {{ .pull_policy }} - ruleset: - event: [ push, pull_request ] - - # if branch equals main add this step to the final pipeline - {{ if (eq $br "main") }} - - - name: build - commands: - - go build - image: {{ .image }} - {{ .pull_policy }} - ruleset: - event: [ push, pull_request ] - - {{ end }} -``` - -The caller of this template could look like: - -```yaml -version: "1" -templates: - - name: sample - source: github.com///path/to/file/