How to Manage the GitHub Token for Gist Publishing in agentsview

Agentsview stores the GitHub personal access token in a local config.json file and exposes both a REST API endpoint and CLI command to set it, validating the token against GitHub's API before persisting it for Gist publishing operations.

Agentsview is an open-source session management tool that requires a GitHub personal access token to publish session data as Gists. Understanding how to manage the GitHub token for Gist publishing in agentsview ensures secure storage, validation, and seamless integration with GitHub's API according to the kenn-io/agentsview source code.

Where agentsview Stores the GitHub Token

The token persists in the GithubToken field of the global Config struct, which is serialized to config.json inside the application's data directory. The Config.SaveGithubToken method in internal/config/config.go handles the atomic write operation, ensuring the data directory exists before updating the file.

This persistence mechanism updates both the in-memory configuration and the JSON config map on disk. When the server restarts, it reloads the token from this file, maintaining continuity across sessions without requiring re-authentication.

Setting the GitHub Token via the REST API

Agentsview exposes the POST /api/v1/config/github endpoint to configure the token programmatically. The handler humaSetGithubConfig in internal/server/huma_routes_config.go accepts a JSON payload containing the token and performs strict validation before storage.

Validation Flow

The endpoint trims the input, verifies it is not empty, then calls validateGithubToken to issue a GET request to https://api.github.com/user. Only upon successful validation—confirming the token is active and retrieving the associated username—does the server save the token via Config.SaveGithubToken and update its runtime configuration.

curl -X POST http://localhost:8080/api/v1/config/github \
  -H "Content-Type: application/json" \
  -d '{"token":"ghp_XXXXXXXXXXXXXXXXXXXX"}'

Configuring the Token via CLI

For command-line workflows, agentsview provides the agentsview config set github --token <TOKEN> command. This CLI tool ultimately invokes the same server handler as the REST API, ensuring consistent validation logic across both interfaces. The command routes through the HTTP layer, meaning the token validation rules remain identical whether you use the API or the terminal.

Runtime Token Access and Thread Safety

The server accesses the stored token through the Server.githubToken() method defined in internal/server/server.go. This method provides thread-safe read access to the configuration, preventing race conditions during concurrent Gist publishing operations.

Direct Token Injection for Testing

Unit tests and custom scripts can bypass the standard configuration flow by calling Server.SetGithubToken. This method, also located in internal/server/server.go, offers a thin, concurrency-safe wrapper around the config field specifically designed for test scenarios.

func TestPublishWithFakeToken(t *testing.T) {
    s := startTestServer(t)               // creates a Server instance
    s.SetGithubToken("fake-token-123")    // inject token for the test

    // now POST /sessions/<id>/publish will succeed (or be mocked)
    resp := s.post(t, "/api/v1/sessions/s1/publish", "{}")
    // assert resp contains expected Gist fields …
}

Using the Token for Gist Publishing

When a client posts to /api/v1/sessions/{id}/publish, the humaPublishSession handler in internal/server/huma_routes_sessions.go retrieves the current token via s.githubToken(). If the token is missing, the server returns a 401 Unauthorized error immediately. Otherwise, the handler builds the Gist payload and calls createGist from internal/server/export.go to publish the content to GitHub.

The publishing flow enforces that the token must be pre-configured; there is no fallback to environment variables or command-line arguments during the actual publish operation.

Summary

• Agentsview persists the GitHub token in config.json via Config.SaveGithubToken in internal/config/config.go
• The POST /api/v1/config/github endpoint in internal/server/huma_routes_config.go validates and stores tokens via humaSetGithubConfig
• CLI commands route through the same validation logic as the REST API
• Runtime access uses thread-safe Server.githubToken() and Server.SetGithubToken methods in internal/server/server.go
• Gist publishing in internal/server/huma_routes_sessions.go requires the token and returns 401 if missing

Frequently Asked Questions

Where is the GitHub token stored on disk?

The token is stored in the GithubToken field of the JSON configuration file located at config.json within the agentsview data directory. The SaveGithubToken method in internal/config/config.go handles the atomic write operation and ensures parent directories exist.

How does agentsview validate the GitHub token before saving?

The server validates tokens by calling validateGithubToken, which issues a GET request to https://api.github.com/user to verify the token's validity and retrieve the associated username. This check occurs in the humaSetGithubConfig handler in internal/server/huma_routes_config.go, preventing invalid tokens from being persisted.

Can I set the GitHub token without using the API?

Yes. You can use the CLI command agentsview config set github --token <TOKEN> or directly modify the config.json file, though manual file editing bypasses validation. For testing purposes, use the Server.SetGithubToken method in internal/server/server.go to inject tokens programmatically without persisting them to disk.

What happens if the GitHub token is missing when publishing a session?

The humaPublishSession handler in internal/server/huma_routes_sessions.go checks for the token via s.githubToken(). If the token is empty or unset, the API returns a 401 Unauthorized status code and the Gist creation process halts before contacting GitHub's servers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}