Skip to content

Getting started with Zuul-Ci and GitHub

Notifications You must be signed in to change notification settings

tibeerorg/zuul_setup_guide

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
 
 

Repository files navigation

Zuul getting started - with GitHub

This documentation is based on https://zuul-ci.org/docs/zuul/tutorials/quick-start.html and NOT purposed for production usage.

Get yourself a zuul instance

You might want to use local docker or some VM (with docker). docker-compose is also required.

Prepare GitHub app (on your machine)

For this demo, I will stick with the GitHub app method and NOT the webhook method. You can either create one for your organization or for your account. If can be public or private, though private would make more sense. Otherwise other people could install them in their repository and might abuse them for crypto-minig, etc.

  1. Go to the settings of your account/organization
  2. Select Developer settings on the left hand side
  3. Select GitHub Apps on the left hand side
  4. Select New GitHub App on the right hand side
  5. Select a unique GitHub App name, e.g. tibeerorg-zuul
  6. Select a dummy Homepage URL (this URL is opened when installing this app to a repository). I used https://www.google.com
  7. Set the Webhook URL to
    http://<zuul-hostname>:<port>/api/connection/<connection-name>/payload
    where
    • zuul-hostname is the IP or DNS name of your server
    • port is the Zuul port (typically 9000)
    • connection-name is the name you will later set in your zuul configuration. In this case I use githubzuulapp
  8. Set the Webhook secret to a value of your choice and save it for later. I'll use wekhooksecretvalue
  9. Select the following Repository persmissions:
    Permission Access
    Administration Read-only
    Checks Read & write
    Contents Read & write
    Issues Read & write
    Pull requests Read & write
    Commit statuses Read & write
  10. Select the events you whish to subscribe to:
  • Check run
  • Commit comment
  • Create
  • Issue comment
  • Issues
  • Label
  • Pull request
  • Pull request review
  • Pull request review comment
  • Push
  • Release
  • Status
  1. Select Where can this GitHub App be installed? to Only on this account
  2. Click on Create GitHub App
  3. Save also the App ID for later (in our case 121873)
  4. Scroll down to Private keys and click Generate a private key
  5. Save the received pem file for later
  6. Install the GitHub app to your whished repositories / accounts / repositories by clicking on Install App on the left hand side.

Note: sometimes it might happen that GitHub does not save your Webhook secret. Just re-enter it and save it again.

Prepare Zuul config (on your Zuul instance)

Clone the example repository

git clone https://opendev.org/zuul/zuul

Replace all content with the equivalant content below. Note the name of the source stanza matches your connection name you put earlier in the Webhook URL. Note that at least the config-projects GitHub respositories need to exists before you start your Zuul services. You may use the one from this organization, but I would suggest to clone it to your account/organization (then you will also be able to set the log server). The opendev.org connection is highly recommended. The base jobs are based on this job collection. By defining include you can restrict zuul to only load jobs and not something like pipelines.

~/zuul/doc/source/examples/etc_zuul/main.yaml

- tenant:
    name: showcase
    source:
      githubzuulapp:
        config-projects:
          - tibeerorg/zuul_config:
              load-branch: main
        untrusted-projects:
          - tibeerorg/zuul_demo_repo
      opendev.org:
        untrusted-projects:
          - zuul/zuul-jobs:
              include:
                - job

Throw away all "connection" sections and replace all of them with these new two. Note, that you need to insert your webhook_token and app_id values you saved earlier. Also note that your connection name needs to match the name you put earlier in the Webhook URL. Otherwise you won't get a connection.

~/zuul/doc/source/examples/etc_zuul/zuul.conf

[connection "githubzuulapp"]
driver=github
webhook_token=wekhooksecretvalue
app_id=121873
app_key=/etc/zuul/github.pem

[connection "opendev.org"]
name=opendev
driver=git
baseurl=https://opendev.org

The github.pem file is not there yet. Use the pem file you saved earlier and upload it to your Zuul instance to this file: ~/zuul/doc/source/examples/etc_zuul/github.pem

Start zuul services (on your zuul instance)

cd zuul/doc/source/examples
sudo -E docker-compose -p zuul-tutorial up -d

This might take a few minutes.

Check the connection (on your machine)

Go back to your GitHub app settings:

  1. Open the Settings
  2. Click on Installed GitHub Apps on the left hand side
  3. Click Configure on the right hand side
  4. Click App settings on the top
  5. Click Advanced on the left hand side
  6. Check if the top entry has a green tick (if not, click on Redeliver)

Access your Zuul (on your machine)

You should now be able to access your Zuul installation by directing your browser to the IP address or DNS name of your server followed by the port (typically 9000)

About

Getting started with Zuul-Ci and GitHub

Topics

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published