gitRepo

gitRepo is used to connect DevOps Assembly Lines to source control repository. Adding it creates a webhook to the repo so that future commits will automatically create a new version with with webhook payload. This will trigger any jobs that have this resource as an IN.

You can create a gitRepo resource by adding it to shippable.resources.yml

resources:
  - name:           <string>
    type:           gitRepo
    integration:    <string>
    pointer:        <object>
  • name -- should be an easy to remember text string

  • type -- is set to gitRepo

  • integration -- name of the subscription integration. Currently supported integration types are:

  • pointer -- is an object that contains integration specific properties

      pointer:
        sourceName:             <string>
        branch:                 <string>
        branches:
          except:
            - <branch name>
            - <branch name>
          only:
            - <branch name>
            - <branch name>
        tags:
          except:
            - <tag name>
            - <tag name>
          only:
            - <tag name>
            - <tag name>
        buildOnCommit:          <Boolean>
        buildOnPullRequest:     <Boolean>
        buildOnRelease:         <Boolean>
        buildOnTagPush:         <Boolean>
    
  • Detailed explation of the pointer properties:

    • sourceName -- (required) is the fully qualified name of the repository in the format org/repo
    • branch -- (optional) specifies specific branch name that this resource represents. If not set, all branches trigger a new version. Cannot be set if branches property is used
    • branches -- (optional) works like the branch but allows to use it for a collection of branches. Cannot be used if branch is used. Wildcards can used in names, e.g., feat-*
      • except -- (optional) Can be used to exclude a collection of branches
      • only -- (optional) Can be used to include only a collection of specific branches
    • tags -- (optional) used to specify a collection of tags and releases upon which a new version is created
      • except -- (optional) Can be used to exclude a collection of tags or releases
      • only -- (optional) Can be used to include only a collection of specific tags or releases
    • buildOnCommit -- (default is true) used to control whether the resource will be updated for commit webhooks
    • buildOnPullRequest -- (default is false) used to control whether the resource will be updated for pull request webhooks
    • buildOnRelease -- (default is false) used to control whether the resource will be updated for release webhooks
    • buildOnTagPush -- (default is false) used to control whether the resource will be updated for tag webhooks

Used in Jobs

This resource is used as an IN for the following jobs:

Default Environment Variables

Whenever gitRepo is used as an IN or OUT for a job that can execute user defined scripts, a set of environment variables are configured by the platform that may be useful to set the context before user defined scripts execute as part of the job. These variables are available when this resource is used.

<NAME> is the the friendly name of the resource.

Environment variable Description
<NAME>_NAME The name of the resource.
<NAME>_ID The ID of the resource.
<NAME>_TYPE The type of the resource. In this case gitRepo.
<NAME>_BASE_BRANCH If the version was created for a pull request, this is the name of the base branch into which the pull request changes will be merged.
<NAME>_BRANCH When the version was created for a commit, this is the name of branch on which the commit occurred. If it was created for a pull request, this is the base branch.
<NAME>_COMMIT SHA of the commit of the version being used.
<NAME>_COMMIT_MESSAGE Commit message of the version being used.
<NAME>_COMMITTER Name of the committer for the SHA being used.
<NAME>_GIT_TAG_NAME If a tag name was present in the current version, this will be the tag name. Supported only if the integration is GitHub.
<NAME>_HEAD_BRANCH If the version in context is a pull requests, then this is the name of the branch the pull request was opened from.
<NAME>_HTTPS_URL The HTTPS URL for the Git repository.
<NAME>_INTEGRATION_<FIELDNAME> Values from the integration that was used. More info on the specific integration page.
<NAME>_IS_GIT_TAG Set to TRUE if the version in context is a git tag based build. Supported only if the integration is GitHub.
<NAME>_IS_RELEASE Set to TRUE if the version in context is a git release based build. Supported only if the integration is GitHub.
<NAME>_KEYPATH Path to the ssh keyfile associated with the gitRepo. This is the key that is used to clone the repo.
<NAME>_OPERATION The operation of the resource; either IN or OUT.
<NAME>_PATH The directory containing files for the resource.
<NAME>_POINTER_BRANCH Branch if defined in the pointer.
<NAME>_POINTER_BRANCHES_EXCEPT_0 Branches except collection if defined in the pointer. 0 through N elements
<NAME>_POINTER_BRANCHES_ONLY_0 Branches only collection if defined in the pointer. 0 through N elements.
<NAME>_POINTER_TAGS_EXCEPT_0 Tags except collection if defined in the pointer. 0 through N elements.
<NAME>_POINTER_TAGS_ONLY_0 Tags only collection if defined in the pointer. 0 through N elements.
<NAME>_POINTER_BUILDONCOMMIT TRUE or FALSE, default is TRUE, if not defined in the pointer.
<NAME>_POINTER_BUILDONPULLREQUEST TRUE or FALSE, default is FALSE, if not defined in the pointer.
<NAME>_POINTER_BUILDONRELEASE TRUE or FALSE, default is FALSE, if not defined in the pointer.
<NAME>_POINTER_BUILDONTAGPUSH TRUE or FALSE, default is FALSE, if not defined in the pointer.
<NAME>_PULL_REQUEST Pull request number if the version was created for a pull request. If not, this will be set to false.
<NAME>_RELEASE_NAME Name of the release if the version in context is a git release based build. Supported only if the integration is GitHub.
<NAME>_RELEASED_AT Timestamp of the release if the version in context is a git release based build. Supported only if the integration is GitHub.
<NAME>_SOURCENAME SourceName defined in the pointer.
<NAME>_SSH_URL The SSH URL for the Git repository.
<NAME>_VERSIONID The ID of the version of the resource being used.
<NAME>_VERSIONNAME The commitSHA of the version of the resource being used.
<NAME>_VERSIONNUMBER The number of the version of the resource being used.

Shippable Utility Functions

To make it easy to use these environment variables, the platform provides a command line utility that can be used to work with these values.

How to use these utility functions is documented here.

Further Reading