The instructions below will help you get up and running quickly.
- Python 2.7
- A Shotgun 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 firstname.lastname@example.org:shotgunsoftware/sg-jira-bridge.git $ git clone email@example.com:shotgunsoftware/shotgunEvents.git
Setting up Shotgun¶
The following fields must be created in Shotgun for each of the following entity types:
|Entity Type||Field Name||Data Type||Display Name (recommended)|
||File/Link||Jira Sync URL|
||Checkbox||Sync In Jira|
Configure your Shotgun Project¶
Configure your Shotgun Project entity with your Jira Sync Settings:
|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¶
The following fields must be created in Jira and made available in Boards:
|Shotgun Type||Text||Stores the associated Shotgun Entity type|
|Shotgun ID||Text||Stores the associated Shotgun Entity ID|
|Shotgun URL||Text||Stores a link to the detail page for the associated entity in Shotgun|
- Navigate to the Jira system settings (Settings > System > WebHooks)
- Click “Create Webhook”
- Add the values for the following:
|Name||“SG Jira Bridge Test”|
|Description||“Webhook that syncs Jira data with Shotgun using the SG Jira Bridge”|
|Exclude Body||(required) [ ] un-checked|
Setting Up Your Config and Env¶
There are two different pieces to setting up the Shotgun Jira Bridge. There’s the bridge itself
sg-jira-bridge), which handles all of the syncing of data between Shotgun and Jira. Then
there’s the Shotgun Event Daemon (
shotgunEvents), which handles dispatching supported Shotgun
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¶
# 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
Settings are defined in the
settings.py file in the root of the repo. For the quickstart,
the default settings are fine as-is.
Credentials are retrieved from environment variables. You may set these in your
environment or use python-dotenv
and define these in a
# Shotgun credentials SGJIRA_SG_SITE='https://mysite.shotgunstudio.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_USERfirstname.lastname@example.org' SGJIRA_JIRA_USER_SECRET='youkn0wwh@tapa$5word1smAKeitag0odone3' # replace with your user's password
Since Jira does not have a concept of a “script” user,
will need to be the designated user account, with appropriate
permissions, that will control the sync updates.
Details for configuring the Shotgun Event Daemon are available on the shotgunEvents wiki
Installing Required Modules¶
# 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/shotgun/plugins ...
The trigger uses the following environment variables to retrieve Shotgun credentials:
# sg_jira_event_trigger.py credentials SGDAEMON_SGJIRA_NAME='sg_jira_event_trigger' SGDAEMON_SGJIRA_KEY='01234567@abcdef0123456789' # replace with your api key
The trigger uses it’s own authentication to Shotgun, 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 Shotgun solely for this trigger.
Starting Everything Up¶
Start SG Jira Bridge¶
$ python webapp.py --settings <path to your settings.py> --port 9090
$ ./shotgunEventDaemon.py foreground
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
Testing It Out¶
Once everything is running you’re ready to test it!
- Create an Asset in Shotgun with a TaskTemplate appied.
- Toggle the Sync In Jira checkbox
onfor 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 Shotgun.
If things don’t seem to be working, check the output from SG Jira Bridge and shotgunEvents in your terminal window for log messages.
For any synced entity, Shotgun 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 Shotgun Entity type and ID in
the Shotgun Type and Shotgun ID fields as well as a link to the
entity in Shotgun in the Shotgun URL field. This is a good indicator
that things are working correctly.