|
| 1 | +# Testing GitHub Actions using Forks |
| 2 | + |
| 3 | +When developing GitHub Actions or automation bots for Enterprise-Java, it is risky to test directly on the main repository. A mistake could accidentally close valid Pull Requests, spam developers with comments, or break build pipelines. |
| 4 | + |
| 5 | +To test safely, developers should use their personal **fork** of the repository. This guide explains how to set up a fork to mimic the main repository and test workflows effectively. |
| 6 | + |
| 7 | +## Prerequisites |
| 8 | + |
| 9 | +By default, GitHub Actions are often disabled on forks to save resources. You must enable them manually: |
| 10 | + |
| 11 | +1. Go to your fork on GitHub (e.g., `github.com/<your-username>/hiero-enterprise-java`). |
| 12 | +2. Click on the **Settings** tab. |
| 13 | +3. On the left sidebar, click **Actions** > **General**. |
| 14 | +4. Select **Allow all actions and reusable workflows**. |
| 15 | +5. Click **Save**. |
| 16 | + |
| 17 | +## The Testing Workflow |
| 18 | + |
| 19 | +Testing a bot or action usually involves two distinct parts: |
| 20 | +1. **The Logic:** The code that runs the bot (e.g., the `.sh` script or `.yml` workflow). |
| 21 | +2. **The Trigger:** An event that causes the bot to run (e.g., a new PR, a comment, or a specific time of day). |
| 22 | + |
| 23 | +### Step 1: Update your Fork's Main Branch |
| 24 | +GitHub Actions usually define the "active" workflows based on the files present in the default branch (usually `main`). To test your new bot logic: |
| 25 | + |
| 26 | +1. Create a branch with your changes (e.g., `feat/new-bot-logic`). |
| 27 | +2. Push this branch to your fork. |
| 28 | +3. Open a Pull Request **targeting your fork's main branch** (Base: `<your-username>:main` ← Compare: `<your-username>:feat/new-bot-logic`). |
| 29 | +4. **Merge** this PR into your fork's `main`. |
| 30 | + |
| 31 | +> **Note:** Your fork's `main` branch now acts as the "production" environment for your test. It contains the code that *runs* the tests. |
| 32 | +
|
| 33 | +### Step 2: Create a Test Scenario |
| 34 | +Now that your fork has the updated logic, you need to create an event to trigger it. |
| 35 | + |
| 36 | +1. Create a new dummy branch (e.g., `test/trigger-bot`). |
| 37 | +2. Make the necessary changes to trigger the specific action (see examples below). |
| 38 | +3. Open a Pull Request **within your fork** (Base: `<your-username>:main` ← Compare: `<your-username>:test/trigger-bot`). |
| 39 | + |
| 40 | +--- |
| 41 | + |
| 42 | +## Modifying Test Timescales |
| 43 | + |
| 44 | +Real-world conditions (like "21 days of inactivity") are impractical for testing. You should temporarily modify the code in your feature branch (Step 1) to simulate these conditions immediately. |
| 45 | + |
| 46 | +### 1. Shortening Time Thresholds |
| 47 | +If a bot waits for **21 days**, change the variable to **0 days** or **minutes** in your script. |
| 48 | + |
| 49 | +**Before (Production Code):** |
| 50 | +```bash |
| 51 | +# Wait for 21 days before marking as stale |
| 52 | +DAYS="${DAYS:-21}" |
| 53 | +``` |
| 54 | + |
| 55 | +**After (Testing Code):** |
| 56 | +```bash |
| 57 | +# Set to 0 to treat everything as immediately stale for testing |
| 58 | +DAYS="${DAYS:-0}" |
| 59 | +``` |
| 60 | + |
| 61 | +### 2. accelerating Cron Schedules |
| 62 | +If a workflow runs once a day, you don't want to wait 24 hours. Modify the `.yml` file to run frequently or allow manual triggers. |
| 63 | + |
| 64 | +**Before:** |
| 65 | +```yaml |
| 66 | +on: |
| 67 | + schedule: |
| 68 | + - cron: "0 12 * * *" # Runs at 12:00 PM daily |
| 69 | +``` |
| 70 | +
|
| 71 | +**After:** |
| 72 | +```yaml |
| 73 | +on: |
| 74 | + workflow_dispatch: # Allows manual button click in Actions tab |
| 75 | + schedule: |
| 76 | + - cron: "*/5 * * * *" # Runs every 5 minutes |
| 77 | +``` |
| 78 | +
|
| 79 | +--- |
| 80 | +
|
| 81 | +## Real World Examples |
| 82 | +
|
| 83 | +### Example 1: Testing an Unverified Commit Bot |
| 84 | +**Goal:** Ensure the bot posts a warning comment if a PR contains unsigned commits. |
| 85 | +
|
| 86 | +1. **Deploy Logic:** Merge the workflow file that checks for GPG signatures into your fork's `main`. |
| 87 | +2. **Trigger Scenario:** |
| 88 | + * Create a new branch: `git checkout -b test/unsigned-commit` |
| 89 | + * Make a dummy change. |
| 90 | + * Commit **without** your GPG signature using the `--no-gpg-sign` flag: |
| 91 | + ```bash |
| 92 | + git commit -m "test: unsigned commit" --no-gpg-sign |
| 93 | + ``` |
| 94 | + * Push and open a PR to your fork's `main`. |
| 95 | +3. **Verify:** Wait a moment and check the PR timeline. The bot should post a comment or fail the check indicating the commit is unverified. |
| 96 | + |
| 97 | +### Example 2: Testing an Inactivity Bot |
| 98 | +**Goal:** Verify the bot unassigns users after a period of inactivity. |
| 99 | + |
| 100 | +1. **Modify Logic:** In your script (Step 1), set `DAYS=0` so the bot considers any issue created "now" as stale. |
| 101 | +2. **Deploy:** Merge this change to your fork's `main`. |
| 102 | +3. **Trigger Scenario:** |
| 103 | + * Create a dummy Issue in your fork. |
| 104 | + * Assign yourself to the Issue. |
| 105 | + * Wait for the scheduled workflow to run (e.g., the 5-minute cron you set up) or manually trigger it via the Actions tab. |
| 106 | +4. **Verify:** Check if the bot posted a comment on the issue and removed you from the assignee list. |
| 107 | + |
| 108 | +## Cleanup |
| 109 | + |
| 110 | +Once you have verified the functionality works as expected: |
| 111 | + |
| 112 | +1. Delete your test branches (`test/trigger-bot`, etc.). |
| 113 | +2. Close any dummy Pull Requests and Issues in your fork. |
| 114 | +3. **Revert the timescale changes** in your feature branch (e.g., change `DAYS=0` back to `DAYS=21`, remove the `*/5` cron). |
| 115 | +4. Create a final Pull Request from your clean feature branch to the official upstream repository. |
0 commit comments