doc: init documentation for Gitploy (#82)

Noah Hanjun Lee · web-flow · commit 87fc2f2328c0 · 2021-09-06T22:23:04.000+09:00
* Index

* 'how it work'

* deploy.yml

* Set advanced features: `pymdownx`

* Self-hosted server

* Deployment

* First deployment

* Configurations
diff --git a/docs/concepts/chatops.md b/docs/concepts/chatops.md
@@ -1,11 +1,13 @@
 # Chatops
 
-ChatOps is a term that’s been coined recently to refer to using chat services, such as Slack or Microsoft Teams, to deploy or run some operations. And Gitploy also supports Chatops as a helper tool to increase speed and accessibility. For example, if the operator wants to rollback out of the office by the incident, he(or she) can rollback easily with the Chatops command.
+ChatOps is a term that’s been coined recently to refer to using chat services, such as Slack or Microsoft Teams, to deploy or run some operations. Gitploy also supports Chatops as a helper tool. 
+
+![Slack deploy](../images//slack-deploy.png)
 
 ## Integration
 
-Currently, *Gitploy supports Slack*, but it will support Microsoft Teams and other chat services near the corner. 
+Currently, Gitploy supports Slack only, but it will support Microsoft Teams near the corner. 
 
 ## Limit
 
-Cloud doesn't support Chatops. *Only self-managed is available.* Please, check [how to integrate with Chatops](../tasks/integration.md).
+Cloud doesn't support Chatops. *Only self-hosted is available.* You can check [how to integrate with Chatops](../tasks/integration.md) for details.
diff --git a/docs/concepts/deploy.yml.md b/docs/concepts/deploy.yml.md
@@ -1,2 +1,40 @@
 # deploy.yml
 
+ Gitploy configures a pipeline with a simple, easy‑to‑read file that you commit to your git repository. 
+
+## Features
+
+### Parameters for Github deployment
+
+Github deployments offer a few configurable [parameters](https://docs.github.com/en/rest/reference/repos#create-a-deployment--parameters). You can configure these parameters in the deploy.yml file. You can check details in the reference.
+
+Here is the example to deploy based on tag:
+
+```yaml
+envs:
+  - name: prod
+    auto_merge: false
+    required_contexts:
+      - "go-test"
+      - "react-test"
+      - "publish-image"
+    production_environment: true
+```
+
+### Approval
+
+Gitploy supports the approval step to protect to deploy until it matches the required approving approvals.
+
+```yaml
+envs:
+  - name: prod
+    approval:
+      enabled: true
+      required_count: 1
+```
+
+## File Location
+
+When you activate the repository in Gitploy, the default path is `deploy.yml` at the root. But you can replace the file path in the settings tab in Gitploy.
+
+*Note that Gitploy always reads the file from the head of the default branch.*
diff --git a/docs/concepts/deployment.md b/docs/concepts/deployment.md
@@ -0,0 +1,15 @@
+# Deployment
+
+Gitploy provides two types of deployment: Deploy and Rollback.
+
+## Deploy
+
+Deploying is the primary feature of Gitploy. When you deploy, you have to select the environment and the `ref`: for the environment, you can choose one of the environments listed in the `deploy.yml`, and for the `ref`, you can choose one of commit, branch, and tag.
+
+With approval, Gitploy waits until it matches the required approving approvals. So you have to confirm to deploy after approval.
+
+## Rollback
+
+Rollback is the best way to recover while you fix the problems. Gitploy supports the rollback. You can choose one of the successful deployments to rollback. 
+
+*Note that if the ref of the selected deployment is a branch, Gitploy automatically references the commit SHA to prevent deploying the head of the branch.*
diff --git a/docs/concepts/how-it-work.md b/docs/concepts/how-it-work.md
@@ -0,0 +1,44 @@
+# How it works
+
+Gitploy builds the system around GitHub [deployment API](https://docs.github.com/en/rest/reference/repos#deployments). **It's an event-driven decoupled way to deploy your code.** Internally, Gitploy creates a new Github deployment resource, and Github dispatches a deployment event that external services can listen for and act. It enables developers and organizations to build loosely coupled tooling. 
+
+This approach has several pros:
+
+* Replace deployment tools easily without changing your deployment pipeline. 
+* Easy to implement details of deploying different types of applications (e.g., web, native).
+
+Below is a simple diagram for how these interactions would work:
+
+```
++---------+             +--------+             +---------+         +-------------+
+| Gitploy |             | GitHub |             |  Tools  |         | Your Server |
++---------+             +--------+             +---------+         +-------------+
+     |                      |                       |                     |
+     |  Create Deployment   |                       |                     |
+     |--------------------->|                       |                     |
+     |                      |                       |                     |
+     |  Deployment Created  |                       |                     |
+     |<---------------------|                       |                     |
+     |                      |                       |                     |
+     |                      |   Deployment Event    |                     |
+     |                      |---------------------->|                     |
+     |                      |                       |     SSH+Deploys     |
+     |                      |                       |-------------------->|
+     |                      |                       |                     |
+     |                      |   Deployment Status   |                     |
+     |                      |<----------------------|                     |
+     |   Deployment Status  |                       |                     |
+     |<---------------------|                       |                     |
+     |                      |                       |                     |
+     |                      |                       |   Deploy Completed  |
+     |                      |                       |<--------------------|
+     |                      |   Deployment Status   |                     |
+     |                      |<----------------------|                     |
+     |   Deployment Status  |                       |                     |
+     |<---------------------|                       |                     |
+     |                      |                       |                     |
+```
+
+Gitploy lets you create a deployment in advanced ways, such as promotion or rollback, and beef up steps to create a new deployment.
+
+*Keep in mind that Gitploy is never actually accessing your servers. It's up to your tools to interact with deployment events.*
diff --git a/docs/concepts/license.md b/docs/concepts/license.md
@@ -6,4 +6,4 @@ After purchase, you can unlock the Gtiploy Enterprise edition by setting [the co
 
 ## Expiry
 
-The license will be expired when it reaches the expiry date. You have to renew the license when it is expired.
+The license will be expired when it reaches the expiry date. You have to renew the license before it is expired.
diff --git a/docs/concepts/overview.md b/docs/concepts/overview.md
diff --git a/docs/concepts/self-hosted-server.md b/docs/concepts/self-hosted-server.md
@@ -0,0 +1,3 @@
+# Self-hosted Server
+
+Gitploy provide self-hosted server which is the practice of locally installing and hosting by the user. We're providing installation guide for each environment. You can check this [guide](../tasks/installation.md) for details.
diff --git a/docs/images/deploy-commit.png b/docs/images/deploy-commit.png
diff --git a/docs/images/github-deployment.png b/docs/images/github-deployment.png
diff --git a/docs/images/slack-deploy.png b/docs/images/slack-deploy.png
diff --git a/docs/index.md b/docs/index.md
@@ -1,3 +1,5 @@
 # Gitploy
 
-Gitploy helps **you can build the advanced deployment pipeline in minutes** based on [Github Deployments](https://docs.github.com/en/rest/reference/repos#deployments). Gitploy is responsible for building the deployment pipeline enables teams to deploy the application with lower risk and faster when to trigger a deployment. 
+Gitploy helps **you can build the advanced deployment pipeline in minutes**. It enables teams to deploy the application with lower risk and faster when to trigger a deployment. And the pipeline is configured with a simple, easy‑to‑read file that you commit to your git repository.
+
+![Gitploy](./images/gitploy.png)
diff --git a/docs/references/GITPLOY_ADMIN_USERS.md b/docs/references/GITPLOY_ADMIN_USERS.md
@@ -0,0 +1,7 @@
+# GITPLOY_ADMIN_USERS
+
+Optional comma-separated list of accounts, used to identify which accounts are admin.
+
+```
+GITPLOY_ADMIN_USERS=noah,liam
+```
diff --git a/docs/references/GITPLOY_GITHUB_CLIENT_ID.md b/docs/references/GITPLOY_GITHUB_CLIENT_ID.md
@@ -0,0 +1,7 @@
+# GITPLOY_GITHUB_CLIENT_ID
+
+Required string value configures the GitHub OAuth client id. This is used to authorize access to GitHub on behalf of a Gitploy user.
+
+```
+GITPLOY_GITHUB_CLIENT_ID=05136f462e57d80189be
+```
diff --git a/docs/references/GITPLOY_GITHUB_CLIENT_SECRET.md b/docs/references/GITPLOY_GITHUB_CLIENT_SECRET.md
@@ -0,0 +1,7 @@
+# GITPLOY_GITHUB_CLIENT_SECRET
+
+Required string value configures the GitHub OAuth client secret. This is used to authorize access to GitHub on behalf of a Gitploy user.
+
+```
+GITPLOY_GITHUB_CLIENT_SECRET=7c2245e9228a77d2cbddaa61ddc78d
+```
diff --git a/docs/references/GITPLOY_ORGANIZATION_ENTRIES.md b/docs/references/GITPLOY_ORGANIZATION_ENTRIES.md
@@ -1,6 +1,6 @@
 # GITPLOY_ORGANIZATION_ENTRIES
 
-Optional comma-separated list of accounts, used to limit which organization(or owner) are syncronized between your source control management system and Gitploy. *Note that this variable must be set before your first login. If you don't set this environment it synchronize with all repositories the user owns.
+Optional comma-separated list of organizations, used to limit which organization(or owner) are syncronized between your source control management system and Gitploy. *Note that this variable must be set before your first login. If you don't set this environment it synchronize with all repositories the user owns.
 
 ```
 GITPLOY_ORGANIZATION_ENTRIES=gitploy-io,octocat,facebook
diff --git a/docs/references/GITPLOY_PROXY_SERVER_HOST.md b/docs/references/GITPLOY_PROXY_SERVER_HOST.md
@@ -0,0 +1,7 @@
+# GITPLOY_PROXY_SERVER_HOST
+
+Optional string value used to create webhooks that are routed through an alternate proxy server. The use case of this setting is that you need GitHub webhooks to route through a public proxy.
+
+```
+GITPLOY_PROXY_SERVER_HOST=external.cloud.gitploy.io
+```
diff --git a/docs/references/GITPLOY_PROXY_SERVER_PROTO.md b/docs/references/GITPLOY_PROXY_SERVER_PROTO.md
@@ -0,0 +1,7 @@
+# GITPLOY_PROXY_SERVER_PROTO
+
+Optional string value used to create webhooks that are routed through an alternate proxy server. The use case of this setting is that you need GitHub webhooks to route through a public proxy. It can be one of them: `http` or `https`.
+
+```
+GITPLOY_PROXY_SERVER_PROTO=https
+```
diff --git a/docs/references/GITPLOY_SERVER_HOST.md b/docs/references/GITPLOY_SERVER_HOST.md
@@ -3,5 +3,5 @@
 Required string value configures the user-facing hostname. This value is used to create webhooks and redirect urls. It has no actual impact on serving traffic.
 
 ```
-GITPLOY_SERVER_HOST=gitploy.jp.ngrok.io
+GITPLOY_SERVER_HOST=cloud.gitploy.io
 ```
diff --git a/docs/references/GITPLOY_SERVER_PROTO.md b/docs/references/GITPLOY_SERVER_PROTO.md
@@ -0,0 +1,7 @@
+# GITPLOY_SERVER_PROTO
+
+Optional string value configures the user-facing protocol. This value is used to create webhooks and redirect urls. It can be one of them: `http` or `https`, and the default value is `https`.
+
+```
+GITPLOY_SERVER_PROTO=https
+```
diff --git a/docs/references/GITPLOY_WEBHOOK_SECRET.md b/docs/references/GITPLOY_WEBHOOK_SECRET.md
@@ -0,0 +1,7 @@
+# GITPLOY_WEBHOOK_SECRET
+
+Optional string value to create an http-signature for the webhook. The webhook recipient use this secret to verify request authenticity.
+
+```
+GITPLOY_WEBHOOK_SECRET=asd212fuas2lfjxye
+```
diff --git a/docs/references/configurations.md b/docs/references/configurations.md
@@ -3,7 +3,14 @@
 Index of server configuration settings:
 
 * [GITPLOY_SERVER_HOST](./GITPLOY_SERVER_HOST.md)
+* [GITPLOY_SERVER_PROTO](./GITPLOY_SERVER_PROTO.md)
+* [GITPLOY_PROXY_SERVER_HOST](./GITPLOY_PROXY_SERVER_HOST.md)
+* [GITPLOY_PROXY_SERVER_PROTO](./GITPLOY_PROXY_SERVER_PROTO.md)
+* [GITPLOY_WEBHOOK_SECRET](./GITPLOY_WEBHOOK_SECRET.md)
 * [GITPLOY_ORGANIZATION_ENTRIES](./GITPLOY_ORGANIZATION_ENTRIES.md)
+* [GITPLOY_ADMIN_USERS](./GITPLOY_ADMIN_USERS.md)
+* [GITPLOY_GITHUB_CLIENT_ID](./GITPLOY_GITHUB_CLIENT_ID.md)
+* [GITPLOY_GITHUB_CLIENT_SECRET](./GITPLOY_GITHUB_CLIENT_SECRET.md)
 * [GITPLOY_SLACK_CLIENT_ID](./GITPLOY_SLACK_CLIENT_ID.md)
 * [GITPLOY_SLACK_CLIENT_SECRET](./GITPLOY_SLACK_CLIENT_SECRET.md)
 * [GITPLOY_SLACK_SIGNING_SECRET](./GITPLOY_SLACK_SIGNING_SECRET.md)
diff --git a/docs/references/deploy.yml.md b/docs/references/deploy.yml.md
@@ -0,0 +1,24 @@
+# deploy.yml
+
+## Env
+
+Field                    |Type                    |Tag       |Description
+---                      |----                    |---       |---
+`name`                   |*string*                |          |This parameter is the runtime environment such as `production`, `staging`, and `qa`. 
+`task`                   |*string*                |`github`  |This parameter is used by the deployment system to distinguish the kind of deployment. The default values is `deploy`, but for rollback, the value is always `rollback`.
+`description`            |*string*                |`github`  |This parameter is the short description of the deployment. The default value is `Gitploy starts to deploy.`
+`auto_merge`             |*boolean*               |`github`  |This parameter is used to ensure that the requested ref is not behind the repository's default branch. If you deploy with the commit or the tag you need to set `false`. The default values is `true`, but for rollback, the value is always `false`.
+`required_contexts`      |*[]string*              |`github`  |This parameter allows you to specify a subset of contexts that must be success. The default value is `nil`, it means every submitted context must be in a success state.
+`production_environment` |*boolean*               |`github`  |This parameter specifies whether this runtime environment is production or not.
+`approval`               |*[Approval](#approval)* |          |This parameter configures approval.
+
+## Approval
+
+Field            |Type      |Tag   |Description
+---              |---       |---   |
+`enabled`        |*boolean* |      |This parameter make to enable the approval feature. The default value is `false`.
+`required_count` |*integer* |      |This parameter determine how many the required approving approvals is needs to deploy. The default value is `0`. 
+
+## Tags
+
+* `github`: Github specific field.
diff --git a/docs/tasks/first-deployment.md b/docs/tasks/first-deployment.md
@@ -0,0 +1,43 @@
+# First Deployment
+
+On this page, we'll set up the first deployment pipeline and deploy it to the environment.
+
+## Step 1: Push deploy.yml
+
+To deploy Gitploy have to read the `deploy.yml` file from the default branch of the repository, so you have to create the file and commit it into the repository. In this example, we'll commit a simple `deploy.yml` file.
+
+```yaml
+# In deploy.yml
+envs:
+  - name: dev
+    auto_merge: false
+    required_contexts: []
+```
+
+```
+git add .
+git commit -m "Add deploy.yml"
+git push
+```
+
+## Step 2: Activate Repository
+
+After commit, you have to activate the repository in Gitploy UI.
+
+## Step 3: Deploy 
+In the 'Deploy' tab, you can find the deployment form. In this example, we'll deploy the commit:
+
+1. Choose the environment `dev`.
+2. Choose the type commit.
+3. Select the commit and click the deploy button.
+
+Figure) Gitploy Deployment Form
+
+![Deploy commit](../images/deploy-commit.png)
+
+## Step 4: Deployment Event
+On the deployment page of Github, you can find the new Github deployment at the top. In production, the deployment tool should listen to the event and start to deploy. You can reference the [community](https://github.com/gitploy-io/gitploy/discussions/categories/share-pipeline) and it is sharing how to implement the whole pipeline.
+
+Figure) Github deployment
+
+![Github deployment](../images/github-deployment.png)
diff --git a/docs/tasks/integration.md b/docs/tasks/integration.md
@@ -1,15 +1,16 @@
 # Integration
 
-
 ## Slack
 
+Slack integration provides Chatops (i.e. deploy, rollback) and notification alert for events.
+
 ### Step 1: Create App
 
 Firstly, we have to create [Slack App](https://api.slack.com/apps). Let’s click the Create App button and fill out inputs.
 
 ### Step 2: Configure Permissions
 
-After creating App let’s move to the *OAuth & Permissions* page. In this section, we have to set up *the redirect URLs* and *Bot Token scopes*. Firstly, let’s add a new redirect URL with the `GITPLOY_SERVER_PROTO://GITPLOY_SERVER_HOST/slack/signin` format; secondly, add `chat:write` and `commands` scopes into the Bot Token scopes.
+After creating App let’s move to the *OAuth & Permissions* page. On this page, we have to set up *the redirect URLs* and *Bot Token scopes*. Firstly, let’s add a new redirect URL with the `GITPLOY_SERVER_PROTO://GITPLOY_SERVER_HOST/slack/signin` format; secondly, add `chat:write` and `commands` scopes into the Bot Token scopes.
 
 Figure) Slack Bot Token Scopes
 
@@ -38,5 +39,7 @@ Figure) Slack Interactivity
 
 ### Step 5: Run Server With App Credentials
 
-To enable Slack integration, you have to set up these environments when you run the server: `GITPLOY_SLACK_CLIENT_ID`, `GITPLOY_SLACK_CLIENT_SECRET`, and `GITPLOY_SLACK_SIGNING_SECRET`. You can get these credentials from *App Credentials* section of *Basic Information* page.
+To enable Slack integration, you have to set up these environments when you run the server: `GITPLOY_SLACK_CLIENT_ID`, `GITPLOY_SLACK_CLIENT_SECRET`, and `GITPLOY_SLACK_SIGNING_SECRET`. You can get these credentials from *App Credentials* section of *Basic Information* page. 
+
+On settings page, you can find the button to connect with Slack. Now, you can run the slash command `/gitploy` in Slack.
 
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -5,16 +5,35 @@ theme:
   palette:
     primary: deep purple
     accent: deep purple 
+  icon:
+    repo: fontawesome/brands/github
 nav:
   - Home: index.md
   - Concepts: 
-    - Overview: concepts/overview.md
-    - "deploy.yaml": concepts/deploy.yml.md
+    - "How it works": concepts/how-it-work.md
+    - "deploy.yml": concepts/deploy.yml.md
+    - Deployment: concepts/deployment.md
     - Permission: concepts/permission.md
+    - "Self-hosted Server": concepts/self-hosted-server.md
     - Chatops: concepts/chatops.md
     - License: concepts/license.md
   - Tasks:
     - Installation: tasks/installation.md
+    - "First Deployment": tasks/first-deployment.md
     - Integration: tasks/integration.md
   - References: 
-    - Configurations: references/configurations.md
+    - Configurations: references/configurations.md
+    - "deploy.yml": references/deploy.yml.md
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/gitploy-io
+  version:
+    provider: mike
+copyright: Copyright &copy; 2021 Gitploy.IO
+repo_name: gitploy-io/gitploy
+repo_url: https://github.com/gitploy-io/gitploy
+edit_uri: edit/main/docs/
+markdown_extensions:
+  - pymdownx.highlight
+  - pymdownx.superfences

Original file line number	Diff line number	Diff line change
`@@ -6,4 +6,4 @@ After purchase, you can unlock the Gtiploy Enterprise edition by setting [the co`
`6`	`6`
`7`	`7`	`## Expiry`
`8`	`8`
`9`		`-The license will be expired when it reaches the expiry date. You have to renew the license when it is expired.`
	`9`	`+The license will be expired when it reaches the expiry date. You have to renew the license before it is expired.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Self-hosted Server`
	`2`	`+`
	`3`	`+Gitploy provide self-hosted server which is the practice of locally installing and hosting by the user. We're providing installation guide for each environment. You can check this [guide](../tasks/installation.md) for details.`