CLI tkn-pac

Pipelines as Code CLI #

Pipelines as Code provide a powerful CLI designed to work with tkn plug-in. tkn pac allows you to :

  • bootstrap: quickly bootstrap a Pipelines as Code installation.
  • create: create a new Pipelines as Code Repository definition.
  • delete: delete an existing Pipelines as Code Repository definition.
  • generate: generate a simple pipelinerun to get you started with Pipelines as Code.
  • list: list Pipelines as Code Repositories.
  • logs: show the logs of a PipelineRun form a Repository CRD.
  • describe: describe a Pipelines as Code Repository and the runs associated with it.
  • resolve: Resolve a pipelinerun as if it were executed by pipelines as code on service.
  • webhook: Updates webhook secret.

Install #

You can grab the latest binary directly for your operating system from the releases page.

Available operating systems are :

  • MacOS - M1 and x86 architecture
  • Linux - 64bits - RPM, Debian packages and tarballs.
  • Linux - ARM 64bits - RPM, Debian packages and tarballs.
  • Windows - Arm 64 Bits and x86 architecture.
On windows tkn-pac will look for the kubernetes config in %USERPROFILE%\.kube\config on Linux and MacOS it will use the standard $HOME/.kube/config.

tkn pac plug-in is available from HomeBrew as a “Tap”, you simply need to run this command to install it :

brew install openshift-pipelines/pipelines-as-code/tektoncd-pac

and if you need to upgrade it :

brew upgrade openshift-pipelines/pipelines-as-code/tektoncd-pac

tkn pac plug-in is compatible with Homebrew on Linux

tkn-pac is available as a docker container, :

# use docker
podman run -e KUBECONFIG=/tmp/kube/config -v ${HOME}/.kube:/tmp/kube \
     -it  ghcr.io/openshift-pipelines/tkn-pac:stable tkn-pac help

If you want to install from the Git repository you can just do :

go install github.com/openshift-pipelines/pipelines-as-code/cmd/tkn-pac

You can install the tkn pac plugin from the Arch User Repository (AUR) with your favourite AUR installer like yay :

yay -S tkn-pac

Commands #

tkn pac bootstrap

bootstrap #

tkn pac bootstrap command will help you to get started installing and configuring Pipelines as code. It currently supports the following providers:

  • GitHub Application on public GitHub
  • GitHub Application on GitHub Enterprise

It will start checking if you have installed Pipelines as Code and if not it will ask you if you want to install (with kubectl) the latest stable release. If you add the flag --nightly it will install the latest code ci release.

Bootstrap detect the OpenShift Route automatically associated to the Pipelines as code controller service. If you don’t have an OpenShift install it will ask you for your public URL (ie: an ingress spec URL) You can override the URL with the flag --route-url.

tkn pac bootstrap github-app

bootstrap github-app #

If you only want to create a GitHub application to use with Pipelines as Code and not the full bootstrap excercise, you can use tkn pac bootstrap github-app directly which will skip the installation and only create the GitHub application and the secret with all the information needed in the pipelines-as-code namespace.

tkn pac create repo

Repository Creation #

tkn pac create repo – Creates a new Pipelines as Code Repository custom resource definition, With a Git repository to execute pipelineruns based on Git events. It will also generate a sample file with a PipelineRun in the .tekton directory called pipelinerun.yaml targeting the main branch and the pull_request and push events. You can customize this by editing the PipelineRun to target a different branch or event.

If you haven’t configured a provider previously, it will follow up with questions if you want to configure a webhook for your provider of choice.

tkn pac delete repo

Repository Deletion #

tkn pac delete repo – will delete a Pipelines as Code Repository definition.

You can specify the flag --cascade to optionally delete the attached secrets (ie: webhook or provider secret) to the Pipelines as Code Repository definition.

tkn pac list

Repository Listing #

tkn pac list – will list all the Pipelines as Code Repositories definition and display the last or the current status (if its running) of the PipelineRun associated with it.

You can add the option -A/--all-namespaces to list all repositories across the cluster. (you need to have the right for it).

You can select the repositories by labels with the -l/--selectors flag.

You can choose to display the real time as RFC3339 rather than the relative time with the --use-realtime flag.

On modern terminal (ie: OSX Terminal, iTerm2, Windows Terminal, GNOME-terminal, kitty and so on…) the links become clickable with control+click or ⌘+click (see the documentation of your terminal for more details) and will open the browser to the console/dashboard URL to see the details of the Pipelinerun associated with it.

tkn pac describe

Repository Describe #

tkn pac describe – will describe a Pipelines as Code Repository definition and the runs associated with it.

You can choose to display the real time as RFC3339 rather than the relative time with the --use-realtime flag.

When the last PipelineRun has failure it will print the last 10 lines of every tasks associated with the PipelineRun thas has been failed highlightign the ERROR or FAILURE and other patterns.

If you want to show the failures of another PipelineRun rather than the last one you can use the --target-pipelinerun or -t flag for that.

tkn pac logs
On modern terminal (ie: OSX Terminal, iTerm2, Windows Terminal, GNOME-terminal, kitty and so on…) the links become clickable with control+click or ⌘+click (see the documentation of your terminal for more details) and will open the browser to the console/dashboard URL to see the details of the Pipelinerun associated with it.
tkn pac logs

Logs #

tkn pac logs – will show the logs attached to a Repository.

If you don’t specify a repository on the command line it will ask you to choose one or auto select it if there is only one.

If there is multiple PipelineRuns attached to the Repo it will ask you to choose one or auto select it if there is only one.

If you add the -w flag it will open the console or the dashboard URL to the log.

The tkn binary needs to be installed to show the logs.

tkn pac generate

Generate #

tkn pac generate: will generate a simple pipelinerun to get you started with Pipelines as Code. It will try to be as smart as possible by detecting the current Git information if you run the command from your source code.

It has some basic language detection and add extra task depending on the language. For example if it detects a file named setup.py at the repository root it will add the pylint task to the generated pipelinerun.

tkn pac resolve

Resolve #

tkn-pac resolve: will run a pipelinerun as if it were executed by pipelines as code on service.

For example if you have a pipelinerun in the .tekton/pull-request.yaml file you can run the command tkn-pac resolve to see it running:

tkn pac resolve -f .tekton/pull-request.yaml|kubectl create -f -

Combined with a kubernetes install running on your local machine (likeCode Ready Containers or Kubernetes Kind ) you can see your run in action without having to generate a new commit.

If you run the command from your source code repository it will try to detect the parameters (like the revision or branch_name) using the information from the Git repository.

You can override the parameters with the -p flag.

For example if you want to use a Git branch as revision and another repo name than the current repo name you can just use :

tkn pac resolve -f .tekton/pr.yaml -p revision=main -p repo_name=othername

-f can as well accept a directory path rather than just a filename and grab every yaml or yml files from that directory.

Multiple -f arguments are accepted to provide multiple files on the command line.

You need to verify that git-clone task (if you use it) can access the repository to the SHA. Which mean if you test your current source code you need to push it first before using tkn pac resolve|kubectl create -.

Compared with running directly on CI, you need to explicitly specify the list of filenames or directory where you have the templates.

When you run the resolver it will try to detect if you have a {{ git_auth_secret }} string inside your template and if there is a match it will ask you to provide a Git provider token.

If you already have an existing secret created in your namespace matching your repository URL it will use it.

You can explicitely provide a token on the command line with the -t or --providerToken flag, or you can set the environment variable PAC_PROVIDER_TOKEN and it will use it instead of asking you.

With the --no-secret flag you can completely skip any secret generation.

There is no clean-up of the secret after the run.

tkn pac webhook add

Configure and create webhook secret for Github, Gitlab and Bitbucket Cloud provider #

tkn-pac webhook add [-n namespace]: Allows you to add new webhook secret for a given provider and update the value of the new webhook secret in the existing Secret object used to interact with Pipelines as Code

tkn pac webhook update-token

Update provider token for existing webhook #

tkn pac webhook update-token [-n namespace]: Allows you to update provider token for an existing Secret object to interact with Pipelines as Code.

Screenshot #

tkn-plug-in