GitHub Installation & User Guide

Rally's GitHub-Services integration creates changeset information in Rally associated with the workspace and SCMRepository of your choice. In Rally, when looking at an artifact, you can see detail on changesets associated with commits from GitHub push activities. Rally also provides reports that use the artifact, changeset, and change information to provide insight into files which get changed frequently or that are associated with higher than normal defect rates and other useful metrics-based reports.

The integration scans for tokens in the commit message that conform to a Rally artifact's FormattedID format. These tokens are validated against Rally so that a reference to a valid Rally artifact (user story, defect, task) results in the association of the artifact to the changeset posted in Rally performed by this integration. However, unlike the Git VCS connector, this GitHub integration does not allow for the changing of an artifact's state.

This integration is Open Source and is located here.

Known limitation: SSO is not supported with this GitHub integration.

Setup overview

The following items are required information needed to configure your GitHub Rally service:

  • Server
    The hostname of the Rally server. You do not need to provide the domain name portion of the server if it is a Rally SaaS server, such as rally1 or trial or demo. If you are using the Rally On-Premises product, you will need to provide the fully qualified hostname.
  • User name
    The Rally user name for your Rally subscription. Be sure to specify the user name (and not the DisplayName, FirstName, LastName, or Email).
  • Password
    The password associated with the above user name.
  • Workspace
    The name of your Rally workspace. This is where the target SCMRepository resides.
  • Repository
    The name of your Rally SCMRepository. All Rally changeset objects belong to a Rally SCMRepository object. If not provided, the name used for this will be the same as your GitHub repository name. If this Rally SCMRepository does not already exist, it will be created.

You can verify your Rally login capability of the above user name and Password by going here.

Connect Rally and GitHub

The web site is home to a free cloud service where you can register an account and then create repositories for the source code of your pet projects. These repositories can be accessed by the general public, unless you register for a private account (check here for current pricing).

As well as being a place for storing the source code of your projects, a GitHub service can be used to update a specified Rally artifact (such as a user story or defect) each time you perform a push (not a commit) of your local source code that commits to one of your GitHub repositories.

The command window used in these steps is a MacOS 10.8 (Mountain Lion) terminal.

Use the following steps to connect Rally and GitHub:

  1. Configure your Rally workspace
  2. Create a Rally defect
  3. Create a free GitHub account
  4. Create a GitHub repository
  5. Create a local repository on your computer
  6. Push your local commits to GitHub
  7. Make local source modifications and push them to GitHub
  8. View the source changes on GitHub
  9. View the new changesets created in Rally

Configure your Rally workspace

Verify that your target WorkspaceConfiguration object has BuildandChangsetEnabled set to true.

Your Rally Workspace administrator needs to enable this for your target Workspace. If it is not enabled, the connector will work, but you won't be able to see any of the Changeset/Change information that is associated with your Rally work items (Story, Defect, Task, and so on).

Procedure: The Workspace administrator must edit the workspace and perform these steps:

  1. Click on Setup. (near top right of screen).
  2. Click on the Workspaces & Projects tab.
  3. Find the desired Workspace in the list and click on it.
  4. Click on Actions (near top right) and select Edit.
  5. Scroll down and check the box labeled Enable Build and Changeset.
  6. Click on Save & Close (at the bottom of window).

Create a Rally defect

A Rally defect can have Rally changesets associated with it. Each git push to your GitHub repository can trigger the creation of a new Rally changeset (a nice audit trail of changes).

  1. In a browser window, login to your Rally subscription (for example,
  2. From the Quality tab, click Defects.
  3. On the Defects summary page, click Actions, then select New Defect.
  4. Enter a name and any other required fields for your new defect.
  5. Click Save (do not click Save & Close).
  6. Take note of the new defect's ID.
  7. Click Save & Close.

Create a free GitHub account

  1. In a browser, navigate to
  2. Create an account.

Note: Sometimes having two GitHubs accounts (for example, personal and work) leads to unnecessary confusion. We recommend using one account until setup is finished.

Create a GitHub repository

  1. In a browser, navigate to, and login.
  2. Click Create a New Repo.
  3. Enter My-Demo-Repo-GitHub in these two fields: Repository name and Description.
  4. Leave the Public field selected.
  5. Click the green button Create repository.
  6. Click the settings icon (a wrench and a screwdriver) in the bottom of the right column of icons.
  7. In the left column, under Options, click Service Hooks.
  8. Scroll down the list of Available Service Hooks and select Rally.
  9. Scroll back up and fill in the fields as follows:
    • Server: rally1 (or you can enter
    • User name: Your Rallyusername
    • Workspace: YourRallyworkspacename
    • Repository: YourRallySCMrepository

      The Rally data model has an SCMRepository object. Every changeset object created in Rally is associated to one of these SCMRepository objects. If you want to give this Rally SCMRepository object a name, enter the value in this box. If there is a Rally SCMRepository by this name, it will be used. If it does not exist, it will be created. If this box is left blank, the name used will be the same name used for your GitHub repository name. There is not a place in the Rally GUI to view a list of your SCMRepositories. To do so, go here and click on the Query button:

    • Password: YourRallypassword
    • Active: This box must be checked, otherwise nothing will be sent to Rally.
  10. Click Update settings.
  11. Scroll down the list of Available Service Hooks and verify there is a green checkmark to the right of the Rally entry.

The GitHub service for Rally is now defined for this GitHub repository and ready to connect to Rally as needed.

Mapping SCMRepositories to VCS repositories

The VCS Connector was designed to operate where this is a one-to-one relationship between a Rally SCMRepository and a VCS repository (Git, GitHub, Subversion, Mercurial, and so on). When run, the VCS Connector creates a Rally SCMRepository item for the value specific in the connector config file if it does not already exist. This removes a small amount of administrative burden in that you do not have to create the Rally SCMRepository item before you run a configuration mentioning a new repository. A one-to-many mapping can create performance issues.

For each repository, there is a config file and a timefile. The timefile records the timestamp of the second-to-last commit for the repository. For example, you have an Apricot repository that had some flurry of commits last fall but nothing since and you also have a Banana repository that has had activity with the last couple of months. When commits for these two repositories get poured into a single Rally SCMRepository, it has the following effect. When processing the config for the Apricot repository, it is searching for recent Changeset records in Rally where recent is defined as the value in the timefile for Apricot. Since the last commit to that repository was last fall, there is going to be an excessive amount of information read-out of the single SCMRepository (because it is looking at all Changesets since last fall, not just the ones for Apricot).

Create a local repository on your computer

  1. Install Git on your computer, if it is not already present.
  2. Enter the following commands at a command prompt (note the output):
    • mkdir My-Demo-Repo-Local # (no output)
    • cd My-Demo-Repo-Local # (no output)
    • touch # (no output)
    • git init

      Initialized empty Git repository in /Users/yourname/My-Demo-Repo-Local/.git/

    • git add # (no output)
    • git commit -m "our first commit for DE307"
    • OUTPUT:
      [master (root-commit) a944e47] our first commit for DE307
      0 files changed
      create mode 100644

Push your local commits to GitHub

  1. Enter these commands at a command prompt (note output):
    • git remote add origin # (no output)
    • git push -u origin master
    • OUTPUT:
      user name for '':
      Password for '': ********
      Counting objects: 3, done.
      Writing objects: 100% (3/3), 226 bytes, done.
      Total 3 (delta 0), reused 0 (delta 0)
      * [new branch] master -> master
      Branch master set up to track remote branch master from origin.

  2. In a browser, go to, and login.
  3. Verify your new source code resides in your repository at GitHub:
  4. Click yourname/My-Demo-Repo-GitHub in the upper-left.
  5. Under the Files tab, click on the file name It should display the source code though it should be empty.

Add a file or a modified file to a local repo, use the following commit: git add

Make local source modifications and push them to GitHub

Enter these commands at a command prompt (note output):

  • echo "My first code change" >> # (no output)
  • git add # (no output)
  • git commit -m 'second commit for DE307'

    [master 502468d] second commit for DE307
    1 file changed, 1 insertion(+)

  • git push -u origin master

    user name for '':
    Password for '': ********
    Counting objects: 5, done.
    Writing objects: 100% (3/3), 269 bytes, done.
    Total 3 (delta 0), reused 0 (delta 0)
    a944e47..502468d master -> master
    Branch master set up to track remote branch master from origin.

Now the local changes to our source code should be in our GitHub repository; they can be viewed in the web browser.

Also, Rally Defect DE307 should have a new changeset object.

View the source changes on GitHub

  1. Login to
  2. On the right side of the page, under Your repositories (x), select yourname/My-Demo-Repo-GitHub.
  3. Click commits in the upper-left corner.
  4. The second commit should display, select it to see the source code changes.

View the new changesets created in Rally

  1. Login to Rally.
  2. From the Quality tab, select Defects.
  3. In the search field, enter DE307.
  4. From the sidebar, click the Changesets (x) link to view the changesets created in the previous steps.
  5. Do one or both of the following :
    • Click the Name column link to open a new browser window that displays the changes to your source code on GitHub.
    • Click the Changes column link to open a new browser window that displays the entire source module with its changes.

In summary, you should have:

  • A free GitHub account on the GitHub website.
  • A free GitHub public repository on the GitHub website, where you can store the source code of your project.
  • A local Git repository on your computer.
  • Real source code from your local project, pushed up to your GitHub repository (only a so far).
  • A defect, created in Rally, with changesets which are associated with some Rally SCMRepository object.


Need more help? The CA Agile Central Community is your one-stop shop for self-service and support. To submit feedback or cases to CA Agile Central Support, find answers, and collaborate with others, please join us at