craft

README

craft

---

• How to use ?
  • Go
  • Linux
• Commands
  • Init
  • Generate
• Craft file
  • VSCode association and schema
• Generations
• Who is using craft ?
• Craft as an SDK

How to use ?

Go

go install github.com/kilianpaquier/craft/cmd/craft@latest

Linux

OS="linux" # change it depending on your case
ARCH="amd64" # change it depending on your case
INSTALL_DIR="$HOME/.local/bin" # change it depending on your case

new_version=$(curl -fsSL "https://api.github.com/repos/kilianpaquier/craft/releases/latest" | jq -r '.tag_name')
url="https://github.com/kilianpaquier/craft/releases/download/$new_version/craft_${OS}_${ARCH}.tar.gz"
curl -fsSL "$url" | (mkdir -p "/tmp/craft/$new_version" && cd "/tmp/craft/$new_version" && tar -xz)
cp "/tmp/craft/$new_version/craft" "$INSTALL_DIR/craft"

Commands

Craft initializes or generates craft projects. Craft projects are only defined by a .craft file
and multiple files automatically generated to avoid multiple hours to setup Continuous Integration, coverage, security analyses, helm chart, etc.

Craft generation can be done with 'craft' command or 'craft generate' command.
Additional generation command are available to generate only subparts of craft layout (like 'craft chart').

Usage:
  craft [flags]
  craft [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  generate    Generate project layout
  help        Help about any command
  init        Initialize craft project
  version     Show current craft version

Flags:
  -d, --dir string          set directory where generation will be made (default is current directory)
  -h, --help                help for craft
      --log-format string   set logging format (either "text" or "json") (default "text")
      --log-level string    set logging level (default "info")

Use "craft [command] --help" for more information about a command.

Init

Initialize new craft project

Usage:
  craft init [flags]

Flags:
  -h, --help   help for init

Global Flags:
  -d, --dir string          set directory where generation will be made (default is current directory)
      --log-format string   set logging format (either "text" or "json") (default "text")
      --log-level string    set logging level (default "info")

Generate

Generate project layout

Usage:
  craft generate [flags]

Flags:
  -h, --help   help for generate

Global Flags:
  -d, --dir string          set directory where generation will be made (default is current directory)
      --log-format string   set logging format (either "text" or "json") (default "text")
      --log-level string    set logging level (default "info")

Craft file

Craft project generation is based on root's .craft file, it can contain the following configurations:

# bot in charge of keeping dependencies up to date
bot: dependabot | renovate

# project's CI (optional)
# providing it will create the appropriate ci files (.gitlab-ci.yml, .github/actions, .github/workflows)
ci:
  # auth configurations for various features in CI
  auth:
    # maintenance auth strategy for the specified maintenance bot (just above)
    maintenance: github-app | github-token | personal-token

    # release auth for github only (how should the release token be retrieved)
    # will stay empty when using gitlab CICD
    release: github-app | github-token | personal-token

  docker:
    # target path for docker push (i.e. kilianpaquier/craft)
    # (optional, by default will be provisionned with <owner>/<repository>)
    path: kilianpaquier/craft
    # specific exposed port (optional, default is 3000)
    # used in various places like helm values.yml service port
    # Dockerfile exposed port
    port: 3000
    # specific docker registry to push images on
    # (optional, by default the CI platform decides, both GitHub and GitLab CI/CD points to their own registry)
    # used in various places like helm values.yml images registry
    # github release workflow to push images
    registry: ghcr.io

  deployment:
    # deployment automatisation on default branch
    auto: true | false
    # deployment platform name
    platform: kubernetes | netlify | pages

  helm:
    # target path for helm cm-push (i.e. kilianpaquier/craft)
    # (optional, by default will be provisionned with <owner>/<repository>)
    path: kilianpaquier/craft
    # whether to push the project helm chart on an helm repository or not
    publish: auto | manual | none
    # specific helm repository to push the generated chart on
    # (optional, by default the CI platform decides, both GitHub and GitLab CI/CD points to their own registry)
    # OCI based repositories can be used
    registry: (oci://)?ghcr.io

  # ci name - self-explaining what each value will generate - (required when ci section is given)
  name: github | gitlab

  # ci global options, providing one or multiple options with tune the ci generation (optional)
  options:
    - codecov
    - codeql
    - labeler
    - pre-commit:auto-commit
    - sonar

  # release specific options
  release:
    # whether the release should run automatically
    auto: true | false
    # whether backmerging should be configured for main, staging and develop branches
    backmerge: true | false

# project's description (optional)
# used in various places like helm Chart.yml description
# Dockerfile description label
description: some useful description

# list of parts to not generate.
exclude:
  - goreleaser
  - makefile
  - pre-commit
  - shell

# list of optional parts to generate.
include:
  - pre-commit:gomod-tidy
  - renovate:post-upgrade

# project's license (optional)
# providing it will download the appropriate license
# used in various places like goreleaser executables license
# github release workflow license addition to releases
license: agpl-3.0 | apache-2.0 | bsd-2-clause | bsd-3-clause | bsl-1.0 | cc0-1.0 | epl-2.0 | gpl-2.0 | gpl-3.0 | lgpl-2.1 | mit | mpl-2.0 | unlicense

# project's maintainers (at least one must be provided)
# the first maintainer will be referenced in various places like in goreleaser configuration
# Dockerfile maintainer / authors label
# sonar.properties organization and project key prefix
# helm values.yml for images owner (e.g ghcr.io/maintainer/app_name)
# all maintainers will be referenced in dependabot assignees and reviewers
# helm Chart.yml maintainers
maintainers:
  - name: maintainer
    email: maintainer@example.com
    url: maintainer.example.com

# platform override in case of gitlab on premise, bitbucket on premise, etc.
# by default, an on premise gitlab will be matched if the host contains "gitlab"
# by default, an on premise bitbucket will be matched if the host contains "bitbucket" or "stash"
# when not overridden, the platform is matched based on "git config --get remote.origin.url" on the returned host (github.com, gitlab.com, ...)
platform: bitbucket | gitea | github | gitlab

VSCode association and schema

When working on vscode, feel free to use craft's schemas to help setup your project:

{
    "files.associations": {
        ".craft": "yaml"
    }
}

It's only creating the association between yaml files and .craft, however combined with vscode extension redhat.vscode-yaml, it will load the schema fine since a header is added in all .craft when written.

Generations

Craft generation is based on separated parsers and separated generators.

• Each parser checks from .craft configuration and project's files to add specific behaviors in a shared structure.
• Each generator generates a part of a project layout (for instance, a generator is in charge of generating the helm chart).

Generation process first runs over all parsers to make sure a project is fully known with its specificities, then it runs over all generators.

Multiple examples:

• A go.mod is detected with Golang parser, combined with ci configuration, then the appropriate CI will be generated.
• A go.mod is detected with Golang parser and a hugo.(toml|yaml|...) or theme.(toml|yaml|...) is detected too, combined with the ci and deployment options, then the appropriate Netlify or Pages (it can be GitLab or GitHub) deployment will be generated in CI files.
• If exclude: [chart] is not given, a custom craft helm chart will be generated. This helm chart can deploy cronjobs, jobs and workers easily from values.yaml file.
• A package.json is detected with Node parser, combined with ci configuration, then the appropriate CI will be generated (codecov analysis, sonar analysis, lint, tests, build if needed).

Who is using craft ?

• https://github.com/kilianpaquier/compare (Golang library)
• https://github.com/kilianpaquier/craft (Golang CLI with executables as artifacts in releases)
• https://github.com/kilianpaquier/dotfiles (Dotfiles repository with various shell scripts)
• https://github.com/kilianpaquier/gitlab-storage-cleaner (Golang CLI with Docker deployment and executables as artifacts in releases)
• https://github.com/kilianpaquier/go-builder-generator (Golang CLI with executables as artifacts in releases)
• https://github.com/kilianpaquier/hugo-primer (Hugo theme)
• https://github.com/kilianpaquier/kilianpaquier.github.io (Hugo static website deployed with Netlify)
• https://github.com/kilianpaquier/pooling (Golang library)
• https://github.com/kilianpaquier/semantic-release-backmerge (semantic-release plugin with static build deployed in npmjs.org)
• https://github.com/kilianpaquier/zsh-plugins (ZSH plugins repository with various shell scripts)
• https://gitlab.com/nath7098/personal-website (Node static website deployed with Docker)

Craft as an SDK

Craft can also be used as an SDK, for that you may check the official documentation on pkg.go.dev.