Skip to content

Commit

Permalink
feat(api,vcs): use new vcs project (#6160)
Browse files Browse the repository at this point in the history 
* feat(api,vcs): use new vcs project

Signed-off-by: Yvonnick Esnault <[email protected]>
  • Loading branch information
@yesnault
yesnault authored May 20, 2022
1 parent dec0398 commit c5cd38f
Show file tree
Hide file tree
Showing 85 changed files with 1,610 additions and 1,385 deletions.
176 changes: 21 additions & 155 deletions docs/content/docs/integrations/bitbucket.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,168 +17,34 @@ This integration enables some features:
- Send [build notifications](https://developer.atlassian.com/server/bitbucket/how-tos/updating-build-status-for-commits/) on your Pull-Requests and Commits on Bitbucket. [More informations]({{<relref "/docs/concepts/workflow/notifications.md#vcs-notifications" >}})
- [Send comments on your Pull-Requests when a workflow is failed]({{<relref "/docs/concepts/workflow/notifications.md#vcs-notifications" >}})

## How to configure Bitbucket Server integration
### Create the Personal Access Token on Bitbucket Datacenter

You need to perform the following steps:
Generate a new token on https://your-bitbucket-datacenter/plugins/servlet/access-tokens/manage with the following scopes:
- `PROJECT READ`
- `REPOSITORY READ`

- Bitbucket admin privileges
- A RSA Key Pair

### Generate RSA Key Pair

Create the private RSA certificate:

```
$ openssl genrsa -out key.pem 1024
```

The content of key.pem have to be used as `privateKey` below in CDS Configuration file.

Generate the public RSA certificate:

```
$ openssl rsa -in key.pem -pubout
```

This will display the public key, you will have to copy-paste it inside `Public Key` field on Bitbucket.


### Create a CDS application in Bitbucket
In Bitbucket go to *Administration Settings* / *Application Links*. Create a new Application with:

- Name: **CDS**
- Type: **Generic Application**
- Application URL: *Your CDS API URL*
- Display URL: *Your CDS API URL*

On this application, you just have to set up *OAuth Incoming Authentication*:

- Consumer Key: **CDS** (you can change it in your configuration file)
- Consumer Name: **CDS**
- Public Key: *Your CDS RSA public key*
- Consumer Callback URL: None
- Allow 2-Legged OAuth: false
- Execute as: None
- Allow user impersonation through 2-Legged OAuth: false

### Complete CDS Configuration File

Set value to `privateKey`. You can modify `consumerKey` if you want.

```yaml
[vcs.servers]

[vcs.servers.Bitbucket]

# URL of this VCS Server
url = "https://mybitbucket.com"

[vcs.servers.Bitbucket.bitbucket]

#######
# CDS <-> Bitbucket. Documentation on https://ovh.github.io/cds/hosting/repositories-manager/bitbucket/
########
# You can change the consumeKey if you want
consumerKey = "CDS"

# Does polling is supported by VCS Server
disablePolling = false

# Does webhooks are supported by VCS Server
disableWebHooks = false
privateKey = "-----BEGIN PRIVATE KEY-----\n....\n-----END PRIVATE KEY-----"

# If you want to have a reverse proxy URL for your repository webhook, for example if you put https://myproxy.com it will generate a webhook URL like this https://myproxy.com/UUID_OF_YOUR_WEBHOOK
# proxyWebhook = ""

# optional, Bitbucket Token associated to username, used to add comment on Pull Request
token = ""

# optional. Bitbucket username, used to add comment on Pull Request on failed build.
username = ""

[vcs.servers.Bitbucket.bitbucket.Status]

# Set to true if you don't want CDS to push statuses on the VCS server
# disable = false
```

You can configure many instances of Bitbucket:
### Import configuration

Create a yml file:

```yaml

[vcs.servers]

[vcs.servers.mybitbucket_instance1]

# URL of this VCS Server
url = "https://mybitbucket-instance1.localhost"

[vcs.servers.mybitbucket_instance1.bitbucket]
consumerKey = "CDS_Instance1"

# Does polling is supported by VCS Server
disablePolling = true

# Does webhooks are supported by VCS Server
disableWebHooks = false

# Does webhooks creation are supported by VCS Server
disableWebHooksCreation = false
privateKey = "-----BEGIN PRIVATE KEY-----\n....\n-----END PRIVATE KEY-----"

# If you want to have a reverse proxy URL for your repository webhook, for example if you put https://myproxy.com it will generate a webhook URL like this https://myproxy.com/UUID_OF_YOUR_WEBHOOK
# proxyWebhook = "https://myproxy.com"

[vcs.servers.mybitbucket_instance1.bitbucket.Status]

# Set to true if you don't want CDS to push statuses on the VCS server
disable = false

# Set to true if you don't want CDS to push CDS URL in statuses on the VCS server
showDetail = true

[vcs.servers.mybitbucket_instance2]

# URL of this VCS Server
url = "https://mybitbucket-instance2.localhost"

[vcs.servers.mybitbucket_instance2.bitbucket]
consumerKey = "CDS_Instance2"

# Does polling is supported by VCS Server
disablePolling = true

# Does webhooks are supported by VCS Server
disableWebHooks = false

# Does webhooks creation are supported by VCS Server
disableWebHooksCreation = false
privateKey = "-----BEGIN PRIVATE KEY-----\n....\n-----END PRIVATE KEY-----"

# If you want to have a reverse proxy URL for your repository webhook, for example if you put https://myproxy.com it will generate a webhook URL like this https://myproxy.com/UUID_OF_YOUR_WEBHOOK
# proxyWebhook = "https://myproxy.com"

[vcs.servers.mybitbucket_instance2.bitbucket.Status]

# Set to true if you don't want CDS to push statuses on the VCS server
disable = false

# Set to true if you don't want CDS to push CDS URL in statuses on the VCS server
showDetail = true

version: v1.0
name: bitbucket
type: bitbucketserver
description: "My Bitbucket Datacenter"
url: "http://localhost:7990/bitbucket"
auth:
user: username-on-bitbucket
token: the-long-token-here
options:
disableStatus: false # Set to true if you don't want CDS to push statuses on the VCS server - optional
disableStatusDetails: false # Set to true if you don't want CDS to push CDS URL in statuses on the VCS server - optional
disablePolling: false # Does polling is supported by VCS Server - optional
disableWebHooks: false # Does webhooks are supported by VCS Server - optional
```
See how to generate **[Configuration File]({{<relref "/hosting/configuration.md" >}})**

## Start the vcs µService

```bash
$ engine start vcs

# you can also start CDS api and vcs in the same process:
$ engine start api vcs
```sh
cdsctl experimental project vcs import YOUR_CDS_PROJECT_KEY vcs-bitbucket.yml
```

## Vcs events
Expand Down
158 changes: 38 additions & 120 deletions docs/content/docs/integrations/bitbucketcloud.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,128 +18,46 @@ This integration enables some features:

## How to configure Bitbucket Cloud integration

+ Follow documentation on https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/, section **Create a consumer**
+ Bitbucket requests some informations:
++ **name** you can simply write CDS
++ **description** is optional
++ **callback url** must be the URL of your CDS -> `{CDS_UI_URL}/cdsapi/repositories_manager/oauth2/callback` (if you are in development mode you have to omit /cdsapi and replace {CDS_UI_URL} with your API URL)
++ **URL** is optional.
++ **Permissions** : select `Account Read`, `Workspace membership Read`, `Repositories Read`, `Webhooks Read and Write`
+ Click on Save and toggle the consumer name to see the generated `Key` and `Secret`. It correspond to `clientId` and `clientSecret` in the CDS config.toml file.

### Complete CDS Configuration File

#### VCS µService Configuration

If you don't already have any of vcs integrations on your CDS please follow these steps. The file configuration for the VCS µService can be retreived with:

```bash
$ engine config new vcs > vcs-config.toml

# or with all other configuration parts:
$ engine config new > config.toml
```

Edit the toml file:

- section `[vcs.api]`
- this section will be used to communicate with CDS API. Check the url and the consumer token generated by CDS.
- Token can be generated with cdsctl:

```bash
$ cdsctl consumer new me \
--scopes=Service \
--name="cds-vcs" \
--description="Consumer token for vcs service" \
--groups="" \
--no-interactive

Builtin consumer successfully created, use the following token to sign in:
xxxxxxxx.xxxxxxx.4Bd9XJMIWrfe8Lwb-Au68TKUqflPorY2Fmcuw5vIoUs5gQyCLuxxxxxxxxxxxxxx
```

```toml
[vcs.api]
maxHeartbeatFailures = 10
requestTimeout = 10
## Consumer Token previously generated
token = "xxxxxxxx.xxxxxxx.4Bd9XJMIWrfe8Lwb-Au68TKUqflPorY2Fmcuw5vIoUs5gQyCLuxxxxxxxxxxxxxx"

[vcs.api.http]
# insecure = false
url = "http://localhost:8081"
```

- section `[vcs.ui.http]`
- URL of CDS UI. This URL will be used by Bitbucket Cloud as a callback on Oauth2. This url must be accessible by users' browsers.

```toml
[vcs.ui.http]
url = "http://localhost:8080"
```

- section `[vcs.servers]`

Then add this part to specify you want to add bitbucketcloud integration. Set value to `clientId` and `clientSecret`.

```toml
[vcs.servers]
[vcs.servers.bitbucketcloud]

[vcs.servers.bitbucketcloud.bitbucketcloud]

# Bitbucket Cloud OAuth Key
clientId = "XXXX"

# Bitbucket Cloud OAuth Secret
clientSecret = "XXXX"

# Does webhooks are supported by VCS Server
disableWebHooks = false

# Does webhooks creation are supported by VCS Server
disableWebHooksCreation = false

#proxyWebhook = "https://myproxy.com/"

[vcs.servers.bitbucketcloud.bitbucketcloud.Status]

# Set to true if you don't want CDS to push statuses on the VCS server
disable = false

# Set to true if you don't want CDS to push CDS URL in statuses on the VCS server
showDetail = false
```

#### hooks µService Configuration

If you have not already a hooks µService configured. Then, as the `vcs` µService, you have to configure the `hooks` µService

```bash
$ engine config new hooks > hooks-config.toml
- Follow the section **Create a consumer** on documentation https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/
- Bitbucket requests some informations:
- **name** you can simply write CDS
- **description** is optional
- **callback url** must be the URL of your CDS -> `{CDS_UI_URL}/cdsapi/repositories_manager/oauth2/callback` (if you are in development mode you have to omit /cdsapi and replace {CDS_UI_URL} with your API URL)
- **URL** is optional.
- **Permissions** : select `Account Read`, `Workspace membership Read`, `Repositories Read`, `Pull requests Read`, `Webhooks Read and Write`
- Click on Save and toggle the consumer name to see the generated `Key` and `Secret`. It correspond to `clientId` and `clientSecret` in the CDS config.toml file.

### Create the Personal Access Token on Bitbucket Datacenter

On https://bitbucket.org/account/settings/app-passwords/ create a new app password with the following scopes:
- Account `Email` and `Read`
- Workspace membership `Read`
- Projects `Read`
- Repositories `Read` and `Write`
- Pull requests `Read` and `Write`
- Webhooks `Read and write`

### Import configuration

Create a yml file:

```yaml
version: v1.0
name: bitbucket-cloud
type: bitbucketcloud
description: "My Bitbucket Cloud"
auth:
user: my-user-on-bitbucket-cloud
token: the-long-token-here
options:
disableStatus: false # Set to true if you don't want CDS to push statuses on the VCS server - optional
disableStatusDetails: false # Set to true if you don't want CDS to push CDS URL in statuses on the VCS server - optional
disablePolling: false # Does polling is supported by VCS Server - optional
disableWebHooks: false # Does webhooks are supported by VCS Server - optional
```
In the `[hooks]` section

- check the URL, this will be used by CDS API to call CDS Hooks
- configure `urlPublic` if you want to use [simple Webhook]({{<relref "/docs/concepts/workflow/hooks/webhook.md">}})
- add a name, as `cds-hooks`

In the `[hooks.api]` section

- put the same token as the `[vcs.api]` section


### Start the vcs and hooks µService

*As a CDS Administrator*

```bash
$ engine start vcs --config vcs-config.toml
$ engine start hooks --config hooks-config.toml

# you can also start CDS api and vcs in the same process:
$ engine start api vcs hooks --config config.toml
```sh
cdsctl experimental project vcs import YOUR_CDS_PROJECT_KEY vcs-bitbucketcloud.yml
```

## Vcs events
Expand Down
Loading

0 comments on commit c5cd38f

Please sign in to comment.