> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Secret

> Creates a new secret for a project.

`Unary` · [`Secrets`](https://ona.com/docs/api-reference/generated/secret/overview)

Creates a new secret for a project.

Use this method to:

* Store sensitive configuration values
* Set up environment variables
* Configure registry authentication
* Add file-based secrets

### Examples

* Create environment variable:

  Creates a secret that will be available as an environment variable.

  ```yaml theme={null}
  name: "DATABASE_URL"
  projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
  value: "postgresql://user:pass@localhost:5432/db"
  environmentVariable: true
  ```

* Create file secret:

  Creates a secret that will be mounted as a file.

  ```yaml theme={null}
  name: "SSH_KEY"
  projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
  value: "-----BEGIN RSA PRIVATE KEY-----\n..."
  filePath: "/home/gitpod/.ssh/id_rsa"
  ```

* Create registry auth:

  Creates credentials for private container registry.

  ```yaml theme={null}
  name: "DOCKER_AUTH"
  projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
  value: "username:password"
  containerRegistryBasicAuthHost: "https://registry.example.com"
  ```

## Endpoint

```text theme={null}
POST /api/gitpod.v1.SecretService/CreateSecret
```

Send a Bearer token as described in [Authentication](https://ona.com/docs/api-reference.md#authenticate-requests). If your organization uses a custom management-plane domain, replace `https://app.ona.com` with that domain.

## Request example

```bash cURL theme={null}
export ONA_HOST=https://app.ona.com
export ONA_API_KEY=<your-token>

curl --request POST \
  --url "$ONA_HOST/api/gitpod.v1.SecretService/CreateSecret" \
  --header "Authorization: Bearer $ONA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "filePath": "<file-path>"
}'
```

```python Python theme={null}
import gitpod.v1.secret_pb2 as secret_pb2
from ona_sdk import create_client_from_env

ona = create_client_from_env()
request = secret_pb2.CreateSecretRequest(
    file_path="<file-path>",
)
response = ona.services.secret.create_secret(request)
print(response)
```

```typescript TypeScript theme={null}
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { CreateSecretRequestSchema } from "@gitpod/sdk/gitpod/v1/secret_pb";

async function main() {
  const ona = createClientFromEnv();
  const request = create(CreateSecretRequestSchema, {
    mount: {
      case: "filePath",
      value: "<file-path>",
    },
  });
  const response = await ona.services.secret.createSecret(request);
  console.log(response);
}

main().catch(console.error);
```

```go Go theme={null}
package main

import (
	"context"
	"fmt"
	"log"

	"connectrpc.com/connect"
	"github.com/gitpod-io/gitpod-sdk-go/sdk"
	gitpodpb "github.com/gitpod-io/gitpod-sdk-go/v1"
)

func main() {
	ona, err := sdk.NewFromEnv()
	if err != nil {
		log.Fatal(err)
	}

	request := connect.NewRequest(&gitpodpb.CreateSecretRequest{
		Mount: &gitpodpb.CreateSecretRequest_FilePath{
			FilePath: "<file-path>",
		},
	})
	response, err := ona.Services.Secret.CreateSecret(context.Background(), request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response.Msg)
}
```

```json Request body theme={null}
{
  "filePath": "<file-path>"
}
```

## Request

`gitpod.v1.CreateSecretRequest`

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | No | Constraints: `string.max_len=127, string.min_len=3, string.pattern=^[0-9a-zA-Z_]&#123;3,&#125;$`. |
| `projectId` | string | No | **Deprecated.** project\_id is the ProjectID this Secret belongs to Deprecated: use scope instead |
| `value` | string | No | value is the plaintext value of the secret. When set, source must be unset or verbatim. Constraints: `string.max_len=10240, string.min_len=0`. |
| `source` | [Source](#type-gitpod-v1-secret-source) | No | source is the source of the secret, possibly verbatim value |
| `filePath` | string | One of `mount` | absolute path to the file where the secret is mounted Constraints: `cel.expression=this.matches('^/[^/].*$'), cel.id=absolute_path, cel.message=value must be an absolute path (e.g. /path/to/file)`. |
| `environmentVariable` | boolean | One of `mount` | secret will be created as an Environment Variable with the same name as the secret |
| `containerRegistryBasicAuthHost` | string | One of `mount` | secret will be mounted as a docker config in the environment VM, mount will have the docker registry host |
| `apiOnly` | boolean | One of `mount` | api\_only indicates the secret is only available via API/CLI. These secrets are NOT automatically injected into services or devcontainers. Useful for secrets that should only be consumed programmatically (e.g., by security agents). |
| `credentialProxy` | [CredentialProxy](#type-gitpod-v1-secret-credential-proxy) | No | credential\_proxy configures transparent credential injection when environments materialize this secret. When set, the credential proxy intercepts HTTPS traffic to the target hosts and replaces the dummy mounted value with the real value in the specified HTTP header. The real secret value is never exposed in the environment. This field is orthogonal to mount - a secret can be both mounted and proxied at the same time. |
| `scope` | [SecretScope](#type-gitpod-v1-secret-scope) | No | scope is the scope of the secret |

## Response

`gitpod.v1.CreateSecretResponse`

| Field | Type | Required | Description |
| - | - | - | - |
| `secret` | [Secret](#type-gitpod-v1-secret) | No | |

## Related types

> [accordion] Secret
>
> `gitpod.v1.Secret`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `id` | string | No | Constraints: `string.uuid=true`. |
> | `name` | string | No | Name of the secret for humans. |
> | `projectId` | string | No | **Deprecated.** The Project ID this Secret belongs to Deprecated: use scope instead Constraints: `string.uuid=true`. |
> | `createdAt` | RFC 3339 timestamp | No | |
> | `updatedAt` | RFC 3339 timestamp | No | |
> | `creator` | [Subject](#type-gitpod-v1-subject) | No | creator is the identity of the creator of the secret |
> | `filePath` | string | One of `mount` | absolute path to the file where the secret is mounted |
> | `environmentVariable` | boolean | One of `mount` | secret will be created as an Environment Variable with the same name as the secret |
> | `containerRegistryBasicAuthHost` | string | One of `mount` | secret will be mounted as a registry secret Constraints: `string.uri=true`. |
> | `apiOnly` | boolean | One of `mount` | api\_only indicates the secret is only available via API/CLI |
> | `scope` | [SecretScope](#type-gitpod-v1-secret-scope) | No | |
> | `credentialProxy` | [CredentialProxy](#type-gitpod-v1-secret-credential-proxy) | No | credential\_proxy configures transparent credential injection via the credential proxy. When set, the credential proxy intercepts HTTPS traffic to the target hosts and replaces the dummy mounted value with the real value in the specified HTTP header. The real secret value is never exposed in the environment. This field is orthogonal to mount - a secret can be both mounted and proxied at the same time. |
> | `source` | [Source](#type-gitpod-v1-secret-source) | No | Source of the secret |

> [accordion] CredentialProxy
>
> CredentialProxy describes how the credential proxy should inject this
> secret into outgoing HTTPS requests.
>
> `gitpod.v1.Secret.CredentialProxy`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `targetHosts` | array of string | No | target\_hosts lists the hostnames to intercept (for example "github.com" or "\*.github.com"). Wildcards are subdomain-only and do not match the apex domain. |
> | `header` | string | No | header is the HTTP header name to inject (e.g. "Authorization"). |

> [accordion] Source
>
> Source defines
>
> `gitpod.v1.Secret.Source`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `verbatim` | boolean | No | |
> | `oidcJfrog` | [OidcJFrog](#type-gitpod-v1-secret-source-oidc-j-frog) | No | |

> [accordion] OidcJFrog
>
> `gitpod.v1.Secret.Source.OidcJFrog`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `host` | string | No | Constraints: `cel.expression=this.matches("^([A-Za-z0-9]([A-Za-z0-9-]&#123;0,61&#125;[A-Za-z0-9])?[.])*[A-Za-z0-9]([A-Za-z0-9-]&#123;0,61&#125;[A-Za-z0-9])?(:([1-9][0-9]&#123;0,3&#125;\|[1-5][0-9]&#123;4&#125;\|6[0-4][0-9]&#123;3&#125;\|65[0-4][0-9]&#123;2&#125;\|655[0-2][0-9]\|6553[0-5]))?$"), cel.id=host_or_host_port, cel.message=host must be a hostname or IP address with optional port, string.min_len=1`. |
> | `providerName` | string | No | Constraints: `string.min_len=1`. |

> [accordion] SecretScope
>
> `gitpod.v1.SecretScope`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `projectId` | string | No | project\_id is the Project ID this Secret belongs to Constraints: `string.uuid=true`. |
> | `userId` | string | No | user\_id is the User ID this Secret belongs to Constraints: `string.uuid=true`. |
> | `organizationId` | string | No | organization\_id is the Organization ID this Secret belongs to Constraints: `string.uuid=true`. |
> | `serviceAccountId` | string | No | service\_account\_id is the Service Account ID this Secret belongs to Constraints: `string.uuid=true`. |

> [accordion] Subject
>
> `gitpod.v1.Subject`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `id` | string | No | id is the UUID of the subject Constraints: `ignore=1, string.uuid=true`. |
> | `principal` | [Principal](#enum-gitpod-v1-principal) | No | Principal is the principal of the subject Constraints: `enum.defined_only=true`. |

> [accordion] Principal
>
> | Value | Number | Description |
> | - | -: | - |
> | `PRINCIPAL_UNSPECIFIED` | 0 | |
> | `PRINCIPAL_ACCOUNT` | 1 | |
> | `PRINCIPAL_USER` | 2 | |
> | `PRINCIPAL_RUNNER` | 3 | |
> | `PRINCIPAL_ENVIRONMENT` | 4 | |
> | `PRINCIPAL_SERVICE_ACCOUNT` | 5 | |
> | `PRINCIPAL_RUNNER_MANAGER` | 6 | |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.