Github Submodule Hook

This service provide an API to update submodules to a specific SHA on a repository. This can be triggered by:

• Manual request (e.g. using curl)
• Github webhooks:
  • Push
  • PR validation
• Gitlab webhooks:

  • Push

  • PR validation

Configuration

The whole configuration is defined in the configuration file. The file is in JSON-format.

It can be passed to the program with the -c option, otherwise, it will check the following places:

• local file named config.json

• Environment variable GITHUB_SUBMODULE_HOOK_CONFIG

• ~/.github_submodule_hook/config.json

• /etc/github_submodule_hook

• file config.json in the same directory as the executable

config.json

{
    "user_file": "users.txt",   // Optional: The file that contains the mapping "user = token"
    "token": "mytoken",         // The token to access the github API (need enough permission)
    "permissions": {            // Permisson tree: you give, for each user, access to different repository
        "<user1>": {
            "<owner>": {
                "<repo>": {
                    "<branch>": [
                        "<submodule1>"
                    ]
                }
            }
        }
    },
    // Define the hooks and which repository to update
    "hooks": {
        "<owner>": {              // owner that triggered the hook
            "<repo>": {           // repository that triggered the hook
                "<branch>": [     // branch that triggered the hook
                    // List of repository + branch + submodule to update
                    {
                        "owner": "<owner-to-update>",
                        "repo": "<repo-to-update>",
                        "branch": "<branch-to-update>",
                        "submodule": "<submodule-to-update>"
                    }
                ]
            }
        }
    }
}

I choose to use a tree owner -> repo -> branch -> submodule for simplicity when we have for example only 1 owner but many repositories. I also wanted a file that can be manually edited

users.txt (or the name you choose to use)

use the CLI to add them:

github_submodule_hook config user add user1

Nb: the file contains 1 entry by line in the following format

{username} = {base64(sha512(token))}

You could generate your own token if you want but this is strongly discouraged.

Usage

user1 can now do the following query

curl -X POST localhost:8000/update/<owner>/<repo>/<branch>/<submodule>/<hash>?token?abcd

Build

cargo build --release --target=x86_64-unknown-linux-gnu

Using Cross

This simplifies cross-build

Install Cross

cargo install cross

Use it to build

cross build --target x86_64-unknown-linux-gnu --release

Choices

Token

• UUID4: This is random and non deterministic, the size is great too.
• SHA512: We don't need any password-specialized hash algorithm:

  • The entropy of the token is good (which is not the case for human password), we don't need salt

  • We don't need slow-by-design algorithm because of the number of possible values.

Misc

For the CLI, I used clap with declaration. I needed to configure cargo

cargo add clap --features derive

Development

• Expose the webhook using ngrok

  ngrok http 8000