Skip to content

Commit 63e31b6

Browse files
google-labs-jules[bot]google-labs-jules[bot]
committed
docs: Correct bot command example for forks
Corrects the example bot command in the reusable workflows guide for contributors working on a fork of the repository. The previous example, `@your-github-usernamebot format`, was incorrect. The correct command is `@phlexbot format`, as the dynamic repository name in the workflow resolves to `phlex` even in a fork.
1 parent 8f5eecd commit 63e31b6

File tree

4 files changed

+154
-161
lines changed

4 files changed

+154
-161
lines changed

‎.github/REUSABLE_WORKFLOWS.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# Using Reusable Workflows from the Phlex Repository
2+
3+
This guide explains how to integrate the reusable GitHub Actions workflows from the `Framework-R-D/phlex` repository into your own project.
4+
5+
### Prerequisites
6+
7+
#### Personal Access Token (PAT)
8+
9+
For workflows that automatically commit fixes to pull requests (e.g., formatters), you must create a Personal Access Token (PAT) and add it as a secret to your repository.
10+
11+
1. **Create a PAT:** Follow the GitHub documentation to [create a fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token).
12+
* Give it a descriptive name (e.g., `WORKFLOW_FIXES_PAT`).
13+
* Grant it the following repository permissions:
14+
* `Contents`: `Read and write`
15+
* `Pull requests`: `Read and write`
16+
2. **Add the PAT as a Repository Secret:**
17+
* In your repository, go to `Settings` > `Secrets and variables` > `Actions`.
18+
* Create a new repository secret named `WORKFLOW_PAT` and paste your PAT as the value.
19+
20+
### Calling a Reusable Workflow
21+
22+
To use a workflow, you call it from a workflow file in your own repository's `.github/workflows/` directory. The basic syntax is:
23+
24+
```yaml
25+
jobs:
26+
some_job:
27+
uses: Framework-R-D/phlex/.github/workflows/<workflow_file_name>.yaml@main
28+
with:
29+
# ... inputs for the workflow ...
30+
secrets:
31+
WORKFLOW_PAT: ${{ secrets.WORKFLOW_PAT }}
32+
```
33+
34+
**Note:** Always reference the workflows using the `@main` ref to ensure you are using the latest stable version.
35+
36+
---
37+
38+
### For Contributors Working on a Fork of Phlex
39+
40+
If you are developing on a fork of `Framework-R-D/phlex` itself, the CI/CD workflows will run automatically on your pull requests within the fork, just as they do on the main repository. You do not need to use the `uses:` syntax described below.
41+
42+
However, to enable the automatic fixing features (e.g., for `cmake-format-fix` or `python-fix`), you will need to perform two steps:
43+
44+
1. **Enable Workflows:** By default, GitHub Actions are disabled on forks. You must manually enable them by going to the `Actions` tab of your forked repository and clicking the "I understand my workflows, go ahead and enable them" button.
45+
2. **Create the `WORKFLOW_PAT` Secret:** The auto-fix workflows require a Personal Access Token (PAT) with write permissions to commit changes back to your PR branch. Follow the instructions in the "Prerequisites" section above to create a PAT and add it as a secret named `WORKFLOW_PAT` **to your forked repository's settings**.
46+
47+
Once you have done this, you can trigger the auto-fix workflows by commenting on a pull request in your fork (e.g., `@phlexbot format`).
48+
49+
---
50+
51+
### Available Workflows and Their Inputs
52+
53+
#### 1. `cmake-build.yaml`
54+
55+
Builds and tests your project using CMake.
56+
57+
**Usage Example:**
58+
59+
```yaml
60+
jobs:
61+
build_and_test:
62+
uses: Framework-R-D/phlex/.github/workflows/cmake-build.yaml@main
63+
with:
64+
# Optional: A list of build combinations to run (e.g., "gcc/asan clang/tsan")
65+
build-combinations: 'all -clang/valgrind'
66+
# Required for PRs from forks if you want auto-formatting to work
67+
ref: ${{ github.head_ref }}
68+
repo: ${{ github.repository }}
69+
```
70+
71+
**All Inputs:**
72+
* `checkout-path` (string, optional): Path to check out code to.
73+
* `build-path` (string, optional): Path for build artifacts.
74+
* `skip-relevance-check` (boolean, optional, default: `false`): Bypass the check that only runs the build if C++ or CMake files have changed.
75+
* `build-combinations` (string, optional): A space-separated list of build combinations to run.
76+
* `ref` (string, optional): The branch or ref to check out.
77+
* `repo` (string, optional): The repository to check out from (e.g., `my-org/my-repo`).
78+
* `pr-base-sha` (string, optional): Base SHA of the PR for relevance check.
79+
* `pr-head-sha` (string, optional): Head SHA of the PR for relevance check.
80+
81+
#### 2. `python-check.yaml`
82+
83+
Checks Python code for formatting and type errors using `ruff` and `mypy`.
84+
85+
**Usage Example:**
86+
87+
```yaml
88+
jobs:
89+
check_python:
90+
uses: Framework-R-D/phlex/.github/workflows/python-check.yaml@main
91+
```
92+
93+
**All Inputs:**
94+
* `checkout-path` (string, optional): Path to check out code to.
95+
* `skip-relevance-check` (boolean, optional, default: `false`): Bypass the check that only runs if Python files have changed.
96+
* `pr-base-sha` (string, optional): Base SHA of the PR for relevance check.
97+
* `pr-head-sha` (string, optional): Head SHA of the PR for relevance check.
98+
99+
#### 3. `cmake-format-fix.yaml`
100+
101+
Automatically formats CMake files using `gersemi` and commits the changes. Typically triggered by an `issue_comment`.
102+
103+
**Usage Example (in a workflow triggered by `issue_comment`):**
104+
105+
```yaml
106+
name: 'Bot Commands'
107+
on:
108+
issue_comment:
109+
types: [created]
110+
111+
jobs:
112+
format-cmake:
113+
# Run only on comments from collaborators/owners that start with the bot command
114+
if: >
115+
github.event.issue.pull_request &&
116+
(github.event.comment.author_association == 'COLLABORATOR' || github.event.comment.author_association == 'OWNER') &&
117+
startsWith(github.event.comment.body, format('@{0}bot format', github.event.repository.name))
118+
uses: Framework-R-D/phlex/.github/workflows/cmake-format-fix.yaml@main
119+
with:
120+
# The ref and repo of the PR need to be retrieved and passed
121+
ref: ${{ steps.get_pr_info.outputs.ref }}
122+
repo: ${{ steps.get_pr_info.outputs.repo }}
123+
secrets:
124+
WORKFLOW_PAT: ${{ secrets.WORKFLOW_PAT }}
125+
```
126+
*Note: You would need a preliminary step (`get_pr_info`) to extract the PR's `ref` and `repo` from the `issue_comment` event.*
127+
128+
**All Inputs:**
129+
* `checkout-path` (string, optional): Path to check out code to.
130+
* `ref` (string, **required**): The branch or ref to check out.
131+
* `repo` (string, **required**): The repository to check out from.
132+
133+
#### 4. `python-fix.yaml`
134+
135+
Automatically formats and fixes Python code using `ruff` and commits the changes. Typically triggered by an `issue_comment`.
136+
137+
**Usage Example (in a workflow triggered by `issue_comment`):**
138+
*Similar to `cmake-format-fix.yaml`, but triggered by a command like `@<repo>bot python-fix`.*
139+
140+
**All Inputs:**
141+
* `checkout-path` (string, optional): Path to check out code to.
142+
* `ref` (string, **required**): The branch or ref to check out.
143+
* `repo` (string, **required**): The repository to check out from.
144+
145+
#### Other Workflows
146+
147+
The repository also provides `actionlint-check.yaml`, `cmake-format-check.yaml`, and `codeql-analysis.yaml`, which can be used in a similar manner.

‎.github/actions/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# GitHub Actions Composite Actions
22

3+
> **Note**
4+
> This document describes the low-level reusable *actions* used within this repository. For instructions on how to use the complete, high-level *workflows* (e.g., `cmake-build.yaml`) from your own project, please see the guide in [`.github/REUSABLE_WORKFLOWS.md`](../REUSABLE_WORKFLOWS.md).
5+
36
This directory contains reusable composite actions for Phlex CI/CD workflows.
47

58
## Available Actions

‎.github/actions/REFACTORING_SUMMARY.md‎

Lines changed: 0 additions & 161 deletions
This file was deleted.

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,7 @@ Clone that repository and follow the instructions there to begin using Phlex.
1919
## Developing Phlex
2020

2121
Instructions for the development of Phlex itself are in the [developer notes](DEVELOPING.md)
22+
23+
## CI/CD
24+
25+
This repository provides a suite of reusable GitHub Actions workflows for building, testing, and formatting C++ and Python projects. For comprehensive instructions on how to use these workflows in your own project, please see the [reusable workflows guide](./.github/REUSABLE_WORKFLOWS.md).

0 commit comments

Comments
 (0)