Gitea Integration for Jira

Documentation

Install it, connect one Gitea, link repositories.

Everything an administrator and a developer needs, in the order you need it. Version 2, the current Marketplace release.

Before you start

Requirements

  • A Gitea instance reachable from Atlassian over the public internet via HTTPS. Forge calls your Gitea API, and Gitea calls Forge back over webhooks. A VPN-only, LAN-only or plain-HTTP instance cannot work.
  • A Gitea account that may register an OAuth2 application and administer webhooks on the repositories you intend to link.
  • Jira Cloud. Site administrator rights to save the connection, project administrator rights to link repositories.

One connection per site

A Jira site connects to a single Gitea instance. Repository links are then made per Jira project, so different projects can follow different repositories on that instance.

Administrator setup

Connect Jira to Gitea

  1. 1

    Open the app settings in Jira

    Apps → Gitea integration. The Connection tab shows the redirect URI this installation uses. Copy it. It is unique to the installation and changes if the app is reinstalled.

  2. 2

    Register an OAuth2 application in Gitea

    In Gitea: Settings → Applications → Manage OAuth2 applications. Paste the redirect URI from step 1 exactly, with no trailing slash and no query string. Gitea returns a client ID and client secret.

  3. 3

    Save the connection, then authorize

    Back in Jira, enter your Gitea base URL (for example https://git.example.com), the client ID and the client secret, and save. Then press Connect: Gitea asks you to authorize, and the app stores the resulting access and refresh tokens. Tokens are refreshed automatically.

  4. 4

    Link repositories, per Jira project

    In a Jira project: Project settings → Gitea integration → Repositories. Pick a repository and link it. The app generates a signed webhook secret and creates the webhook in Gitea for you. If the token cannot administer that repository, the screen shows the webhook URL and secret so you can paste them into Gitea by hand.

Repository links are scoped to the Jira project that created them. Only issues belonging to that project are linked from that repository's events.

Daily use

What developers do

Mention an issue key

Any Jira issue key in a commit message, branch name, pull request title or pull request description links that commit, branch or pull request to the issue. Several keys in one message are all linked.

  • PROJ-123 fix expired refresh token — links the commit.
  • feat/PROJ-123-refresh-token — links the branch.

Post a comment from a commit

The #comment directive posts on the issue:

  • PROJ-123 #comment deployed to staging

The comment appears on the issue prefixed with the short commit hash. Work logging and issue transitions are not part of this version.

Where it shows up

  • Jira's built-in Development panel — commits, branches and pull requests, next to any other development tool you use.
  • Gitea activity panel on the issue — the same links with author, message and timestamp, plus recent webhook deliveries so you can see the integration working.

Create a branch from an issue

On a Jira issue, use the Gitea action to create a branch: pick the repository, accept or edit the prefilled branch name, pick the branch to start from. Pull request status then follows the work — open, reviewing, merged, closed.

Reference

Gitea events the app consumes

  • push — commit links and #comment directives
  • create / delete — branch links
  • pull_request — pull request links and status
  • pull_request_review — moves status to reviewing

Every delivery must carry a valid HMAC signature from the secret issued when the repository was linked. Unsigned, missigned, unknown repository, or replayed deliveries are rejected and recorded in the activity list.

Release, issue and wiki events are not consumed: deployments and Gitea releases do not appear in Jira in this version.

Reference

Who can do what

  • Jira site administrator — enters and changes the Gitea connection, authorizes it, runs the connection test.
  • Jira project administrator — links and unlinks repositories for that project, reads its webhook setup and activity.
  • Any user who can see the issue — reads the panels. Comments posted by the integration are authored by the app, not by a user.

Where your data lives

The app runs entirely on Atlassian's Forge platform. There is no vendor backend and no third-party data processor. Connection credentials, repository links and webhook secrets are held in Forge hosted storage inside your own site's partition. The only outbound traffic is to your Gitea host. See the privacy policy and data retention statement.

Troubleshooting

Common failures

Authorization fails, or Gitea says the redirect URI is unregistered

The redirect URI in the Gitea OAuth2 application does not match the one this installation uses.

Copy it again from the Connection tab and paste it verbatim. Reinstalling the app issues a new URI, and Gitea regenerates the client secret whenever you edit the application — re-save the new secret in Jira afterwards.

Nothing appears on the issue after a push

Either the webhook is not reaching Forge, or the issue is out of scope for that repository.

  1. Check recent deliveries on the repository in Gitea. A 401 means the secret was edited after linking; unlink and relink to issue a fresh secret.
  2. Confirm the issue belongs to the Jira project that linked the repository. Links are project-scoped.
  3. Confirm the key is a real issue key in that site — unknown keys are skipped silently.
My repository is not in the picker

The picker lists the first 50 repositories the connected account can see.

On larger instances, enter the repository by full name (owner/name) instead.

The webhook was not created automatically

The authorized account cannot administer webhooks on that repository.

The screen falls back to showing the target URL and the secret. Create the webhook in Gitea manually: content type JSON, the shown secret as the HMAC secret, and the push, create, delete, pull request and pull request review events.

I unlinked a repository — is the Gitea webhook gone?

No. Unlinking revokes the secret in Jira, so further deliveries are rejected, but the hook itself stays in Gitea.

Delete it in the repository's webhook settings if you want Gitea to stop sending.

Uninstalling

Leaving cleanly

  1. Unlink repositories, so Jira stops accepting their deliveries.
  2. Delete the webhooks in Gitea on those repositories.
  3. Revoke the OAuth2 application in Gitea.
  4. Uninstall the app in Jira.

On uninstall the app's data is soft-deleted and then removed under Atlassian's standard retention and disposal policy; a reinstall within 21 days can be relinked to the previous data. The retention statement has the detail.