Atlassian Forge Guide: Jira Project Permission Module Docs
Need custom Jira access rules? Use atlassian forge jira project permission module docs to configure and check permissions correctly. Read now.
If Jira project access needs to match a rule your team has created, standard permissions may not be enough. Forge can help you add a custom project permission, but the module’s manifest setup is only one part of the work. You also need to understand how administrators grant the permission and how your app checks it. Confusing those steps can leave a permission visible in Jira but ineffective in your app. But here's the truth: a reliable implementation starts by separating registration, configuration, and runtime checks. This guide explains what the Jira project permission module does, how to plan and test it, and what to verify in Atlassian’s current Forge reference before you deploy.
What the Jira project permission module does
The Forge jira:projectPermission module lets an app define a custom permission at the Jira project level. That permission can represent a project-specific action, such as approving a release checklist or viewing a restricted project panel.
Think of it as a named access rule that your app introduces to Jira. It does not automatically grant access to every project or replace Jira’s permission settings. A Jira administrator still needs to configure access, and the app needs to apply the permission correctly wherever it protects functionality.
Here's why the distinction matters: a permission has three practical parts. Forge registers the custom permission, a project administrator controls who receives it, and your app checks whether the current user has it before showing or performing a protected action.
- Registration: The app declares the permission through its Forge manifest.
- Administration: Jira project permissions or schemes determine who receives access.
- Enforcement: The app checks permission before exposing the relevant feature or action.
For example, an app might define “Approve release plan” as a project permission. An administrator can then assign that permission to the project’s release managers. Your app should still verify the current user’s access before allowing an approval.

Before you add a custom permission
Start by describing the action you want to protect in plain language. “Can approve release plans” is clearer than “release access,” because it identifies one capability instead of suggesting broad access to an entire area.
Next, decide whether the rule truly belongs at the project level. If the same action should be available across all projects, another permission model may fit better. If it concerns one project’s work, a project permission is a more natural choice.
You might be wondering: does adding a permission automatically control every part of Jira? No. Your app must apply its checks to each relevant action. A user may be allowed to open a page but still lack permission to approve a plan.
- Name the action users can take.
- Identify the feature, page, or operation that needs protection.
- Determine who should receive permission and who should manage that assignment.
- Check the current Forge manifest reference for the module’s required fields and supported configuration.
How to implement the permission in Forge
Use this workflow to move from an access requirement to a permission you can test. Manifest fields and supported patterns can change, so verify the current Atlassian Forge reference before writing or updating your app configuration.
- Define the permission’s purpose. Write a short description that explains the action. For example: “Approve release plans for this project.” Avoid vague labels such as “Manage” unless the permission truly covers several related actions.
- Register the module. Add the
jira:projectPermission declaration to the Forge manifest using the current module reference. Check required properties, naming rules, and any supported function or handler configuration.
- Connect the permission to your app behavior. Identify where the app must check access. This could be before rendering a protected control, accepting an approval, or returning restricted project information.
- Deploy to a development site. Install or upgrade the app in a test environment. Confirm that Jira recognizes the permission and that an administrator can configure it as intended.
- Test both access outcomes. Check what happens for a user who has the permission and one who does not. Include a direct request to the protected action, not just a visual check of the page.
- Document the administration steps for your team. Explain who grants the permission and where project administrators can find it. Keep instructions focused on the permission’s actual scope.
Let me explain why the direct request test matters. Hiding an approval button may improve the interface, but it does not prove the approval action is protected. If a user can trigger that action another way, the permission check is incomplete.
How to test and deploy safely
Test with at least two accounts: one that should receive the custom permission and one that should not. Use a project with the intended configuration, then repeat the test on a project where the permission has not been granted.
For a release-approval app, the first account should see and complete the approval action. The second account should not be able to complete it, even when trying through a direct action or a refreshed page.
The best part? A small test matrix can reveal gaps before deployment. Include a project administrator, a permitted project member, and a member without permission. Check both the visible interface and the protected operation.
- Does the permission appear with a clear name and description?
- Can the intended administrator grant or remove it?
- Does the app allow the protected action only for permitted users?
- Does access change appropriately after the permission is removed?
- Do errors explain that access is restricted without exposing protected information?
After testing, review app scopes and permissions separately. A custom project permission controls your app’s project-level behavior; it does not automatically provide every Jira API access your app may need.
Common design mistakes to avoid
Making one permission cover unrelated actions: A permission called “Project manager” may end up controlling approvals, settings, and exports. Split distinct actions when administrators need to assign them to different people.
Relying on the interface alone: Hiding a button does not protect the operation behind it. Check permission at the point where your app performs the restricted action.
Assuming the permission is granted automatically: Registration and assignment are separate. Provide clear setup instructions so administrators know how to give the permission to the right people.
Testing only one project: Permission settings can differ by project. Try a configured project and one without the custom permission to catch assumptions about inherited or default access.
ONES.com: A separate option for project and knowledge management

Value proposition
ONES.com combines project management and knowledge management in one platform, powered by ONES Assistant. ONES Project is a Jira alternative, while ONES Wiki is a Confluence alternative; they are sold separately and are not Forge modules.
Core capabilities
- Work spread across project and knowledge systems: ONES.com brings project management and knowledge management into one platform, helping teams keep related work easier to follow.
- Jira workflows need adapting: ONES Project supports Jira-compatible workflows, giving teams a familiar structure as they evaluate a Jira alternative.
- Reporting requires extra setup: Built-in reporting helps teams review project progress without assembling every view themselves.
- Teams need project-specific processes: Custom workflows and fields let teams shape work around their own review and delivery requirements.
- Sprint work needs coordination: Sprint management supports teams planning and tracking iterative delivery.
- Repeated tasks take time: Automation can reduce routine steps in supported project workflows.
- Self-hosting is a requirement: ONES.com offers Cloud, On-Premise, Private Cloud, and Air-gapped deployments.
- Self-hosted teams worry about missing features: The cloud and self-hosted versions have full feature parity, and deployment choice can support on-premise requirements.
Application scenarios
A team comparing Jira alternatives could use ONES Project to manage sprint work, custom fields, workflows, and reporting. If the team also wants a separate knowledge base, it can consider ONES Wiki, the Confluence alternative.
A team with restricted network requirements can evaluate ONES.com’s On-Premise, Private Cloud, or Air-gapped deployment. The free plan supports 30 seats, which gives a smaller team room to try the platform before a broader rollout.
Common challenges when using project permissions
- Problem: Administrators cannot tell what the permission allows. Solution: Use an action-focused name and description, then provide a short setup note with a concrete example.
- Problem: A user sees a protected control but cannot complete the action. Solution: Review how the interface and action endpoint check permission. Keep the displayed controls consistent with the actual access rule.
- Problem: Removing permission does not seem to take effect. Solution: Retest with a refreshed session and check every relevant operation. Confirm that your app does not rely on an outdated permission result.
- Problem: The app works in development but not after release. Solution: Review deployment and installation steps, manifest changes, and project configuration in the target environment. Test the installed version using accounts with different access.
FAQs
What does the Forge Jira project permission module do?
It lets a Forge app define a custom permission for Jira projects. Administrators can use project permission settings to control who receives that permission. The app must still check access before allowing protected functionality. The module does not automatically secure every page or action in your app.
Does adding a custom permission grant it to project users?
No. Defining the permission and granting it are separate steps. The app registers the permission, while an administrator configures access for the relevant project. Your setup instructions should explain who can assign it and what the permission allows.
Should I hide a feature when a user lacks permission?
Hiding an unavailable control can make the experience clearer, but it is not enough by itself. Your app should also check permission when the user attempts the protected operation. Test both the visible interface and the action itself, including direct requests where applicable.
Where can I confirm the manifest fields?
Check Atlassian’s current Forge module reference for jira:projectPermission. Confirm the required properties and any supported function configuration before deploying. The exact manifest structure is important, and module references can change as Forge evolves.
Conclusion
A Forge project permission gives your app a way to express a custom project-level access rule. Define one clear action, register it using the current manifest reference, and make sure administrators know how to grant it.
Then test both permitted and restricted accounts, including the protected action itself. That extra care helps prevent a permission that looks correct in Jira but fails to protect the feature it was meant to control.