Skip to content

Commit 10f44e2

Browse files
CWade3051CWade3051
committed
Add GitHub workflows overview documentation
Introduces ghworkflow.md, a comprehensive guide to the repository's GitHub Actions workflows. The document summarizes each workflow's purpose, triggers, jobs, and provides instructions for adapting them to forked repositories.
1 parent 6de5706 commit 10f44e2

File tree

1 file changed

+240
-0
lines changed

1 file changed

+240
-0
lines changed

‎ghworkflow.md‎

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
# GitHub Workflows Overview
2+
3+
This document summarizes the workflows found in the `.github/workflows` folder of this repository, their purposes, and what you need to change to use them in your own forked repo.
4+
5+
---
6+
7+
## 1. `.github/workflows/azure-dev-validation.yaml`
8+
- **Purpose:** Validates the Azure Developer (`azd`) template and Bicep files for infrastructure-as-code best practices and security.
9+
- **Triggers:** On push or pull request to `main` branch, but only if files in the `infra/` folder change. Can also be run manually via workflow dispatch.
10+
- **Jobs:**
11+
- **bicep**: Checks out code, builds the main Bicep file for linting using Azure CLI.
12+
- **psrule**: Checks out code, runs PSRule analysis for Azure security best practices on test Bicep files, uploads results to the Security tab (only for the original repo).
13+
- **To use:**
14+
- Update file paths if your Bicep files are in a different folder or have different names.
15+
- Update `inputPath` if you don't use `.test.bicep` files.
16+
- Change or remove `if: github.repository == 'Azure-Samples/azure-search-openai-demo'` to enable uploading in your own repo.
17+
- Make sure your repo allows writing security events if you want SARIF results in the Security tab.
18+
- Update Azure CLI version if you need a newer version.
19+
20+
## 2. `.github/workflows/azure-dev.yml`
21+
**Purpose:** Automates deployment of the app and infrastructure to Azure using the Azure Developer CLI (`azd`).
22+
23+
**Triggers:**
24+
- On push to `main` or `master` branches
25+
- Manual trigger via workflow dispatch
26+
27+
**Jobs:**
28+
- **build**: Sets up environment, installs dependencies, logs into Azure, provisions infrastructure, and deploys the app
29+
30+
**Step-by-step:**
31+
- Checks out the repo
32+
- Installs Azure Developer CLI (`azd`)
33+
- Installs Node.js (v18)
34+
- Logs into Azure using federated credentials (OpenID Connect)
35+
- Provisions infrastructure with `azd provision` (using secrets for app registration)
36+
- Deploys the application with `azd deploy`
37+
38+
**What to change when forking or using in a new repo:**
39+
- **Branch names:** If your main branch is not `main` or `master`, update the `branches` list under `push`
40+
- **Environment variables:** All `env:` variables are set from GitHub repository variables (not secrets). You must set these in your repo’s GitHub Actions settings (Settings → Variables)
41+
- **Secrets:** You must add `AZD_INITIAL_ENVIRONMENT_CONFIG`, `AZURE_SERVER_APP_SECRET`, and `AZURE_CLIENT_APP_SECRET` as GitHub secrets (Settings → Secrets and variables → Actions)
42+
- **Azure setup:** Run `azd pipeline config` in your repo to set up required Azure federated credentials and permissions
43+
- **Resource names:** Update any resource names, locations, or SKUs to match your Azure environment
44+
- **App registration:** Make sure your Azure AD app registrations (client/server) and secrets are correct for your environment
45+
- **Permissions:** The workflow uses federated credentials for secretless login. Make sure your Azure subscription and tenant are configured for this
46+
- **Node version:** Update `node-version` if your app requires a different version
47+
48+
**Summary:**
49+
This workflow is the main automation for Azure deployment. You must set up all required variables and secrets in your repo, and ensure your Azure environment matches the configuration. After setup, you can deploy by pushing to your main branch or running the workflow manually.
50+
51+
## 3. `.github/workflows/evaluate.yaml`
52+
**Purpose:** Automates evaluation of the RAG (Retrieval-Augmented Generation) answer flow for pull requests, posting results as comments and artifacts.
53+
54+
**Triggers:**
55+
- When a comment is created on a pull request with the exact body `/evaluate` by a repo member, collaborator, or owner
56+
57+
**Jobs:**
58+
- **evaluate**: Sets up environment, builds and runs the app locally, runs evaluation scripts, uploads results, and comments on the PR
59+
60+
**Step-by-step:**
61+
- Checks if the comment is `/evaluate` and the author is a repo member/collaborator/owner
62+
- Comments on the PR to indicate evaluation is starting
63+
- Checks out the PR branch
64+
- Installs Python and Node dependencies
65+
- Installs Azure Developer CLI (`azd`)
66+
- Logs into Azure using federated credentials and Azure CLI
67+
- Refreshes environment variables
68+
- Builds the frontend
69+
- Installs backend and evaluation dependencies
70+
- Runs the backend server locally in the background
71+
- Runs the evaluation script against the local server
72+
- Uploads evaluation results and server logs as build artifacts
73+
- Summarizes results and posts a comment on the PR with the evaluation summary and a link to the workflow run
74+
75+
**What to change when forking or using in a new repo:**
76+
- **Environment variables:** All `env:` variables are set from GitHub repository variables. You must set these in your repo’s GitHub Actions settings (Settings → Variables)
77+
- **Secrets:** You must add `AZD_INITIAL_ENVIRONMENT_CONFIG`, `AZURE_SERVER_APP_SECRET`, and `AZURE_CLIENT_APP_SECRET` as GitHub secrets (Settings → Secrets and variables → Actions)
78+
- **Evaluation scripts:** Make sure `evals/evaluate.py` and related scripts exist and are compatible with your repo
79+
- **Server startup:** The workflow assumes your backend can be started with `python3 -m quart --app main:app run --port 50505`. Update this if your backend uses a different entrypoint or port
80+
- **Artifact paths:** Update artifact upload paths if your evaluation or server logs are stored elsewhere
81+
- **Permissions:** The workflow uses federated credentials for secretless login. Make sure your Azure subscription and tenant are configured for this
82+
- **Node/Python versions:** Update `node-version` and `python-version` if your app requires different versions
83+
- **PR comment triggers:** The workflow only runs for `/evaluate` comments on PRs. You can change this to use a different trigger or command
84+
85+
**Summary:**
86+
This workflow enables automated, reproducible evaluation of PRs. You must set up all required variables, secrets, and ensure your evaluation scripts and server startup match your repo. After setup, collaborators can trigger evaluation by commenting `/evaluate` on a PR.
87+
88+
## 4. `.github/workflows/frontend.yaml`
89+
**Purpose:** Lints and checks code formatting in the frontend using Prettier.
90+
91+
**Triggers:**
92+
- On push or pull request to `main` branch, but only if files in the `app/frontend/` folder change
93+
94+
**Jobs:**
95+
- **prettier**: Checks out code, installs frontend dependencies, runs Prettier to check formatting
96+
97+
**Step-by-step:**
98+
- Checks out the repo
99+
- Changes directory to `app/frontend`
100+
- Installs npm dependencies
101+
- Runs `npx prettier --check .` to check code formatting in the frontend
102+
103+
**What to change when forking or using in a new repo:**
104+
- **File paths:** If your frontend code is in a different folder, update the `paths` triggers and the `cd` command in the workflow
105+
- **Branch names:** If your main branch is not `main`, update the `branches` list under `push` and `pull_request`
106+
- **Prettier config:** Make sure you have a Prettier configuration file (`.prettierrc`, `prettier.config.js`, etc.) in your frontend folder, or update the workflow to use your config location
107+
- **Node version:** The workflow uses the default Node version. If your frontend requires a specific Node version, add a `setup-node` step
108+
- **Dependencies:** Ensure your `package.json` includes Prettier as a dev dependency, or update the workflow to install it globally
109+
110+
**Summary:**
111+
This workflow is safe to enable in your fork. Just update file paths, branch names, and Prettier configuration as needed for your repo structure and preferences.
112+
113+
### 5. `.github/workflows/lint-markdown.yml`
114+
**Purpose:** Lints Markdown files in the repository using `markdownlint` to enforce style and formatting rules.
115+
116+
**Triggers:**
117+
- On pull request to `main` branch, but only if any `.md` file changes
118+
119+
**Jobs:**
120+
- **lint-markdown**: Checks out code, runs markdownlint on all Markdown files except those in the `data/` folder
121+
122+
**Step-by-step:**
123+
- Checks out the repo
124+
- Runs `markdownlint` using the configuration file `.github/workflows/markdownlint-config.json`
125+
- Lints all Markdown files (`**/*.md`), ignoring files in the `data/` folder
126+
127+
**What to change when forking or using in a new repo:**
128+
- **Branch names:** If your main branch is not `main`, update the `branches` list under `pull_request`
129+
- **Markdownlint config:** Update the `config` path if you move or rename your markdownlint configuration file
130+
- **File patterns:** Update the `files` and `ignore` patterns if your Markdown files are in different locations or you want to lint/exclude different files
131+
- **Markdownlint rules:** Customize the rules in your markdownlint config file to match your preferred style
132+
133+
**Summary:**
134+
This workflow is safe to enable in your fork. Just update branch names, config file path, and file patterns as needed for your repo structure and preferences.
135+
136+
## 6. `.github/workflows/validate-markdown.yml`
137+
**Purpose:** Validates Markdown and Jupyter Notebook files for broken links, broken relative paths, and locale issues in URLs.
138+
139+
**Triggers:**
140+
- On pull request to `main` branch, if any `.md` or `.ipynb` file changes (uses `pull_request_target` for security)
141+
142+
**Jobs:**
143+
- **check-broken-paths**: Checks for broken relative paths in Markdown and notebook files
144+
- **check-urls-locale**: Checks that URLs do not contain country/locale codes
145+
- **check-broken-urls**: Checks for broken URLs in Markdown and notebook files
146+
147+
**Step-by-step:**
148+
- Checks out the repo at the PR head commit
149+
- Runs `action-check-markdown` to check for broken relative paths, using the repo root as the directory
150+
- Runs `action-check-markdown` to check that URLs do not contain locale codes
151+
- Runs `action-check-markdown` to check for broken URLs
152+
- Uses a guide URL for contributors to fix issues (points to the original repo's CONTRIBUTING.md)
153+
154+
**What to change when forking or using in a new repo:**
155+
- **Branch names:** If your main branch is not `main`, update the `branches` list under `pull_request_target`
156+
- **Guide URL:** Update `guide-url` to point to your own repo's CONTRIBUTING.md or documentation
157+
- **File patterns:** Update the `paths` list if you want to include/exclude different file types
158+
- **GitHub token:** The workflow uses `${{ secrets.GITHUB_TOKEN }}` which is automatically provided by GitHub Actions
159+
- **Action version:** The workflow uses `john0isaac/[email protected]`. Update if a newer version is available or required
160+
161+
**Summary:**
162+
This workflow is safe to enable in your fork. Just update branch names, guide URL, and file patterns as needed for your repo structure and preferences.
163+
164+
### 7. `.github/workflows/nightly-jobs.yaml`
165+
**Purpose:** Runs scheduled jobs (nightly builds/tests) and allows manual triggering.
166+
167+
**Triggers:**
168+
- Scheduled every night at midnight UTC (`cron: '0 0 * * *'`)
169+
- Manual trigger via workflow dispatch
170+
171+
**Jobs:**
172+
- **python-test:** Calls the `python-test.yaml` workflow to run Python tests and checks
173+
174+
**What to change when forking or using in a new repo:**
175+
- **Schedule:** Update the `cron` expression if you want a different schedule
176+
- **Job calls:** If you rename or move the test workflow, update the `uses:` path
177+
178+
**Summary:**
179+
This workflow is safe to enable in your fork. Just update the schedule and job call path as needed.
180+
181+
---
182+
183+
### 8. `.github/workflows/python-test.yaml`
184+
**Purpose:** Runs Python tests, linting, type checks, formatting, and E2E tests across multiple OS, Python, and Node versions.
185+
186+
**Triggers:**
187+
- On push or pull request to `main` branch (ignores markdown, devcontainer, azdo, and GitHub config files)
188+
- Can be called by other workflows (like `nightly-jobs.yaml`)
189+
190+
**Jobs:**
191+
- **test_package:** Runs on Ubuntu and Windows, with a matrix of Python (3.9–3.13) and Node (20.14, 22) versions
192+
193+
**Step-by-step:**
194+
- Checks out the repo
195+
- Installs Python and Node dependencies
196+
- Builds the frontend
197+
- Installs backend dependencies
198+
- Lints Python code with Ruff
199+
- Checks types with Mypy (in `scripts/` and `app/backend/`)
200+
- Checks formatting with Black
201+
- Runs Python tests with pytest (with coverage, only on non-Windows runners)
202+
- Runs E2E tests with Playwright (only on non-Windows runners)
203+
- Uploads Playwright traces as artifacts if E2E tests fail
204+
205+
**What to change when forking or using in a new repo:**
206+
- **Branch names:** If your main branch is not `main`, update the `branches` list
207+
- **Paths:** Update `paths-ignore` if you want to include/exclude different files
208+
- **Python/Node versions:** Update the matrix to match your supported versions
209+
- **Test/lint/type check commands:** Update commands if your repo uses different tools or config files
210+
- **Artifact paths:** Update if your test results are stored elsewhere
211+
- **Playwright tests:** Make sure your E2E tests and Playwright setup match your repo
212+
213+
**Summary:**
214+
This workflow is safe to enable in your fork. Just update branch names, matrix versions, test/lint/type check commands, and artifact paths as needed for your repo.
215+
216+
### 9. `.github/workflows/stale-bot.yml`
217+
**Purpose:** Automatically marks and closes stale issues and pull requests to keep the repo clean.
218+
219+
**Triggers:**
220+
- Scheduled to run daily at 1:30 AM UTC (`cron: '30 1 * * *'`)
221+
222+
**Jobs:**
223+
- **stale:** Uses the `actions/stale` GitHub Action to mark issues/PRs as stale and close them after inactivity
224+
225+
**Step-by-step:**
226+
- Runs the `actions/stale` action
227+
- Marks issues and PRs as stale if they have been open for 60 days with no activity
228+
- Posts a message when marking as stale
229+
- Closes issues after 7 days of being marked stale (unless activity resumes)
230+
- Closes PRs after 10 days of being marked stale (unless activity resumes)
231+
- Posts a message when closing
232+
233+
**What to change when forking or using in a new repo:**
234+
- **Schedule:** Update the `cron` expression if you want a different schedule
235+
- **Stale/close messages:** Customize the messages to match your repo’s tone or instructions
236+
- **Days before stale/close:** Adjust `days-before-issue-stale`, `days-before-pr-stale`, `days-before-issue-close`, and `days-before-pr-close` to fit your workflow (note: `-1` disables auto-closing)
237+
- **Action version:** Update `actions/stale@v9` if a newer version is available
238+
239+
**Summary:**
240+
This workflow is safe to enable in your fork. Just update the schedule, messages, and timing as needed for your repo’s issue/PR management preferences.

0 commit comments

Comments
 (0)