docs: add documentation generation and ci

Signed-off-by: Massimiliano Giovagnoli <[email protected]>

.goreleaser.yaml

@@ -1,4 +1,4 @@
-project_name: peribolos-owners-syncer
+project_name: kamajicli
 
 before:
  hooks:
@@ -50,29 +50,26 @@ signs:
  artifacts: all
  output: true
 
-# create a docker image
-# https://goreleaser.com/customization/docker
-dockers:
-- image_templates:
- - 'ghcr.io/maxgio92/{{.ProjectName}}:{{ .Tag }}'
- - 'ghcr.io/maxgio92/{{.ProjectName}}:v{{ .Major }}.{{ .Minor }}'
- - 'ghcr.io/maxgio92/{{.ProjectName}}:latest'
- use: buildx
- build_flag_templates:
- - "--pull"
- - "--label=org.opencontainers.image.created={{.Date}}"
- - "--label=org.opencontainers.image.name={{.ProjectName}}"
- - "--label=org.opencontainers.image.revision={{.FullCommit}}"
- - "--label=org.opencontainers.image.version={{.Version}}"
- - "--label=org.opencontainers.image.source={{.GitURL}}"
+kos:
+- base_image: cgr.dev/chainguard/static
+ repository: ghcr.io/maxgio92/kamajicli
+ bare: true
+ tags:
+ - '{{ .Version }}'
+ - '{{ .Major }}.{{ .Minor }}'
+ - latest
+ platforms:
+ - linux/amd64
+ - linux/arm64
+ sbom: spdx
 
 # signs our docker image
 # https://goreleaser.com/customization/docker_sign
 docker_signs:
 - cmd: cosign
  env:
  - COSIGN_EXPERIMENTAL=1
- artifacts: images
+ artifacts: all
  output: true
  args:
  - 'sign'

Makefile

@@ -1,21 +1,7 @@
 APP := peribolos-syncer
-VERSION := 0.1.1
 
 user := maxgio92
-oci_image := quay.io/$(user)/$(APP)
-
-bins := docker git go gofumpt golangci-lint
-
-PACKAGE_NAME := github.com/$(user)/$(APP)
-GOLANG_CROSS_VERSION ?= v$(shell sed -nE 's/go[[:space:]]+([[:digit:]]\.[[:digit:]]+)/\1/p' go.mod)
-
-GIT_HEAD_COMMIT ?= $$($(git) rev-parse --short HEAD)
-GIT_TAG_COMMIT ?= $$($(git) rev-parse --short $(VERSION))
-GIT_MODIFIED_1 ?= $$($(git) diff $(GIT_HEAD_COMMIT) $(GIT_TAG_COMMIT) --quiet && echo "" || echo ".dev")
-GIT_MODIFIED_2 ?= $$($(git) diff --quiet && echo "" || echo ".dirty")
-GIT_MODIFIED ?= $$(echo "$(GIT_MODIFIED_1)$(GIT_MODIFIED_2)")
-GIT_REPO ?= $$($(git) config --get remote.origin.url)
-BUILD_DATE ?= $$($(git) log -1 --format="%at" | xargs -I{} date -d @{} +%Y-%m-%dT%H:%M:%S)
+bins := git go gofumpt golangci-lint ginkgo
 
 define declare_binpaths
 $(1) = $(shell command -v 2>/dev/null $(1))
@@ -25,6 +11,14 @@ $(foreach bin,$(bins),\
  $(eval $(call declare_binpaths,$(bin)))\
 )
 
+.PHONY: ginkgo
+ginkgo:
+ @$(go) install github.com/onsi/ginkgo/v2/ginkgo
+
+.PHONY: docs
+docs:
+ @go run docs/docs.go
+
 .PHONY: build
 build:
  @$(go) build .
@@ -34,8 +28,8 @@ run:
  @$(go) run .
 
 .PHONY: test
-test:
- @$(go) test -v -cover -gcflags=-l ./...
+test: ginkgo
+ @$(ginkgo) ./...
 
 .PHONY: lint
 lint: golangci-lint
@@ -49,20 +43,6 @@ golangci-lint:
 gofumpt:
  @$(go) install mvdan.cc/[email protected]
 
-.PHONY: oci/build
-oci/build: test
- @$(docker) build . -t $(oci_image):$(VERSION) -f Dockerfile \
- --build-arg GIT_HEAD_COMMIT=$(GIT_HEAD_COMMIT) \
- --build-arg GIT_TAG_COMMIT=$(GIT_TAG_COMMIT) \
- --build-arg GIT_MODIFIED=$(GIT_MODIFIED) \
- --build-arg GIT_REPO=$(GIT_REPO) \
- --build-arg GIT_LAST_TAG=$(VERSION) \
- --build-arg BUILD_DATE=$(BUILD_DATE)
-
-.PHONY: oci/push
-oci/push: oci/build
- @$(docker) push $(oci_image):$(VERSION)
-
 .PHONY: clean
 clean:
  @rm -f $(APP)
@@ -73,4 +53,3 @@ help: list
 .PHONY: list
 list:
  @LC_ALL=C $(MAKE) -pRrq -f $(lastword $(MAKEFILE_LIST)) : 2>/dev/null | awk -v RS= -F: '/^# File/,/^# Finished Make data base/ {if ($$1 !~ "^[#.]") {print $$1}}' | sort | egrep -v -e '^[^[:alnum:]]' -e '^$@$$'
-

cmd/contants.go

@@ -0,0 +1,10 @@
+package cmd
+
+const (
+ CommandName = "peribolos-syncer"
+ CommandLongDescription = `
+Tool to synchronize Peribolos configuration from external sources.
+
+It synchronize GitHub Team configurations with external GitHub people source of truth, like OWNERS files.
+`
+)

cmd/root.go

@@ -24,13 +24,12 @@ import (
  "github.com/maxgio92/peribolos-syncer/internal/output"
 )
 
-var cfgFile string
-
 // New returns a new root command.
 func New() *cobra.Command {
  cmd := &cobra.Command{}
- cmd.Use = "orgs-owners-syncer"
- cmd.Short = "A brief description of your application"
+ cmd.Use = CommandName
+ cmd.Long = CommandLongDescription
+ cmd.DisableAutoGenTag = true
 
  // Add subcommands.
  cmd.AddCommand(sync.New())

cmd/sync/contants.go

@@ -0,0 +1,6 @@
+package sync
+
+const (
+ commandName = "sync"
+ commandShortDescription = "Synchronize Peribolos config with external GitHub people source of truth"
+)

cmd/sync/github/constants.go

@@ -1,6 +1,17 @@
 package github
 
 const (
+ commandName = "github"
+ commandShortDescription = "Synchronize Peribolos config on remote GitHub repositories via Pull Request"
+ commandExample = `
+peribolos-syncer sync github --org=acme --team=app-maintainers
+--peribolos-config-path=config/org.yaml --peribolos-config-repository=community --peribolos-config-git-ref=main
+--owners-repository=app --owners-git-ref=main --owners-path=OWNERS
+--github-username=bot --github-token-path=./bot_token
+--git-author-name=bot --git-author-email="[email protected]"
+--gpg-public-key=./bot.pub --gpg-private-key=./bot.asc
+`
+
  syncerSignature = "Autogenerated with [peribolos-syncer](https://github.com/maxgio92/peribolos-syncer)."
  ownersDoc = "https://docs.prow.k8s.io/docs/components/plugins/approve/approvers/#overview"
  peribolosConfigFile = "org.yaml"

cmd/sync/github/sync_github.go

@@ -65,9 +65,10 @@ func New() *cobra.Command {
  }
 
  cmd := &cobra.Command{
- Use: "github",
- Short: "Synchronize Peribolos org.yaml file from OWNERS file on remote github repositories via Pull Request",
- RunE: o.Run,
+ Use: commandName,
+ Short: commandShortDescription,
+ Example: commandExample,
+ RunE: o.Run,
  }
 
  // Organization sync options.

cmd/sync/local/constants.go

@@ -17,6 +17,12 @@ limitations under the License.
 package local
 
 const (
+ commandName = "local"
+ commandShortDescription = "Synchronize Peribolos config on local filesystem"
+ commandExample = `
+peribolos-syncer sync local --owners-file OWNERS --peribolos-config org.yaml --org acme --team app-maintainers
+`
+
  flagOwnersFilePath = "owners-file"
  flagPeribolosConfigFilepath = "orgs-config"
  defaultOwnersFilepath = "OWNERS"

cmd/sync/local/sync_local.go

@@ -44,8 +44,9 @@ func New() *cobra.Command {
  }
 
  cmd := &cobra.Command{
- Use: "local",
- Short: "Synchronize Peribolos org.yaml file from OWNERS file in the local filesystem",
+ Use: commandName,
+ Short: commandShortDescription,
+ Example: commandExample,
  }
 
  cmd.RunE = o.Run

cmd/sync/sync.go

@@ -26,8 +26,8 @@ import (
 // New returns a new root command.
 func New() *cobra.Command {
  cmd := &cobra.Command{
- Use: "sync",
- Short: "Synchronize Peribolos org,yaml file from OWNERS file",
+ Use: commandName,
+ Short: commandShortDescription,
  }
 
  // Add sync subcommand.

docs/_index.md

@@ -0,0 +1,27 @@
+---
+title: peribolos-syncer
+--- 
+
+## peribolos-syncer
+
+
+
+### Synopsis
+
+
+Tool to synchronize Peribolos configuration from external sources.
+
+It synchronize GitHub Team configurations with external GitHub people source of truth, like OWNERS files.
+
+
+### Options
+
+```
+ -h, --help help for peribolos-syncer
+```
+
+### SEE ALSO
+
+* [peribolos-syncer sync](peribolos-syncer_sync.md) - Synchronize Peribolos config with external GitHub people source of truth
+* [peribolos-syncer version](peribolos-syncer_version.md) - Return the syncer version
+

docs/docs.go

@@ -0,0 +1,52 @@
+package main
+
+import (
+ "fmt"
+ "os"
+ "path"
+ "strings"
+
+ "github.com/spf13/cobra/doc"
+
+ "github.com/maxgio92/peribolos-syncer/cmd"
+)
+
+const (
+ docsDir = "docs"
+ fileTemplate = `---
+title: %s
+--- 
+
+`
+)
+
+var (
+ filePrepender = func(filename string) string {
+ title := strings.TrimPrefix(strings.TrimSuffix(strings.ReplaceAll(filename, "_", " "), ".md"), fmt.Sprintf("%s/", docsDir))
+ return fmt.Sprintf(fileTemplate, title)
+ }
+ linkHandler = func(filename string) string {
+ if filename == cmd.CommandName+".md" {
+ return "_index.md"
+ }
+ return filename
+ }
+)
+
+func main() {
+ if err := doc.GenMarkdownTreeCustom(
+ cmd.New(),
+ docsDir,
+ filePrepender,
+ linkHandler,
+ ); err != nil {
+ fmt.Println(err)
+ os.Exit(1)
+ }
+
+ err := os.Rename(path.Join(docsDir, cmd.CommandName+".md"), path.Join(docsDir, "_index.md"))
+ if err != nil {
+ fmt.Println(err)
+ os.Exit(1)
+ }
+}

docs/peribolos-syncer_sync.md

@@ -0,0 +1,20 @@
+---
+title: peribolos-syncer sync
+--- 
+
+## peribolos-syncer sync
+
+Synchronize Peribolos config with external GitHub people source of truth
+
+### Options
+
+```
+ -h, --help help for sync
+```
+
+### SEE ALSO
+
+* [peribolos-syncer](_index.md) - 
+* [peribolos-syncer sync github](peribolos-syncer_sync_github.md) - Synchronize Peribolos config on remote GitHub repositories via Pull Request
+* [peribolos-syncer sync local](peribolos-syncer_sync_local.md) - Synchronize Peribolos config on local filesystem
+

docs/peribolos-syncer_sync_github.md

@@ -0,0 +1,63 @@
+---
+title: peribolos-syncer sync github
+--- 
+
+## peribolos-syncer sync github
+
+Synchronize Peribolos config on remote GitHub repositories via Pull Request
+
+```
+peribolos-syncer sync github [flags]
+```
+
+### Examples
+
+```
+
+peribolos-syncer sync github --org=acme --team=app-maintainers
+--peribolos-config-path=config/org.yaml --peribolos-config-repository=community --peribolos-config-git-ref=main
+--owners-repository=app --owners-git-ref=main --owners-path=OWNERS
+--github-username=bot --github-token-path=./bot_token
+--git-author-name=bot --git-author-email="[email protected]"
+--gpg-public-key=./bot.pub --gpg-private-key=./bot.asc
+
+```
+
+### Options
+
+```
+ --dry-run Dry run for testing. Uses API tokens but does not mutate.
+ --git-author-email string The Git author email with which write commits for the update of the Peribolos config
+ --git-author-name string The Git author name with which write commits for the update of the Peribolos config
+ --github-allowed-burst int Size of token consumption bursts. If set, --github-hourly-tokens must be positive too and set to a higher or equal number.
+ --github-app-id string ID of the GitHub app. If set, requires --github-app-private-key-path to be set and --github-token-path to be unset.
+ --github-app-private-key-path string Path to the private key of the github app. If set, requires --github-app-id to bet set and --github-token-path to be unset
+ --github-client.backoff-timeout duration Largest allowable Retry-After time for requests to the GitHub API. (default 2m0s)
+ --github-client.initial-delay duration Initial delay before retries begin for requests to the GitHub API. (default 2s)
+ --github-client.max-404-retries int Maximum number of retries that will be used for a 404-ing request to the GitHub API. (default 2)
+ --github-client.max-retries int Maximum number of retries that will be used for a failing request to the GitHub API. (default 8)
+ --github-client.request-timeout duration Timeout for any single request to the GitHub API. (default 2m0s)
+ --github-endpoint Strings GitHub's API endpoint (may differ for enterprise). (default https://api.github.com)
+ --github-graphql-endpoint string GitHub GraphQL API endpoint (may differ for enterprise). (default "https://api.github.com/graphql")
+ --github-host string GitHub's default host (may differ for enterprise) (default "github.com")
+ --github-hourly-tokens int If set to a value larger than zero, enable client-side throttling to limit hourly token consumption. If set, --github-allowed-burst must be positive too.
+ --github-throttle-org Strings Throttler settings for a specific org in org:hourlyTokens:burst format. Can be passed multiple times. Only valid when using github apps auth.
+ --github-token-path string Path to the file containing the GitHub OAuth secret.
+ --github-username string The GitHub username
+ --gpg-private-key string The path to the private GPG key for signing git commits
+ --gpg-public-key string The path to the public GPG key for signing git commits
+ -h, --help help for github
+ --org string The name of the GitHub organization to update configuration for
+ -r, --owners-git-ref string The base Git reference at which parse the OWNERS hierarchy (default "master")
+ -o, --owners-path string The path to the OWNERS file from the root of the Git repository. Ignored with sync-github.
+ --owners-repository string The name of the github repository from which parse OWNERS file
+ --peribolos-config-git-ref string The base Git reference at which pull the peribolos config repository (default "master")
+ -c, --peribolos-config-path string The path to the peribolos organization config file from the root of the Git repository (default "org.yaml")
+ --peribolos-config-repository string The name of the github repository that contains the peribolos organization config file
+ --team string The name of the GitHub team to update configuration for
+```
+
+### SEE ALSO
+
+* [peribolos-syncer sync](peribolos-syncer_sync.md) - Synchronize Peribolos config with external GitHub people source of truth
+