# Publishing your application with the AWS SAM CLI
To make your AWS SAM application available for others to find and deploy, you can use the AWS SAM CLI to publish it to the AWS Serverless Application Repository. To publish your application using the AWS SAM CLI, you must define it using an AWS SAM template. You also must have tested it locally or in the AWS Cloud.
Follow the instructions in this topic to create a new application, create a new version of an existing application, or update the metadata of an existing application. (What you do depends on whether the application already exists in the AWS Serverless Application Repository, and whether any application metadata is changing.) For more information about application metadata, see [AWS SAM template Metadata section properties](serverless-sam-template-publishing-applications-metadata-properties.md).
## Prerequisites
Before you publish an application to the AWS Serverless Application Repository using the AWS SAM CLI, you must have the following:
+ The AWS SAM CLI installed. For more information, see [Install the AWS SAM CLI](install-sam-cli.md). To determine whether the AWS SAM CLI is installed, run the following command:
```
sam --version
```
+ A valid AWS SAM template.
+ Your application code and dependencies that the AWS SAM template references.
+ A semantic version, required only to share your application publicly. This value can be as simple as 1.0.
+ A URL that points to your application's source code.
+ A `README.md` file. This file should describe how customers can use your application and how to configure it before deploying it in their own AWS accounts.
+ A `LICENSE.txt` file, required only to share your application publicly.
+ If your application contains any nested applications, you must have already published them to the AWS Serverless Application Repository.
+ A valid Amazon Simple Storage Service (Amazon S3) bucket policy that grants the service read permissions for artifacts that you upload to Amazon S3 when you package your application. To set up this policy, do the following:
1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).
1. Choose the name of the Amazon S3 bucket that you used to package your application.
1. Choose **Permissions**.
1. On the **Permissions** tab, under **Bucket policy**, choose **Edit**.
1. On the **Edit bucket policy** page, paste the following policy statement into the **Policy** editor. In the policy statement, make sure to use your bucket name in the `Resource` element and your AWS account ID in the `Condition` element. The expression in the `Condition` element ensures that AWS Serverless Application Repository has permission to access only applications from the specified AWS account. For more information about policy statements, see [IAM JSON policy elements reference](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html) in the *IAM User Guide*.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "serverlessrepo.amazonaws.com"
},
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::/*",
"Condition" : {
"StringEquals": {
"aws:SourceAccount": "123456789012"
}
}
}
]
}
```
------
1. Choose **Save changes**.
## Publishing a new application
### Step 1: Add a `Metadata` section to the AWS SAM template
First, add a `Metadata` section to your AWS SAM template. Provide the application information to be published to the AWS Serverless Application Repository.
The following is an example `Metadata` section:
```
Metadata:
AWS::ServerlessRepo::Application:
Name: my-app
Description: hello world
Author: user1
SpdxLicenseId: Apache-2.0
LicenseUrl: LICENSE.txt
ReadmeUrl: README.md
Labels: ['tests']
HomePageUrl: https://github.com/user1/my-app-project
SemanticVersion: 0.0.1
SourceCodeUrl: https://github.com/user1/my-app-project
Resources:
HelloWorldFunction:
Type: AWS::Lambda::Function
Properties:
...
CodeUri: source-code1
...
```
For more information about the `Metadata` section of the AWS SAM template, see [AWS SAM template Metadata section properties](serverless-sam-template-publishing-applications-metadata-properties.md).
### Step 2: Package the application
Run the following AWS SAM CLI command, which uploads the application's artifacts to Amazon S3 and outputs a new template file called `packaged.yaml`:
```
sam package --output-template-file packaged.yaml --s3-bucket
```
You use the `packaged.yaml` template file in the next step to publish the application to the AWS Serverless Application Repository. This file is similar to the original template file (`template.yaml`), but it has a key difference—the `CodeUri`, `LicenseUrl`, and `ReadmeUrl` properties point to the Amazon S3 bucket and objects that contain the respective artifacts.
The following snippet from an example `packaged.yaml` template file shows the `CodeUri` property:
```
MySampleFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: s3://bucketname/fbd77a3647a4f47a352fcObjectGUID
...
```
### Step 3: Publish the application
To publish a private version of your AWS SAM application to the AWS Serverless Application Repository, run the following AWS SAM CLI command:
```
sam publish --template packaged.yaml --region us-east-1
```
The output of the `sam publish` command includes a link to your application on the AWS Serverless Application Repository. You can also go directly to the [AWS Serverless Application Repository landing page](https://serverlessrepo.aws.amazon.com/applications) and search for your application.
### Step 4: Share the application (optional)
By default, your application is set to private, so it isn't visible to other AWS accounts. To share your application with others, you must either make it public or grant permission to a specific list of AWS accounts.
For information about sharing your application using the AWS CLI, see [AWS Serverless Application Repository Resource-Based Policy Examples](https://docs.aws.amazon.com/serverlessrepo/latest/devguide/security_iam_resource-based-policy-examples.html) in the *AWS Serverless Application Repository Developer Guide*. For information on sharing your application using the AWS Management Console, see [Sharing an Application](https://docs.aws.amazon.com/serverlessrepo/latest/devguide/serverlessrepo-how-to-publish.html#share-application) in the *AWS Serverless Application Repository Developer Guide*.
## Publishing a new version of an existing application
After you've published an application to the AWS Serverless Application Repository, you might want to publish a new version of it. For example, you might have changed your Lambda function code or added a new component to your application architecture.
To update an application that you've previously published, publish the application again using the same process detailed previously. In the `Metadata` section of the AWS SAM template file, provide the same application name that you originally published it with, but include a new `SemanticVersion` value.
For example, consider an application published with the name `SampleApp` and a `SemanticVersion` of `1.0.0`. To update that application, the AWS SAM template must have the application name `SampleApp` and a `SemanticVersion` of `1.0.1` (or anything other than `1.0.0`).
## Additional topics
+ [AWS SAM template Metadata section properties](serverless-sam-template-publishing-applications-metadata-properties.md)
# AWS SAM template Metadata section properties
`AWS::ServerlessRepo::Application` is a metadata key that you can use to specify application information that you want published to the AWS Serverless Application Repository.
**Note**
CloudFormation [intrinsic functions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html) aren't supported by the `AWS::ServerlessRepo::Application` metadata key.
## Properties
This table provides information about the properties of the `Metadata` section of the AWS SAM template. This section is required to publish applications to the AWS Serverless Application Repository using the AWS SAM CLI.
****
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| Name | String | TRUE | The name of the application. Minimum length=1. Maximum length=140. Pattern: `"[a-zA-Z0-9\\-]+";` |
| Description | String | TRUE | The description of the application. Minimum length=1. Maximum length=256. |
| Author | String | TRUE | The name of the author publishing the application. Minimum length=1. Maximum length=127. Pattern: `"^[a-z0-9](([a-z0-9]\|-(?!-))*[a-z0-9])?$";` |
| SpdxLicenseId | String | FALSE | A valid license identifier. To view the list of valid license identifiers, see [SPDX License List](https://spdx.org/licenses/) on the Software Package Data Exchange (SPDX) website. |
| LicenseUrl | String | FALSE | The reference to a local license file, or an Amazon S3 link to a license file, that matches the spdxLicenseID value of your application. An AWS SAM template file that hasn't been packaged using the `sam package` command can have a reference to a local file for this property. However, for an application to be published using the `sam publish` command, this property must be a reference to an Amazon S3 bucket. Maximum size: 5 MB. You must provide a value for this property in order to make your application public. Note that you cannot update this property after your application has been published. So, to add a license to an application, you must either delete it first, or publish a new application with a different name. |
| ReadmeUrl | String | FALSE | The reference to a local readme file or an Amazon S3 link to the readme file that contains a more detailed description of the application and how it works. An AWS SAM template file that hasn't been packaged using the `sam package` command can have a reference to a local file for this property. However, to be published using the `sam publish` command, this property must be a reference to an Amazon S3 bucket. Maximum size: 5 MB. |
| Labels | String | FALSE | The labels that improve discovery of applications in search results. Minimum length=1. Maximum length=127. Maximum number of labels: 10. Pattern: `"^[a-zA-Z0-9+\\-_:\\/@]+$";` |
| HomePageUrl | String | FALSE | A URL with more information about the application—for example, the location of your GitHub repository for the application. |
| SemanticVersion | String | FALSE | The semantic version of the application. For the Semantic Versioning specification, see the [Semantic Versioning](https://semver.org/) website. You must provide a value for this property in order to make your application public. |
| SourceCodeUrl | String | FALSE | A link to a public repository for the source code of your application. |
## Use cases
This section lists the use cases for publishing applications, along with the `Metadata` properties that are processed for that use case. Properties that are *not* listed for a given use case are ignored.
+ **Creating a new application** – A new application is created if there is no application in the AWS Serverless Application Repository with a matching name for an account.
+ `Name`
+ `SpdxLicenseId`
+ `LicenseUrl`
+ `Description`
+ `Author`
+ `ReadmeUrl`
+ `Labels`
+ `HomePageUrl`
+ `SourceCodeUrl`
+ `SemanticVersion`
+ The content of the AWS SAM template (for example, any event sources, resources, and Lambda function code)
+ **Creating an application version** – An application version is created if there is already an application in the AWS Serverless Application Repository with a matching name for an account *and* the SemanticVersion *is* changing.
+ `Description`
+ `Author`
+ `ReadmeUrl`
+ `Labels`
+ `HomePageUrl`
+ `SourceCodeUrl`
+ `SemanticVersion`
+ The content of the AWS SAM template (for example, any event sources, resources, and Lambda function code)
+ **Updating an application** – An application is updated if there is already an application in the AWS Serverless Application Repository with a matching name for an account *and* the SemanticVersion *is not* changing.
+ `Description`
+ `Author`
+ `ReadmeUrl`
+ `Labels`
+ `HomePageUrl`
## Example
The following is an example `Metadata` section:
```
Metadata:
AWS::ServerlessRepo::Application:
Name: my-app
Description: hello world
Author: user1
SpdxLicenseId: Apache-2.0
LicenseUrl: LICENSE.txt
ReadmeUrl: README.md
Labels: ['tests']
HomePageUrl: https://github.com/user1/my-app-project
SemanticVersion: 0.0.1
SourceCodeUrl: https://github.com/user1/my-app-project
```