End of support notice: On October 7, 2026, AWS will end support for AWS Proton. After October 7, 2026, you will no longer be able to access the AWS Proton console or AWS Proton resources. Your deployed infrastructure will remain intact. For more information, see [AWS Proton Service Deprecation and Migration Guide](https://docs.aws.amazon.com/proton/latest/userguide/proton-end-of-support.html).
# Service sync configurations
With service sync, you can configure and deploy your AWS Proton services using Git. You can use service sync to manage initial deployments and updates to your AWS Proton service with a configuration defined in a Git repository. Through Git, you can use features like version tracking and pull requests to configure, manage, and deploy your services. Service sync combines AWS Proton and Git to help you provision standardized infrastructure that is defined and managed through AWS Proton templates. It manages service definitions in your Git repository and reduces tool switching. Compared to using Git alone, the standardization of templates and deployment in AWS Proton helps you spend less time managing your infrastructure. AWS Proton also provides higher transparency and auditability for both developers and platform teams.
## AWS Proton OPS file
The `proton-ops` file defines where AWS Proton finds the spec file that's used to update your service instance. It also defines what order to update service instances in and when to promote changes from one instance to another.
The `proton-ops` file supports syncing a service instance using the spec file, or multiple spec files, found in your linked repository. You can do this by defining a sync block in the `proton-ops` file, like in the following example.
**Example ./configuration/proton-ops.yaml:**
```
sync:
services:
frontend-svc:
alpha:
branch: dev
spec: ./frontend-svc/test/frontend-spec.yaml
beta:
branch: dev
spec: ./frontend-svc/test/frontend-spec.yaml
gamma:
branch: pre-prod
spec: ./frontend-svc/pre-prod/frontend-spec.yaml
prod-one:
branch: prod
spec: ./frontend-svc/prod/frontend-spec-second.yaml
prod-two:
branch: prod
spec: ./frontend-svc/prod/frontend-spec-second.yaml
prod-three:
branch: prod
spec: ./frontend-svc/prod/frontend-spec-second.yaml
```
In the preceding example, `frontend-svc` is the service name, and `alpha`, `beta`, `gamma`, `prod-one`, `prod-two`, and `prod-three` are the instances.
The `spec` file can be all of the instances or a subset of the instances that are defined within the `proton-ops` file. However, at minimum, it must have the instance defined within the branch and the spec it's syncing from. If instances aren't defined in the `proton-ops` file, with the specific branch and `spec` file location, service sync won't create or update those instances.
The following examples show what the `spec` files look like. Remember, the `proton-ops` file is synced from these `spec` files.
**Example `./frontend-svc/test/frontend-spec.yaml`:**
```
proton: "ServiceSpec"
instances:
- name: "alpha"
environment: "frontend-env"
spec:
port: 80
desired_count: 1
task_size: "x-small"
image: "public.ecr.aws/z9d2n7e1/nginx:1.21.0"
- name: "beta"
environment: "frontend-env"
spec:
port: 80
desired_count: 1
task_size: "x-small"
image: "public.ecr.aws/z9d2n7e1/nginx:1.21.0"
```
**Example `./frontend-svc/pre-prod/frontend-spec.yaml`:**
```
proton: "ServiceSpec"
instances:
- name: "gamma"
environment: "frontend-env"
spec:
port: 80
desired_count: 1
task_size: "x-small"
image: "public.ecr.aws/z9d2n7e1/nginx:1.21.0"
```
**Example `./frontend-svc/prod/frontend-spec-second.yaml`:**
```
proton: "ServiceSpec"
instances:
- name: "prod-one"
environment: "frontend-env"
spec:
port: 80
desired_count: 1
task_size: "x-small"
image: "public.ecr.aws/z9d2n7e1/nginx:1.21.0"
- name: "prod-two"
environment: "frontend-env"
spec:
port: 80
desired_count: 1
task_size: "x-small"
image: "public.ecr.aws/z9d2n7e1/nginx:1.21.0"
- name: "prod-three"
environment: "frontend-env"
spec:
port: 80
desired_count: 1
task_size: "x-small"
image: "public.ecr.aws/z9d2n7e1/nginx:1.21.0"
```
If an instance doesn't sync, and there's a continuing issue when trying to sync it, calling the [https://docs.aws.amazon.com//proton/latest/APIReference/API_GetServiceInstanceSyncStatus.html](https://docs.aws.amazon.com//proton/latest/APIReference/API_GetServiceInstanceSyncStatus.html) API may help in resolving the issue.
**Note**
Customers using service sync are still restricted by AWS Proton limits.
**Blockers**
By syncing your service using AWS Proton service sync, you can update your service spec and create and update service instances from your Git repository. However, there may be moments where you need to update a service or instance manually through the AWS Management Console or AWS CLI.
AWS Proton helps avoid overwriting any manual changes you make through the AWS Management Console or AWS CLI, such as updating a service instance or deleting a service instance. To achieve this, AWS Proton automatically creates a service sync blocker by disabling service sync when it detects a manual change.
To get all the blockers associated with a service, you must do the following in order for each `serviceInstance` associated to the service:
+ Call the `getServiceSyncBlockerSummary` API with only the `serviceName`.
+ Call the `getServiceSyncBlockerSummary` API with the `serviceName` and `serviceInstanceName`.
This returns a list of the most recent blockers and the status associated with them. If any blockers are marked **ACTIVE**, you must resolve them by calling the `UpdateServiceSyncBlocker` API with the `blockerId` and `resolvedReason` for each one.
If you manually update or create a service instance, AWS Proton creates a service sync blocker on the service instance. AWS Proton continues to sync all other service instances, but disables the syncing of this service instance until the blocker is resolved. If you delete a service instance from a service, AWS Proton creates a service sync blocker on the service. This prevents AWS Proton from syncing any of the service instances until the blocker has been resolved.
After you have all the active blockers, you must resolve them by calling the `UpdateServiceSyncBlocker` API with the `blockerId` and `resolvedReason` for each of the active blockers.
Using the AWS Management Console, you can determine if a service sync is disabled by navigating to AWS Proton and choosing the **Service Sync** tab. If the service or service instances are blocked, an **Enable** button appears. To enable service sync, choose **Enable**.
**Topics**
+ [AWS Proton OPS file](#service-sync-ops)
+ [Create a service sync configuration](create-service-sync.md)
+ [View configuration details for a service sync](get-service-sync.md)
+ [Edit a service sync configuration](update-service-sync.md)
+ [Delete a service sync configuration](delete-service-sync.md)
# Create a service sync configuration
You can create a service sync configuration using the console or AWS CLI.
------
#### [ AWS Management Console ]
1. On the **Choose a service template** page, select a template and choose **Configure**.
1. On the **Configure service** page, in the **Service details** section, enter a new **Service name**.
1. (Optional) Enter a description for the service.
1. In the **Application source code repository** section, choose **Choose a linked Git repository** to select a repository you've already linked with AWS Proton. If you don't already have a linked repository, choose **Link another Git repository** and follow the instructions in [Create a link to your repository](https://docs.aws.amazon.com//proton/latest/userguide/ag-create-repo.html).
1. For **Repository**, choose the name of your source code repository from the list.
1. For **Branch**, choose the name of the repository branch for your source code from the list.
1. (Optional) In the **Tags** section, choose **Add new tag** and enter a key and value to create a customer managed tag.
1. Choose **Next**.
1. On the **Configure service instances** page, in the **Service definition source** section, select **Sync your service from Git**.
1. In the **Service definition files** section, if you want AWS Proton to create your `proton-ops` file, select **I want AWS Proton to create the files**. With this option, AWS Proton creates the `spec` and `proton-ops` file in the locations you specify. Select **I am providing my own files** to create your own OPS file.
1. In the **Service definition repository** section, choose **Choose a linked Git repository** to select a repository you've already linked with AWS Proton.
1. For **Repository name**, choose the name of your source code repository from the list.
1. For **`proton-ops` file branch**, choose the name of your branch from the list where AWS Proton will put your OPS and spec file.
1. In the **Service instances** section, each field is automatically filled based on the values in the `proton-ops` file.
1. Choose **Next** and review your inputs.
1. Choose **Create**.
------
#### [ AWS CLI ]
**Create a service sync configuration using the AWS CLI**
+ Run the following command.
```
$ aws proton create-service-sync-config \
--resource "service-arn" \
--repository-provider "GITHUB" \
--repository "example/proton-sync-service" \
--ops-file-branch "main" \
--proton-ops-file "./configuration/custom-proton-ops.yaml" (optional)
```
The response is as follows.
```
{
"serviceSyncConfig": {
"branch": "main",
"filePath": "./configuration/custom-proton-ops.yaml",
"repositoryName": "example/proton-sync-service",
"repositoryProvider": "GITHUB",
"serviceName": "service name"
}
}
```
------
# View configuration details for a service sync
You can view the configuration details data for a service sync using the console or AWS CLI.
------
#### [ AWS Management Console ]
**Use the console to view configuration details for a service sync**
1. In the navigation pane, choose **Services**.
1. To view detail data, choose the name of a service that you created a service sync configuration for.
1. In the detail page for the service, select the **Service sync** tab to view the configuration detail data for the service sync.
------
#### [ AWS CLI ]
**Use the AWS CLI to get a synced service.**
Run the following command.
```
$ aws proton get-service-sync-config \
--service-name "service name"
```
The response is as follows.
```
{
"serviceSyncConfig": {
"branch": "main",
"filePath": "./configuration/custom-proton-ops.yaml",
"repositoryName": "example/proton-sync-service",
"repositoryProvider": "GITHUB",
"serviceName": "service name"
}
}
```
**Use the AWS CLI to get the service sync status.**
Run the following command.
```
$ aws proton get-service-sync-status \
--service-name "service name"
```
------
# Edit a service sync configuration
You can edit a service sync configuration using the console or AWS CLI.
------
#### [ AWS Management Console ]
Edit a service sync configuration using the console.
1. In the navigation pane, choose **Services**.
1. To view detail data, choose the name of a service that you created a service sync configuration for.
1. On the service detail page, choose the **Service sync** tab.
1. In the **Service sync** section, choose **Edit**.
1. On the **Edit** page, update the information you want to edit and then choose **Save**.
------
#### [ AWS CLI ]
**The following example command and response shows how you can edit a service sync configuration using the AWS CLI.**
Run the following command.
```
$ aws proton update-service-sync-config \
--service-name "service name" \
--repository-provider "GITHUB" \
--repository "example/proton-sync-service" \
--ops-file-branch "main" \
--ops-file "./configuration/custom-proton-ops.yaml"
```
The response is as follows.
```
{
"serviceSyncConfig": {
"branch": "main",
"filePath": "./configuration/custom-proton-ops.yaml",
"repositoryName": "example/proton-sync-service",
"repositoryProvider": "GITHUB",
"serviceName": "service name"
}
}
```
------
# Delete a service sync configuration
You can delete a service sync configuration using the console or AWS CLI.
------
#### [ AWS Management Console ]
**Delete a service sync configuration using the console**
1. On the service details page, choose the **Service sync** tab.
1. In the **Service sync details** section, choose **Disconnect** to disconnect your repository. After your repository is disconnected, we no longer sync the service from that repository.
------
#### [ AWS CLI ]
**The following example commands and responses show how to use the AWS CLI to delete service synced configurations.**
Run the following command.
```
$ aws proton delete-service-sync-config \
--service-name "service name"
```
The response is as follows.
```
{
"serviceSyncConfig": {
"branch": "main",
"filePath": "./configuration/custom-proton-ops.yaml",
"repositoryName": "example/proton-sync-service",
"repositoryProvider": "GITHUB",
"serviceName": "service name"
}
}
```
**Note**
Service sync doesn't delete service instances. It only deletes the configuration.
------