GitHub

Configure GitHub

The recommended way to use Zuul with GitHub is by creating a GitHub App. This allows you to easily add it to GitHub projects, and reduces the likelihood of running into GitHub rate limits. You’ll need an organization in Github for this, so create one if you haven’t already. In this example we will use my-org.

To create a GitHub application:

  • Go to your organization settings page to create the application, e.g.: https://github.com/organizations/my-org/settings/apps/new

  • Set GitHub App name to “my-org-zuul”

  • Set Setup URL to your setup documentation, when user install the application they are redirected to this url

  • Set Webhook URL to http://<zuul-hostname>:<port>/api/connection/<connection-name>/payload.

  • Create a Webhook secret

  • Set permissions:

    • Repository administration: Read

    • Checks: Read & Write

    • Repository contents: Read & Write (write to let zuul merge change)

    • Issues: Read & Write

    • Pull requests: Read & Write

    • Commit statuses: Read & Write

  • Set events subscription:

    • Check run

    • Commit comment

    • Create

    • Push

    • Release

    • Issue comment

    • Issues

    • Label

    • Pull request

    • Pull request review

    • Pull request review comment

    • Status

  • Set Where can this GitHub App be installed to “Any account”

  • Create the App

  • Generate a Private key in the app settings page

Go back to the General settings page for the app, https://github.com/organizations/my-org/settings/apps/my-org-zuul and look for the app ID number, under the About section.

Edit /etc/zuul/zuul.conf to add the following:

sudo bash -c "cat >> /etc/zuul/zuul.conf <<EOF

[connection github]
driver=github
app_id=<APP ID NUMBER>
app_key=/etc/zuul/github.pem
webhook_token=<WEBHOOK SECRET>
EOF"

Upload the private key which was generated earlier, and save it in /etc/zuul/github.pem.

Restart all of Zuul:

sudo systemctl restart zuul-executor.service
sudo systemctl restart zuul-web.service
sudo systemctl restart zuul-scheduler.service

Go to the Advanced tab for the app in GitHub, https://github.com/organizations/my-org/settings/apps/my-org-zuul/advanced, and look for the initial ping from the app. It probably wasn’t delivered since Zuul wasn’t configured at the time, so click Resend and verify that it is delivered now that Zuul is configured.

Create two new repositories in your org. One will hold the configuration for this tenant in Zuul, the other should be a normal project repo to use for testing. We’ll call them zuul-test-config and zuul-test, respectively.

Visit the public app page on GitHub, https://github.com/apps/my-org-zuul, and install the app into your org.

Edit /etc/zuul/main.yaml so that it looks like this:

- tenant:
    name: quickstart
    source:
      zuul-git:
        config-projects:
          - zuul/zuul-base-jobs
        untrusted-projects:
          - zuul/zuul-jobs
      github:
        config-projects:
          - my-org/zuul-test-config
        untrusted-projects:
          - my-org/zuul-test

The first section, under zuul-git imports the standard library of Zuul jobs that we configured earlier. This adds a number of jobs that you can immediately use in your Zuul installation.

The second section is your GitHub configuration.

After updating the file, restart the Zuul scheduler:

sudo systemctl restart zuul-scheduler.service

Add an initial pipeline configuration to the zuul-test-config repository. Inside that project, create a zuul.yaml file with the following contents:

- pipeline:
    name: check
    description: |
      Newly opened pull requests enter this pipeline to receive an
      initial verification
    manager: independent
    trigger:
      github:
        - event: pull_request
          action:
            - opened
            - changed
            - reopened
        - event: pull_request
          action: comment
          comment: (?i)^\s*recheck\s*$
        - event: check_run
    start:
      github:
        check: 'in_progress'
        comment: false
    success:
      github:
        check: 'success'
    failure:
      github:
        check: 'failure'

Merge that commit into the repository.

In the zuul-test project, create a .zuul.yaml file with the following contents:

- project:
    check:
      jobs:
        - noop

Open a new pull request with that commit against the zuul-test project and verify that Zuul reports a successful run of the noop job.