The Continuous Integration (CI) will start a build for every Pull Request issued. Build is re-triggered whenever a change to such a PR is pushed. Additionally the CI also starts a build for all pushed commits (either directly pushed by authorized team members or due to merging a PR).

The result of such PR build runs will be visible within the individual PR ("checks" section) and in the list of open PR. Same applies for the commit builds on the commit history list.

The build result is visualized as follows:

• Orange circle = Build pending/running
• Green tick mark = Build passed
• Red cross = Build failed

Clicking on the related icons or links will directly ope the build result on our CI server. The last results can be seen here.

Among defining the status of the Pull Request, each such build also produces a debug APK for install: cgeo-debug.apk (without key for google maps). Note that even a failed build may have an apk file.

The CI executes different "build stages", and depending on which stage fails there might be build results available from previous stage. The following "stages" are executed from a logical perspective (note that real CI might execute them in different order or different grouping. TODO: someone knowing our CI better might want to review the following):

• Compile code
• Execute unit tests (Non-instrumented unit tests)
• Run code style checks (Codacy)
• Build installable APK (cgeo-debug.apk)
• Install APK in emulator and run Android instrumented tests

Jenkins is configured with 2 executors. This allows to run multiple jobs in parallel (which is necessary for having nested jobs, where one master job invokes different child jobs). As there is only 1 Android emulator, we cannot run multiple Android tests in parallel. Therefore each job accessing the emulator must have these settings active:

• Throttle concurrent builds
• Multi-Project Throttle Category: Android Emulator

Jenkins can generally be restarted from the web page. This should not be done, as the installation is somewhat special. Restarts should therefore always be done by mucek4 from the terminal.

We implemented in our CI the GitHub Pull Request Builder Plugin.

When a new pull request is opened in the project and the author of the pull request isn't whitelisted, builder will ask Can one of the core team members give me the the permission to test this?. One of the admins can comment

• ok to test to accept this pull request for testing
• test this please for one time test run
• add to whitelist to add the author to the whitelist

For more details see https://github.com/jenkinsci/ghprb-plugin/blob/master/README.md .

This section describes how to setup the integration between Github and our CI (as of of 12/2021).

Note: The PR Builder Plugin and the commit builder can automatically manage the below mentioned webhooks. This however was found not working lately (not further investigated), therefore the configuration guide below describes the manual setup of webhooks.

In order to integrate these plugins into the Github workflow of this repository the following steps need to be taken:

• C1: Generate a SSH key pair for our bot user cgeo-ci-bot and store the public key on the SSH-key store of this user on Github and store the private key in the credential manager of our CI (Using authorization is mandatory since 11/2021 to pull from Github using the Github API)
• C2: Generate a webhook on Github with the following settings:
  • Payload URL: https://ci.cgeo.org/ghprbhook/
  • Content type: application/json
  • Secret: A self defined secret text to be stored on the CI side in a later step (Mandatory since 11/2021 on Github)
  • Events: Individual - Pull Request & Issue Comments
• C3: Generate an access token if not already existing (preferable using our dedicated cgeo-ci-bot bot account, who has appropriate access levels to the repository). The access token needs to following permissions:
  • admin:repo_hook
  • repo
  • repo:status Store the access token into the credential manager of our CI.
• Generate another webhook for submitting push events to Jenkins:
  • Payload URL: https://ci.cgeo.org/github-webhook/
  • Content type: application/json
  • Secret: You might reuse C2 secret here (not sure whether this is needed for that hook)
  • Event: Just the push event

Go to the Jenkins configuration page and configure the following:

• Section "Github":

  • Name: Choose a unique name
  • API URL: https://api.github.com
  • Credentials: C3 (see above)

• Section "Github Pull Request Builder":

  • Github Server API URL: https://api.github.com
  • Shared secret: C2 (see above)
  • Credentials: C3 (see above)
  • Description: A unique name

On the individual continous integration jobs the following needs to be configured:

• Section "Source Code Management"

  • Choose Git as SCM tool
  • Repository URL: git@github.com:cgeo/cgeo.git
  • Credentials: C1 (see above)

• For section "Build Trigger" select one of the following

  • Choose GitHub hook trigger for GITScm polling for commit builds
  • Choose Github Pull Request Builder for PR builds and select the matching PR build plugin description (see above) to be used
  • Activate Use github hooks for build triggering to use the webhook previously defined on Github. If you dont activate this option it will still work but only by regular polling (causing slight delays and might still miss events).

If some of the automatism fails between Github and our CI these are the starting points you should check:

• Check the Jenkins log on whether you see any authorization or webhook content problems.
• Check on the Github webhook page whether webhooks got generated and delivered properly. You can use "Edit" on the relevant webhooks to see more details about deliveries, responses and you can also trigger a re-delivery from there.