Rally
Bot GitHub App Integration

The
Rally
Bot GitHub App Integration lets you connect
Rally
user stories or defects to pull requests in GitHub.
  • The
    Rally
    Bot GitHub App integration is compatible with GitHub
    .com
    or Cloud-hosted Enterprise versions. It does not support the GitHub Enterprise On-Premises version.
  • GitHub has developed a
    Rally
    + GitHub app that can be used with the GitHub Enterprise On-Premises version. Learn more about the
    Rally
    + GitHub app.
  • A
    Rally
    administrator must install and configure the
    Rally
    Bot GitHub App Integration. Learn more.
  • Once the
    Rally
    Bot GitHub App Integration is installed, developers can connect
    Rally
    user stories and defects to pull requests in GitHub. Learn more.
How the
Rally
Bot GitHub App Integration Works
  1. Open a pull request in GitHub referencing the
    Rally
    user story or defect URL in the pull request description.
  2. Rally
    Bot automatically creates a connection in
    Rally
    for any linked artifacts.
    • The title, FormattedID, and description for the user story or defect are added to the GitHub pull request.
    • The connection is added to the user story or defect, making it easy to see the associated pull request with a direct link to view it in GitHub.
Frequently Asked Questions about the
Rally
Bot GitHub App Integration
  • Q: Can I paste the
    Rally
    URL link in markdown syntax in the GitHub pull request?
    A: No. If you paste the
    Rally
    URL as part of markdown syntax, the content reference will not be recognized by GitHub.
  • Q: If I change the user story or defect URL link in the pull request, will it update with the new information from
    Rally
    ?
    A: Yes. It will remove the connection from the old URL link and put it on the new URL link.
  • Q: If I change the pull request title or description in GitHub, will it update in
    Rally
    ?
    A: Yes
  • Q: If I change the title or description in
    Rally
    , will the information in the pull request update in GitHub?
    A: No. It will only update for new links added or updated.
  • Q: Will a connection work on a draft pull request?
    A: Yes
  • Q: Can I install more than one
    Rally
    Bot on a GitHub organization?
    A: No. A known limitation for GitHub is one
    Rally
    Bot per organization.
  • Q: Can I remove a content attachment in GitHub?
    A: Yes. You can use the
    Remove
    link in the pull request.
  • Q: Can one pull request link to more than one user story?
    A: Yes, but all URLs need to be in the pull request description to create the connections.
  • Q: Does the pull request need to be open, or will the connection also work for closed pull requests?
    A: The pull request does not need to be open, but the URL must be added to the description body of the pull request. The connection will not work if the URL is added to a comments section.
The
Rally
Bot GitHub App Integration
The
Rally
Bot integration is between a
Rally
subscription and GitHub organization. This configuration exists at the subscription level rather than the workspace or project level. Keeping the mapping at the highest level possible reduces complications.
Subscription to Organization
Configuring the integration to scan all repositories within your GitHub organization allows the integration to scan and find the right repository, and the right pull requests, to connect to
Rally
.
The integration setup defines what parts of your
Rally
and GitHub footprints can be scanned, looking for the unique identifiers that indicate to the integration that a connection should be established.
API Keys in the
Rally
Bot GitHub App Integration
You need to create a
Rally
API Key that the integration can use to access data without requiring a username and password.
When you choose the user that will generate your
Rally
API key to use in the configuration flow, you are determining the area of
Rally
your integration will scan. Everything that this user has permission to see, your integration can scan looking for the identifiers indicating a connection.
We recommend creating a service account, not tied to a real person, and assigning it the administrator level privileges that are appropriate for your group. For example:
  • If you have a
    Rally
    subscription with 10 workspaces, but only one workspace has users that are also using GitHub, your service user should be a workspace level administrator assigned to the workspace who actively uses GitHub.
  • If you have a
    Rally
    subscription with two workspaces for your two business units, and various projects and teams across both are all using GitHub, you would create a service account and assign subscription level administrator rights to that user.
Understanding
Rally
Bot GitHub App Integration Permissions
The permissions are compliant with GitHub App security policies. Learn more.
Installation Permissions: GitHub Organization Owner or GitHub App Manager permissions. You can check to see if you have the required permissions by going to
https://github.com/organizations/{Your Organization Name}/settings/installations
. If you do not have access, you can request to become an App Manager from your GitHub Organization owner.
What can a
Rally
user see in GitHub based on their permissions?
The simple answer is "whatever they could see before". No matter what level of access they have in
Rally
as a user, if they select a pull request URL in
Rally
that someone else connected, they are required to authenticate in GitHub.
What can a GitHub user can see in
Rally
based on their permissions?
A GitHub user that cannot access a project in
Rally
will not be able to do so through a connection to GitHub. However, the Title, Description, and FormattedID of the
Rally
user story or defect will be visible.