diff --git a/cli/exec/exec.go b/cli/exec/exec.go
index 1e918538c91..a2d5ca0bb6e 100644
--- a/cli/exec/exec.go
+++ b/cli/exec/exec.go
@@ -24,7 +24,7 @@ import (
 	"slices"
 	"strings"
 
-	"codeberg.org/6543/xyaml"
+	"codeberg.org/6543/xyaml/v2"
 	"github.com/oklog/ulid/v2"
 	"github.com/urfave/cli/v3"
 	"go.uber.org/multierr"
diff --git a/go.mod b/go.mod
index 7f4cd2a5d26..843f02d21b9 100644
--- a/go.mod
+++ b/go.mod
@@ -6,8 +6,8 @@ require (
 	al.essio.dev/pkg/shellescape v1.6.0
 	charm.land/huh/v2 v2.0.3
 	code.gitea.io/sdk/gitea v0.25.1
-	codeberg.org/6543/go-yaml2json v1.0.0
-	codeberg.org/6543/xyaml v1.1.0
+	codeberg.org/6543/go-yaml2json/v2 v2.0.0
+	codeberg.org/6543/xyaml/v2 v2.0.1
 	codeberg.org/mvdkleijn/forgejo-sdk/forgejo/v3 v3.0.0
 	github.com/6543/logfile-open v1.2.1
 	github.com/adrg/xdg v0.5.3
@@ -57,6 +57,7 @@ require (
 	github.com/zalando/go-keyring v0.2.8
 	gitlab.com/gitlab-org/api/client-go/v2 v2.34.0
 	go.uber.org/multierr v1.11.0
+	go.yaml.in/yaml/v4 v4.0.0-rc.4
 	golang.org/x/crypto v0.52.0
 	golang.org/x/image v0.41.0
 	golang.org/x/net v0.55.0
@@ -80,6 +81,7 @@ require (
 	charm.land/bubbles/v2 v2.0.0 // indirect
 	charm.land/bubbletea/v2 v2.0.2 // indirect
 	charm.land/lipgloss/v2 v2.0.1 // indirect
+	codeberg.org/6543/xyaml v1.1.0 // indirect
 	filippo.io/edwards25519 v1.2.0 // indirect
 	github.com/42wim/httpsig v1.2.4 // indirect
 	github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c // indirect
diff --git a/go.sum b/go.sum
index 97afd0313a9..c5d57fd1e1f 100644
--- a/go.sum
+++ b/go.sum
@@ -10,10 +10,12 @@ charm.land/lipgloss/v2 v2.0.1 h1:6Xzrn49+Py1Um5q/wZG1gWgER2+7dUyZ9XMEufqPSys=
 charm.land/lipgloss/v2 v2.0.1/go.mod h1:KjPle2Qd3YmvP1KL5OMHiHysGcNwq6u83MUjYkFvEkM=
 code.gitea.io/sdk/gitea v0.25.1 h1:yywxWwoV+SdjHtbC6unBiXojWdZOtoHuGhEazEXeWuE=
 code.gitea.io/sdk/gitea v0.25.1/go.mod h1:uDFWYBU8dgZsgOHwe6C/6olxvf8FHguNB3wW1i83fgg=
-codeberg.org/6543/go-yaml2json v1.0.0 h1:heGqo9VEi7gY2yNqjj7X4ADs5nzlFIbGsJtgYDLrnig=
-codeberg.org/6543/go-yaml2json v1.0.0/go.mod h1:mz61q14LWF4ZABrgMEDMmk3t9dPi6zgR1uBh2VKV2RQ=
+codeberg.org/6543/go-yaml2json/v2 v2.0.0 h1:S2c643uPhlNlURQWjnnOyOGmiAcCewINBzpGRcfwaVg=
+codeberg.org/6543/go-yaml2json/v2 v2.0.0/go.mod h1:a0LIJUJKeRvfGJMQC0aDdywyqgQQzaAT2zzi7OPDeOE=
 codeberg.org/6543/xyaml v1.1.0 h1:0PWTy8OUqshshjrrnAXFWXSPUEa8R49DIh2ah07SxFc=
 codeberg.org/6543/xyaml v1.1.0/go.mod h1:jI7afXLZUxeL4rNNsG1SlHh78L+gma9lK1bIebyFZwA=
+codeberg.org/6543/xyaml/v2 v2.0.1 h1:GIkCLqf8TeUHjRqTbhCOGAmc8pzCuAFr4lWgLV+HgPc=
+codeberg.org/6543/xyaml/v2 v2.0.1/go.mod h1:OiVkoPEUSJK4xUub8OuQvdnJM9SpM74oGxpGB045JVI=
 codeberg.org/mvdkleijn/forgejo-sdk/forgejo/v3 v3.0.0 h1:s2fK+FBwvcYsmKDjNhmoe7B8q9zsgs0UrSlYe9r4XjM=
 codeberg.org/mvdkleijn/forgejo-sdk/forgejo/v3 v3.0.0/go.mod h1:Is2jTpS1dizeXm4skQv/ES3QVqnzcNhn2GzZXpiw9f8=
 filippo.io/edwards25519 v1.2.0 h1:crnVqOiS4jqYleHd9vaKZ+HKtHfllngJIiOpNpoJsjo=
@@ -655,6 +657,8 @@ go.yaml.in/yaml/v2 v2.4.3 h1:6gvOSjQoTB3vt1l+CU+tSyi/HOjfOjRLJ4YwYZGwRO0=
 go.yaml.in/yaml/v2 v2.4.3/go.mod h1:zSxWcmIDjOzPXpjlTTbAsKokqkDNAVtZO0WOMiT90s8=
 go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
+go.yaml.in/yaml/v4 v4.0.0-rc.4 h1:UP4+v6fFrBIb1l934bDl//mmnoIZEDK0idg1+AIvX5U=
+go.yaml.in/yaml/v4 v4.0.0-rc.4/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
 golang.org/x/arch v0.22.0 h1:c/Zle32i5ttqRXjdLyyHZESLD/bB90DCU1g9l/0YBDI=
 golang.org/x/arch v0.22.0/go.mod h1:dNHoOeKiyja7GTvF9NJS1l3Z2yntpQNzgrjh1cU103A=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
diff --git a/pipeline/frontend/yaml/compiler/settings/params.go b/pipeline/frontend/yaml/compiler/settings/params.go
index 4196ccbec57..e90693e02d3 100644
--- a/pipeline/frontend/yaml/compiler/settings/params.go
+++ b/pipeline/frontend/yaml/compiler/settings/params.go
@@ -20,8 +20,8 @@ import (
 	"strconv"
 	"strings"
 
-	"codeberg.org/6543/go-yaml2json"
-	"gopkg.in/yaml.v3"
+	"codeberg.org/6543/go-yaml2json/v2"
+	"go.yaml.in/yaml/v4"
 )
 
 // ParamsToEnv uses reflection to convert a map[string]interface to a list
@@ -97,7 +97,7 @@ func sanitizeParamValue(v any, getSecretValue func(name string) (string, error))
 
 	case reflect.Map:
 		switch v := v.(type) {
-		// gopkg.in/yaml.v3 only emits this map interface
+		// go.yaml.in/yaml/v4 only emits this map interface
 		case map[string]any:
 			// check if it's a secret and return value if it's the case
 			value, isSecret, err := injectSecret(v, getSecretValue)
@@ -204,7 +204,7 @@ func injectSecretRecursive(v any, getSecretValue func(name string) (string, erro
 	switch t.Kind() {
 	case reflect.Map:
 		switch v := v.(type) {
-		// gopkg.in/yaml.v3 only emits this map interface
+		// go.yaml.in/yaml/v4 only emits this map interface
 		case map[string]any:
 			// handle secrets
 			value, isSecret, err := injectSecret(v, getSecretValue)
diff --git a/pipeline/frontend/yaml/compiler/settings/params_test.go b/pipeline/frontend/yaml/compiler/settings/params_test.go
index 43238d46302..b83281003c1 100644
--- a/pipeline/frontend/yaml/compiler/settings/params_test.go
+++ b/pipeline/frontend/yaml/compiler/settings/params_test.go
@@ -20,7 +20,7 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
-	"gopkg.in/yaml.v3"
+	"go.yaml.in/yaml/v4"
 )
 
 func TestParamsToEnv(t *testing.T) {
diff --git a/pipeline/frontend/yaml/constraint/constraint.go b/pipeline/frontend/yaml/constraint/constraint.go
index 0dfed2713df..55f0460f2b1 100644
--- a/pipeline/frontend/yaml/constraint/constraint.go
+++ b/pipeline/frontend/yaml/constraint/constraint.go
@@ -21,7 +21,7 @@ import (
 	"slices"
 
 	"github.com/expr-lang/expr"
-	"gopkg.in/yaml.v3"
+	"go.yaml.in/yaml/v4"
 
 	"go.woodpecker-ci.org/woodpecker/v3/pipeline/frontend/metadata"
 	yaml_base_types "go.woodpecker-ci.org/woodpecker/v3/pipeline/frontend/yaml/types/base"
@@ -123,6 +123,9 @@ func (when *When) IsLocal() bool {
 }
 
 func (when *When) UnmarshalYAML(value *yaml.Node) error {
+	if value.Kind == yaml.DocumentNode && len(value.Content) == 1 {
+		value = value.Content[0]
+	}
 	switch value.Kind {
 	case yaml.SequenceNode:
 		if err := value.Decode(&when.Constraints); err != nil {
diff --git a/pipeline/frontend/yaml/constraint/constraint_test.go b/pipeline/frontend/yaml/constraint/constraint_test.go
index 41a5f05209a..6292c48a72c 100644
--- a/pipeline/frontend/yaml/constraint/constraint_test.go
+++ b/pipeline/frontend/yaml/constraint/constraint_test.go
@@ -19,7 +19,7 @@ import (
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
-	"gopkg.in/yaml.v3"
+	"go.yaml.in/yaml/v4"
 
 	"go.woodpecker-ci.org/woodpecker/v3/pipeline/frontend/metadata"
 )
diff --git a/pipeline/frontend/yaml/constraint/list.go b/pipeline/frontend/yaml/constraint/list.go
index 3a7ac307dfb..2ebc03ad494 100644
--- a/pipeline/frontend/yaml/constraint/list.go
+++ b/pipeline/frontend/yaml/constraint/list.go
@@ -19,7 +19,7 @@ import (
 
 	"github.com/bmatcuk/doublestar/v4"
 	"go.uber.org/multierr"
-	"gopkg.in/yaml.v3"
+	"go.yaml.in/yaml/v4"
 
 	yaml_base_types "go.woodpecker-ci.org/woodpecker/v3/pipeline/frontend/yaml/types/base"
 )
@@ -75,6 +75,9 @@ func (c *List) Excludes(v string) bool {
 
 // UnmarshalYAML unmarshal the constraint.
 func (c *List) UnmarshalYAML(value *yaml.Node) error {
+	if value.Kind == yaml.DocumentNode && len(value.Content) == 1 {
+		value = value.Content[0]
+	}
 	out1 := struct {
 		Include yaml_base_types.StringOrSlice
 		Exclude yaml_base_types.StringOrSlice
diff --git a/pipeline/frontend/yaml/constraint/list_test.go b/pipeline/frontend/yaml/constraint/list_test.go
index 84e8e9595bc..7aafb51bb6a 100644
--- a/pipeline/frontend/yaml/constraint/list_test.go
+++ b/pipeline/frontend/yaml/constraint/list_test.go
@@ -18,7 +18,7 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
-	"gopkg.in/yaml.v3"
+	"go.yaml.in/yaml/v4"
 )
 
 func TestConstraintList(t *testing.T) {
diff --git a/pipeline/frontend/yaml/constraint/map_test.go b/pipeline/frontend/yaml/constraint/map_test.go
index 30ea3cbd62a..2f3d4e49f9b 100644
--- a/pipeline/frontend/yaml/constraint/map_test.go
+++ b/pipeline/frontend/yaml/constraint/map_test.go
@@ -18,7 +18,7 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
-	"gopkg.in/yaml.v3"
+	"go.yaml.in/yaml/v4"
 )
 
 func TestConstraintMap(t *testing.T) {
diff --git a/pipeline/frontend/yaml/constraint/path.go b/pipeline/frontend/yaml/constraint/path.go
index 384e7b8f692..109fc710eaa 100644
--- a/pipeline/frontend/yaml/constraint/path.go
+++ b/pipeline/frontend/yaml/constraint/path.go
@@ -19,7 +19,7 @@ import (
 	"strings"
 
 	"github.com/bmatcuk/doublestar/v4"
-	"gopkg.in/yaml.v3"
+	"go.yaml.in/yaml/v4"
 
 	yaml_base_types "go.woodpecker-ci.org/woodpecker/v3/pipeline/frontend/yaml/types/base"
 	"go.woodpecker-ci.org/woodpecker/v3/shared/optional"
@@ -35,6 +35,9 @@ type Path struct {
 
 // UnmarshalYAML unmarshal the constraint.
 func (c *Path) UnmarshalYAML(value *yaml.Node) error {
+	if value.Kind == yaml.DocumentNode && len(value.Content) == 1 {
+		value = value.Content[0]
+	}
 	out1 := struct {
 		Include       yaml_base_types.StringOrSlice `yaml:"include"`
 		Exclude       yaml_base_types.StringOrSlice `yaml:"exclude"`
diff --git a/pipeline/frontend/yaml/constraint/path_test.go b/pipeline/frontend/yaml/constraint/path_test.go
index 8222eeb2949..32aa263f94c 100644
--- a/pipeline/frontend/yaml/constraint/path_test.go
+++ b/pipeline/frontend/yaml/constraint/path_test.go
@@ -18,7 +18,7 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
-	"gopkg.in/yaml.v3"
+	"go.yaml.in/yaml/v4"
 )
 
 func TestConstraintPath(t *testing.T) {
diff --git a/pipeline/frontend/yaml/linter/linter.go b/pipeline/frontend/yaml/linter/linter.go
index 2c8ff1c0036..9318820915a 100644
--- a/pipeline/frontend/yaml/linter/linter.go
+++ b/pipeline/frontend/yaml/linter/linter.go
@@ -18,7 +18,7 @@ import (
 	"fmt"
 	"slices"
 
-	"codeberg.org/6543/xyaml"
+	"codeberg.org/6543/xyaml/v2"
 	"go.uber.org/multierr"
 
 	pipeline_errors "go.woodpecker-ci.org/woodpecker/v3/pipeline/errors"
diff --git a/pipeline/frontend/yaml/linter/schema/schema.go b/pipeline/frontend/yaml/linter/schema/schema.go
index 228cf8b465e..70b9bde683c 100644
--- a/pipeline/frontend/yaml/linter/schema/schema.go
+++ b/pipeline/frontend/yaml/linter/schema/schema.go
@@ -21,10 +21,10 @@ import (
 	"io"
 	"strings"
 
-	"codeberg.org/6543/go-yaml2json"
-	"codeberg.org/6543/xyaml"
+	"codeberg.org/6543/go-yaml2json/v2"
+	"codeberg.org/6543/xyaml/v2"
 	"github.com/xeipuuv/gojsonschema"
-	"gopkg.in/yaml.v3"
+	"go.yaml.in/yaml/v4"
 )
 
 //go:embed schema.json
diff --git a/pipeline/frontend/yaml/matrix/matrix.go b/pipeline/frontend/yaml/matrix/matrix.go
index 7616f07fbe6..09cf43e136f 100644
--- a/pipeline/frontend/yaml/matrix/matrix.go
+++ b/pipeline/frontend/yaml/matrix/matrix.go
@@ -17,7 +17,7 @@ package matrix
 import (
 	"strings"
 
-	"codeberg.org/6543/xyaml"
+	"codeberg.org/6543/xyaml/v2"
 
 	pipeline_errors "go.woodpecker-ci.org/woodpecker/v3/pipeline/errors"
 )
diff --git a/pipeline/frontend/yaml/parse.go b/pipeline/frontend/yaml/parse.go
index 07452b6d9fa..fe1af64fb63 100644
--- a/pipeline/frontend/yaml/parse.go
+++ b/pipeline/frontend/yaml/parse.go
@@ -15,7 +15,7 @@
 package yaml
 
 import (
-	"codeberg.org/6543/xyaml"
+	"codeberg.org/6543/xyaml/v2"
 
 	"go.woodpecker-ci.org/woodpecker/v3/pipeline/frontend/yaml/types"
 )
diff --git a/pipeline/frontend/yaml/parse_test.go b/pipeline/frontend/yaml/parse_test.go
index 806185926c1..e6d5c669c86 100644
--- a/pipeline/frontend/yaml/parse_test.go
+++ b/pipeline/frontend/yaml/parse_test.go
@@ -19,7 +19,7 @@ import (
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
-	"gopkg.in/yaml.v3"
+	"go.yaml.in/yaml/v4"
 
 	"go.woodpecker-ci.org/woodpecker/v3/pipeline/frontend/metadata"
 	yaml_base_types "go.woodpecker-ci.org/woodpecker/v3/pipeline/frontend/yaml/types/base"
diff --git a/pipeline/frontend/yaml/types/base/int_test.go b/pipeline/frontend/yaml/types/base/int_test.go
index afc384dbe7d..64b543dd75f 100644
--- a/pipeline/frontend/yaml/types/base/int_test.go
+++ b/pipeline/frontend/yaml/types/base/int_test.go
@@ -18,7 +18,7 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
-	"gopkg.in/yaml.v3"
+	"go.yaml.in/yaml/v4"
 )
 
 type StructStringOrInt struct {
diff --git a/pipeline/frontend/yaml/types/base/slice_test.go b/pipeline/frontend/yaml/types/base/slice_test.go
index c22d8cc506c..0886a22a015 100644
--- a/pipeline/frontend/yaml/types/base/slice_test.go
+++ b/pipeline/frontend/yaml/types/base/slice_test.go
@@ -18,7 +18,7 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
-	"gopkg.in/yaml.v3"
+	"go.yaml.in/yaml/v4"
 )
 
 type StructStringOrSlice struct {
diff --git a/pipeline/frontend/yaml/types/container_list.go b/pipeline/frontend/yaml/types/container_list.go
index 49e7b284b28..e8fd5ec8d80 100644
--- a/pipeline/frontend/yaml/types/container_list.go
+++ b/pipeline/frontend/yaml/types/container_list.go
@@ -17,7 +17,7 @@ package types
 import (
 	"fmt"
 
-	"gopkg.in/yaml.v3"
+	"go.yaml.in/yaml/v4"
 )
 
 // ContainerList contains ordered collection of containers.
@@ -27,6 +27,9 @@ type ContainerList struct {
 
 // UnmarshalYAML implements the Unmarshaler interface.
 func (c *ContainerList) UnmarshalYAML(value *yaml.Node) error {
+	if value.Kind == yaml.DocumentNode && len(value.Content) == 1 {
+		value = value.Content[0]
+	}
 	switch value.Kind {
 	// We support maps ...
 	case yaml.MappingNode:
diff --git a/pipeline/frontend/yaml/types/container_test.go b/pipeline/frontend/yaml/types/container_test.go
index 7dae38dd851..e5896356c21 100644
--- a/pipeline/frontend/yaml/types/container_test.go
+++ b/pipeline/frontend/yaml/types/container_test.go
@@ -18,7 +18,7 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
-	"gopkg.in/yaml.v3"
+	"go.yaml.in/yaml/v4"
 
 	"go.woodpecker-ci.org/woodpecker/v3/pipeline/frontend/yaml/constraint"
 	"go.woodpecker-ci.org/woodpecker/v3/pipeline/frontend/yaml/types/base"
diff --git a/pipeline/frontend/yaml/types/network_test.go b/pipeline/frontend/yaml/types/network_test.go
index 2eb95ccda35..8fb631f39f6 100644
--- a/pipeline/frontend/yaml/types/network_test.go
+++ b/pipeline/frontend/yaml/types/network_test.go
@@ -18,7 +18,7 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
-	"gopkg.in/yaml.v3"
+	"go.yaml.in/yaml/v4"
 )
 
 func TestMarshalNetworks(t *testing.T) {
diff --git a/pipeline/frontend/yaml/types/volume_test.go b/pipeline/frontend/yaml/types/volume_test.go
index a6e27a0fe3c..68d3d7563ef 100644
--- a/pipeline/frontend/yaml/types/volume_test.go
+++ b/pipeline/frontend/yaml/types/volume_test.go
@@ -18,7 +18,7 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
-	"gopkg.in/yaml.v3"
+	"go.yaml.in/yaml/v4"
 )
 
 func TestMarshalVolumes(t *testing.T) {
diff --git a/shared/optional/serialization.go b/shared/optional/serialization.go
index c59a6e4d793..8d4adaca54b 100644
--- a/shared/optional/serialization.go
+++ b/shared/optional/serialization.go
@@ -8,7 +8,7 @@ package optional
 import (
 	"encoding/json"
 
-	"gopkg.in/yaml.v3"
+	"go.yaml.in/yaml/v4"
 )
 
 func (o *Option[T]) UnmarshalJSON(data []byte) error {
@@ -29,6 +29,9 @@ func (o Option[T]) MarshalJSON() ([]byte, error) {
 }
 
 func (o *Option[T]) UnmarshalYAML(value *yaml.Node) error {
+	if value.Kind == yaml.DocumentNode && len(value.Content) == 1 {
+		value = value.Content[0]
+	}
 	var v *T
 	if err := value.Decode(&v); err != nil {
 		return err
diff --git a/shared/optional/serialization_yaml_test.go b/shared/optional/serialization_yaml_test.go
index c5f79730b8e..065653fa8db 100644
--- a/shared/optional/serialization_yaml_test.go
+++ b/shared/optional/serialization_yaml_test.go
@@ -10,7 +10,7 @@ import (
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
-	"gopkg.in/yaml.v3"
+	"go.yaml.in/yaml/v4"
 
 	"go.woodpecker-ci.org/woodpecker/v3/shared/optional"
 )