Skip to content

Commit 45dd2eb

Browse files
zachallercrenshaw-dev
zachaller
and
crenshaw-dev
authored
docs: installation and setup docs (#143)
* save Signed-off-by: Zach Aller <[email protected]> * save Signed-off-by: Zach Aller <[email protected]> * save Signed-off-by: Zach Aller <[email protected]> * save Signed-off-by: Zach Aller <[email protected]> * save Signed-off-by: Zach Aller <[email protected]> * save Signed-off-by: Zach Aller <[email protected]> * getting started Signed-off-by: Zach Aller <[email protected]> * be consistent don't add status Signed-off-by: Zach Aller <[email protected]> * save Signed-off-by: Zach Aller <[email protected]> * copilot Signed-off-by: Zach Aller <[email protected]> * url Signed-off-by: Zach Aller <[email protected]> * add SCM open to PRs Signed-off-by: Zach Aller <[email protected]> * cleanup Signed-off-by: Zach Aller <[email protected]> * Update docs/getting-started.md Co-authored-by: Michael Crenshaw <[email protected]> * Update docs/getting-started.md Co-authored-by: Michael Crenshaw <[email protected]> * Update docs/getting-started.md Co-authored-by: Michael Crenshaw <[email protected]> * Update docs/getting-started.md Co-authored-by: Michael Crenshaw <[email protected]> * add note about autoMerge false Signed-off-by: Zach Aller <[email protected]> * docs tweaks Signed-off-by: Michael Crenshaw <[email protected]> * use -k kubectl Signed-off-by: Zach Aller <[email protected]> * fix kubectl cmd Signed-off-by: Zach Aller <[email protected]> * fix link Signed-off-by: Zach Aller <[email protected]> --------- Signed-off-by: Zach Aller <[email protected]> Signed-off-by: Michael Crenshaw <[email protected]> Co-authored-by: Michael Crenshaw <[email protected]>
1 parent ad76147 commit 45dd2eb

File tree

5 files changed

+127
-75
lines changed

5 files changed

+127
-75
lines changed

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,3 +36,5 @@ junit.xml
3636

3737
./install.yaml
3838
release_dist
39+
40+
venv

‎docs/README.md‎

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

‎docs/example-resources/PullRequest.yaml‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,3 @@ spec:
1212

1313
# Must be closed, merged, or open. Default is open.
1414
state:
15-
status:
16-
observedGeneration:
17-
id:
18-
state:
19-
prCreationTime:

‎docs/getting-started.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Getting Started
2+
3+
This guide will help you get started installing and setting up the GitOps Promoter. We currently only support
4+
GitHub and GitHub Enterprise as the SCM providers. We would welcome any contributions to add support for other
5+
providers.
6+
7+
## Requirements
8+
9+
* kubectl CLI
10+
* kubernetes cluster
11+
* GitHub or GitHub Enterprise Application
12+
* Will take PRs to add support for other SCM providers
13+
14+
## Installation
15+
16+
To install GitOps Promoter, you can use the following command:
17+
18+
```bash
19+
kubectl apply -f https://github.com/argoproj-labs/gitops-promoter/releases/download/v0.0.1-rc1/install.yaml
20+
```
21+
22+
## GitHub App Configuration
23+
24+
You will need to [create a GitHub App](https://docs.github.com/en/developers/apps/creating-a-github-app) and configure
25+
it to allow the GitOps Promoter to interact with your GitHub repository.
26+
27+
!!! note "Configure your webhook ingress"
28+
29+
We do support configuration of a GitHub App webhook that triggers PR creation upon Push. However, we do not configure
30+
the ingress to allow GitHub to reach the GitOps Promoter. You will need to configure the ingress to allow GitHub to reach
31+
the GitOps Promoter via the service promoter-webhook-receiver which listens on port `3333`. If you do not use webhooks
32+
you might want to adjust the auto reconciliation interval to a lower value using these CLI flags `--promotion-strategy-requeue-duration` and
33+
`--change-transfer-policy-requeue-duration`.
34+
35+
During the creation the GitHub App, you will need to configure the following settings:
36+
37+
* Permissions
38+
* Commit statuses - Read & write
39+
* Contents - Read & write
40+
* Pull requests - Read & write
41+
* Webhook URL (Optional - but highly recommended)
42+
* `https://<your-promoter-webhook-receiver-service>/`
43+
44+
The GitHub App will generate a private key that you will need to save. You will also need to get the App ID and the
45+
installation ID in a secret as follows:
46+
47+
```yaml
48+
apiVersion: v1
49+
kind: Secret
50+
metadata:
51+
name: <your-secret-name>
52+
type: Opaque
53+
stringData:
54+
appID: <your-app-id>
55+
installationID: <your-installation-id>
56+
privateKey: <your-private-key>
57+
```
58+
59+
!!! note
60+
61+
This Secret will need to be installed to the same namespace that you plan on creating PromotionStrategy resources in.
62+
63+
We also need a GitRepository and ScmProvider, which is are custom resources that represents a git repository and a provider.
64+
Here is an example of both resources:
65+
66+
```yaml
67+
apiVersion: promoter.argoproj.io/v1alpha1
68+
kind: ScmProvider
69+
metadata:
70+
name: <your-scmprovider-name>
71+
spec:
72+
secretRef:
73+
name: <your-secret-name>
74+
github: {}
75+
---
76+
apiVersion: promoter.argoproj.io/v1alpha1
77+
kind: GitRepository
78+
metadata:
79+
name: <git-repository-ref-name>
80+
spec:
81+
name: <repo-name>
82+
owner: <github-org-username>
83+
scmProviderRef:
84+
name: <your-scmprovider-name> # The secret that contains the GitHub App configuration
85+
```
86+
87+
!!! note
88+
89+
The GitRepository and ScmProvider also need to be installed to the same namespace that you plan on creating PromotionStrategy
90+
resources in, and it also needs to be in the same namespace of the secret it references.
91+
92+
## Promotion Strategy
93+
94+
The PromotionStrategy resource is the main resource that you will use to configure the promotion of your application to different environments.
95+
Here is an example PromotionStrategy resource:
96+
97+
```yaml
98+
apiVersion: promoter.argoproj.io/v1alpha1
99+
kind: PromotionStrategy
100+
metadata:
101+
name: demo
102+
spec:
103+
environments:
104+
- autoMerge: false
105+
branch: environment/development
106+
- autoMerge: false
107+
branch: environment/staging
108+
- autoMerge: false
109+
branch: environment/production
110+
gitRepositoryRef:
111+
name: <git-repository-ref-name> # The name of the GitRepository resource
112+
```
113+
114+
!!! note
115+
116+
Notice that the branches are prefixed with `environment/`. This is a convention that we recommend you follow.
117+
118+
!!! note
119+
120+
The `autoMerge` field is optional and defaults to `true`. We set it to `false` here because we do not have any
121+
CommitStatus checks configured. With these all set to `false` we will have to manually merge the PRs.

‎mkdocs.yml‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,13 @@ markdown_extensions:
2020
- markdown_include.include
2121
- codehilite:
2222
css_class: highlight
23+
- admonition
24+
- pymdownx.superfences
2325
nav:
2426
- Overview: index.md
27+
- Getting Started: getting-started.md
2528
- Architecture: architecture.md
2629
- CRD Specs: crd-specs.md
2730
- Gating Promotions: gating-promotions.md
2831
- Multi-Tenancy: multi-tenancy.md
29-
- Tool Comparison: tool-comparison.md
32+
- Tool Comparison: tool-comparison.md

0 commit comments

Comments
 (0)