Defining a project
For all of the following procedures, you must be logged in as a user with the Jira administrators global permissions.
A Jira admin can create projects for all applications installed, but if they don't have application access for that application, they won't be able to view the project after they have created it.
Creating a project
- In the top menu, select Projects > Create project.
- Follow the wizard to create the project.
About the project types:
- Depending on which Jira applications you have installed, you may have more than one project type available.
- Each project type has a specific set of features.
- All users on the Jira instance will be able to see all projects, but what features they see and what actions they can take are determined by their application access and the project specific permissions.
About shared configurations:
- When you create a new project from a template, that project is created with its own set of schemes. These schemes are:
- a permission scheme (default)
- a notification scheme (default)
- an issue security scheme
- a workflow scheme
- an issue type scheme
- an issue type screen scheme
- a field configuration scheme (default)
- Sometimes you may wish to share schemes among your projects, so that editing one scheme changes that scheme in several projects at once.
- You can select Create with shared configuration to select an existing project and to use that project's schemes. Note that when you're sharing schemes, any change to the scheme will affect all the projects using that scheme.
About the project details:
- The project key will be used as the prefix of this project's issue keys (e.g. 'TEST-100'). Choose one that is descriptive and easy to type.
- The project lead is a unique project role. Choose the person who manages the project as the project lead. If there is only one user in your Jira system, the Project Lead will default to that person and this field will not be available.
- If you're creating a project using a project type related to an application you currently do not have access to, Jira will display a checkbox that will allow you to grant yourself access to that application. This will add you to the default group of that application, and you will count as a user for that license.
Convert a project type
At some point you may wish to convert an existing project to a different project type. For instance, you can convert a Jira Software project to a Jira Core project at the end of a Jira Software evaluation period, or when your team grows. You can only convert to project types of Jira applications that you have installed. Note that a project administrator may also change the project type.
- In the upper-right corner of the screen, select Administration
> Projects. - Select the relevant project.
- Select Details in the Project settings menu.
- Change the project type, and select Save details. Only project types for applications you have installed will be available.
You can review more on project types and what your users will see on the project type and application overview page.
Re-index a project
To provide fast searching, Jira creates an index of the text entered into issue fields. It's sometimes necessary to regenerate this index manually; for instance if issues have been manually entered into the database, or the index has been lost or corrupted. You regenerate the index for your entire Jira instance, or you can do it on a per project basis. Follow these instructions to re-index a single project.
- In the upper-right corner of the screen, select Administration > Projects.
- Select the relevant project.
- Select Re-index project in the Project settings menu.
- Select Start project re-index.
Archiving a project
If your team has completed a project, you can archive it, so it doesn’t stick around if it’s no longer needed. An archived project will no longer appear in Jira, but you can keep viewing archived issues as read-only either through direct links or mentions in other projects.
- In the upper-right corner of the screen, select Administration > Projects.
- Find a project you want to archive, and select More
> Archive. The project will be moved to the Archived projects page, which you can find in the left-hand navigation.
For more information about archiving projects, see Archiving a project.
Delete a project
If you're thinking about deleting a project from your Jira instance, remember that you can't reinstate it from within Jira. Once the project's been deleted, it can only be recovered by reinstating a backup or an XML copy, and this is no trivial task. Make sure you're comfortable deleting the project before proceeding. Deleting a project will only delete the issues, versions and components associated with the project. It won't delete any of the associated schemes, workflows or issues types, or any content that could be shared with another project.
- In the upper-right corner of the screen, select Administration > Projects.
- Select the relevant project.
- Select Delete project in the Project settings menu.
- Select Delete to begin deleting the project.
- Acknowledge the project has been deleted.
Configuring a project
- Go to the settings page for the project by doing either of the following:
- In the upper-right corner of the screen, select Administration > Projects, and then select the relevant project.
- Navigate to the desired project's summary via the Project dropdown, and select the Project settings link.
- In the upper-right corner of the screen, select Administration
- Use the links on the left to navigate between the different project settings. Read the sections below for a description of each setting.
Project details
Select Details in the Project settings sidebar, and edit the project details as desired. Once you've completed your edits, don't forget to select the Save button. Note the following:
- Editing the project key: This is not a simple task. Read this page before you edit the project key: Editing a project key.
- Using the Wiki Style Renderer in the project description: You can use the Wiki Style Renderer to display rich text (HTML) in your project description.
- Choosing a project avatar: If you don't want to use a project avatar, you can upload a transparent pixel. This effectively loads the transparent pixel, which means you won't see an image.
About project categories:
Categories can be viewed/created via Administration > Projects > Project Categories.
Why are categories useful? Jira can search for all the issues in a particular project category (e.g. category = "buildeng" in an advanced search), and can display projects sorted by the project category. A Jira project can only belong to one category. Please note that a project category is not part of a project hierarchy. Also, Jira does not support sub-projects or parent projects.
Issue types
Jira enables you to keep track of different types of things — bugs, tasks, helpdesk tickets, etc — by using different issue types. You can also configure each issue type to act differently, e.g. to follow a different process flow or track different pieces of information.
Click either Issue Types in the left menu or one of the issue types under it, e.g. Bug, Task, Story, etc:
- Issue Types: Click this to configure which issue types apply to this project (choose an issue type scheme or edit the existing scheme). You can also configure the workflow, fields and screens for the issue type in the project, but it is easier to do this by clicking one of the issue types.
- One of the issue types (e.g. Bug, Task, Story): Click this to configure the workflow/screen for the issue type in the project. The workflow screen (Workflow tab) shows the workflow designer. The screen (View tab) shows the screen designer.
Workflows
Your Jira issues can follow a process that mirrors your team's practices. A workflow defines the sequence of steps (or statuses) that an issue will follow, e.g. Open, In Progress, Resolved. You can configure how issues will transition between statuses, e.g. who can transition them, under what conditions, and which screen will be displayed for each transition.
- Workflow Scheme — the project's workflow scheme determines which workflows (issue state transitions) apply to issue types in this project.
Screens
Jira allows you to display particular pieces of issue information at particular times, by defining screens. A screen is simply a collection of fields. You can choose which screen to display when an issue is being created, viewed, edited, or transitioned through a particular step in a workflow.
- Screen Scheme — the project's screen scheme determines which screens are displayed for different issue operations (view, edit, create);
OR - Issue Type Screen Scheme — the project's issue type screen scheme determines which screens are displayed for different issue operations (view, edit, create), for different issue types.
Fields
You can customize fields in Jira, configuring them as follows:
- make required or optional
- use rich text formatting or plain text
- make hidden or visible
You define this behavior by using a field configuration and Field configuration scheme, which determines which field configuration applies to issue types in this project.
To make a field available in projects of your choice, you need to add those projects to the field’s context. See Configuring custom field contexts for details.
Settings
- Application Links (Configure project links) — if you have linked your Jira instance to other Atlassian applications, like Confluence, FishEye or other Jira instances, you will be able to link this Jira project to areas of those applications that contain information relating to your project or team. For example, Confluence spaces, FishEye repositories, Jira projects (in another Jira instance), etc. This allows you to take advantage of integration points between these applications. See Link to other applications for information about application links and project links.
Roles
Different people may play different roles in different projects — the same person may be a leader of one project but an observer of another project. Jira enables you to allocate particular people to specific roles in your project.
- Project Lead — user fulfilling the role of project leader. Used as the 'Default Assignee' (except for Jira Software projects where it is set to 'Unassigned'), and potentially elsewhere in Jira (e.g. in permission schemes, notification schemes, issue security schemes and workflows).
Default Assignee — the user to whom issues in this project are initially assigned when created. Can be either the 'Project Lead' (above), or, if Allow unassigned issues is set to On in Jira's general configuration, 'Unassigned'. There are also default component assignees.
By default, new projects also have their 'Default Assignee' set to 'Unassigned.' You can change this here if you want to set it to be a specific role, i.e. 'Project Lead.'
- Project Roles — members are users/groups who fulfil particular functions for this project. Project roles are used in permission schemes, notification schemes, issue security schemes and workflows.
Versions
Issues can be grouped in Jira by allocating them to versions. For example, if you are using Jira to manage the development of a product or manage the build of a house, you may want to define different versions to help you track which issues relate to different phases of your product or build (e.g. 1.0, 1.1, 1.2, 2.0, 2.0.1). Jira can help you manage, release and archive your versions. Versions can also have a Release Date, and will automatically be highlighted as "overdue" if the version is unreleased when this date passes.
- Versions — versions defined in the project. See the version management page for details.
Components
You may want to define various components to categorize and manage different issues. For a software development project, for example, you might define components called "Database", "Usability", "Documentation" (note that issues can belong to more than one component). You can choose a Default Assignee for each component, which is useful if you have different people leading different sub-teams in your project.
- Components — logical groups that this project's issues can belong to. See the component management page for details.
Permissions
Jira allows you to control who can access your project, and exactly what they can do (e.g. "Work on Issues", "Comment on Issues", "Assign Issues"), by using project permissions. You can also control access to individual issues by using security levels. You can choose to grant access to specific users, or groups, or roles (note that roles are often the easiest to manage).
- Permission Scheme — the project's permission scheme determines who has permission to view or change issues in this project.
- Issue Security Scheme — the project's issue security scheme determines what visibility levels issues in this project can have.
Notifications
Jira can notify the appropriate people when a particular event occurs in your project (e.g. "Issue Created", "Issue Resolved"). You can choose specific people, or groups, or roles to receive email notifications when different events occur. (Note that roles are often the easiest to manage.)
- Notification Scheme — the project's notification scheme determines who receives email notifications of changes to issues in this project.
Email — specifies the 'From' address for emails sent from this project.Only available if an SMTP email server has been configured in Jira.
Note that the Default Notification Scheme (shipped with Jira) is associated with all new projects by default.This means that if you have an outgoing (SMTP) mail server set up, that email notifications will be sent as soon as there is any activity (e.g. issues created) in the new project.
Development tools
The Development tools section is only available on Jira Software projects, and can only be viewed by Jira Software users. It gives you an overview of the development tools that are connected and which users can use the integration features between them:
- View permission - This section lists which users can see the development tools integration features (like the Create Branch link) on the view issue screen, as well as other development-related information, like commits, reviews and build information. This ability is controlled by the "View Development Tools" project permission.
- Applications - This section shows which development tools are connected to Jira via application links and are eligible to use the development tool features in Jira.
A note about project administrators
A project administrator in Jira is someone who has the project-specific Administer Projects project permission, but not necessarily the Jira Administrator global permission.
Without the Jira Administrator global permission, however, project administrators can do the following:
- Edit the project name
- Edit the project description
- Edit the project avatar image
- Edit the project URL
- Edit the project lead
- Edit project role membership
- Change the project type
- Define project components
- Define project versions
- View, but not select nor edit the project's schemes (notification scheme, permission scheme, etc)
Changing the project category of a Jira project requires Jira Administrator global permission.