Gitify Contributing Guide

May 10, 2026 ยท View on GitHub

Hi! We're really excited that you're interested in contributing to Gitify!

Before submitting your contribution, please read through the following guide.

We also suggest you read the Project Philosophy in our documentation.

Getting Started

Tip

Optional: If you prefer to use your own OAuth credentials, you can do so by passing them as environment variables when bundling the app. This is optional as the app has some default "development" keys (use at your own discretion).

OAUTH_CLIENT_ID="123" pnpm build

To get started:

Clone the repository and install dependencies:

pnpm install

Copy the .env.template to .env and add update GITHUB_TOKEN with a GitHub Personal Access Token. This is used for fetching the latest GitHub GraphQL API schema for graphql-codegen.

GITHUB_TOKEN=<some personal access token>

Start development mode (includes GraphQL codegen and hot module reload):

pnpm dev

Tests

Tooling is unified through Vite+, which bundles the linter (oxlint), formatter (oxfmt), test runner (Vitest), and dev/build pipeline (Vite).

# Run lint, format, and type checks
pnpm check

# Auto-fix formatting and lint issues
pnpm check:fix

# Run unit tests with coverage
pnpm test

# Update vitest snapshots
pnpm test -u

Code Style & Conventions

  • Linting and formatting are configured in vite.config.ts (the lint and fmt blocks). Please run pnpm check before submitting a PR.
  • Follow existing file and folder naming conventions.
  • Keep commit messages clear and descriptive.

How to Report Bugs or Request Features

If you encounter a bug or have a feature request, please open an issue with clear steps to reproduce or a detailed description of your idea. Check for existing issues before creating a new one.

Releases

The release process is automated. Follow the steps below.

  1. Verify features: Ensure all features and fixes you want included in the release are merged into main.
  2. Check dependencies: Review the Renovate Dependency Dashboard for any dependency updates you want to include.
  3. Create a release branch:
  • Name your branch release/vX.X.X (e.g., release/v1.2.3).
  • Run pnpm version <new-version-number> to bump the version in package.json and create a version commit/tag.
  • Update sonar.projectVersion within sonar-project.properties
  • Commit and push these changes.
  • Open a Pull Request (PR) from your release branch.
  1. GitHub release: GitHub Actions will automatically build, sign, and upload release assets to a new draft release with automated release notes.
  2. Merge the release branch: Once the PR is approved and checks pass, merge your release branch into main.
  3. Publish the release:
  • Finalize the release notes in the draft release on GitHub.
  • Confirm all assets are present and correct.
  • Publish the release.
  1. Update milestones:
  • Edit the current Milestone:
    • Add a link to the release notes in the description.
    • Set the due date to the release date.
    • Close the milestone.
  • Create a New Milestone for the next release cycle.
  1. A new homebrew cask will be automatically published (workflow runs ~3 hours)

Design Guidelines

  1. Use sentence case where possible
  2. Use GitHub's Octicons for iconography

Project Philosophy

This project is a tool for monitoring new notifications from supported Git forges. It's not meant to be a full-featured forge client. We want to keep it simple and focused on that core functionality. We're happy to accept contributions that help us achieve that goal, but we're also happy to say no to things that don't. We're not trying to be everything to everyone.

Multi-forge support

Gitify supports notifications from multiple Git forges. New forges may be added under the following conditions:

  • Adapter-based: the forge is implemented behind the ForgeAdapter interface in src/renderer/utils/forges/. No forge-specific branching outside the adapter module.
  • Designated maintainer: every forge has at least one named maintainer in MAINTAINERS.md who owns triage and CI for that adapter.
  • Capability-honest UI: features unsupported by a forge (e.g. mark-as-done) must hide gracefully, not silently no-op.
  • No core-platform churn: Octicons, Octokit, and the Primer Design System remain in place. Octokit is scoped to the GitHub adapter; other adapters use plain fetch.

Currently supported forges: GitHub (Cloud, Enterprise Server, Enterprise Cloud with Data Residency) and Gitea (incl. Forgejo, Codeberg).

Things we won't do