MonkeyCI Github Plugin

This is a Clojure lib that provides functions to interact with the Github API from a MonkeyCI build.

Usage

In your .monkeyci directory, add the dependency to your deps.edn:

{:deps {com.monkeyci/plugin-github {:mvn/version "0.1.0-SNAPSHOT"}}}

Then, in your build.clj, require the namespace, and then you can add one of the provided build jobs:

(require '[monkey.ci.plugin.github :as gh])

Provided Jobs

The jobs currently provided are these:

release-job

Creates a release according to the current build settings. This job will only be executed if the build is triggered from a tag. It will use the tag name as release name, formatted using the configured format string.

;; Job that will create a release in Github for the commit tag,
;; formatting the tag by prefixing it with a `v`.
(gh/release-job {:name-format "v%s"})

This job in turn invokes the create-release! function in Github. This call requires some sort of authentication to the Github API, for which it will automatically fetch the github-token build parameter, or you can provide your own :token in the job configuration. If no token is provided, the job will fail.

The jobs usually run inside the build script itself, so they don't need to start a new container, and are very fast.

The release-job function accepts these options:

Option	Default	Meaning
name-format	v%s	How the release name is formatted using the tag name
dependencies		Optional dependencies for the job
org	Build org	The organisation to use when calling Github. Defaults to the organisation extracted from the repository url.
repo	Build repo	The repository to create the release on. Defaults to the configured MonkeyCI repo.
desc		Optional description for the release
token	github-token param or GITHUB_TOKEN env	The token to use to authenticate to Github.

patch-job

The patch-job can be used to patch one or more files in another Github repo. You're free to patch files in the same repo, but this can lead to an infinite build loop. Patching files can be useful when you have an infrastructure as code system and you want to auto-deploy a container image that you just built.

;; Patch a single file
(gh/patch-job {:org "my-org"
               :repo "my-repo"
	       :branch "main"
	       :path "path/to/file"
	       :patcher (fn [txt]
	                  "this is the new file contents")
	       :commit-msg "File updated by build"})

;; Patch a multiple files
(gh/patch-job {:org "my-org"
               :repo "my-repo"
	       :branch "main"
	       :patches
	       [{:path "path/to/file"
	         :patcher (fn [txt]
	                    "this is the new file contents")}
                {:path "path/to/other/file"
	         :patcher (fn [txt]
	                    "this is another file contents")}]
	       :commit-msg "Files updated by build"})

The patch-job function accepts these options:

Option	Default	Meaning
path		The path to the file to patch (overrides patches below)
patcher		The 1-arity function that receives the original file contents and returns the new contents
patches		List of patches, each containing a path and patcher
dependencies		Optional dependencies for the job
org	Build org	The organisation to use when calling Github. Defaults to the organisation extracted from the repository url.
repo	Build repo	The repository to create the release on. Defaults to the configured MonkeyCI repo.
commit-msg		The commit message to use
token	github-token param or GITHUB_TOKEN env	The token to use to authenticate to Github.
job-id	patch	The id of the job

TODO

• As soon as MonkeyCI supports it, we should allow invoking the MonkeyCI API to create the release.
• Allow using app config (client id and secret) to authenticate to Github.

License

Copyright (c) 2024-2025 by Monkey Projects

MIT License