> ## 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.
# Upsert Automations File
> Upserts the automations file for the given environment.
`Unary` ยท [`Environment Automations`](/docs/api-reference/generated/environment-automation/overview)
Upserts the automations file for the given environment.
Use this method to:
* Configure environment automations
* Update automation settings
* Manage automation files
### Examples
* Update automations file:
Updates or creates the automations configuration.
```yaml theme={null}
environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
automationsFile:
services:
web-server:
name: "Web Server"
description: "Development web server"
commands:
start: "npm run dev"
ready: "curl -s http://localhost:3000"
triggeredBy:
- postDevcontainerStart
tasks:
build:
name: "Build Project"
description: "Builds the project artifacts"
command: "npm run build"
triggeredBy:
- postEnvironmentStart
```
## Endpoint
```text theme={null}
POST /api/gitpod.v1.EnvironmentAutomationService/UpsertAutomationsFile
```
Send a Bearer token as described in [Authentication](/docs/api-reference#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=
curl --request POST \
--url "$ONA_HOST/api/gitpod.v1.EnvironmentAutomationService/UpsertAutomationsFile" \
--header "Authorization: Bearer $ONA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"environmentId": ""
}'
```
```python Python theme={null}
import gitpod.v1.environment_automation_pb2 as environment_automation_pb2
from ona_sdk import create_client_from_env
ona = create_client_from_env()
request = environment_automation_pb2.UpsertAutomationsFileRequest(
environment_id="",
)
response = ona.services.environment_automation.upsert_automations_file(request)
print(response)
```
```typescript TypeScript theme={null}
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { UpsertAutomationsFileRequestSchema } from "@gitpod/sdk/gitpod/v1/environment_automation_pb";
async function main() {
const ona = createClientFromEnv();
const request = create(UpsertAutomationsFileRequestSchema, {
environmentId: "",
});
const response = await ona.services.environmentAutomation.upsertAutomationsFile(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.UpsertAutomationsFileRequest{
EnvironmentId: "",
})
response, err := ona.Services.EnvironmentAutomation.UpsertAutomationsFile(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
```
```json Request body theme={null}
{
"environmentId": ""
}
```
## Request
`gitpod.v1.UpsertAutomationsFileRequest`
| Field | Type | Required | Description |
| ----------------- | --------------------------------------------------- | -------- | -------------------------------- |
| `environmentId` | string | No | Constraints: `string.uuid=true`. |
| `automationsFile` | [AutomationsFile](#type-gitpod-v1-automations-file) | No | |
## Response
`gitpod.v1.UpsertAutomationsFileResponse`
| Field | Type | Required | Description |
| ------------------- | --------------- | -------- | ----------- |
| `updatedServiceIds` | array of string | No | |
| `updatedTaskIds` | array of string | No | |
## Related types
WARN: Do not remove any field here, as it will break reading automation yaml files. We error if there are any
unknown fields in the yaml (to ensure the yaml is correct), but would break if we removed any fields.
This includes marking a field as "reserved" in the proto file, this will also break reading the yaml.
`gitpod.v1.AutomationsFile`
| Field | Type | Required | Description |
| ---------- | -------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------ |
| `services` | map of string to [Service](#type-gitpod-v1-automations-file-service) | No | Constraints: `map.keys.string.pattern=^[a-zA-Z0-9_-]{1,128}$`. |
| `tasks` | map of string to [Task](#type-gitpod-v1-automations-file-task) | No | Constraints: `map.keys.string.pattern=^[a-zA-Z0-9_-]{1,128}$`. |
`gitpod.v1.AutomationsFile.Service`
| Field | Type | Required | Description |
| ------------------ | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | No | Constraints: `string.min_len=1`. |
| `description` | string | No | |
| `commands` | Commands | No | |
| `triggeredBy` | array of string | No | Constraints: `repeated.items.string.in=manual, repeated.items.string.in=postDevcontainerStart, repeated.items.string.in=postEnvironmentStart, repeated.items.string.in=prebuild`. |
| `runsOn` | RunsOn | No | |
| `role` | string | No | Constraints: `string.in=, string.in=ai-agent, string.in=default, string.in=editor`. |
| `readinessTimeout` | duration string | No | Constraints: `duration.lte.seconds=86400`. |
`gitpod.v1.AutomationsFile.Task`
| Field | Type | Required | Description |
| ------------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | No | Constraints: `string.min_len=1`. |
| `description` | string | No | |
| `command` | string | No | Constraints: `string.min_len=1`. |
| `dependsOn` | array of string | No | |
| `triggeredBy` | array of string | No | Constraints: `repeated.items.string.in=manual, repeated.items.string.in=postDevcontainerStart, repeated.items.string.in=postEnvironmentStart, repeated.items.string.in=prebuild`. |
| `runsOn` | RunsOn | No | |
| `prebuildRequiresSuccess` | boolean | No | prebuild\_requires\_success controls whether a non-successful outcome of this task should fail the prebuild. When true and the task is triggered by a prebuild trigger, any terminal phase other than SUCCEEDED will cause the prebuild to fail. Defaults to false. |