From 47d3bbe33c92b505ee418de55549bb3cad52f6e9 Mon Sep 17 00:00:00 2001 From: Chmouel Boudjnah Date: Fri, 30 Jun 2023 10:23:23 +0200 Subject: [PATCH] Use tkn pac create repository instead of repo and CRD -> CR Let's use the long form of the command tkn pac create repository instead of just repo and actually say CR instead of CRD since that's more accurate. Signed-off-by: Chmouel Boudjnah --- docs/content/_index.md | 17 ++- docs/content/docs/install/getting-started.md | 103 +++++++++++++------ pkg/cmd/tknpac/bootstrap/web.go | 2 +- 3 files changed, 86 insertions(+), 36 deletions(-) diff --git a/docs/content/_index.md b/docs/content/_index.md index 650f5e11b..0aae1ecc5 100644 --- a/docs/content/_index.md +++ b/docs/content/_index.md @@ -53,10 +53,19 @@ tracking using a Git workflow. ## Getting Started -The easiest way to get started is to use the `tkn pac` CLI and its [bootstrap](/docs/guide/cli/#commands) command. - -- This [Guide]({{< relref "/docs/install/getting-started.md" >}}) will help you getting started -- If you prefer a video, this [Walkthrough video](https://youtu.be/cNOqPgpRXQY) will guide you through the `tkn-pac bootstrap` flow. +The easiest way to get started is to use the `tkn pac` CLI and its +[bootstrap](/docs/guide/cli/#commands) command. We recommend you to start +playing with Pipelines-as-Code with your personal [GitHub](https://github.com/) +user by installing Pipelines-as-Code on your laptop with +[Kind](https://kind.sigs.k8s.io/) or [OpenShift +Local](https://developers.redhat.com/products/openshift-local/overview) and +explore how it works before installing it on your own cluster. + +- This [Guide]({{< relref "/docs/install/getting-started.md" >}}) will help you + get started by creating a GitHub Application, configuring Pipelines-as-Code, + and creating your first PipelineRun from a Pull Request. +- If you prefer a video, this [walkthrough video](https://youtu.be/cNOqPgpRXQY) + will guide you through the process. ## Documentation diff --git a/docs/content/docs/install/getting-started.md b/docs/content/docs/install/getting-started.md index c5e4213ff..7c7ff3961 100644 --- a/docs/content/docs/install/getting-started.md +++ b/docs/content/docs/install/getting-started.md @@ -1,12 +1,16 @@ --- -title: Getting quickly started +title: Getting started guide. weight: 2 --- # Getting started with Pipelines-as-Code This guide will walk you through the process of getting started with Pipelines-as-Code. -This will start with the installation of Pipelines-as-Code on your cluster, then the creation of a GitHub Application, the creation of a Repository CRD to specify which repository you want to use with Pipelines-as-Code and finally we are going to create a simple Pull Request to test that configuration and see how the Pipelines-as-Code flow looks like. +This will start with the installation of Pipelines-as-Code on your cluster, then +the creation of a GitHub Application, the creation of a Repository CR to specify +which repository you want to use with Pipelines-as-Code, olnd finally we are +going to create a simple Pull Request to test that configuration and see how the +Pipelines-as-Code flow looks like. ## Prerequisites @@ -26,7 +30,7 @@ Let's get started with `tkn pac bootstrap`: ### Pipelines-as-Code Installation -```console +```bash % tkn pac bootstrap => Checking if Pipelines-as-Code is installed. 🕵️ Pipelines-as-Code doesn't seem to be installed in the pipelines-as-code namespace. @@ -51,24 +55,34 @@ This will let your git platform provider (e.g., GitHub) reach the controller wit ### Tekton Dashboard -Another question is only asked if you are not running on OpenShift. It will detect if you have the [Tekton Dashboard](https://github.com/tekton/dashboard) installed and if you want to use it for the links to show the logs or description of the PipelineRun. +Another question is only asked if you are not running on OpenShift. It will +detect if you have the [Tekton Dashboard](https://github.com/tekton/dashboard) +installed and if you want to use it for the links to show the logs or +description of the PipelineRun. ```console 👀 We have detected a tekton dashboard install on http://dashboard.paac-127-0-0-1.nip.io ? Do you want me to use it? Yes ``` -## GitHub Application Creation +## GitHub Application -The next step is to create a GitHub Application. You don't necessarily need to use Pipelines-as-Code with a GitHub Application (you can use it with a simple webhook as well), but it's the method that will give you the best experience. +The next step is to create a GitHub Application. You don't necessarily need to +use Pipelines-as-Code with a GitHub Application (you can use it with a simple +webhook as well), but it's the method that will give you the best experience. -You first need to enter the name of the GitHub Application you want to create. This name must be unique, so try to choose a name that is not too obvious and won't conflict with existing applications. +You first need to enter the name of the GitHub Application you want to +create. This name must be unique, so try to choose a name that is not too +obvious and won't conflict with existing applications. ```console ? Enter the name of your GitHub application: My PAAC Application ``` -As soon as you press Enter, the CLI will try to launch your web browser with the URL , which will display a button to create the GitHub Application. When you click the button, you will be redirected to GitHub and see the following screen: +As soon as you press Enter, the CLI will try to launch your web browser with the +URL , which will display a button to create the GitHub +Application. When you click the button, you will be redirected to GitHub and see +the following screen: ![GitHub Application Creation](/images/github-app-creation-screen.png) @@ -80,14 +94,22 @@ If you are satisfied with the name, you can click the "Create GitHub App" button https://github.com/apps/my-paac-application -💡 Don't forget to run "tkn pac create repo" to create a new Repository CRD on your cluster. +💡 Don't forget to run "tkn pac create repository" to create a new Repository CR on your cluster. ``` -You can visit the provided URL, click on `App settings`, and inspect how the GitHub Application has been created. `tkn pac bootstrap` will have configured everything you need to get started with Pipelines-as-Code, but you can customize settings if necessary. +You can visit the your newly created GitHub Application by clicking on the URL, +by clicking on the `App settings` button you can inspect how the GitHub +Application has been created. The `tkn pac bootstrap` command will have +configured everything you need to get started with Pipelines-as-Code, but you +can customize advanced settings in there if necessary. + +{{< hint info >}} +A useful tab to look at is the "Advanced" tab, this is where you can see all the recent deliveries of the GitHub app toward the Pipelines-as-Code controller. This is useful to debug if you have any issues with the communication between GitHub and the endpoint URL, or to investigate which events are being sent. +{{< /hint >}} -### Creating a GitHub Repository and Adding the GitHub Application to It +### Creating a GitHub Repository -As mentioned at the end of the `tkn pac bootstrap` command, you need to create a Repository CRD to specify which repository you want to use with Pipelines-as-Code. +As mentioned at the end of the `tkn pac bootstrap` command, you need to create a Repository CR to specify which repository you want to use with Pipelines-as-Code. If you don't have a repository, you can easily create one using this template: @@ -96,35 +118,51 @@ If you don't have a repository, you can easily create one using this template: Choose your username (e.g., `chmouel` for me) and a repository name (e.g., `pac-demo`), then click the "Create repository from template" button. {{< hint info >}} -Pipelines-as-Code also works well with private repositories, but let's keep it simple for now and create a public repository. +Pipelines-as-Code also works well with [private repositories]({{< relref "/docs/guide/privaterepo.md" >}}), but let's keep it simple for now and create a public repository. {{< /hint >}} Your repository is now created on GitHub at . -Next, you need to add the GitHub Application you created to this repository. You can do that by going to the GitHub App URL provided by `tkn pac bootstrap`, for example: +### Install the GitHub Application in our Repository - +Next, you need to add the GitHub Application you created to this repository. You can do that by following these steps: -Click on the "Install" button and choose the repository you just created under your username. +1. Go to the GitHub App URL provided by `tkn pac bootstrap`, for example: [https://github.com/apps/my-paac-application](https://github.com/apps/my-paac-application). +2. Click on the "Install" button. +3. Choose the repository you just created under your username. + +Here is an example of what it looks like for me: ![GitHub Application Installation](/images/github-app-install-application-on-repo.png) -## Creating a Repository CRD +### Check-out the newly created repository -Let's go back to the terminal and Checkout the newly created repository: +Let's go back to the terminal and check-out the newly created repository +with Git: -```console +```bash git clone https://github.com/$yourusername/pac-demo cd pac-demo ``` -You are now ready to start the command: +We navigate inside our repository since `tkn pac` will use the Git information +to provide some hepful defaults with the subsequent commands we will execute. -```console -tkn pac create repo +## Create a Repository CR + +{{< hint info >}} +A Repository CR is how you configure Pipelines-as-Code. It's a Kubernetes object that is not part of the core Kubernetes API. It's a way to extend Kubernetes with new objects. In this case, we are using a CR to specify which Repository URL (among other [settings]({{< relref "/docs/guide/repositorycrd.md" >}})) we want to use with Pipelines-as-Code and the namespace location where our PipelineRuns will be run. +{{< /hint >}} + +You are now ready to create a Repository CR with the command: + +```bash +tkn pac create repository ``` -`tkn pac create repo` try to be smart and helpful, as soon you are launching it will have detected the git information of the current repository and will ask you if you want to use those values. +The command try to be smart and helpful, and as soon you are launching it will have +detected the git information of the current repository and will ask you if you +want to use those values. ```console ? Enter the Git repository url (default: https://github.com/chmouel/pac-demo): @@ -138,7 +176,7 @@ You probably want to press enter here to use the default value, and then it will ? Would you like me to create the namespace pac-demo-pipelines? (Y/n) ``` -When this is done the process will be over it will generate a `Repository` CRD in your cluster and create a directory called `.tekton` with a file named `pipelinerun.yaml` in it. +When this is done the process will be over it will generate a `Repository` CR in your cluster and create a directory called `.tekton` with a file named `pipelinerun.yaml` in it. ```console ℹ Directory .tekton has been created. @@ -157,13 +195,13 @@ Now that we have our Repository CR created in our namespace our `.tekton/pipelin Let's first create a branch to create a Pull Request from that branch. -```console +```bash git checkout -b tektonci ``` Let's commit the `.tekton/pipelinerun.yaml` file and push it to our repository: -```console +```bash git add . git commit -m "Adding Tekton CI` git push origin tektonci @@ -179,7 +217,7 @@ As soon as you create the Pull Request you will see that the Pipelines-as-Code h ![GitHub Application Installation](/images/github-app-install-CI-triggered.png) -You can click on the "Details" link to see the details of the running of the PipelineRun. `Pipelines-as-Code` will let you know that you can follow the logs on your Dashboard like Tekton Dashboard or OpenShift Pipelines Console or even via the tkn CLI on your cluster. +You can click on the "Details" link to see the details of the running of the PipelineRun. `Pipelines-as-Code` will let you know that you can follow the logs on your Dashboard like [Tekton Dashboard](https://github.com/tekton/dashboard) or the OpenShift Pipelines [Console](https://docs.openshift.com/container-platform/latest/web_console/web-console.html) or if you prefer you can use [tekton CLI](https://tekton.dev/docs/cli/) to follow the PipelineRun execution on your cluster. When the PipelineRun is finished you will see an error on that Detail screen: @@ -189,7 +227,7 @@ That was on purpose, we have detected some error on the Go code and GolangCI lin ![GitHub Application Installation](/images/github-app-matching-annotations.png) -### Fixing the error +### Fixing the error and pushing again Let's go ahead and go back to our terminal and fix that error. Edit the file `main.go` select everything and replace it with this content @@ -208,8 +246,8 @@ func main() { commit this file and push it to your branch: -```console -git commit -a -m "Fixing the error" +```bash +git commit -a -m "Errare humanum est, ignoscere divinum." git push origin tektonci ``` @@ -219,4 +257,7 @@ If you go back to your web browser you will see that the PipelineRun has been tr ## Conclusion -You have now successfully, setu-up and used Pipelines-as-Code to run your CI on your repository. You can now go ahead and customize your `.tekton/pipelinerun.yaml` file to your liking and add more tasks to it. +Congratulations! You have now successfully setup Pipelines-as-Code for running +Continuous Integration on your repository. Now, you can freely proceed to +[customize]({{< relref "/docs/guide/authoringprs.md" >}}) your `.tekton/pipelinerun.yaml` file as per your preferences and +include additional tasks as needed. diff --git a/pkg/cmd/tknpac/bootstrap/web.go b/pkg/cmd/tknpac/bootstrap/web.go index c5261612e..40e4726b3 100644 --- a/pkg/cmd/tknpac/bootstrap/web.go +++ b/pkg/cmd/tknpac/bootstrap/web.go @@ -75,7 +75,7 @@ func startWebServer(ctx context.Context, opts *bootstrapOpts, run *params.Run, j } fmt.Fprintf(opts.ioStreams.Out, "🚀 You can now add your newly created application on your repository by going to this URL:\n\n%s\n\n", *manifest.HTMLURL) - fmt.Fprintf(opts.ioStreams.Out, "💡 Don't forget to run the \"%s pac create repo\" to create a new Repository CRD on your cluster.\n", settings.TknBinaryName) + fmt.Fprintf(opts.ioStreams.Out, "💡 Don't forget to run the \"%s pac create repository\" to create a new Repository CR on your cluster.\n", settings.TknBinaryName) detectString := detectSelfSignedCertificate(ctx, opts.RouteName) if detectString != "" {