Skip to content
This repository has been archived by the owner on Apr 27, 2023. It is now read-only.

Latest commit

 

History

History
276 lines (227 loc) · 8.6 KB

CONFIG.md

File metadata and controls

276 lines (227 loc) · 8.6 KB
Raw

Configuration

Machine account

It is preferable to create a 'machine account' and not use your personal account. For example, all projects for periph.io are tested with the account github.com/gohci-bot.

OAuth2 token

  • Visit github.com/settings/tokens.
    • Click Generate new token button on the top right.
    • Add a description like gohci
    • Check gist and repo:status
      • Do not give any write access to this token!
    • Click Generate token.
  • Save this AccessToken string, you'll need it later in the worker's gohci.yml at the oauth2accesstoken line.

Worker setup

Now it's time to setup the worker itself.

gohci requires Go 1.8

Debian

This includes Raspbian and Ubuntu.

  • Install Go.
    • The Go version in packages is kinda old, so it's preferable to install a recent version.
    • See official instructions for help.
  • Create a gohci standard account (optional).
  • Setup $PATH to include ~/go/bin
  • Install git.
  • Install gohci-worker.
  • Create the directory gohci.
  • Set up the system to run gohci-worker automatically and update it every day via systemd/setup.sh .

Overall it looks like this:

sudo apt install git
export PATH="$PATH:$HOME/go/bin"
echo 'export PATH="$PATH:$HOME/go/bin"' >> ~/.bash_aliases
go get -u -v periph.io/x/gohci/cmd/gohci-worker
mkdir -p ~/gohci
$HOME/go/src/periph.io/x/gohci/systemd/setup.sh

Windows

  • Install Go.
  • Install git
  • Create a gohci standard account (optional).
  • Enable auto-login.
    • Win-R
    • netplwiz
    • Uncheck Users must enter a user name and password to use this computer.
    • OK
    • Type password twice.
  • Create a batch file %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\gohci.bat that contains the following: 
    @echo off
title gohci
cd %USERPROFILE%\gohci
:loop
gohci-worker
goto loop
  • Auto-update can be done via the task scheduler. The following command will auto-update gohci-worker every day: 
    schtasks /create /tn "Update gohci-worker" /tr "go get -v -u periph.io/x/gohci/cmd/gohci-worker" /sc minute /mo 1439
    • The task should show up with: schtasks /query /fo table | more or navigating the GUI with taskschd.msc.
  • Open cmd and run: 
    go get -u -v periph.io/x/gohci/cmd/gohci-worker
mkdir %USERPROFILE%/gohci
cd %USERPROFILE%/gohci
  • Run gohci-worker twice to make sure the firewall popup is shown and you allow the app.

macOS

  • Install Xcode (which includes git).
  • Install Go.
  • Install Homebrew (optional).
  • Create a gohci standard account (optional).
  • Install gohci-worker and setup for auto-start: 
    go get -u -v periph.io/x/gohci/cmd/gohci-worker
mkdir -p ~/Library/LaunchAgents
cp $HOME/go/src/periph.io/x/gohci/macos/gohci.plist ~/Library/LaunchAgents
mkdir -p ~/gohci
  • Enable auto-login via system preferences.

Worker configuration

  • Create ~/gohci/gohci.yml with the default configuration: 
    mkdir -p ~/gohci
cd ~/gohci
gohci-worker
  • It will look like this, with comments added here: 
    # The TCP port the HTTP server should listen on. It needs to be "frontend" by an
# HTTPS enabled proxy, like caddyserver.com
port: 8080
# The GitHub webhook secret when receiving events:
webhooksecret: <random string>
# The GitHub oauth2 client token when updating status and gist:
oauth2accesstoken: Get one at https://github.com/settings/tokens
# Name of the worker as presented on the status:
name: raspberrypi
  • Edit the values based on your needs.
  • Run gohci-worker again and it will start a web server. When gohci-worker is running, updating gohci.yml will make the process quit (after completing any enqueued checks).
  • Reboot the host and make sure gohci-worker starts correctly.

Private repository

gohci-worker will automatically switch from HTTPS to SSH checkout when the repository is private. For it to work you must:

  • On your device, create a key via ssh-keygen -C "raspberrypi" and do not specify a password.
  • Visit github.com/<user>/<repo>/settings/keys.
  • Click Add deploy key.
  • Put a name of the device and paste the content of the public key at $HOME/.ssh/id_rsa.pub, %USERPROFILE%\.ssh\id_rsa.pub on Windows.
  • Do not check Allow write access!
    • This means the ssh key only works for this repository and grants read-only access.
  • Click Add key.

Project

Project access

The machine account must have access to set a commit status:

  • As your normal account, visit github.com/<user>/<repo>/settings/collaboration.
  • Add the machine account as a Write collaborator.
    • Sadly Write access is needed even for just status update. This is fine because:
      • Your machine account doesn't have an ssh key setup.
      • Your machine account has 2FA enabled.
      • The OAuth2 token is read only.
  • Login as the machine account on GitHub and accept the invitation.

Webhook

Visit to github.com/<user>/<repo>/settings/hooks and create a new webhook.

  • Payload URL: Use your worker IP address or hostname as the hook URL, https://1.2.3.4/gohci/workerA?altPath=foo.io/x/project&superUsers=user1,user2,user3.
    • altPath: Set it when using canonical import path. For example, periph.io/x/gohci. Leave it unspecified otherwise, which should be the general case.
    • superUsers: a comma separate list of GitHub user accounts. These users can trigger a check run by typing the comment gohci on a PR or a commit as explained in the FAQ.
    • Both altPath and superUsers are optional.
  • Content type: select application/json.
  • Type the random string found in webhooksecret in gohci.yml.
  • Click Let me select individual events and check:
    • Commit comments
    • Issue Comments
    • Pull requests
    • Pull request review comments
    • Push
    • All the items except the last one are for the magic gohci hotword by super users. The last one is for post merge testing.
  • Save the settings. If the 'ping' is red, it means that you may have typoed the query argments (altPath or superUsers) or that the HTTPS proxy is misconfigured.

Project config

Now it's time to customize the checks run via a .gohci.yml in the root directory of your repository.

Refer to the official documentation.

When the worker name is not provided, this becomes the default checks as in this example:

# See https://github.com/periph/gohci
version: 1
workers:
- name: win10
  checks:
  - cmd:
    - go
    - test
    - -race
    - ./...
  - cmd:
    - go
    - vet
    - ./...
- checks:
  - cmd:
    - go
    - test
    - ./...

Testing

Push a new branch to your repository with a .gohci.yml file. Check the gohci worker logs to see progress, and look at the commits to see status being updated. You can see it at github.com/<user>/<repo>/commits/<branch>