Configure commitdog with your platform token

Before you can commit, create repos, open PRs, or publish releases, commitdog needs a personal access token for your Git platform. Run commitdog setup once per platform — you can store tokens for all four (GitHub, GitLab, Gitea, and Forgejo) at the same time.

Run the setup command

Open a terminal and run:

commitdog setup

commitdog will ask which platform you want to configure:

  which platform token do you want to configure?

  1  github
  2  gitlab
  3  gitea
  4  forgejo

  [1/2/3/4] pick › 1

Enter the number for your platform and press Enter.

Enter your email

commitdog will prompt you for the email address associated with your platform account. This email is applied per-repo via git config --local so your global Git config stays untouched.If you already have an email saved, commitdog will show it and ask if you want to change it.

Create and enter your token

commitdog will display where to create your token and which scopes are required (see the platform-specific instructions below). Paste your token at the prompt.Token validation runs locally — commitdog checks the token format before saving it.

Confirm the saved config

After saving, commitdog confirms the location of your config file:

  ✓ saved to ~/.config/commitdog/config.toml

Repeat commitdog setup for any additional platforms you want to configure.

Token requirements by platform

Create a personal access token on your platform with the scopes listed below, then paste it into the commitdog setup prompt.

GitHub
GitLab
Gitea
Forgejo

Create a classic personal access token at github.com/settings/tokens.Required scopes:

Scope	Purpose
`repo`	Read and write access to repositories
`write:org`	Manage organization resources (required for org repos)
`read:user`	Read your public profile information

commitdog expects a classic PAT. Fine-grained tokens are not supported. Your token must start with ghp_ or github_pat_.

Create a legacy personal access token at gitlab.com/-/profile/personal_access_tokens.Required scope:

Scope	Purpose
`api`	Full API access (includes repos, releases, and packages)

After entering your token, commitdog will ask for your GitLab instance URL. Press Enter to use https://gitlab.com or paste a self-hosted URL.

Your token must start with glpat-.

Create a personal access token under Settings → Applications in your Gitea instance.Required permissions (read + write):

Permission	Purpose
`repository`	Read and write repositories
`organization`	Manage organization resources
`user`	Read and write user information

After entering your token, commitdog will prompt you for your Gitea instance URL (e.g. https://git.yourcompany.com).

Create a personal access token under Settings → Applications in your Forgejo instance.Required permissions (read + write):

Permission	Purpose
`repository`	Read and write repositories
`organization`	Manage organization resources
`user`	Read and write user information

After entering your token, commitdog will prompt you for your Forgejo instance URL (e.g. https://git.yourcompany.com).

Where your config is stored

commitdog writes your credentials to:

~/.config/commitdog/config.toml

The file is created with 0600 permissions (readable only by your user). A typical config looks like this:

email = "you@example.com"

[github]
token = "ghp_..."
email = "you@example.com"

[gitlab]
token = "glpat-..."
host = "https://gitlab.com"
email = "you@example.com"

Your tokens never leave your machine except when commitdog makes a direct API call to the platform (for example, when creating a repo or publishing a release). No data is sent anywhere else.

Start a new repository

Once commitdog setup is complete, you can create a new repository on your platform and push your first commit — without opening a browser:

commitdog init

commitdog connects to your platform using the saved token, asks you to name the repo, choose between private and public, optionally select an organization, then runs git init, makes the first commit, sets the remote, and pushes.

  which platform is this repo on?

  1  github
  2  gitlab
  3  gitea
  4  forgejo

  [1/2/3/4] pick › 1

  ✓ connected as alice
  repo name [my-project] ›
  private or public? [P/u] ›

  creating repo... ✓ repo created: https://github.com/alice/my-project
  ✓ committed: feat: initial commit
  ✓ pushed
  live at https://github.com/alice/my-project

If a .commitdog file already exists in the directory, commitdog reads the platform from it and skips the platform prompt.

Get Started

Core Commands

Releasing

Security

Reference

Configure commitdog with your platform token

Token requirements by platform

Where your config is stored

Start a new repository

​Token requirements by platform

​Where your config is stored

​Start a new repository

Token requirements by platform

Where your config is stored

Start a new repository