Add the documentation for usecase (#241)

Author: Noah Hanjun Lee

docs/concepts/deploy.yml.md

@@ -1,26 +1,30 @@
 # deploy.yml
 
-Gitploy configures a pipeline with a simple, easy‑to‑read file that you commit to your git repository. *The configuration file must be at the head of the default branch.* The default path is `deploy.yml` at the root directory, but you can replace the file path in the settings tab of Gitploy. You can check the [document](../references/deploy.yml.md) for the specification of the configuration file.
+Gitploy configures a pipeline with a simple, easy‑to‑read file that you commit to your git repository. *The configuration file must be at the head of the default branch.* The default path is `deploy.yml` at the root directory, but you can replace the file path in the settings tab of Gitploy. You can check the [documentation](../references/deploy.yml.md) for the specification of the configuration file and also references [Use Cases](../tasks/usecases.md).
 
-## Environments
+## Features
+### Multi Environment
 
-You can configure each environments, respectively. The configuration have to be under the `evns` field. The following example show each environments have different configuration.
+For multi-environment, Gitploy provides you can make different pipelines for each environment, respectively. The configuration has to be defined under the `envs` field. The following example shows each environment has a different configuration.
 
 ```yaml
 envs:
-  - name: dev
+  # Development environment
+  - name: development
     auto_merge: false
     required_contexts: []
+
+  # Production environment
   - name: production
     auto_merge: true
     required_contexts: 
       - test
       - docker-image
 ```
 
-## Parameters of GitHub deployment API
+### Parameters of GitHub deployment API
 
-Internally, Gitploy posts a deployment to GitHub [deployments API](https://docs.github.com/en/rest/reference/repos#create-a-deployment) with parameters from the configuration file. These parameter help you can verify the artifact before you start to deploy. The configuration file provides fields to configure all parameters of GitHub deployment API. You can check the [document](../references/deploy.yml.md) for the detail.
+Internally, Gitploy posts a deployment to GitHub [deployments API](https://docs.github.com/en/rest/reference/repos#create-a-deployment) with parameters from the configuration file. These parameters help you can verify the artifact before you start to deploy.  The configuration provides fields to set all parameters of GitHub deployment API. You can check the [document](../references/deploy.yml.md) for the detail.
 
 ```yaml
 envs:
@@ -33,7 +37,7 @@ envs:
       - integration-test
     production_environment: true
 ```
-## Review
+### Review
 
 Gitploy provides the review process. You can list up to users on the configuration file. You can check the [document](./review.md) for the detail.
 

docs/tasks/first-deployment.md

@@ -0,0 +1,44 @@
+# Use Cases
+
+## Deploying the head of the `main` branch
+
+The general way of deployment is deploying the head of the `main` branch that has only verified commits. To constrain deploying only the head of the `main` branch, we can use the `auto_merge` parameter of GitHub [deployment API](https://docs.github.com/en/rest/reference/repos#create-a-deployment) to ensure that the deployment is the head of the branch, and set `deployable_ref` field with the `main`.
+
+```yaml
+envs:
+  - name: production
+    auto_merge: true
+    deployable_ref: main
+    production_environment: true
+```
+
+## Deploying with the version
+
+The versioning is the general way to specify the artifact or the commit, and GitHub provides the release page for versioning. If your team (or organization) wants to constrain deploying with the version, you can use the `deployable_ref` field like below.
+
+```yaml
+envs:
+  - name: production
+    auto_merge: false
+    deployable_ref: "v.*\..*\..*"       # Semantic versioning
+    production_environment: true
+```
+
+## Deploying the artifact
+
+The artifact could be a binary file from compiling source codes or a docker image, which means we have to build the artifact before we deploy. The commit status is the best way to verify if the artifact exists or not. The builder, such as GitHub Action or Circle CI, posts the commit status after building the artifact, and we can verify it by the `required_contexts` parameter when we deploy. You can reference the `deploy.yml` of Gitploy.
+
+```yaml
+envs:
+  - name: production
+    auto_merge: false
+    required_contexts:
+      - "publish-image"         # The commit status of building the artifact.
+    production_environment: true
+```
+
+## Questions?
+
+We are always happy to help with questions you might have. You can post questions or comments to our [community](https://github.com/gitploy-io/gitploy/discussions). 
+
+And we are very welcome to share your deployment pipeline at our [community](https://github.com/gitploy-io/gitploy/discussions).

docs/tasks/usecases.md

@@ -25,7 +25,7 @@ nav:
   - Tasks:
     - Installation: tasks/installation.md
     - Database: tasks/database.md
-    - "First Deployment": tasks/first-deployment.md
+    - "Use Cases": tasks/usecases.md
     - Integration: tasks/integration.md
   - References: 
     - Configurations: references/configurations.md