Skip to content

Commit

Permalink
Add GitHub PR Bot Commands page to documentation (#4167)
Browse files Browse the repository at this point in the history
  • Loading branch information
marrobi authored Dec 6, 2024
1 parent b67018f commit 43cab59
Show file tree
Hide file tree
Showing 4 changed files with 68 additions and 63 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ ENHANCEMENTS:
* Update Guacamole version and dependencies ([#4140](https://github.com/microsoft/AzureTRE/issues/4140))
* Add partial (core resources only) support for customer managed keys ([#4141](https://github.com/microsoft/AzureTRE/issues/4142), [#4144](https://github.com/microsoft/AzureTRE/issues/4144))
* Update the Azure CLI version to 2.67.0 in dev container and vmss ([#4157](https://github.com/microsoft/AzureTRE/pull/4157))
* Move Github PR bot commands into main documentation ([#4167](https://github.com/microsoft/AzureTRE/pull/4167))

BUG FIXES:
- Update KeyVault references in API to use the version so Terraform cascades the update ([#4112](https://github.com/microsoft/AzureTRE/pull/4112))
Expand Down
65 changes: 65 additions & 0 deletions docs/tre-developers/github-pr-bot-commands.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# GitHub PR Bot Commands

## PR Comment bot commands

**Notes**
- these commands are not immediate - you need to wait for the GitHub action that performs the task to start up.
- builds triggered via these commands will use the workflow definitions from `main`. To test workflow changes before merging to `main`, the changes need to be pushed to a branch in the main repo and then the `deploy_tre_branch.yml` workflow can be run against that branch.

These commands can only be run when commented by a user who is identified as a repo collaborator (see [granting access to run commands](#granting-access-to-run-commands))

### `/help`

This command will cause the pr-comment-bot to respond with a comment listing the available commands.

### `/test [<sha>]`

This command runs the build, deploy, and smoke tests for a PR.

For PRs from maintainers (i.e. users with write access to microsoft/AzureTRE), `/test` is sufficient.

For other PRs, the checks below should be carried out. Once satisfied that the PR is safe to run tests against, you should use `/test <sha>` where `<sha>` is the SHA for the commit that you have verified.
You can use the full or short form of the SHA, but it must be at least 7 characters (GitHub UI shows 7 characters).

**IMPORTANT**

This command works on PRs from forks, and makes the deployment secrets available.
Before running tests on a PR, ensure that there are no changes in the PR that could have unintended consequences (e.g. leak secrets or perform undesirable operations in the testing subscription).

Check for changes to anything that is run during the build/deploy/test cycle, including:
- modifications to workflows (including adding new actions or changing versions of existing actions)
- modifications to the Makefile
- modifications to scripts
- new python packages being installed

### `/test-extended [<sha>]` / `/test-extended-aad [<sha>]`/ `/test-shared-services [<sha>]`

This command runs the build, deploy, and smoke & extended / shared services tests for a PR.

For PRs from maintainers (i.e. users with write access to microsoft/AzureTRE), `/test-extended` is sufficient.

If a change has been made which would affect any of the core shared services, make sure you run `/test-shared-services`.

For other PRs, the checks below should be carried out. Once satisfied that the PR is safe to run tests against, you should use `/test-extended <sha>` where `<sha>` is the SHA for the commit that you have verified.
You can use the full or short form of the SHA, but it must be at least 7 characters (GitHub UI shows 7 characters).

**IMPORTANT**

As with `/test`, this command works on PRs from forks, and makes the deployment secrets available.
Before running tests on a PR, run the same checks on the PR code as for `/test`.

### `/test-destroy-env`

When running `/test` multiple times on a PR, the same TRE ID and environment are used by default. The `/test-destroy-env` command destroys a previously created validation environment, allowing you to re-run `/test` with a clean starting point.

The `/test-destroy-env` command also destroys the environment associated with the PR branch (created by running the `deploy_tre_branch` workflow).

### `/test-force-approve`

This command skips running tests for a build and marks the checks as completed.
This is intended to be used in scenarios where running the tests for a PR doesn't add value (for example, changing a workflow file that is always pulled from the default branch).


## Granting access to run commands

Currently, the GitHub API to determine whether a user is a collaborator doesn't seem to respect permissions that a user is granted via a group. As a result, users need to be directly granted `write` permission in the repo to be able to run the comment bot commands.
64 changes: 1 addition & 63 deletions maintainers.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,69 +3,7 @@
This document is targeted at maintainers of the AzureTRE project.
For information on developing and contributing to AzureTRE, see the [TRE Developers docs](https://microsoft.github.io/AzureTRE/tre-developers/)

## PR Comment bot commands

**Notes**
- these commands are not immediate - you need to wait for the GitHub action that performs the task to start up.
- builds triggered via these commands will use the workflow definitions from `main`. To test workflow changes before merging to `main`, the changes need to be pushed to a branch in the main repo and then the `deploy_tre_branch.yml` workflow can be run against that branch.

These commands can only be run when commented by a user who is identified as a repo collaborator (see [granting access to run commands](#granting-access-to-run-commands))

### `/help`

This command will cause the pr-comment-bot to respond with a comment listing the available commands.

### `/test [<sha>]`

This command runs the build, deploy, and smoke tests for a PR.

For PRs from maintainers (i.e. users with write access to microsoft/AzureTRE), `/test` is sufficient.

For other PRs, the checks below should be carried out. Once satisfied that the PR is safe to run tests against, you should use `/test <sha>` where `<sha>` is the SHA for the commit that you have verified.
You can use the full or short form of the SHA, but it must be at least 7 characters (GitHub UI shows 7 characters).

**IMPORTANT**

This command works on PRs from forks, and makes the deployment secrets available.
Before running tests on a PR, ensure that there are no changes in the PR that could have unintended consequences (e.g. leak secrets or perform undesirable operations in the testing subscription).

Check for changes to anything that is run during the build/deploy/test cycle, including:
- modifications to workflows (including adding new actions or changing versions of existing actions)
- modifications to the Makefile
- modifications to scripts
- new python packages being installed

### `/test-extended [<sha>]` / `/test-extended-aad [<sha>]`/ `/test-shared-services [<sha>]`

This command runs the build, deploy, and smoke & extended / shared services tests for a PR.

For PRs from maintainers (i.e. users with write access to microsoft/AzureTRE), `/test-extended` is sufficient.

If a change has been made which would affect any of the core shared services, make sure you run `/test-shared-services`.

For other PRs, the checks below should be carried out. Once satisfied that the PR is safe to run tests against, you should use `/test-extended <sha>` where `<sha>` is the SHA for the commit that you have verified.
You can use the full or short form of the SHA, but it must be at least 7 characters (GitHub UI shows 7 characters).

**IMPORTANT**

As with `/test`, this command works on PRs from forks, and makes the deployment secrets available.
Before running tests on a PR, run the same checks on the PR code as for `/test`.

### `/test-destroy-env`

When running `/test` multiple times on a PR, the same TRE ID and environment are used by default. The `/test-destroy-env` command destroys a previously created validation environment, allowing you to re-run `/test` with a clean starting point.

The `/test-destroy-env` command also destroys the environment associated with the PR branch (created by running the `deploy_tre_branch` workflow).

### `/test-force-approve`

This command skips running tests for a build and marks the checks as completed.
This is intended to be used in scenarios where running the tests for a PR doesn't add value (for example, changing a workflow file that is always pulled from the default branch).


## Granting access to run commands

Currently, the GitHub API to determine whether a user is a collaborator doesn't seem to respect permissions that a user is granted via a group. As a result, users need to be directly granted `write` permission in the repo to be able to run the comment bot commands.
For information on GitHub PR Bot Commands, see the [GitHub PR Bot Commands docs](https://microsoft.github.io/AzureTRE/tre-developers/github-pr-bot-commands/)

## Periodic tasks

Expand Down
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,7 @@ nav:
- Letsencrypt: tre-developers/letsencrypt.md
- Releases: tre-developers/release.md
- GitHub Actions: tre-admins/setup-instructions/workflows.md
- GitHub PR Bot Commands: tre-developers/github-pr-bot-commands.md

- Developing Workspace Templates: # Docs aimed at developers creating workspace templates
- Authoring Workspace Templates: tre-workspace-authors/authoring-workspace-templates.md
Expand Down

0 comments on commit 43cab59

Please sign in to comment.