GitHub Repository Manager

The GitHub Repository Manager Integration have to be configured on your CDS by a CDS Administrator.

This integration allows you to link a Git Repository hosted by GitHub to a CDS Application.

This integration enables some features:

Resume on what you have to do before using the GitHub Integration

  1. As a CDS Administrator:
    1. Create a CDS application on GitHub
    2. Complete CDS Configuration File
    3. Start the vcs µService
  2. As a user, which is admin on a CDS Project: link Project to GitHub
  3. As a user, with writing rights on a CDS project:
    1. Link a CDS Application to a Git repository
    2. Add a repository webhook on a workflow (this will automatically create a webhook on GitHub)

How to configure GitHub integration

Create a CDS application on GitHub

As a CDS Administrator

Go to https://github.com/settings/developers and Register a new OAuth application. Set :

Example for a local configuration:

Integration GitHub New OAuth App

Click on Register Application, then on the next page, GitHub give you a Client ID and a Client Secret

Complete CDS Configuration File

VCS µService Configuration

The file configuration for the VCS µService can be retreived with:

$ engine config new vcs > vcs-config.toml

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

Edit the toml file:

[vcs]
  URL = "http://localhost:8084"

  # Name of this CDS VCS Service
  # Enter a name to enable this service
  name = "cds-vcs"
    [vcs.ui.http]
      url = "http://localhost:8080"
  [vcs.api]
    maxHeartbeatFailures = 10
    requestTimeout = 10
    token = "enter sharedInfraToken from section [api.auth] here"

    [vcs.api.grpc]
      # insecure = false
      url = "http://localhost:8082"

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

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

      [vcs.servers.Github.github]

        #######
        # CDS <-> Github. Documentation on https://ovh.github.io/cds/hosting/repositories-manager/github/
        ########
        # Github OAuth Application Client ID
        clientId = "xxxx"

        # Github OAuth Application Client Secret
        clientSecret = "xxxx"

        # Does polling is supported by VCS Server
        disablePolling = false

        # Does webhooks are supported by VCS Server
        disableWebHooks = false

        # 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, Github Token associated to username, used to add comment on Pull Request
        token = ""

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

        [vcs.servers.Github.github.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

As the vcs µService, you have to configured the hooks µService

$ engine config new hooks > hooks-config.toml

In the [hooks] section

In the [hooks.api] section

Start the vcs and hooks µService

As a CDS Administrator

$ 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

As a user, which is admin on a CDS Project

Go on your CDS Project -> Advanced -> Link a repository manager

Select GitHub in the list, then click on Connect

github-add-on-prj.png

A confirmation page is now displayed, click on the link Click Here

github-modal-click-here.png

By clicking on Click Here, you call GitHub and you will be redirected on the same page. The Repository is now added on the CDS Project with a small warning Unused repository manager GitHub on .. as you don’t use the repository yet in your CDS Project.

github-added.png

As a user, with writing rights on a CDS project

Go on your CDS Project -> You Application -> Advanced -> Link application to a repository

Select GitHub, then select a Git Repository

github-app-repo.png

The application is linked, you have now to choose a method to Git Clone your repository.

github-app-freshly-added.png

Example with https method, without authentication:

github-app-repo-configured.png

Add a repository webhook on a workflow

As a user, with writing rights on a CDS project

Select the first pipeline, then click on Add a hook in the sidebar.

github-wf-select-pipeline.png

Select the RepositoryWebhook, then click on Save.

github-wf-add-repowebhook.png

The webhook is automatically created on GitHub.

What’s next?

FAQ

My CDS is not accessible from GitHub, how can I do?

When someone git push on your Git Repository, GitHub have to call your CDS to run your CDS Workflow. This is the behaviour of the RepositoryWebhook. But if your CDS is not reacheable from GitHub, how can you do?

By chance, you have two choices :)

Git Repository Poller documentation

    # 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 = ""

If you hesitate between the two: the RepositoryWebhook is more reactive than the Git Repository Poller.

I don’t see the type Git Repository Poller nor RepositoryWebhook when I add a Hook

Before adding a hook on your Workflow, you have to add the application in the Pipeline Context. Select the first pipeline, then click on Edit the pipeline context from the sidebar.

Pipeline Context Documentation

VCS events

For now, CDS supports push events. CDS uses this push event to remove existing runs for deleted branches (24h after branch deletion).