Quick Start
The instructions below will help you get up and running quickly.
Requirements
Python 3.9
A ShotGrid site
A Jira site
Getting the Code
The quickest way to get the code required is by cloning the Github repos
SG Jira Bridge: https://github.com/shotgunsoftware/sg-jira-bridge
shotgunEvents: https://github.com/shotgunsoftware/shotgunEvents
$ cd /path/to/put/this
$ git clone git@github.com:shotgunsoftware/sg-jira-bridge.git
$ git clone git@github.com:shotgunsoftware/shotgunEvents.git
A note about Jira servers hosted by Atlassian
In April 2019, Atlassian put a new set of rules around accessing user data due to the the European GDPR regulation. Since then, email addresses of Jira users are no longer accessible.
As the ShotGrid Jira bridge relies on this information to pair ShotGrid users with Jira users, some extra steps will be required to configure the Jira bridge. This quickstart page will alert you when these extra steps are needed.
Setting up ShotGrid
Required Fields
The following fields must be created in ShotGrid for each of the following entity types:
Entity Type |
Data Type |
Display Name |
Description |
Field Name (auto-generated) |
---|---|---|---|---|
Project |
File/Link |
Jira Sync URL |
URL of SG Jira Bridge (see below) |
|
Project |
Text |
Jira Key |
Synced Project Key value in Jira |
|
Task |
Text |
Jira Key |
Synced Issue Key value in Jira |
|
Task |
Checkbox |
Sync In Jira |
Enable/Disable syncing for this Task |
|
Task |
File/Link |
Jira URL |
Link to synced Issue in Jira |
|
Note |
Text |
Jira Key |
Synced Issue Key/Comment ID in Jira |
|
HumanUser |
Text |
Jira Account Id |
Synced Account Id in Jira. |
|
Note
All
Jira Key
fields must be configured with the “Ensure unique value per project” setting checked. This setting can be found by showing the relevant field in an entity spreadsheet view and then right clicking the header for that column. Select theConfigure field...
menu option.The
HumanUser.sg_jira_account_id
field is only necessary if your Jira server is hosted by Atlassian.
Configure your ShotGrid Project
Configure your ShotGrid Project entity with your Jira Sync Settings:
Field |
Value |
Description |
---|---|---|
Jira Sync URL |
|
The address where you’ll run the SG Jira Bridge webserver |
Jira Key |
<JIRA PROJECT KEY> |
The Project Key in Jira for the Project
you’re syncing (eg |
Setting up Jira
Required Fields
The following fields must be created in Jira and made available in Boards:
Field Name |
Type |
Description |
---|---|---|
Shotgun Type |
Text |
Stores the associated ShotGrid Entity type |
Shotgun ID |
Text |
Stores the associated ShotGrid Entity ID |
Shotgun URL |
Text |
Stores a link to the detail page for the associated entity in ShotGrid |
Jira Webhook
Navigate to the Jira system settings (Settings > System > WebHooks)
Click “Create Webhook”
Add the values for the following:
Field |
Example |
---|---|
Name |
“SG Jira Bridge Test” |
URL |
https://<url_for_sg_jira_bridge>/jira2sg/default/issue/${issue.key} The
<url_for_sg_jira_bridge> is the host name or IP address of the computer youwill be launching
webapp.py or service.py from. |
Description |
“Webhook that syncs Jira data with ShotGrid using the SG Jira Bridge” |
JQL |
|
Events |
|
Exclude Body |
(required) [ ] un-checked |
Note
If you are setting up a local development environment and need Jira to have access to localhost
in order for the Jira webhook to successfully delivery its payload to the bridge, be sure to
follow the instructions in the Testing on a Machine Not Accessible to Jira
section of the
debugging guide.
Jira Permissions
In order for the Jira Bridge to be able to create and update issues in Jira, the Jira user associated with the Bridge will need to have certain permissions. Depending on your current Jira permission rules, you may not need to make any changes here. But if you would like to restrict the user to only the required permissions, you will need to add the following:
Browse Projects (to access custom fields)
Assignable User (to get the list of users that can be assigned to an issue)
Assign Issues
Close Issues
Create Issues
Edit Issues
Modify Reporter
Transition Issues
Add Comments
Edit All Comments
Setting Up Your Config and Env
There are two different pieces to setting up the ShotGrid Jira Bridge. There’s the bridge itself
(sg-jira-bridge
), which handles all of the syncing of data between ShotGrid and Jira. Then
there’s the ShotGrid Event Daemon (shotgunEvents
), which handles dispatching supported ShotGrid
events to the bridge.
Since they are installed in different locations and each setup has different python module requirements, the instructions below describe how to setup an environment for each of them separately.
SG Jira Bridge
Installing Required Modules
We recommend setting up a virtual environment.
Ensure you have virtualenv installed in your global Python installation.
A requirements.txt
file is provided to install all required packages.
# create a virtualenv
$ virtualenv venv
# Activate the virtualenv
# On MacOS/Linux:
$ source venv/bin/activate
# On Windows (using PowerShell)
$ venv/Scripts/activate
# Install required packages
pip install -r /path/to/sg-jira-bridge/requirements.txt
Note
If you are upgrading from a previous version of the bridge, we recommend you upgrade the dependencies
as we’ve had to fork the jira
Python module to add a missing feature:
pip install --upgrade -r /path/to/sg-jira-bridge/requirements.txt
Settings
Settings are defined in the settings.py
file in the root of the repo. For the quickstart,
the default settings are fine as-is.
Authentication
Credentials are retrieved from environment variables. You may set these in your
environment or use python-dotenv
and define these in a .env
file.
# ShotGrid credentials
SGJIRA_SG_SITE='https://mysite.shotgrid.autodesk.com'
SGJIRA_SG_SCRIPT_NAME='sg-jira-bridge'
SGJIRA_SG_SCRIPT_KEY='01234567@abcdef0123456789' # replace with your api key
# Jira credentials
SGJIRA_JIRA_SITE='https://mystudio.atlassian.net'
SGJIRA_JIRA_USER='richard.hendricks@piedpiper.com'
SGJIRA_JIRA_USER_SECRET='youkn0wwh@tapa$5word1smAKeitag0odone3' # replace with your user's password or API key
Note
Jira Cloud requires the use of an API token and will not work with a user password. See https://confluence.atlassian.com/x/Vo71Nw for information on how to generate a token.
Jira Server Support API tokens. Please provide an empty string as SGJIRA_JIRA_USER and make sure SGJIRA_JIRA_SITE is the REST API base URL.
For more information, see: https://developer.atlassian.com/cloud/jira/platform/jira-rest-api-basic-authentication/
Note
Since Jira does not have a concept of a “script” user, SGJIRA_JIRA_USER
will need to be the designated user account, with appropriate
permissions, that will control the sync updates. Note that the user should
not be your personal user account, as the bridge will ignore and not sync
to ShotGrid any events triggered in Jira by that user. This ensures that
the bridge will not end up in a “ping pong” state, where it bounces the
same event back-and-forth between Jira and ShotGrid. As such, you will need
to create a dedicated user account in Jira for use with the bridge.
shotgunEvents
Details for configuring the ShotGrid Event Daemon are available on the shotgunEvents wiki
Installing Required Modules
We recommend setting up a virtual environment. Ensure you have virtualenv installed in your global Python installation.
# create a virtualenv
$ virtualenv venv
# Activate the virtualenv
# On MacOS/Linux:
$ source venv/bin/activate
# On Windows (using PowerShell)
$ venv/Scripts/activate
# Install required packages for the trigger.
# Note: This requirements.txt is in the "sg-jira-bridge/triggers"
# subdirectory, NOT in the root of the project.
pip install -r /path/to/sg-jira-bridge/triggers/requirements.txt
Enable the SG Jira Trigger
Add the path to the SG Jira Bridge sg_jira_event_trigger.py
file to the
shotgunEvents conf file:
...
[plugins]
# Plugin related settings
# A comma delimited list of paths where the framework should look for plugins to
# load.
paths: /path/to/sg_jira_bridge/triggers, /path/to/any/other/shotgunEvents/plugins
...
Authentication
The trigger uses the following environment variables to retrieve ShotGrid credentials:
# sg_jira_event_trigger.py credentials
SGDAEMON_SGJIRA_NAME='sg_jira_event_trigger'
SGDAEMON_SGJIRA_KEY='01234567@abcdef0123456789' # replace with your api key
Note
The trigger uses it’s own authentication to ShotGrid, independent of the auth used in the SG Jira Bridge Server and the main shotgunEvents settings. We highly recommend you add an additional Script User in ShotGrid solely for this trigger.
Note
If you are using sg-jira-bridge v0.2.2 or later, these environment variables can also be defined in the .env
file from the SG Jira Bridge section
Define a Mapping Between Jira and ShotGrid Status Names
The bridge needs to know how to map a status in ShotGrid to a status in Jira and vice versa. Your status names likely differ from the default ones. Make sure the values in TASK_ISSUE_STATUS_MAPPING match the names used in your workflow:
{
"wtg": "Backlog",
"rdy": "Selected For Development",
"ip": "In Progress",
}
Starting Everything Up
Match ShotGrid users with Jira users (for Jira servers hosted by Atlassian only)
$ python update_shotgun_users.py --settings <path to your settings.py> --project <id of your project>
Note
For every user found in ShotGrid, the script will search for a Jira user with the same email address. If you have multiple users in ShotGrid with the same email address, only the first one, i.e. the one with the lowest id, will be associated with a Jira account.
If you wish to change the ShotGrid user associated with a Jira account, e.g. the
script associated the first ShotGrid user with an account when you actually wanted
the second one, you can take the account id from the HumanUser.sg_jira_account_id
field from one user and copy it to another user and then clear the original user’s
account id.
If new users are added to Jira and ShotGrid, run this script again and the new user accounts will be paired. Existing pairings will be left as they were.
Note
Due to Jira API restrictions, we can only search for email addresses of users
that can be assigned on issues for a given Jira project. If all
your Jira users can access any Jira project, the value for the --project
argument can be any project id. If you have restrictions, you will need to
run this script once per project so that all your Jira users can be discovered
and paired with a ShotGrid user.
Start SG Jira Bridge
$ python webapp.py --settings <path to your settings.py> --port 9090
Start shotgunEvents
$ ./shotgunEventDaemon.py foreground
Note
This starts the event daemon in foreground mode, logging everything to the
terminal which is helpful for testing. When running in production, you’ll
start it with ./shotgunEventDaemon.py start
Testing It Out
Once everything is running you’re ready to test it!
Create an Asset in ShotGrid with a TaskTemplate appied.
Toggle the Sync In Jira checkbox
on
for one of the Tasks.Navigate to your Jira site to see the Issue created for that Task.
Change the status in Jira to see the status change in ShotGrid.
If things don’t seem to be working, check the output from SG Jira Bridge and shotgunEvents in your terminal window for log messages.
Note
For any synced entity, ShotGrid stores the associated Jira key in the
sg_jira_key
field which will update automatically when you initially
sync the Task. Jira stores the associated ShotGrid Entity type and ID in
the Shotgun Type and Shotgun ID fields as well as a link to the
entity in ShotGrid in the Shotgun URL field. This is a good indicator
that things are working correctly.
Note
If you are using a Jira Server version 9 or later, API breaking changes were introduced. Beta versions of sg-jira-bridge will be available soon.