diff --git a/docs/reference/installation/server/scm.md b/docs/reference/installation/server/scm.md index 954552c..eb7a425 100644 --- a/docs/reference/installation/server/scm.md +++ b/docs/reference/installation/server/scm.md @@ -30,7 +30,7 @@ The following options are used to configure the component: | `scm.app.private-key` | base64 encoded private key value for SCM App integration (one of this OR `scm.app.private-key.path` required when `scm.app.id` set) | `false` | `N/A` | `SCM_APP_PRIVATE_KEY`,`VELA_SCM_APP_PRIVATE_KEY` | | `scm.app.private-key.path` | filesystem path to private key for SCM App integration (alternative to `scm.app.private-key`) | `false` | `N/A` | `SCM_APP_PRIVATE_KEY_PATH`,`VELA_SCM_APP_PRIVATE_KEY_PATH` | | `scm.app.webhook-secret` | webhook HMAC secret for SCM App integration (required when `scm.app.id` set and webhook validation enabled) | `false` | `N/A` | `SCM_APP_WEBHOOK_SECRET`,`VELA_SCM_APP_WEBHOOK_SECRET` | -| `scm.app.permissions` | allowed installation token permissions for SCM App integration | `false` | `[ contents:read, checks:write ]` | `SCM_APP_PERMISSIONS`,`VELA_SCM_APP_PERMISSIONS` | +| `scm.app.permissions` | allowed installation token permissions for SCM App integration | `false` | `[ contents:read, checks:write, deployments:write ]` | `SCM_APP_PERMISSIONS`,`VELA_SCM_APP_PERMISSIONS` | | `scm.repo.roles-map` | map of SCM repository roles -> Vela permissions | `false` | `{ admin: admin, write: write, maintain: write, triage: read, read: read }` | `SCM_REPO_ROLES_MAP`,`VELA_SCM_REPO_ROLES_MAP` | | `scm.org.roles-map` | map of SCM organization roles -> Vela permissions | `false` | `{ admin: admin, member: read }` | `SCM_ORG_ROLES_MAP`,`VELA_SCM_ORG_ROLES_MAP` | | `scm.team.roles-map` | map of SCM team roles -> Vela permissions | `false` | `{ maintainer: admin, member: read }` | `SCM_TEAM_ROLES_MAP`,`VELA_SCM_TEAM_ROLES_MAP` | @@ -39,6 +39,10 @@ The following options are used to configure the component: For more information on these configuration options, please see the [server reference](/docs/reference/installation/server/server.md). ::: +:::note +If your repositories use the `deployment` event in Vela, ensure `deployments:write` is included in `scm.app.permissions` so deployment statuses can be updated correctly. +::: + ## Drivers The following drivers are available to configure the component: diff --git a/docs/reference/installation/server/secret.md b/docs/reference/installation/server/secret.md index 9e3327d..7899aea 100644 --- a/docs/reference/installation/server/secret.md +++ b/docs/reference/installation/server/secret.md @@ -35,6 +35,21 @@ The following options are used to configure the component: For more information on these configuration options, please see the [server reference](/docs/reference/installation/server/server.md). ::: +## Native Secret Availability + +Vela can enable or disable native secret management operations by secret scope at runtime. + +The following server variables control this behavior: + +* `VELA_ENABLE_REPO_SECRETS` +* `VELA_ENABLE_ORG_SECRETS` +* `VELA_ENABLE_SHARED_SECRETS` + +These values default to `true` and can be updated by platform administrators via the server settings APIs/UI. + +If a secret scope is disabled, non-`GET` secret operations for that scope (for example create, update, and delete) are blocked. +`GET` requests remain allowed so existing secrets can still be read/listed. + ## Drivers The following drivers are available to configure the component: diff --git a/docs/reference/installation/server/server.md b/docs/reference/installation/server/server.md index 6ba0e6c..0a2653c 100644 --- a/docs/reference/installation/server/server.md +++ b/docs/reference/installation/server/server.md @@ -412,6 +412,42 @@ This variable should only be used for local development. This variable has a default value of `true`. ::: +### VELA_ENABLE_REPO_SECRETS + +This variable controls whether repository-level native secrets are enabled. + +The variable can be provided as a `boolean`. + +:::note +This variable has a default value of `true`. + +This property can be updated while the server is running using the [settings component](/docs/reference/installation/server/settings.md). +::: + +### VELA_ENABLE_ORG_SECRETS + +This variable controls whether organization-level native secrets are enabled. + +The variable can be provided as a `boolean`. + +:::note +This variable has a default value of `true`. + +This property can be updated while the server is running using the [settings component](/docs/reference/installation/server/settings.md). +::: + +### VELA_ENABLE_SHARED_SECRETS + +This variable controls whether shared native secrets are enabled. + +The variable can be provided as a `boolean`. + +:::note +This variable has a default value of `true`. + +This property can be updated while the server is running using the [settings component](/docs/reference/installation/server/settings.md). +::: + ### VELA_LOG_LEVEL This variable sets the log level for the server process. diff --git a/docs/reference/installation/server/settings.md b/docs/reference/installation/server/settings.md index 202a89f..d45f62f 100644 --- a/docs/reference/installation/server/settings.md +++ b/docs/reference/installation/server/settings.md @@ -17,6 +17,9 @@ The following properties are available to be updated: * [`VELA_CLONE_IMAGE`](/reference/installation/server/#vela_clone_image) * [`VELA_MAX_DASHBOARD_REPOS`](/reference/installation/server/#vela_max_dashboard_repos) * [`VELA_QUEUE_RESTART_LIMIT`](/reference/installation/server/#vela_queue_restart_limit) +* [`VELA_ENABLE_REPO_SECRETS`](/reference/installation/server/#vela_enable_repo_secrets) +* [`VELA_ENABLE_ORG_SECRETS`](/reference/installation/server/#vela_enable_org_secrets) +* [`VELA_ENABLE_SHARED_SECRETS`](/reference/installation/server/#vela_enable_shared_secrets) ## Configuration diff --git a/docs/reference/sdk/go.md b/docs/reference/sdk/go.md index 3f80401..9e09f05 100644 --- a/docs/reference/sdk/go.md +++ b/docs/reference/sdk/go.md @@ -13,7 +13,7 @@ For a complete list of APIs and examples, please take a look at the [Godoc Refer ## Minimum requirements -Go 1.13 or above +Go 1.26 or above ## Get build info example @@ -23,32 +23,34 @@ Below is a sample Go program demonstrating how to authenticate and get a build w package main import ( + "context" "fmt" "github.com/go-vela/sdk-go/vela" ) func main() { + ctx := context.Background() + // 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) + return } - // set the Authentication mechanisms for the client + // set token authentication 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) + build, resp, err := client.Build.Get(ctx, "go-vela", "sdk-go", 1) if err != nil { fmt.Println(err) + return } fmt.Printf("Received response code %d, for build %+v", resp.StatusCode, build) diff --git a/docs/reference/yaml/git.md b/docs/reference/yaml/git.md index 86224e3..95f1b42 100644 --- a/docs/reference/yaml/git.md +++ b/docs/reference/yaml/git.md @@ -42,4 +42,22 @@ git: :::note This token will only be generated if the repository owner also has access to the repositories listed. -::: \ No newline at end of file +::: + +## API Access With Installation Tokens + +Starting in `v0.28`, installation tokens generated with the `git.token` block can also be used for Vela API endpoints that require repo `read` or `write` access. + +This makes `VELA_GIT_TOKEN` useful for automation patterns that call Vela APIs from within a build (for example, listing build data or creating deployment-related resources). + +When Vela receives an installation token for these endpoints, it validates: + +* token scope (repository access) +* token permissions (for example `contents:read` vs `contents:write`) +* token validity via server-side token cache metadata + +If a token does not include the required repository or permission level, the request is rejected with `401`. + +:::tip +Use least privilege for the `permissions` map and only grant `write` for resources your pipeline actually needs. +::: diff --git a/docs/usage/enable_repo.md b/docs/usage/enable_repo.md index 93fe6d2..c2ac926 100644 --- a/docs/usage/enable_repo.md +++ b/docs/usage/enable_repo.md @@ -19,6 +19,10 @@ For this example, we'll go over using the UI to add the repo. You can always hea Your repo now has the necessary webhook to Vela. +:::tip +In newer UI versions, repository enablement may also be available directly from the builds view when a repository is not yet active. +::: + :::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/docs/usage/secrets.md b/docs/usage/secrets.md index f6d1fae..6c8a1ad 100644 --- a/docs/usage/secrets.md +++ b/docs/usage/secrets.md @@ -17,6 +17,10 @@ Internal secrets are generally managed via the UI or the [CLI](/docs/reference/c A full pipeline example is available [here](/docs/usage/examples/secrets_internal.md) +:::note +Starting in `v0.28`, Vela de-duplicates origin secrets by `name` during compile. If the same origin secret name appears multiple times, only one instance is retained. +::: + _Example pipeline YAML block for internal secrets_ ```yaml diff --git a/docs/usage/troubleshooting.md b/docs/usage/troubleshooting.md index 46f4e08..cde34c1 100644 --- a/docs/usage/troubleshooting.md +++ b/docs/usage/troubleshooting.md @@ -350,4 +350,25 @@ steps: data_center: east ``` -Now when Vela compiles the pipeline, the `parameters` blocks for each step will include the `log_level` and `repo` pairs from the base anchor. \ No newline at end of file +Now when Vela compiles the pipeline, the `parameters` blocks for each step will include the `log_level` and `repo` pairs from the base anchor. + +## `v0.28` Buildkite Legacy Removal + +With `v0.28`, Vela removed the Buildkite parser dependency and no longer supports legacy pipeline parsing behavior. + +If your repository still relies on `version: "legacy"` semantics, pipeline compilation can fail after upgrade. + +### Symptoms + +* Pipeline validation errors that did not appear before upgrade +* Build creation succeeds but compile fails with YAML parsing/validation errors + +### Resolution + +* Ensure your pipeline uses supported Vela YAML format (`version: "1"`) +* Run [`vela validate pipeline`](/docs/reference/cli/pipeline/validate.md) locally and fix reported schema or type issues +* Update any templates that were relying on legacy parser quirks + +:::tip +Treat this migration similarly to the `v0.26` YAML parser migration: validate pipelines and templates before or immediately after upgrade. +:::