chore: various updates for v0.28 release

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:

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:

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.

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

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)    

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.
-:::
+:::
+
+## 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.
+:::

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).
 :::

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

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.
+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.
+:::