.forgejo/workflows | ||
crates | ||
resources | ||
src | ||
templates | ||
tests | ||
.editorconfig | ||
.env.example | ||
.gitignore | ||
.pre-commit-config.yaml | ||
build.rs | ||
Cargo.lock | ||
Cargo.toml | ||
CHANGELOG.md | ||
cliff.toml | ||
Dockerfile | ||
Justfile | ||
LICENSE | ||
README.md |
Artifactview
View CI build artifacts from Forgejo/Github using your web browser.
Forgejo and GitHub's CI systems allow you to upload files and directories as artifacts. These can be downloaded as zip files. However there is no simple way to view individual files of an artifact.
Artifactview is a small web application that fetches these CI artifacts and displays their contents.
It offers full support for single page applications and custom 404 error pages.
Single-page applications require a file named 200.html
placed in the root directory,
which will be served in case no file exists for the requested path. A custom 404 error
page is defined using a file named 404.html
in the root directory.
Artifactview displays a file listing if there is no index.html
or fallback page
present, so you can browse artifacts that dont contain websites.
How to use
Open a Github/Gitea/Forgejo actions run with artifacts and paste its URL into the input
box on the main page. You can also pass the run URL with the ?url=
parameter.
Artifactview will show you a selection page where you will be able to choose the artifact you want to browse.
Setup
You can run artifactview using the docker image provided under
thetadev256/artifactview:latest
or bare-metal using the provided binaries.
Artifactview is designed to run behind a reverse proxy since it does not support HTTPS
by itself. If you are using a reverse proxy, you have to set the REAL_IP_HEADER
option
to the client IP address header name provided by the proxy (usually x-forwarded-for
.
Otherwise artifactview will assume it is being accessed by only 1 client (the proxy
itself) and the rate limiter would count all users as one.
Docker Compose
Here is an example setup with docker-compose, using Traefik as a reverse proxy:
services:
artifactview:
image: thetadev256/artifactview:latest
restart: unless-stopped
networks:
- proxy
environment:
ROOT_DOMAIN: av.thetadev.de
REAL_IP_HEADER: x-forwarded-for
GITHUB_TOKEN: github_pat_123456
REPO_WHITELIST: github.com;codeberg.org;code.thetadev.de
SITE_ALIASES: gh=>github.com;cb=>codeberg.org;th=>code.thetadev.de
labels:
- "traefik.enable=true"
- "traefik.docker.network=proxy"
- "traefik.http.routers.artifactview.entrypoints=websecure"
- "traefik.http.routers.artifactview.rule=HostRegexp(`^[a-z0-9-]*.?av.thetadev.de$`)"
networks:
proxy:
external: true
Configuration
Artifactview is configured using environment variables.
Variable | Default | Description |
---|---|---|
PORT |
3000 | HTTP port |
CACHE_DIR |
/tmp/artifactview | Temporary directory where to store the artifacts |
ROOT_DOMAIN |
localhost:3000 | Public hostname+port number under which artifactview is accessible. If this is configured incorrectly, artifactview will show the error message "host does not end with configured ROOT_DOMAIN" |
RUST_LOG |
info | Logging level |
NO_HTTPS |
false | Set to True if the website is served without HTTPS (used if testing artifactview without an ) |
MAX_ARTIFACT_SIZE |
100000000 (100 MB) | Maximum size of the artifact zip file to be downloaded |
MAX_FILE_SIZE |
100000000 (100 MB) | Maximum contained file size to be served |
MAX_FILE_COUNT |
10000 | Maximum amount of files within a zip file |
MAX_AGE_H |
12 | Maximum age in hours after which cached artifacts are deleted |
ZIP_TIMEOUT_MS |
1000 | Maximum time in milliseconds for reading the index of a zip file. If this takes too long, the zip file is most likely excessively large or malicious (zip bomb) |
GITHUB_TOKEN |
- | GitHub API token for downloading artifacts. Using a fine-grained token with public read permissions is recommended |
MEM_CACHE_SIZE |
50 | Artifactview keeps artifact metadata as well as the zip file indexes in memory to improve performance. The amount of cached items is adjustable. |
REAL_IP_HEADER |
- | Get the client IP address from a HTTP request header If Artifactview is exposed to the network directly, this option has to be unset. If you are using a reverse proxy the proxy needs to be configured to send the actual client IP as a request header. For most proxies this header is x-forwarded-for . |
LIMIT_ARTIFACTS_PER_MIN |
5 | Limit the amount of downloaded artifacts per IP address and minute |
REPO_BLACKLIST |
- | List of sites/users/repos that can NOT be accessed. The blacklist takes precedence over the whitelist (repos included in both lists cannot be accessed) Example: github.com/evil-corp/world-destruction;codeberg.org/blackhat;example.org |
REPO_WHITELIST |
- | List of sites/users/repos that can ONLY be accessed. If the whitelist is empty, it will be ignored and any repository can be accessed. Uses the same syntax as REPO_BLACKLIST . |
SITE_ALIASES |
- | Aliases for sites to make URLs shorter Example: gh => github.com;cb => codeberg.org |
SUGGESTED_SITES |
codeberg.org; github.com; gitea.com | List of suggested code forges (host only, without https://, separated by ; ). If repo_whitelist is empty, this value is used for the matched sites in the userscript. The first value is used in the placeholder URL on the home page. |
VIEWER_MAX_SIZE |
500000 | Maximum file size to be displayed using the viewer |
Technical details
URL format
Artifactview uses URLs in the given format for accessing the individual artifacts:
<HOST>--<USER>--<REPO>--<RUN>-<ARTIFACT>.hostname
Example: https://github-com--theta-dev--example-project--4-11.example.com
The reason for using subdomains instead of URL paths is that many websites expect to be
served from a separate subdomain and access resources using absolute paths. Using URLs
like example.com/github.com/theta-dev/example-project/4/11/path/to/file
would make the
application easier to host, but it would not be possible to simply preview a
React/Vue/Svelte web project.
Since domains only allow letters, numbers and dashes but repository names allow dots and underscores, these escape sequences are used to access repositories with special characters in their names.
-0
->.
-1
->-
-2
->_
Another issue with using subdomains is that they are limited to a maximum of 63 characters. Most user and repository names are short enough for this not to become a problem, but it could still happen that a CI run becomes inaccessible. Since the run ID is incremented on each new CI run, it might even happen that Artifactview works fine at the beginning of a project, but the subdomains exceed the length limit in the future.
That's why I added aliases for forge URLs. You can for example alias github.com as gh, shaving 8 characters from the subdomain. This makes the subdomains short enogh that you will be unlikely to hit the limit even with longer user/project names.
Security considerations
It is recommended to use the whitelist feature to allow artifactview to access only trusted servers, users and organizations.
Since many
well-known URIs
are used to configure security-relevant properties of a website or attest ownership of a
website (like .well-known/acme-challenge
for issuing TLS certificates), Artifactview
will serve no files from the .well-known
folder.
There is a configurable limit for both the maximum downloaded artifact size and the maximum size of individual files to be served (100MB by default). Additionally there is a configurable timeout for the zip file indexing operation. These measures should protect the server againt denial-of-service attacks like overfilling the server drive or uploading zip bombs.