Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(api,vcs): use new vcs project #6160

Merged
merged 22 commits into from
May 20, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
176 changes: 21 additions & 155 deletions docs/content/docs/integrations/bitbucket.md
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
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