|
1 | 1 | # GitHub Workflows |
2 | 2 |
|
3 | | -Here we have defined the workflows used for CI/CD for this SDK. |
4 | | -The files here are: |
5 | | -- dotnetworkflow.yml: This file is a template that is used by the SDK workflow. This template has the following parameters: |
6 | | - - runs-on-config (mandatory): indicates the runner that will run the workflow. Available runners [here](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners). |
7 | | - - dotnet-version (mandatory): indicates the dotnet version that will be installed on the runner. The available versions depends on the runners. Check it on the link above. |
8 | | - - build-config (mandatory): indicates the configuration used to build/test the sdk. |
9 | | - - run-tests (mandatory): indicates if the workflow will run the unit tests. |
10 | | - - publish-package (mandatory): indicates if the workflow will publish the artifacts (packages). |
11 | | -- sdk-workflow.yml: This is the real workflow that will run on every PR or every push on the defined branches. |
12 | | - |
13 | | -For any changes, you can use the following documentation ([GitHub Actions Syntax](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)) as a reference. |
| 3 | +This directory contains GitHub Actions workflows that automate the build, test, and deployment processes for the Migration SDK. |
| 4 | + |
| 5 | +More info can be found in [Migration SDK Release Process for Package Repositories (Binaries)](https://docs.google.com/document/d/1XD68jhh0WnIOeLbxS6-xrhaYCNe18fGZakrfOz886cM/edit?tab=t.0). |
| 6 | + |
| 7 | +## TL;DR |
| 8 | + |
| 9 | +For production releases: |
| 10 | + |
| 11 | +- Packages are built, tested, and deployed to **staging** environment |
| 12 | +- Deployment to production requires approval through GitHub Environments |
| 13 | +- When manual approval is provided, deployment to **production** environment happens |
| 14 | + |
| 15 | +When code is merged to main/feature/staging/release branches: |
| 16 | + |
| 17 | +- Packages are built and versioned |
| 18 | +- Tests and linting are run |
| 19 | +- Packages are automatically deployed to the **development** environment |
| 20 | + |
| 21 | +When a PR is opened: |
| 22 | + |
| 23 | +- Packages are built and versioned |
| 24 | +- Tests and linting are run |
| 25 | +- No deployment occurs |
| 26 | + |
| 27 | +When sdk-workflow is started manually: |
| 28 | + |
| 29 | +- Packages are built and versioned |
| 30 | +- Tests and linting are run |
| 31 | +- Packages are automatically deployed to the **staging** environment |
| 32 | + |
| 33 | + |
| 34 | +## Overview |
| 35 | + |
| 36 | +The workflows are organized hierarchically with a main workflow orchestrating various specialized workflows: |
| 37 | + |
| 38 | +- **sdk-workflow.yml**: The main orchestrator workflow that coordinates all other workflows |
| 39 | +- **build-*.yml**: Workflows for building different components (.NET, Python, docs) |
| 40 | +- **test-*.yml**: Workflows for running tests for different components |
| 41 | +- **lint-*.yml**: Workflows for linting code |
| 42 | +- **deploy-*.yml**: Workflows for deploying to different environments |
| 43 | +- **create-release.yml**: Workflow for creating GitHub releases |
| 44 | + |
| 45 | +## Main Workflow |
| 46 | + |
| 47 | +The `sdk-workflow.yml` workflow is the entry point that coordinates all other workflows. It runs on: |
| 48 | + |
| 49 | +- Push to main, release, staging, and feature branches |
| 50 | +- Pull requests (opened, synchronized, reopened, or ready for review) |
| 51 | +- Manual workflow dispatch |
| 52 | + |
| 53 | +The workflow includes: |
| 54 | + |
| 55 | +1. **Define Versions**: Generates version numbers for packages |
| 56 | +2. **Build**: Builds .NET, Python, and documentation |
| 57 | +3. **Lint**: Runs code style checks |
| 58 | +4. **Test**: Runs tests for all components |
| 59 | +5. **Deploy**: Deploys to development, staging, or production environments based on triggers |
| 60 | + |
| 61 | +## Deployment Environments |
| 62 | + |
| 63 | +The SDK supports the following deployment environments: |
| 64 | + |
| 65 | +- **Development**: Automatic deployment on pushes or beta manual triggers |
| 66 | +- **Staging**: Manual deployment with Production release type or beta-to-production intent |
| 67 | +- **Production**: Manual deployment after approval from staging with proper release flags |
| 68 | + |
| 69 | +## Testing with Act |
| 70 | + |
| 71 | +[Act](https://github.com/nektos/act) allows you to run GitHub Actions workflows locally for testing. To use Act with these workflows: |
| 72 | + |
| 73 | +### Running Workflows Locally |
| 74 | + |
| 75 | +#### Testing the Main Workflow |
| 76 | + |
| 77 | +```bash |
| 78 | +# Test the main workflow on push event |
| 79 | +act push -W .github/workflows/sdk-workflow.yml |
| 80 | + |
| 81 | +# Test with workflow_dispatch event (manual trigger with inputs) |
| 82 | +act workflow_dispatch -W .github/workflows/sdk-workflow.yml --input release-type=Beta --input intent-beta-to-prod=false |
| 83 | +``` |
| 84 | + |
| 85 | +#### Testing Individual Workflows |
| 86 | + |
| 87 | +```bash |
| 88 | +# Test building .NET |
| 89 | +act workflow_call -W .github/workflows/build-dotnet.yml --input beta-version=0.1.0-beta123.post1 --input runs-on-config=ubuntu-latest |
| 90 | + |
| 91 | +# Test running tests |
| 92 | +act workflow_call -W .github/workflows/test-dotnet.yml |
| 93 | +``` |
| 94 | + |
| 95 | +### Act Configuration |
| 96 | + |
| 97 | +For best results, create an `.actrc` file in your repository root: |
| 98 | + |
| 99 | +```bash |
| 100 | +-P ubuntu-latest=ghcr.io/catthehacker/ubuntu:full-22.04 |
| 101 | +--artifact-server-path=<Local Path to a temp folder for storing artifacts> |
| 102 | +``` |
| 103 | + |
| 104 | +`ubuntu:full` is required for building the docs. |
| 105 | + |
| 106 | +### Environment and Secrets Configuration |
| 107 | + |
| 108 | +When testing with Act, you'll need to provide environment variables and secrets that would normally be available in GitHub. The repository includes template files for this purpose: |
| 109 | + |
| 110 | +1. **Environment Variables**: Copy `.github/.vars.default` to `.github/.vars` |
| 111 | + |
| 112 | + ```bash |
| 113 | + cp .github/.vars.default .github/.vars |
| 114 | + ``` |
| 115 | + |
| 116 | +2. **Secrets**: Copy `.github/.secrets.default` to `.github/.secrets` |
| 117 | + |
| 118 | + ```bash |
| 119 | + cp .github/.secrets.default .github/.secrets |
| 120 | + ``` |
| 121 | + |
| 122 | +3. Edit `.github/.secrets` to add your actual secret values: |
| 123 | + |
| 124 | + ```bash |
| 125 | + NUGET_PUBLISH_API_KEY=your-nuget-api-key |
| 126 | + PYPI_PUBLISH_USER_PASS=your-pypi-password |
| 127 | + ``` |
| 128 | + |
| 129 | +4. Run Act with these files: |
| 130 | + |
| 131 | + ```bash |
| 132 | + act push -W .github/workflows/sdk-workflow.yml --secret-file .github/.secrets --var-file .github/.vars |
| 133 | + ``` |
| 134 | + |
| 135 | +The `.vars.default` file includes settings for different environments (development, staging, and production). Uncomment the appropriate section based on which environment you want to test. |
| 136 | + |
| 137 | +### Using the VS Code Extension |
| 138 | + |
| 139 | +For a more user-friendly experience, you can use the [GitHub Local Actions VS Code extension](https://marketplace.visualstudio.com/items?itemName=github-actions.github-actions-localhost): |
| 140 | + |
| 141 | +1. Install the extension from the VS Code marketplace |
| 142 | +2. Open the command palette (Ctrl+Shift+P) and search for "GitHub Actions: Run Locally" |
| 143 | +3. Select the workflow you want to run |
| 144 | +4. Configure your environment variables and secrets in the extension interface |
| 145 | + - From the steps above, after creating local .vars and .secrets file, Use "Locate Variable File" and "Locate Secret File" to find them. More details here: https://sanjulaganepola.github.io/github-local-actions-docs/usage/settings/ |
| 146 | + - Once you've added your local .vars and .secrets file, remember to CHECK THE BOX or else it won't pick it up. |
| 147 | +5. You need to add in a artifacts-server-path field under Options (This is for the upload parts. Go to `Settings` -> `Options` -> `+` -> `artifact-server-path` and define a temp folder (D:\temp) |
| 148 | +6. Run the workflow and view the results directly in VS Code |
| 149 | + |
| 150 | +### Limitations |
| 151 | + |
| 152 | +When testing with Act: |
| 153 | + |
| 154 | +1. GitHub environment variables and secrets need to be manually defined in `.vars` and `.secrets` files or via CLI arguments |
| 155 | +2. Some GitHub-specific features like environment protection rules won't work locally |
| 156 | +3. Act detects when it's running and uses a timestamp instead of run numbers for versioning |
| 157 | +4. **Environment Support**: Act has limited support for GitHub's environment concept. Workflows that transition between different deployment environments (development → staging → production) are particularly challenging to test locally, as Act does not fully simulate GitHub's environment-specific variable scoping. For example, workflows that depend on different variable values in staging versus production environments may not behave as expected during local testing, since the same variables are used across all simulated environments. |
0 commit comments