GitHub image storage

The built-in github provider writes files to a repository and branch and returns an image address. This example uses owner/docs-images on main; owner is a placeholder.

1. Prepare a repository and branch

Choose or create an image repository and initialize it, for example with a README. Check the real branch name: main, master, or your own branch. The uploader does not create repositories or branches.

For public articles, confirm readers can access the assets anonymously. Private repository download links can require authentication even after a successful upload.

2. Create a token with write access

Open GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens. Choose the resource owner, restrict the token to your target repository, grant Contents: Read and write, and set an expiration. Organization repositories may require approval.

Enter the token only in your local PicList configuration. See GitHub's token guide and repository contents API.

3. Configure PicList

Expand PicBed → GitHub → Add New Configuration:

Field	Example	Meaning
Config Name	Docs images	Name inside PicList
repo	owner/docs-images	User or organization / repository, without a full web URL
branch	main	An existing branch
token	Enter locally	Token with repository content write access
path	images/	Directory inside the repository
customUrl	Leave empty for the first test	Optional resource-serving prefix
webPath	Leave empty for the first test	Directory under a custom serving domain

Confirm, select the configuration card, and set the default provider. Configuration card instructions apply to all built-in providers.

4. Upload and verify the link

1. On Upload, check GitHub and the configuration name.
2. Upload photo.png.
3. Check photo.png under main → images/ in the repository.
4. Copy URL from the PicList gallery and open it without a GitHub login.
5. Switch to Markdown and paste into your editor's preview.

Without customUrl, the uploader uses the API's download_url. A public repository example has this shape:

https://raw.githubusercontent.com/owner/docs-images/main/images/photo.png

This is a placeholder address. A repository's blob web page is not a direct image URL.

Use a custom resource prefix

Set a prefix after confirming your resource service can read the repository. For example:

Field	Example
customUrl	https://raw.githubusercontent.com/owner/docs-images/main
path	images/
webPath	Empty, to follow the upload directory

The result should end with /images/photo.png. Check webPath if the prefix already includes a directory. Browser or CDN caches can delay visible changes.

What happens to repeated filenames?

The uploader can reuse a file with identical contents at the same repository, branch, and path. Different contents at an existing path cause a conflict; do not expect a silent overwrite.

For new screenshots, enable Automatic naming, such as {filename}-{str-6} or {Y}{m}{d}-{ulid}. Use an explicit repository editing workflow when updating an existing file and check its references.

Common problems

Symptom	Check
401 / 403	Token expiry, repository scope, Contents write access, organization approval
404	repo format, account access, repository and branch existence
422 or conflict	Different contents already exist at that path; test a new name
Upload succeeds but article has no image	Anonymous access and direct image URL rather than a web page
Old image still appears	Actual repository contents, URL, browser or CDN cache

Create a separate Cloud management configuration to browse repository images from other devices. The gallery records uploads made on this computer.