diff --git a/README.md b/README.md index 212e4d3..a1884d5 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # CI/CD Template with GitHub Actions for deepset Cloud -This repository serves as a sample template example to showcase how you can implement CI/CD with GitHub Actions by leveraging the deepset Cloud REST APIs. It demonstrates how to work with two separate workspaces: **dev** and **prod**. +This repository provides a sample template for implementing CI/CD using GitHub Actions with deepset Cloud REST APIs. It demonstrates working with two separate workspaces: **dev** and **prod**. -The purpose of this template is to illustrate best practices and provide a starting point for setting up automated pipeline management and deployment in deepset Cloud environments. While it's designed to be functional, you may need to adapt and extend it to fit your specific use case and requirements. +The template illustrates best practices and offers a starting point for setting up automated pipeline management and deployment in deepset Cloud environments. While it is fully functional, you may need to customize it to fit your specific use case and requirements. ## Table of Contents @@ -23,8 +23,8 @@ The purpose of this template is to illustrate best practices and provide a start Before using this template, ensure you have the following: - A **deepset Cloud** account with access to your **dev** and **prod** workspaces. -- A **GitHub** account with permissions to create repositories and set up GitHub Actions. -- Basic understanding of **Git** and GitHub workflows. +- A **GitHub** account with permissions to create repositories and configure GitHub Actions. +- A basic understanding of **Git** and GitHub workflows. ## Repository Structure @@ -50,26 +50,24 @@ your-repo/ ## Setup Instructions -1. **Clone the Repository locally**: +1. Clone the repository locally: ```bash git clone https://github.com/deepset-ai/deepset-cloud-github-action-template cd your-repo ``` -2. **Set Up GitHub Secrets**: +2. Set up GitHub Secrets: - - Navigate to your GitHub repository. - - Go to **Settings** > **Secrets and variables** > **Actions**. - - Click **"New repository secret"** and add the following secret: + a. Navigate to your GitHub repository. + b. Go to **Settings** > **Secrets and variables** > **Actions**. + c. Click **"New repository secret"** and add the following secret: - `DEEPSET_CLOUD_API_KEY`: Your deepset Cloud API key. - **Note**: The same API key is used for both dev and prod environments. + **Note**: The same API key is used for dev and prod environments. -3. **Configure Workspace Names**: - - - Update the workspace names in the workflow files: +3. Configure workspace names. Update the workspace names in the workflow files: - In `.github/workflows/deploy-dev.yml`, replace `"YOUR_DEV_WORKSPACE_NAME"` with your actual **dev** workspace name. - In `.github/workflows/deploy-prod.yml`, replace `"YOUR_PROD_WORKSPACE_NAME"` with your actual **prod** workspace name. @@ -78,52 +76,51 @@ your-repo/ ### Branching Strategy -- **Development Branch (`dev`)**: Used for integrating and testing Pipeline changes. Automatically deploys to the **dev** workspace upon push. -- **Production Branch (`main`)**: Contains stable and reviewed Pipeline YAMLs. Deployment to the **prod** workspace is triggered on push or manually via GitHub Actions. +- **Development Branch (`dev`)**: Used for integrating and testing pipeline changes. Automatically deploys to the **dev** workspace on push. +- **Production Branch (`main`)**: Contains stable and reviewed pipeline YAMLs. Deployment to the **prod** workspace is triggered on push or manually through GitHub Actions. ### Adding or Updating Pipelines -1. **Add or Modify Pipeline Files**: - - Create a new directory under `pipelines/` for each pipeline. - - Each pipeline directory should contain two files: `indexing.yaml` and `query.yaml`. +1. Add pipeline files: + a. For each pipeline, create a new directory under `pipelines/`. + b. Each pipeline directory should contain two files: `indexing.yaml` (with the indexing pipeline) and `query.yaml` (with the query pipeline). -2. **Commit Changes**: +2. After you updated your pipeline, commit the changes: ```bash git add pipelines/your-pipeline-name/ git commit -m "Add/Update pipeline: your-pipeline-name" ``` -3. **Push to the Appropriate Branch**: +3. Push your changes to the appropriate branch: - For development: `git push origin dev` - For production: `git push origin main` ### Triggering Deployments - **Automatic Deployment**: - - **Dev Workspace**: Pushing to the `dev` branch triggers the `deploy-dev.yml` workflow. - - **Prod Workspace**: Pushing to the `main` branch triggers the `deploy-prod.yml` workflow. + - Dev Workspace: Pushing to the `dev` branch triggers the `deploy-dev.yml` workflow. + - Prod Workspace: Pushing to the `main` branch triggers the `deploy-prod.yml` workflow. - **Manual Deployment**: - - For production, you can manually trigger the workflow: + For production, you can manually trigger the workflow: 1. Go to the **Actions** tab in your GitHub repository. 2. Select **"Deploy to Prod Workspace"** workflow. 3. Click **"Run workflow"**. ### Rollback Procedures -To revert to a previous pipeline version: - -1. **Revert Changes in Git**: +To revert to a previous pipeline version, revert your changes in Git: ```bash git revert git push origin dev # or main, depending on the branch ``` -2. The GitHub Actions workflow will automatically redeploy the pipelines based on the reverted code. +The GitHub Actions workflow automatically redeploys the pipelines based on the reverted code. ## Extending the Template -- **Add More Environments**: Copy and modify existing workflows for additional environments like staging. -- **Notifications**: Add steps to send deployment notifications via email, Slack, etc. +- To add more environments, copy and update existing workflows for additional environments, like staging. +- To enable deployment notifications, add steps to send them using email, Slack, and the like. +