Documentation for JIRA 6.4 (This documentation includes the project navigation sidebar). Not using this? See below:
(JIRA 6.4 without sidebar documentation | JIRA 6.3.x documentation | JIRA Cloud documentation | earlier versions of JIRA)

Skip to end of metadata
Go to start of metadata

This page tells you how to add a new project or configure an existing project. You must be a JIRA administrator to add/configure a project.

A JIRA project is a collection of issues. Your team could use a JIRA project to coordinate the development of a product, track a project, manage a help desk, and more, depending on your requirements.

On this page:

Creating a project

To create a new project in JIRA:

  1. Click Projects (in header) > Create project.
  2. Follow the wizard to create the project.

About the project types:

  • Simple Issue Tracking: This project provides you with a quick and easy way to get JIRA up and running for simple issue tracking. For details, see Simple Issue Tracking project.
  • Project Management: This project type creates the default JIRA project.
  • Agile Software Development — Scrum (JIRA Agile required)This project provides you with a template for Scrum software development, including a Scrum board and Agile-specific issue types, like Story and Epic.
  • Agile Software Development — Kanban (JIRA Agile required)This project provides you with a template for Kanban software development, including a Kanban board and Agile-specific issue types, like Story and Epic.
  • Software Development: This project provides you with a template to use for software development. For details, see Software Development project.
  • JIRA Default Schemes: This is the only project type that creates a project (the default JIRA project) using the shared JIRA default schemes. If you create a project using any other project type, the project will use project-specific schemes (i.e. issue type scheme, workflow scheme, screen scheme and issue type screen 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.

Configuring a project

To configure a project in JIRA:

  1. Navigate to the administration page for the project:
    • Choose > Projects., or
    • Navigate to the desired project's summary and click the Project Administration button at the bottom of the project navigation sidebar.
  2. Use the tabs on the left to navigate between the different project settings. Read the sections below for a description of each setting.

Project details

Click Edit Project at the top of the Project Summary page and edit the project details as desired. 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 HTML in the project description: You can include HTML, but make sure all your tags are closed. Please be aware that this is completely unfiltered HTML and as such, it is susceptible to cross site scripting attacks.
  • Choosing a project avatar: If you don't want to use a project avatar, you can upload a transparent pixel.

About project categories:

The project category is not edited in the Edit Project dialog. Instead, click the link next to the Category field (under the project name) on the project Administration page. 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 view the issue types that have been specified for your project, and the fields and workflow configured for each issue type. If you have the JIRA Administrators (global permission), you can also configure the issue types.

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 view which issue types apply to this project, (i.e. the issue type scheme). You can also view 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.
    If you are a JIRA administrator, click the Actions menu to edit the issue types in the current scheme or use a different scheme for your project. 
  • One of the issue types (e.g. Bug, Task, Story): Click this to view the workflow (Workflow tab)/screen (View tab) for the issue type in the project.
    If you are a JIRA administrator, you can also configure the workflow (via the workflow designer) and the fields for the issue type (screen designer) via the tabs.

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

JIRA enables you to define field behavior: each field can be required/optional, rich text/plain text, hidden/visible. You define this behavior by using a field configuration.

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 Linking to Another Application 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' (see below), 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.
    (info) 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

If you are using JIRA to manage the development of a product, you may want to define different versions to help you track which issues relate to different releases of your product (e.g. 1.0, 1.1, 1.2, 2.0 beta, 2.0). 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 categorise 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).

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.

(warning) Please note, 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 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
  • 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.

39 Comments

  1. It might be helpful to add a note in for people using Jira as part of Studio. Until recently you got to this functionality by clicking on the "administer project" screen from jira. This link is still there, but takes you to a different screen where you can configure some general studio stuff, but nothing JIRA specific like  change project lead or versions (which you could until recently). To see the screen referenced in this doc (in Studio), you need to go to administration > issues > projects > project-name

  2. Anonymous

    I have been administering JIRA for a while and this is the 1st time I come upon this page. However, I do not get to see such a Project Summary Screen in my installations.

    The screen I view contains information such as Description, 30 Day Summary and Activity Stream. I am also lacking the People, Permissions etc tabs.

     

    Is there a way to have JIRA display a similar Project Summary screen such as the one demonstrated above? 

    Thank you,

    ~/Michael

  3. Anonymous

     

    Could you please provide me some direction. I completed the below steps and still I can now have my Project Lead/Administer add users to the "People" tab under her project's administration.

     

    1. Created a new "TEST" project under JIRA admin account
    2. Assigned "John Doe" as Project lead
    3. Created New permission scheme granting "Project Lead" access to every field- including Project Administer.
    4. Signed in with John Doe's account.
    5. Clciked Administeation
    6. Selected "Test" project
    7. Clicked People
    8. Began typing in existing users to add. But NO names appear (While I am able to add users in the JIRA Admin account)
    9. Signed back into JIRA Admin
    10. pdated the security scheme to grant thje single user "John Doe" access to ALL fields, including Project Administer
    11. Repeated steps 4-8
    12. I'm also unable to "Edit the Proejct" or select a" different security scheme" or "security level"

     

    Please let me know what I'm doing wrong- I've been scouring your documentation

     

    http://confluence.atlassian.com/display/JIRA/Defining+a+Project?showComments=true&showCommentArea=true#addcomment

  4. Anonymous

    Is ist possible to grant only the permission "create project" to a group or user?

    We have a group "projectmanagement" which should be able to create projects, but it must not have the permission as a "JIRA-Administrator".

    1. Anonymous

      I would also be interested in an answer to this question. It should be possible to create projects without being a system-wide administrator.

       

    2. I second this request. We are in the same situation and giving project manager JIRA administration permissions is way too much.

    3. Additionally the projects, once created, should allow for "project-administrators" to update things like workflows, screens, permissions, etc through the Administration features.  This should not require the "jira-administrators" to be in charge of this for every project.

  5. Anonymous

    Is there a REST API for creating projects ?

     

    1. Hi there,

      The starting point for our REST API documentation is here, although unfortunately, it is currently not possible to create new projects using the REST API.

      Cheers,

      Giles.

      1. Any plans to add that?

  6. Anonymous

    Hi,
    how to configure a default assigned to create an issue?

  7. Anonymous

    Hi, I am trying to set up a filtered list at the Project level. Just want to show projects assigned to my group. The Project list add-on for the dashboard is a manual selection. I would like projects that my group creates to automatically be added to the project list for my group, and I want to be able to show the Lead and the status - active, on hold, etc...

     

    How can I create that list? No tasks, just Projects filtered to only show my group.

    Thank you in advance,

    Howard

  8. Anonymous

    Hi,

    Could you please give me a timeframe for when the project management project template is going to be available.

    Thanks,

    Alice

  9. Anonymous

    Hi,

    Is it possible to copy a Project to start a new one which is a derivate but no new Version of the old one?

     

    thanks,

    Norbert

  10. Anonymous

    Unfortunately i find no hint on which characters the project-key can consist.

    "TEST" seems to be possible, but what about "TEST123" ? The Project-key-pattern is since V6 no more changable. This would be a knock-out anti-feature of Jira, as we create for each softwaremodule automatically (rpc-api) corresponding jira-projects, confluence-pages and stash-projects.

    1. Hi,

      Please see this announcement for JIRA 6.1 (not released yet) which is relevant to your question: End of Support Announcements for JIRA.

      Please also note, the announcement about the project key format not being configurable in 6.0 was retracted and has now been removed from the documentation.

      Kind Regards,
      Andrew

  11. Choose the type of project that you want to create.

    Brilliant!!! been waiting for project templates for ages.

    Currently, choosing Blank Project, Bug Tracking, Software Development or Project Management in the dialog will create thedefault JIRA project.

    Doh! (sad)

     

    1. It looks like that feature was so nearly ready for use but it was released anyway. It's even got a tutorial on how to create your own templates. But for now, it's just mildly confusing and full of promise.

    2. Is this still true? Does anyone know where the real documentation is for what the different project types currently do and what the plan is for them? Also, I'm looking for the Agile documentation for what is created when a KanBan or Scrum project is created.

      1. We do have two new project templates in JIRA 6.1:

        Simple Issue Tracking project

        Software Development project

        The Agile documentation is here: JIRA Agile Documentation

        Hope this helps!

        Susan

        1. I'm looking for a functional definition of the following project types. I want to know what the functional difference between each is. I cannot find any documentation on what happens when you click on these different project types when creating a new project. The descriptions under each type on the create project screen are not enough to understand what the functional difference is between them. For example, what options will I get in JIRA when I choose a Bug Tracking project compared to a blank project?

          • Blank Project
          • Software Development
          • Bug Tracking
          • Project Management
          • (Agile Scrum and Agile Kanban - for JIRA Agile)

           

          1. Susan's links have that information for the Blank Project ("Simple") and Software Development projects. I'd like to see the other ones documented as well.

            1. I am very interested in using the Project Management and Bug Tracking workflows. Also, better definitions of the workflows (Lisa's Comment) is desired.

  12. Project templates are a great idea. It would be even better if I could configure the templates in JIRA and not via a plug in. It is everything in JIRA, the workflows, issue type schemes etc, We have to do the same tasks for every new project, temples will save our time.

  13. Fully agree with Team TI/BA - definitely should be configured within JIRA

  14. Editing the project category also requires JIRA admin (at least currently). Can we update the documentation to explicitly say such? I have had a few users assume they could with just Project Administrator role when reviewing this page. Thanks!

  15. Anonymous

    I've 2 quick questions if I may,

    1)  How do you change the Project Leader for a live project?

    2)  Is there any way to slice permission sets so that a user only has a sub-set of the admin rights (e.g. only having the admin rights to be able to add users, not change workflows)?

    Any tips/info greatly appreciated!

  16. Anonymous

    1)  How do you change the Project Leader for a live project?
    Found it!

  17. Anonymous

    In the Project Administration tab in the left navigation bar when I click on "Project Mappings" it says

    Project Mapping "None Configured" 

    "This page allows you to associate a mapping scheme with the project". 

    • What is "Project Mappings"? 
    • How does one configure "Project Mappings"?

    Cannot find any documentation on this topic

    1. Hi,

      It sounds like you are using a JIRA instance which has the Customware JIRA connector plugin installed (I'm guessing that you are using JIRA OnDemand).

      I'd recommend contacting the Customware (now known as "Service Rocket") support team for assistance, see http://marketplace.servicerocket.com/category/support

      Kind Regards,
      Andrew

  18. If you think numbers should be allowed in the project key, please vote here.  Please!

    JRA-37162 - Allow numerical numbers in project Keys for OnDemand Closed

  19. Running Atlassian JIRA 6.2.3 here, and would love to pore over more comprehensive, nut and bolts descriptions of the available Project Types. Simple Issue Tracking project and Software Development project are only the tip of the iceberg. The blurbs in the "Select Project Type" panel are just that... blurbs. I'd like to see full documentation, on the order of the two above-linked pages, for ALL the Project Types (which includes those that might appear when certain Add-Ons are present):

    • Simple Issue Tracking
    • Software Development
    • Service Desk
    • Project Management
    • Agile Scrum
    • Agile Kanban
    • Demo Project
    • JIRA Classic
    1. Me too. If you're willing to read source, then config/simple-issue-tracking.json in the source jar dependencySources/jira-core-project-templates-2.31-sources.jar may be a helpful place to start.

       

      1. Thank you, Matt. I guess that's one way to become familiar with what's inside the project types. Still would be nice to have formal documentation for them. Until then, the need to know, at least for us, has been rendered immaterial, since we've simply started with the issue types, workflow, screens, and fields of the Project Management type, and then customized the hell out of it all. In this regard, I will say that configurability at the JIRA 6 level is superb.

        1. Not the easiest way, but it is there. I think it's an example of one of the things that Atlassian started years ago that set them apart. Fixed prices for products, prices that were 10% of some similar products ,and everyone gets to see the source code. The last decision certainly made a huge difference in the way that the Atlassian community has been able to grow. Writing books about products where you can't see the source code would feel wrong to me now.

    2. Me too. I have exactly same requirement as Christopher Watson [Rev Agency]. Is there are document on that?? Have Atlassian added those topics in documentation yet?? I am badly looking for that as I have to set best practice around agile projects in JIRA, and one of which is "How to create an Agile Project in JIRA", my support team will need it. Now Atlassian documents don't talk about that. I want to ensure that I am advocating correct practice to my team.

      Thanks and Regards, Deepti

      1. Hi Deepti Jain,

        We do have some straight forward JIRA Agile documentation here: JIRA Agile Documentation. However we don't really have a lot around best practice as such. We do have training courses here which may help too, there are a some free walk throughs at the bottom of the JIRA list.

        Hope this helps!

        Warren

  20. Thank you very much for the update on the project types section.

  21. The notes under Creating a Project state

    About the project types:

    • JIRA Classic: This project type creates the default JIRA project. The project will use the shared JIRA default schemes. Note, if you create a project using any of the other project types, project-specific schemes (i.e. issue type scheme, workflow scheme, screen scheme and issue type screen scheme) will be created for that project.

    I am just interested in the thinking behind this design. In what circumstances is it useful to have separate (but initially identical) schemes created for a new project?

    If I need to share schemes between projects to make them easier to manage, then I would choose "JIRA Classic".

    If I need to have separate schemes because I need to customize each one, then it seems extremely unlikely that I would want to start from some arbitrary template created by Atlassian ("Simple Issue Tracking" or "Software Development") .

    I can see the point of starting with independent default schemes or shared default schemes, (or ideally user defined templates as others have mentioned) but I just don't see the situation where one would choose "Simple Issue Tracking" or "Software Development",

    Any ideas?