Skip to content

Commit

Permalink
docs: Github summary
Browse files Browse the repository at this point in the history
  • Loading branch information
@cybersokari
cybersokari committed Dec 6, 2024
1 parent a265eec commit 5c00492
Show file tree
Hide file tree
Showing 2 changed files with 67 additions and 63 deletions.
130 changes: 67 additions & 63 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,23 +1,28 @@
![Deployment](https://github.com/cybersokari/allure-docker-deploy/actions/workflows/deploy.yaml/badge.svg?branch=main)
![](https://img.shields.io/docker/pulls/sokari/allure-docker-deploy)
# Allure Docker Deploy
_A simple way to share and backup `allure` test reports._
_An easy-to-use Docker solution for sharing and backing up Allure test reports_

This [Docker image](https://hub.docker.com/r/sokari/allure-docker-deploy) will enable you to share [Allure test reports](https://allurereport.org/) seamlessly with stakeholders via an ephemeral URL and backup all file History and Retries in Firebase Cloud Storage. You can generate unique URLs for each test run, allowing you to preview previous test run reports after generating a new report.
It works in both CI and local environments, requiring minimal setup. The generated URLs are hosted with [Firebase-hosted website](https://firebase.google.com/docs/hosting), and a free tier Firebase plan is all you need to get started.
This [Docker image](https://hub.docker.com/r/sokari/allure-docker-deploy) lets you share [Allure test reports](https://allurereport.org/) seamlessly via an ephemeral URL. It also backs up all report history and retries to Firebase Cloud Storage, enabling unique URLs for each test run and previewing previous reports.

Works in both CI and local environments with minimal setup, utilizing [Firebase Hosting](https://firebase.google.com/docs/hosting). A free Firebase plan is sufficient to get started.


---

## Key Features
- **Cloud Storage**: Save Allure test results and history in a Google Cloud Storage bucket.
- **Test Report preview URL**: Generates and hosts Allure reports on a website for easy sharing with stakeholders, powered by Firebase Hosting
- **Slack notification** Review Test report preview URL in Slack after every test run (Coming soon)
- **Watch Mode**: Continuously detects test results and takes action (backup to storage and publish report website): Only enable this when running this image locally.

- **Cloud Storage**: Automatically backs up Allure test results and history in a Google Cloud Storage bucket.
- **Preview URLs**: Generates ephemeral Allure report URLs hosted on Firebase for easy sharing with stakeholders.
- **Slack Integration**: _(Coming Soon)_ Notify team members with preview URLs directly in Slack after each test run.
- **Continuous Deployment**: In Watch Mode, the container detects changes, generates reports, and uploads them automatically. Suitable for testing locally.

---

## Use cases
### GitHub Actions
## Use Cases

### 1. GitHub Actions
#### Sample Workflow
```yaml
name: Allure Docker Deploy
on:
Expand Down Expand Up @@ -55,16 +60,22 @@ jobs:
sokari/allure-docker-deploy:latest

```
Tips:
1. Use a different value `WEBSITE_ID` in every test run. `${{ github.ref }}` is a good example.
2. Set the WEBSITE_EXPIRES value appropriately to deallocate old test run sites.
3. Mount the `$GITHUB_STEP_SUMMARY` file to see your test report URL in GitHub Actions job summary
### Local test runs
#### Step 1: Pull the Docker Image

**URL preview in GitHub Actions summary**
<div style="text-align: left"><img src="assets/example-github-summary.png" height="300" alt="GitHub Action Summary"></div>

Tips
1. Use unique values for `WEBSITE_ID` (e.g., `${{ github.ref }}`) to avoid overwriting reports.
2. Configure `WEBSITE_EXPIRES` to manage the duration of hosted reports.
3. Mount `$GITHUB_STEP_SUMMARY` to display the test report URL in GitHub Actions job summaries.

### 2. Local test runs
**Step-by-Step Guide**
#### 1. Pull the Docker Image
```bash
docker pull sokari/allure-docker-deploy:latest
```
#### Step 2: Run the Container
#### 2. Run the Container
```shell
docker run -d \
-e GOOGLE_APPLICATION_CREDENTIALS=/credentials/gcp-key.json \
Expand All @@ -77,7 +88,7 @@ docker run -d \
-v /path/to/gcp-key.json:/credentials/gcp-key.json \
sokari/allure-docker-deploy
```
With `docker-compose.yaml`:
##### 3. With `docker-compose.yaml`:
```yaml
services:
allure:
Expand All @@ -98,17 +109,43 @@ services:
TTL_SECS: 60
```
**URL preview in console**
<div style="text-align: left"><img src="assets/ci-report-url-ss.png" height="300" alt="Firebase CLI console output"></div>
## Requirements
1. **Google Cloud Credentials**:
- Set up a Google Cloud [service account](https://firebase.google.com/docs/admin/setup#initialize_the_sdk_in_non-google_environments) with access to your storage bucket and Firebase Hosting.
- Download the `service-account-file.json` JSON file that the `GOOGLE_APPLICATION_CREDENTIALS` environment variable will point to.
- Create a Google Cloud [service account](https://firebase.google.com/docs/admin/setup#initialize_the_sdk_in_non-google_environments) with access to Firebase Hosting and Cloud Storage
- Download the `service-account-file.json` JSON file.

2. **Google Cloud Storage Bucket**:
- A storage bucket to store test results and reports.
- Create a bucket to store test results and reports. You can use the default.

3. **Website ID**:
- A unique identifier for your hosted report website in Firebase (for example, `feature_mission-2-jupiter`).
- Use a unique identifier for each hosted report. Example: `feature_mission-2-jupiter`).

---


## How it works

1. Mount test results' directory.
- Bind your `/allure-results` directory to the container.
2. Set required environment variables:
- `GOOGLE_APPLICATION_CREDENTIALS`: Path to your GCP credentials file.
- `STORAGE_BUCKET`: The name of your Google Cloud Storage bucket (if using cloud storage).
- `WEBSITE_ID`: A unique identifier for your test report site. You can use different identifiers to get a new site for every test run. Using the same `WEBSITE_ID` overwrites the previous Test Report.
3. Watch Mode:
- When `WATCH_MODE` is set to `true`, the container will watch for updates in the `/allure-results` directory.
- Upload results to the specified Google Cloud Storage bucket (if `STORAGE_BUCKET` is provided).
- Host the generated Allure report on Firebase Hosting (if `WEBSITE_ID` is provided).
- Perform both actions if both environment variables are set.
- On every new file detected, the `TTL_SECS` restarts the countdown toward deployment/storage.
4. [Report history and retries](https://allurereport.org/docs/history-and-retries/#history-and-retries)
- Set `KEEP_HISTORY` to back up your `allure-report/history` after every report generation.
- Set `KEEP_RETRIES` to back up files every file in the `/allure-results` mount directory after report generation.
- Disabled if not `STORAGE_BUCKET` is provided


---

Expand All @@ -130,49 +167,16 @@ services:
---


## How it works

1. Mount your test results directory (`/allure-results`) to the container.
2. Configure required environment variables:
- `GOOGLE_APPLICATION_CREDENTIALS`: Path to your GCP credentials file.
- `STORAGE_BUCKET`: The name of your Google Cloud Storage bucket (if using cloud storage).
- `WEBSITE_ID`: A unique identifier for the Firebase Hosting site. You can use different identifiers to get a new website for every test run. Using the same `WEBSITE_ID` for multiple runs will replace the previous Test Report on the previously generated URL
3. When `WATCH_MODE` is set to `true`, the container will watch for updates in the `/allure-results` directory. Once no new files are detected within the `TTL_SECS` timeframe, it will:
- Upload results to the specified Google Cloud Storage bucket (if `STORAGE_BUCKET` is provided).
- Host the generated Allure report on Firebase Hosting (if `WEBSITE_ID` is provided).
- Perform both actions if both environment variables are set.
4. Optionally configure `TTL_SECS` (default: 45 seconds) when running in `WATCH_MODE` to delay the active functionalities (Hosting/Storage) as Allure result files are being added to the `/allure-results`. On every new file detected, the `TTL_SECS` restarts the countdown toward deployment/storage. Report generation, deployment, and storage begin if no new file is detected after the `TTL_SECS`.
5. [Report history and retries](https://allurereport.org/docs/history-and-retries/#history-and-retries) are auto-enabled as `allure-report/history` directory is saved in storage after report generation.
6. The autogenerated Allure Report website is powered by Firebase hosting [preview channel](https://firebase.google.com/docs/hosting/test-preview-deploy?hl=en&authuser=0#preview-channels) which is ephemeral with a 7 days expiry by default. You can adjust the duration with the `WEBSITE_EXPIRES` environment variable in the docker run command or docker-compose file. Use `h` for hours, `d` for days, and `w` for weeks (for example, `12h`, `7d`, `2w`, respectively). The max duration is 30 days.

_Note: While you can use Firebase hosting for free, you need to enable billing to use Cloud Storage.
Nevertheless, you have free 5GB of storage before you will incur any charges_

---

## Where to find your hosted test report URL
| Platform | Report URL output location |
|-----------|----------------------------------|
| GitHub | Logs, GitHub Actions job summary |
| Gitlab | Logs |
| Localhost | Logs |
### URL in logs example
<div style="text-align: left"><img src="assets/ci-report-url-ss.png" height="220" alt="Firebase CLI console output"></div>

_You can also find the URL in your Firebase Console Dashboard._

## Comparison: Docker Deploy vs Allure GitHub Actions Integration

| Feature | Allure Docker Deploy | [Allure GitHub Actions Integration](https://allurereport.org/docs/integrations-github/#github-actions-integration) |
|-------------------------------------------|-----------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
| **Unique URLs for each deployment** | Yes, every deployment generates a unique ephemeral URL for the test report. | No, reports are deployed to a single GitHub Pages URL, overwriting previous reports. |
| **Report history and retries** | Keeps complete history and retries by saving test result files to Cloud Storage for future report generations. | No retires, only report history retrieved from the previous GitHub Pages deployment. |
| **Cloud Storage backup** | Automatically backs up test result files to Google Cloud Storage. | No backup functionality; relies on GitHub repositories for report storage. |
| **Direct deployment without Git commits** | Deploys directly to Firebase Hosting without committing generated reports to Git. | Requires committing generated reports to GitHub Pages. |
| **Further analysis capabilities** | Allows access to all saved test result files for additional analysis beyond the Allure-generated report. | No such functionality provided. |
| **Slack notifications** | Planned (coming soon). | Not supported. |
| **Hosting platform** | Firebase Hosting, with ephemeral URLs that can be customized and set to expire (default: 7 days, max: 30 days). | GitHub Pages, with a persistent single URL. |
## Comparison: Allure Docker Deploy vs The Official GitHub Actions Integration

| Feature | Allure Docker Deploy | [Allure GitHub Actions Integration](https://allurereport.org/docs/integrations-github/) |
|-------------------------------------------|------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| **Unique URLs for each deployment** | ✅ Yes, every deployment generates a unique ephemeral URL for the test report. | ❌ No, reports are deployed to a single GitHub Pages URL, overwriting previous reports. |
| **Report history and retries** | ✅ Keeps complete history and retries by saving test result files to Cloud Storage for future reports. | ❌ Limited; only report history is retrieved from the previous GitHub Pages deployment. |
| **Cloud Storage backup** | ✅ Automatically backs up test result files to Google Cloud Storage. | ❌ No backup functionality; relies on GitHub repositories for report storage. |
| **Direct deployment without Git commits** | ✅ Deploys directly to Firebase Hosting without committing generated reports to Git. | ❌ Requires committing generated reports to GitHub Pages. |
| **Further analysis capabilities** | ✅ Allows access to all saved test result files for additional analysis beyond the Allure-generated report. | ❌ No such functionality provided. |
| **Slack notifications** | 🚧 Planned (Coming Soon). | ❌ Not supported. |

---

Expand Down
Binary file added assets/example-github-summary.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 5c00492

Please sign in to comment.