Skip to end of metadata
Go to start of metadata

(warning) The information on this page only applies if you are using JIRA Agile with JIRA Server. If you are using JIRA Agile with JIRA Cloud, you do not need to install JIRA Agile as it is bundled as a commercial add-on. For more details, read Atlassian OnDemand and Add-ons (Plugins).

Before you begin

We highly recommend that you upgrade/install JIRA Agile outside of office hours, as the installation/upgrade tasks may reduce the performance of your server. Please also check the following before you start the installation/upgrade:

  • Check your JIRA permissions. The JIRA System Administrators global permission is required for the instructions on this page.
  • Check the Supported Platforms for JIRA Agile:
    • Ensure your version of JIRA supports the intended JIRA Agile version.
      If you are using a version of JIRA prior to 6.0, please use these instructions instead of the page you are currently reading.
    • Ensure that your browser is supported.
  • Check for any known issues in the JIRA Agile Knowledge Base.
  • Allocate an extra 256M of RAM to JIRA, just for JIRA Agile — i.e. please allocate a minimum of 512M to JIRA, instead of 256M. For details on how to do this, please see: Increasing JIRA Memory.

Please note: JIRA Agile alters JIRA database tables to support project templates. Also, JIRA Agile will add additional tables to the JIRA database. However, enabling or disabling the JIRA Agile add-on will not cause any damage to your JIRA data.

On this page:

Related pages:

Installing JIRA Agile

Step 1. Install the JIRA Agile Add-on

(info) If you are using JIRA 6.3.1 or later, you will have the option of including JIRA Agile when you install JIRA, as JIRA Agile is bundled with JIRA. If you have done this, you do not need to install it again. However, you may need need to upgrade it (after entering your license details), as the bundled JIRA Agile version may not be compatible with the JIRA. 

  1. Log in to JIRA as a user with the 'JIRA System Administrators' global permission.
  2. Click the 'cog' icon on the top bar (or click Administation if using an older version of JIRA) and select Add-ons. The Universal Plugin Manager (UPM) page will be displayed.
  3. On the Find new add-ons page, type 'JIRA Agile' in the search box.
  4. The JIRA Agile add-on will appear in the list below the search box. Click the Install button. A confirmation message and the add-on details will display, if it is installed successfully.

If your JIRA instance is on a server that cannot access the internet, you will need to download the JIRA Agile add-on separately (from the Atlassian Marketplace) and install the add-on file by upload, as described here: Installing add-ons.

Step 2. Enter your JIRA Agile License

  1. Log in as a user with the JIRA System Administrators global permission.
  2. Click the 'cog' icon on the top bar and select Add-ons.
  3. Click Manage Add-ons in the left menu.
  4. In the 'Filter visible add-ons' box, enter 'jira agile', then expand the 'JIRA Agile' entry in the filtered results.
  5. Click the pencil icon next to the License Key field to make it editable.
  6. Paste your license into the License Key field and click Update.
    (info) You can copy your JIRA Agile license from https://my.atlassian.com, where you can either generate a new Evaluation License Key, or retrieve your old License Key if you already have one.

JIRA Agile license must match JIRA license

Please note, if you are using a commercial (i.e. not an evaluation) license for JIRA Agile, it must match your JIRA license. For example, if you have a JIRA 25 User Commercial license you must have a JIRA Agile 25 User Commercial license. JIRA Agile evaluation licenses do not need to match JIRA licenses.

Step 3. Start JIRA Agile

Click the Agile tab to go to JIRA Agile.

Step 4. Configure JIRA Agile

To configure JIRA Agile, read the JIRA Agile 101 Guide.

About language support

English, French, German, Japanese, Dutch and Spanish are currently supported for JIRA Agile. Almost all character sets (like Cyrillic, Greek...) are supported for input. More languages will be supported in future releases. For details, please see Atlassian Translations.

(info) Important note about custom fields: the language in which JIRA Agile custom fields are created is the default JIRA language (not the Java locale) at the time that you install JIRA Agile. Since custom fields are locked, you cannot change the language other than using the workaround in GHS-10356.

Upgrading JIRA Agile

(warning) Before you begin, please read the latest Release Notes and version-specific Upgrade Notes, and ensure that you are running a version of JIRA that is compatible with your new version of JIRA Agile.

To upgrade JIRA Agile:

  1. Log in to JIRA as a user with the 'JIRA System Administrators' global permission.
  2. Click the 'cog' icon on the top bar (or click Administation if using an older version of JIRA) and select Add-ons. The Universal Plugin Manager (UPM) page will be displayed.
  3. On the Manage Add-ons page, look in the Add-Ons Requiring Action section and locate JIRA Agile .

  4. Click the Update button.

If your JIRA instance is on a server that cannot access the internet, you will need to download the JIRA Agile add-on separately (from the Atlassian Marketplace) and install the add-on file by upload, as described here: Installing add-ons.

Disabling JIRA Agile

  1. Log in to JIRA as a user with the 'JIRA System Administrators' global permission.
  2. Click the 'cog' icon on the top bar (or click Administation if using an older version of JIRA) and select Add-ons. The Universal Plugin Manager (UPM) page will be displayed.
  3. On the Purchased Add-ons page, click Check for Purchases then locate JIRA Agile .
  4. Click the Manage button. The details for the JIRA Agile add-on will display.
  5. Click the Disable button.

Getting Help

You may wish to check out the Atlassian Answers for JIRA Agile for advice from other users. If you need further assistance from us to resolve a problem, please log an issue on our support system.

11 Comments

  1. How can I use the UPM offline on a server that has no connection to the internet?

    1. Hi,

      You won't be able to install JIRA Agile via the UPM if your server cannot access the internet. You will need to download the add-on separately (from the Atlassian Marketplace) and install the add-on file by upload, as described here: Installing add-ons.

      Kind regards,
      Andrew

      1. Thanks a lot for pointing that out now in the article above as well. Especially the direct download link helps, since I allways ended up in "try/buy"-sites so far... Thanks as well to the JIRA support for that fast help. You guys are on the ball - keep it up!

  2. How can I manually install an old version of Agile. I need to get a specific version so I can import a project from a backup

    1. Hi Paul,

      You will need to download the old version from here: https://marketplace.atlassian.com/plugins/com.pyxis.greenhopper.jira/versions and then follow the instructions on this page to manually upload it: Installing add-ons (see 'Installing by file upload' section).

      Kind regards,
      Andrew 

  3. Sometimes Agile isn't functional until I bounce the JIRA server (6.6.11 was like this). Other times, it is fine. This would be handy to know BEFOREHAND, if it could be included in the Release Notes? Or ideally on the version information snippet on the add-ons page when I click the JIRA Agile add-on to see what version is coming!

    1. Hi Paula,

      We usually do advise (in the release notes) if JIRA needs to be restarted after a JIRA Agile upgrade. JIRA Agile 6.6.11 should not have required a JIRA restart. I'm not sure why JIRA Agile didn't work until you did a restart. 

      If this occurs again, please don't hesitate to get in touch with our support team. They will be able to help you figure out what is going on.

      Kind regards,
      Andrew 

    2. For the past two updated on our server, I've had to restart the JIRA Agile plugin manually. The upgrade leaves it disabled and causes numerous issues during our upgrade.

      1. Hi MAAS,

        If this continues to occur in future upgrades, can you please contact our support team? The recent releases should not have required a restart after the upgrade.

        Kind regards,
        Andrew 

        1. For the first time, I had the same problem when I tried to upgrade from JIRA Agile 6.7.4 to 6.7.6.  I submitted a ticket and waiting to hear back.

  4. I had the same problem when I tried to upgrade from JIRA Agile 6.7.4 to 6.7.6.

    The only fix to re-enable JIRA Agile was to restart the service. This seems less than robust for an add-on upgrade.