|
| 1 | +## Sample of **File-based Trigger Trigger** - Trigger an OCI DevOps Build pipeline with an external code repo (Github). |
| 2 | + |
| 3 | + |
| 4 | +In Oracle Cloud Infrastructure (OCI) DevOps, a build run can be automatically triggered when you commit your changes to a code repository. |
| 5 | + |
| 6 | +You can control the trigger action by specifying the modified files in your repository to be included or excluded during the build run. The file-based trigger action is applicable only for the **Push** event. |
| 7 | + |
| 8 | + |
| 9 | +### External Connection. |
| 10 | +With external connection the OCI DevOps build pipeline and triggers can connect to external repositories such as GitHub, GitLab, Bitbucket Cloud, Visual Builder Studio, Bitbucket Server, and GitLab Server. |
| 11 | + |
| 12 | +In this example, we will be using a repo from the Github repo. To establish and use the external repo from Github we will be using Github PAT stored under OCI Vault. |
| 13 | + |
| 14 | +### File-Based Trigger |
| 15 | +For triggering a build run based on file changes, the following two options are provided: |
| 16 | + |
| 17 | +**Files to include**: By default, changes to all files in the repository are included when a build run is triggered. The Files to Include option allows you to specify a list of files and directories in the repository that you have changed and for which you want to trigger a build run. Files are specified using glob patterns. Trigger action is based on the changes affecting at least one of the included files. |
| 18 | + |
| 19 | +**Files to exclude**: By default, changes to all files in the repository are included when a build run is triggered. The Files to Exclude option allows you to specify a list of files and directories in the repository that you want to exclude from the build run. Files are specified using glob patterns. Changes affecting only the excluded files do not trigger a build. If files are specified for both include and exclude, then the exclude filter is applied to the output of the include filter. |
| 20 | + |
| 21 | + |
| 22 | +#### Objectives |
| 23 | + |
| 24 | +- Create GitHub PAT and store it within OCI Vault. |
| 25 | +- Create an external connection within OCI DevOps. |
| 26 | +- Create a build pipeline with an external code repo. |
| 27 | +- Create a devops trigger. |
| 28 | +- Test and validate trigger conditions. |
| 29 | + |
| 30 | + |
| 31 | +* Specific instruction to clone only this example. |
| 32 | + |
| 33 | + ``` |
| 34 | + $ git init oci-devops-trigger-from-github-repo |
| 35 | + $ cd oci-devops-trigger-from-github-repo |
| 36 | + $ git remote add origin https://github.com/oracle-devrel/oci-devops-examples |
| 37 | + $ git config core. sparsecheckout true |
| 38 | + $ echo "oci-coderepo-examples/oci-devops-trigger-from-github-repo/*">>.git/info/sparse-checkout |
| 39 | + $ git pull --depth=1 origin main |
| 40 | +
|
| 41 | + ``` |
| 42 | +
|
| 43 | +### Procedure |
| 44 | +
|
| 45 | +#### OCI Notifications. |
| 46 | +
|
| 47 | +- Create an OCI notification topic - https://docs.oracle.com/en-us/iaas/Content/Notification/Tasks/managingtopicsandsubscriptions.htm#createTopic |
| 48 | +
|
| 49 | +
|
| 50 | +#### OCI Identity setups. |
| 51 | +
|
| 52 | +- Create a dynamic group and add the below rules. - |
| 53 | +
|
| 54 | +```java |
| 55 | +ALL {resource.type = 'devopsbuildpipeline', resource.compartment.id = 'COMPARMENT OCID'} |
| 56 | +ALL {resource.type = 'devopsrepository', resource.compartment.id = 'COMPARMENT OCID'} |
| 57 | +ALL {resource.type = 'devopsconnection',resource.compartment.id = 'compartmentOCID'} |
| 58 | +``` |
| 59 | + |
| 60 | +- Create a policy with the below statements. |
| 61 | + |
| 62 | +```java |
| 63 | +Allow dynamic-group "NAME OF THE DynamicGroup" to manage repos in compartment "COMPARTMENT NAME" |
| 64 | +Allow dynamic-group "NAME OF THE DynamicGroup" to use ons-topics in compartment "COMPARTMENT NAME" |
| 65 | +Allow dynamic-group "NAME OF THE DynamicGroup" to read secret-family in compartment "COMPARTMENT NAME" |
| 66 | +``` |
| 67 | +- If the user is not part of the `Tenancy Administrator` group, the user group needs an additional policy statement to validate the external connection. It is an optional policy statement. |
| 68 | +```java |
| 69 | +Allow group "Name of the User Group Name" to use DevOps-connection in compartment "COMPARTMENT NAME" |
| 70 | +``` |
| 71 | +#### Github Initial setup. |
| 72 | +- Login to GitHub and create a new repo. |
| 73 | +- Push the repo content here to the Github repo. |
| 74 | +  |
| 75 | +- Refer [Github official documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) and create a personal access token, it can be a classical token or a fine-grained-token for specific repo. |
| 76 | +- Make a note of GitHub PAT. |
| 77 | +#### OCI Vault setup. |
| 78 | +- Create a vault - https://docs.oracle.com/en-us/iaas/Content/KeyManagement/Tasks/managingvaults_topic-To_create_a_new_vault.htm#createnewvault |
| 79 | +- Create a master key - https://docs.oracle.com/en-us/iaas/Content/KeyManagement/Tasks/managingkeys_topic-To_create_a_new_key.htm#createnewkey |
| 80 | +- Create a secret and add the GitHub PAT value. |
| 81 | +  |
| 82 | +#### OCI DevOps setups. |
| 83 | +- Create a DevOps project and associate it with the notification topic - https://docs.oracle.com/en-us/iaas/Content/devops/using/create_project.htm |
| 84 | +  |
| 85 | +- Ensure to enable logging for the projects. |
| 86 | +- Create an `External Connection`. - https://docs.oracle.com/en-us/iaas/Content/devops/using/create_connection.htm |
| 87 | +- Open the navigation menu and click Developer Services. Under DevOps, click Projects. |
| 88 | +- Select a project and from the left-side menu, click External Connections. |
| 89 | +- Click Create External Connection. |
| 90 | +  |
| 91 | +- Provide a `name` and `description`.Select the type `Github`. |
| 92 | +  |
| 93 | +- Select the `Vault` created and the `secret` which contains the PAT. |
| 94 | +- Click `Validate connection` and verify the connection is valid |
| 95 | +  |
| 96 | +- If the validation is successful, then a success message is displayed. Otherwise, a failure message is displayed. If the validation fails, you must generate a PAT and store your PAT securely in an OCI vault. You can then update the vault secret by editing the connection details. |
| 97 | +- Create a `Build pipeline`. |
| 98 | +  |
| 99 | +- With in build pipeline add a `managed build stage`. |
| 100 | +- Provide a name and description for the stage. |
| 101 | +- Provide path `build-pipeline/build_spec.yaml` as the path for `build spec file path`. |
| 102 | +  |
| 103 | +- Select the primary code repository, select the connection type as `Github` and the `External connection` created. |
| 104 | +- Select the appropriate GitHub repo and branch. |
| 105 | +  |
| 106 | +- Once the repo is selected create the stage. The build pipeline will look as below. |
| 107 | +  |
| 108 | +#### OCI DevOps trigger conditions with External connection. |
| 109 | +In Oracle Cloud Infrastructure (OCI) DevOps, a build run can be automatically triggered when you commit your changes to a code repository. In the DevOps service, you can create your private code repositories or connect to external code repositories and trigger the build |
| 110 | +* Open the navigation menu and click Developer Services. Under DevOps, click Projects. |
| 111 | +* On the DevOps Projects page, select a project. |
| 112 | +* On the details page of the project, from the left side, click Triggers. |
| 113 | +* Click Create Trigger. |
| 114 | +  |
| 115 | +- Enter a name select the external connection as Github and select the connection created. |
| 116 | +  |
| 117 | +- With in action select the `Build pipeline` and event type as `push`. |
| 118 | +  |
| 119 | +  |
| 120 | +- Select the `branch`,` files to include` and `files to exclude`.In this sample, we will add the trigger for path `build-pipelines/build_spec.yaml` and exclude all *.md file changes. |
| 121 | +  |
| 122 | +- Add the actions and create the trigger. Copy the URL and secrets that will be prompted on the screen. |
| 123 | +  |
| 124 | + |
| 125 | +#### GitHub Webhook configurations. |
| 126 | +- Follow GitHub official documentation to create the webhook against the repo - https://docs.github.com/en/webhooks/using-webhooks/creating-webhooks |
| 127 | +  |
| 128 | +- Within webhook use the URL received and secrets from OCI DevOps trigger as Payload URL and Secret respectively. Use `application/json as the content type. |
| 129 | +  |
| 130 | +- As soon as the webhook is created, a test ping event will be triggered from GitHub using the payload URL and secrets. The details can be found in the `recent deliveries` tab against the webhook created. |
| 131 | +  |
| 132 | +  |
| 133 | + |
| 134 | +#### Test & Validate the Triggers |
| 135 | +- Update the file `build-pipeline/build_spec.yaml` add an echo statement to the end of the steps and commit to the repo. |
| 136 | +  |
| 137 | +- Check for the recent deliveries under webhook for the `push ' action. |
| 138 | +  |
| 139 | +- Verify the request and response to validate the trigger. |
| 140 | +  |
| 141 | +- With in build pipeline, check for build history and you should see a new build run. |
| 142 | +  |
| 143 | +- To validate the file-based trigger file exclusion, edit and add some comments to the `README.md`.Commit the changes back to the repo. |
| 144 | +  |
| 145 | +- Verify the webhook under `recent deliveries`.It should show a response code for `202` as there is no valid condition (due to exclusion) to trigger a build run. |
| 146 | +  |
| 147 | +- Incas of a failure of webhook, validate it via request and response to know more. |
| 148 | +  |
| 149 | + |
| 150 | +Contributors |
| 151 | +=========== |
| 152 | +- Author: Rahul M R. |
| 153 | +- Collaborators: NA |
| 154 | +- Last release: September 2023 |
| 155 | +Back to examples. |
| 156 | +---- |
| 157 | +- 🍿 [Back to OCI Devops Coderepo sample](./../README.md) |
| 158 | +- 🏝️ [Back to OCI Devops sample](./../../README.md) |
| 159 | + |
0 commit comments