Merge pull request #176 from stakater/docs-updated1

secret docs

content/for-developers/tutorials/outer-loop/add-ci-pipeline/03-create-webhook.md

@@ -0,0 +1,65 @@
+# Setting Up Webhook in SCM (GitHub) for Pipeline as Code
+
+The webhook setup acts as a bridge between your code repository and the CI/CD pipeline. It allows your pipeline to be triggered automatically whenever specific events occur in your repository, such as code pushes or pull requests. The webhook secret further ensures that these interactions are secured and authenticated.
+
+## Objectives
+
+- Obtain Interceptor URL from SAAP admin.
+- Create Webhook Secret for your webhook security.
+- Add webhook in your source code repository.
+
+## Key Results
+
+- Established a webhook connection between GitHub and your pipeline.
+- Created a webhook secret for secure communication.
+
+## Tutorial
+
+1. Begin by accessing the repository where you plan to set up the webhook. In your source code GitHub repository, locate and click on the `Settings` tab.
+
+     ![Repository settings](images/repository-settings.png)
+
+1. Within the repository settings, navigate to the `Webhooks` section. This is where you can manage and configure webhooks for your repository.
+
+     ![Webhook](images/webhook.png)
+
+1. Click on the option to `Add a new webhook` to initiate the process of creating a new webhook for your repository.
+
+     ![Webhook](images/add-webhook.png)
+
+1. To set up the webhook, you'll need the `URL of the pipeline-as-code interceptor`. This URL is used to connect GitHub with your SAAP's pipeline system.
+
+1. Ask the SAAP admin to provide you with the `Interceptor URL` "route" from the project or namespace where the pipeline-as-code is installed.
+
+1. Back in the GitHub repository's webhook settings, enter the `pipeline-as-code interceptor URL` you obtained in the previous step in the `Payload URL`.
+
+1. Choose `Content type` as `application/json`.
+
+1. Let's create a secret for our webhook to make it secure. Open up a terminal and generate a random secret with this command.
+
+      ```sh
+      openssl rand -hex 20
+      ```
+
+!!! note  
+    Save the secret because we will need it later.
+
+   Now copy it and paste it under `Secret` section in Webhook.
+
+1. Choose the specific events that should trigger the webhook. Click “Let me select individual events” and select the following events to trigger the webhook:
+
+    - Commit status
+    - Issue comments
+    - Pushes
+    - pull requests
+
+1. Click on `Add webhook`/`Update webhook`.
+
+     ![Webhook details](images/webhook-details.png)
+
+     Once you've entered the interceptor URL and chosen the triggering events, proceed to add the webhook. This will establish the connection between your GitHub repository and SAAP pipeline.
+
+!!! note
+    For GitLab Webhook configuration follow [this](https://pipelinesascode.com/docs/install/gitlab/), for Bitbucket webhook configuration follow [this](https://pipelinesascode.com/docs/install/bitbucket_cloud/).
+
+Great! Now that you added a Webhook to your repository, let's move on to create secret for it in the next tutorial.

content/for-developers/tutorials/outer-loop/github-pat/github-pat.md → content/for-developers/tutorials/outer-loop/add-ci-pipeline/04-configure-github-access.md

@@ -1,54 +1,62 @@
 # Configure SCM (GitHub) Access
 
+The first thing that you will need to do for your Tekton pipeline to work is to create a Repository CR. The Repository CR tells pipeline-as-code controller that events from a specific repository need to be handled. It also provides a way for pipeline as code controller to authenticate with the GitHub repository through a personal access token.
+
+We will add the Repository CR in three steps.
+
+* First, we will generate a personal access token on GitHub.
+* Second, we will create an External Secret and add the token to Vault.
+* Last, we will create a repository CR and reference the secret in it.
+
 In this section, you'll learn how to configure GitHub access by generating a Fine-grained Personal Access Token (PAT) and securely storing it as a secret in Vault. These steps are essential for establishing a secure and automated Continuous Integration/Continuous Deployment (CI/CD) pipeline using pipeline-as-code concepts.
 
 A Fine-grained PAT ensures that your CI/CD pipeline can securely interact with your GitHub repositories. By generating a token with finely controlled permissions, you grant the pipeline only the specific access it requires, reducing potential security risks. Additionally, storing the PAT in Vault adds an extra layer of security to protect your credentials.
 
 ## Objectives
 
-- Generate a Fine-grained PAT with the necessary permissions for pipeline integration.
-- Securely store the GitHub PAT in Vault for added protection.
+* Generate a Fine-grained PAT with the necessary permissions for pipeline integration.
+* Securely store the GitHub PAT in Vault for added protection.
 
 ## Key Results
 
-- Personal Access Token (PAT) with the specified permissions is generated successfully in the GitHub account.
-- The GitHub PAT is securely stored in Vault and can be accessed only by authorized entities, enhancing security.
+* Personal Access Token (PAT) with the specified permissions is generated successfully in the GitHub account.
+* The GitHub PAT is securely stored in Vault and can be accessed only by authorized entities, enhancing security.
 
 ## Tutorial
 
 ### Generate Token (PAT) on GitHub
 
 1. Generate a Fine-grained Token (PAT) on GitHub. PAT (Fine-grained): Allows you to select repositories from your GitHub organization that can use the token.[`Create a fine-grained token`](https://github.blog/2022-10-18-introducing-fine-grained-personal-access-tokens-for-github/) with the below-mentioned permissions for your source code repository:
 
-    - Go to your GitHub account `settings` for the top-right corner on your profile.
+   * Go to your GitHub account `settings` for the top-right corner on your profile.
 
     <div style="text-align:center"><img src="images/git-account-settings.png" /></div>
 
-    - Navigate to `Developer settings`
+   * Navigate to `Developer settings`
 
         <div style="text-align:center"><img src="images/developer-settings.png" /></div>
 
-    - Go to `Personal access tokens`.
-    - From drop-down select `Fine-grained Tokens`.
-    - Click `Generate new token`.
+   * Go to `Personal access tokens`.
+   * From drop-down select `Fine-grained Tokens`.
+   * Click `Generate new token`.
 
     <div style="text-align:center"><img src="images/pat-create.png" /></div>
 
-    - Provide a name for the token.
-    - Select the `Resource owner`(your organization).
-    - Provide `Repository access` (source code repository) to this token.
-    - Select the following scopes/permissions:
+   * Provide a name for the token.
+   * Select the `Resource owner`(your organization).
+   * Provide `Repository access` (source code repository) to this token.
+   * Select the following scopes/permissions:
 
-        - Administration (Read only)
-        - Commit status (Read only)
-        - Contents (Read only)
-        - Metadata (Read only)
-        - Pull requests (Read and write)
-        - Webhook (Read and write)
+        * Administration (Read only)
+        * Commit status (Read only)
+        * Contents (Read only)
+        * Metadata (Read only)
+        * Pull requests (Read and write)
+        * Webhook (Read and write)
 
     <div style="text-align:center"><img src="images/pat-permissions.png" /></div>
 
-    !!! note
-        > Save the token cautiously, you'll need to save it in `Vault` in upcoming tutorials.
+   !!! note
+   > Save the token cautiously, you'll need to save it in `Vault` in upcoming tutorials.
 
 Congratulations! You have successfully configured GitHub access. Let's move to next tutorial.

content/for-developers/tutorials/outer-loop/add-ci-pipeline/05-add-external-secret.md

@@ -0,0 +1,3 @@
+# Add External Secrets
+
+Let's add some external secrets now.

content/for-developers/tutorials/outer-loop/add-ci-pipeline/06-create-repository.md

@@ -0,0 +1,3 @@
+# Create Repository
+
+Let's finally create the Repository CR

content/for-developers/tutorials/outer-loop/add-ci-pipeline/07-add-secrets-to-apps-gitops.md

@@ -0,0 +1,3 @@
+# Add Secrets to Apps GitOps
+
+Let's add the required secrets to our GitOps repository

content/for-developers/tutorials/outer-loop/add-ci-pipeline/08-adding-pipeline.md

@@ -0,0 +1,3 @@
+# Adding Pipeline
+
+Let's finally add our first task.

content/for-developers/tutorials/outer-loop/prerequisites.md

@@ -6,7 +6,7 @@ Before you embark on setting up your pipeline as code, it's essential to ensure
 
 In certain cases, you may need to add a new environment to an existing application within a tenant. For example, when incorporating a production cluster into your infrastructure, you'll want to extend your application's deployment capabilities to this new environment. Ensure you have a clear understanding of how to add and configure this environment to your application as part of your prerequisites.
 
-## [Personal Access Token (PAT)](./github-pat/github-pat.md)
+## [Personal Access Token (PAT)](./add-ci-pipeline/04-configure-github-access.md)
 
 A Personal Access Token (PAT) is an essential component for ensuring secure and authenticated interactions with your code repositories. This token serves as a vital bridge between your pipeline and your version control system, allowing it to access and manage your code repositories. Whether it's for fetching code, creating branches, or managing pull requests, this token is the cornerstone of performing Git operations securely.
 

mkdocs.yml

@@ -144,10 +144,14 @@ nav:
                 - for-developers/tutorials/outer-loop/prerequisites.md
                 - for-developers/tutorials/outer-loop/add-build-environment/add-environment.md
                 - Configure Pipeline for your application:
-                  - for-developers/tutorials/outer-loop/add-ci-pipeline/overview.md
-                  - for-developers/tutorials/outer-loop/deploying-secrets.md
-                  - for-developers/tutorials/outer-loop/github-pat/github-pat.md
-                  - for-developers/tutorials/outer-loop/webhook-setup/webhook-setup.md
+                  - for-developers/tutorials/outer-loop/add-ci-pipeline/01-overview.md
+                  - for-developers/tutorials/outer-loop/add-ci-pipeline/02-deploying-secrets.md
+                  - for-developers/tutorials/outer-loop/add-ci-pipeline/03-create-webhook.md
+                  - for-developers/tutorials/outer-loop/add-ci-pipeline/04-configure-github-access.md
+                  - for-developers/tutorials/outer-loop/add-ci-pipeline/05-add-external-secret.md
+                  - for-developers/tutorials/outer-loop/add-ci-pipeline/06-create-repository.md
+                  - for-developers/tutorials/outer-loop/add-ci-pipeline/07-add-secrets-to-apps-gitops.md
+                  - for-developers/tutorials/outer-loop/add-ci-pipeline/08-adding-pipeline.md
                   - for-developers/tutorials/outer-loop/create-repo-crd/create-repository.md
                   - for-developers/tutorials/outer-loop/github-ssh/github-ssh.md
                   - for-developers/tutorials/outer-loop/add-ci-pipeline/add-ci-pipeline.md