Skip to content

Commit 748cf55

Browse files
author
Noah Lee
authored
Enhance the document for Integration (#33)
* Enhance the integration document * Add the document for Spinnaker
1 parent ae1bc21 commit 748cf55

File tree

3 files changed

+132
-26
lines changed

3 files changed

+132
-26
lines changed

‎docs/concepts/self-hosted-server.md

Lines changed: 0 additions & 7 deletions
This file was deleted.

‎docs/tasks/integration.md

Lines changed: 132 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -4,51 +4,164 @@ sidebar_position: 3
44

55
# Integration
66

7-
## GitHub Action
7+
## Deployment API
88

9-
GitHub Actions help you automate tasks to run an actual deployment. GitHub Actions are event-driven, meaning that you can run a series of commands after a deployment event has occurred.
9+
As described in the '[How it works](../concepts/how-it-work.md)' document, two preparations are required to connect with the deployment API; 1) Make sure your deployment tooling is listening for the Github [deployment](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#deployment) event. 2) Update the deployment status by [API](https://docs.github.com/en/rest/reference/deployments#create-a-deployment-status) after execution is complete. This document will show how you can connect with the mainstream deployment tools.
1010

11-
To listening the deployment event, you must specify `deployment` for the `on` field. And you can use the `if` conditional to run a job for the specific environment. Here is the example below.
11+
### GitHub Action
12+
13+
#### Listening for an event
14+
15+
GitHub Action provides the `on` syntax to define the type of activity that will trigger a workflow run, and it supports the deployment event.
1216

1317
```yaml
14-
# Listening the deployment event
1518
on:
1619
deployment
20+
```
1721
22+
And you can use the `if` conditional to run a job when an environment is met. You can use context to access the deployment environment.
23+
24+
```yaml
25+
jobs:
26+
deploy-production:
27+
runs-on: ubuntu-latest
28+
if: ${{ github.event.deployment.environment === 'production' }}
29+
```
30+
31+
#### Update the deployment status
32+
33+
The third-party plugin, [chrnorm/deployment-status](https://github.com/chrnorm/deployment-status), provides that a GitHub action updates the status of deployments as part of your GitHub CI workflows.
34+
35+
36+
```yaml
1837
jobs:
1938
deploy-dev:
2039
runs-on: ubuntu-latest
21-
# Run a job when the environment is 'production.
22-
if: ${{ github.event.deployment.environment == 'production' }}
2340
steps:
24-
-
25-
name: Checkout
26-
uses: actions/checkout@v2
41+
...
2742
-
28-
name: Start to deploy
43+
name: Update the deployment status
2944
uses: chrnorm/deployment-status@releases/v1
3045
with:
31-
deployment_id: ${{ github.event.deployment.id }}
32-
description: Start to deploy ...
33-
state: "in_progress"
3446
token: "${{ github.token }}"
35-
# Run your deployment commands.
47+
deployment_id: ${{ github.event.deployment.id }}
48+
description: Finish to deploy successfully.
49+
state: "success"
3650
```
3751

38-
## Slack
52+
You can reference this [example](https://github.com/gitploy-io/gitploy/discussions/178) for integrating with GitHub action.
53+
54+
### Drone CI
55+
56+
#### Listening for an event
57+
58+
Drone CI provides the `trigger` field to limit pipeline execution based on the drone event type, supporting the `promote` event.
59+
60+
```yaml
61+
trigger:
62+
event:
63+
- promote
64+
```
65+
66+
And you can access the [`DRONE_DEPLOY_TO`](https://docs.drone.io/pipeline/environment/reference/drone-deploy-to/) environment by the environment if you need the conditional step.
67+
68+
#### Update the deployment status
69+
70+
The third-party plugin, [cedrichopf/drone-status](https://github.com/cedrichopf/drone-status), provides that a Drone CI updates the status of deployments as part of your CI pipelines.
71+
72+
```yaml
73+
steps:
74+
- name: Update the deployment status
75+
image: cedrichopf/drone-status
76+
settings:
77+
api_token:
78+
from_secret: GITHUB_TOKEN
79+
context: deploy
80+
state: success
81+
description: Finish to deploy successfully.
82+
```
83+
84+
### Spinnaker
85+
86+
#### Listening for an event
87+
88+
The trigger type has to be the webhook type to listen to an event, and the constraints verify repository and environment to determine if triggered or not.
89+
90+
![Spinnaker Webhook Trigger](../../static/img/docs/spinnaker-trigger.png)
91+
92+
#### Update the deployment status
93+
94+
Spinnaker provides a simple way to add a custom stage to call API instead of extending through codes. Spinnaker can typically make API calls as part of a pipeline by adding a custom stage.
95+
96+
To create a custom webhook, we have to add the configuration to the `orca-local.yml` file, located in `$HOME/.hal/default/profiles`. And the custom stage has a few variables, `owner`, `repo`, `deployment_id`, `description`, and `state`, for updating the deployment status dynamically. You can set up the variables for your project.
97+
98+
<details>
99+
<summary>Custom Stage</summary>
100+
101+
```yaml
102+
webhook:
103+
preconfigured:
104+
- label: Update Deployment status
105+
type: updateDeploymentStatus
106+
enabled: true
107+
description: Update the deployment status.
108+
method: POST
109+
url: https://api.github.com/repos/${ parameterValues['owner'] }/${ parameterValues['repo'] }/deployments/${ parameterValues['deployment_id'] }/statuses
110+
customHeaders:
111+
# Replace with your GitHub token.
112+
Authorization:
113+
- token GITHUB_TOKEN
114+
Content-Type:
115+
- application/json
116+
payload: |-
117+
{
118+
"description": "${parameterValues['description']}",
119+
"state": "${parameterValues['state']}",
120+
"log_url": "http://localhost:9000/#/applications/${execution.application}/executions/details/${execution.id}"
121+
}
122+
parameters:
123+
- label: GitHub Owner
124+
name: owner
125+
type: string
126+
- label: GitHub Repo
127+
name: repo
128+
type: string
129+
- lable: Deployment ID
130+
name: deployment_id
131+
type: string
132+
- label: Description
133+
name: description
134+
type: string
135+
- label: State
136+
name: state
137+
type: string
138+
description: The state can be one of "queued", "in_progress", "success", "failure"
139+
```
140+
141+
</details>
142+
143+
You can reference the [spinnaker demo](https://github.com/gitploy-io/spinnaker-demo) for integrating with Spinnaker.
144+
145+
146+
147+
### Internal Deployment Tooling
148+
149+
GitHub provides a well-organized [document](https://docs.github.com/en/rest/guides/delivering-deployments) to guide to build an internal deployment tooling to deploy on your servers with the Deployment API.
150+
151+
## Notification
39152

40-
Slack integration provides notifications for events.
153+
### Slack
41154

42-
### Step 1: Create App
155+
#### Step 1: Create App
43156

44157
Firstly, we have to create [Slack App](https://api.slack.com/apps). You should click the Create App button and fill out inputs.
45158

46-
### Step 2: Configure Permissions
159+
#### Step 2: Configure Permissions
47160

48161
After creating App, we move to the *OAuth & Permissions* page and set up *the redirect URLs* and *Bot Token scopes*on this page. Firstly, you should add a new redirect URL with the `GITPLOY_SERVER_PROTO://GITPLOY_SERVER_HOST/slack/signin` format; secondly, add `chat:write` scope into the Bot Token scopes.
49162

50163
![Slack Bot Token Sceops](../../static/img/docs/slack-bot-token-scopes.png)
51164

52-
### Step 3: Run Server With App Credentials
165+
#### Step 3: Run Server With App Credentials
53166

54167
To enable Slack integration, you have to set up these environments when you run the server: `GITPLOY_SLACK_CLIENT_ID` and `GITPLOY_SLACK_CLIENT_SECRET`. You can get these credentials from *App Credentials* section of *Basic Information* page.

‎static/img/docs/spinnaker-trigger.png

42.4 KB
Loading

0 commit comments

Comments
 (0)