---
title: "Linking Jira with Confluence using Gaia for Jira app"
canonical: "https://support.appfire.com/space/GFJ/17629638/Linking%20Jira%20with%20Confluence%20using%20Gaia%20for%20Jira%20app"
format: markdown
---
> Macro (aura-html)
Gaia for Jira app allows you to create a new Confluence space once you create a new Jira Project. On this page, we would like to share some features that you can use to quickly and easily connect Jira and Confluence.
## Pre-requisites
This tutorial was written considering that :
- you have a Jira instance installed and running on your server with Gaia for Jira installed;
- you have a Confluence instance installed and running on your server or you are using the Confluence Cloud service from Atlassian;
- you are logged into Jira and Confluence.
## Linking Jira issues with Confluence pages
This section contains the instructions to automatically create Jira issues links into the Confluence pages of your templates, by adding the Gaia tags for Jira issues.
#### 1. Adding the Jira Issues Gaia tags into a Confluence page :
In your Confluence Space template, create a link to a Jira issue, by adding the following tag element into your text
`##ID:``mytag``##`
Where *mytag* represents a unique string. The figure below depicts an example of using tags in a table element. Here, *mytag* is replaced with *1.1* and *1.2*. Tags can be added anywhere in the text section of a Confluence page.
> ℹ️ **Valid characters for tags**
> ℹ️
> ℹ️ You may use alphanumeric characters, dashes, and dots only for *mytag*. Other characters are not supported. Also, we require that *mytag* is limited to 16 characters.
#### 2. Add the same tag in the Jira issue you want to link :
To associate a tag added into a Confluence page to any Jira issue, add the exact same tag in the Comments section of a Jira issue, as shown below :
> ❌ **Watch out the JIRA editor!**
> ❌
> ❌ Newer versions of Jira offer a rich-text editor for writing comments. Please note that formatting within the tag (such as bold characters) is not supported and may cause the tag not to be recognized by Gaia when creating new projects.
> ❌
> ❌ Also, this editor replaces key names with their corresponding hyperlinks, which also changes the formatting of the tags (tags generally become blue and clickable). To avoid this, make sure you do not use key names for your tags. For instance, if your issue has MYPROJ-1 as issue key, do not use MYPROJ-1 as the tag name.
#### 3. Create the template files:
To use this feature, you need to export your templates by creating the [Jira issues file](https://appfire.atlassian.net/wiki/spaces/GFJ/pages/17629228/Creating+your+own+Jira+issues+file) and the [Confluence Space file](https://appfire.atlassian.net/wiki/spaces/GFJ/pages/17629593/Creating+your+own+Confluence+space+file). When the files are created, use them in your templates settings in the Gaia Configuration.
You're done!
## Linking Jira project with Confluence JQL queries
This section contains the instructions to automatically update the JQL queries used in Confluence macros, by adding Gaia tags.
#### Adding the Jira project key Gaia tag into a Confluence JQL query:
In your Confluence Space template, when you specify a JQL query in a macro (e.g: Jira Issue) you can use the tag `##PROJECTKEY##` to add a reference to the project that will be created from that template.
When the project will be created, Gaia for Jira will automatically replace this tag by the project key.
For example:
> ℹ️ **Confluence refuses to let me add my keys or queries**
> ℹ️
> ℹ️ Note that if you try to embed these keys into macros or JQL queries, they might sometimes be refused, as Confluence does not recognize them as a valid project. To bypass this limitation, you may need to edit the Confluence page source using a source editor ([https://marketplace.atlassian.com/plugins/com.atlassian.confluence.plugins.editor.confluence-source-editor/server/overview](https://marketplace.atlassian.com/plugins/com.atlassian.confluence.plugins.editor.confluence-source-editor/server/overview)).
## Automating the insertion of the project title and project key in Confluence pages
This section contains the instructions to automatically insert the name of the space and the project key into Confluence pages or Confluence macros, by adding Gaia tags.
### Inserting the project name or project key in a Confluence page
In a Confluence page content or page titles of your template, you may, at any time, add a tag to insert the project name or the project key after project instantiation. This allows generating more dynamic Spaces, which refer to the current project instance. Just add the following tags:
| **Key** | **Effect** |
| --- | --- |
| `##PROJECTKEY##` | Will be replaced with the project key |
| `##PROJECTTITLE##` | Will be replaced with the project name |
### Inserting the project name or project key in a Confluence macro
Besides, you may also insert these tags in Confluence macros. For instance, the Roadmap Planner macro may refer to the tags described above.
> Macro (roadmap)
> ℹ️ **How to edit macros and queries?**
> ℹ️
> ℹ️ Note that if you try to embed these keys into macros or JQL queries, they might sometimes be refused, as Confluence does not recognize them as a valid project. To bypass this limitation, you may need to edit the Confluence page source using a source editor ([https://marketplace.atlassian.com/plugins/com.atlassian.confluence.plugins.editor.confluence-source-editor/server/overview](https://marketplace.atlassian.com/plugins/com.atlassian.confluence.plugins.editor.confluence-source-editor/server/overview)).