GitHub Organization Project

The Github Organization project module handles creating Jenkins Github Organization jobs, which are made up of multibranch pipelines for all repositories containing the specified Jenkinsfile(s). You may specify githuborg in the project-type attribute of the Job definition.

Plugins required:

Job Parameters:
  • github-org (dict): Refer to github_org for documentation.
  • periodic-folder-trigger (str): How often to scan for new branches or pull/change requests. Valid values: 1m, 2m, 5m, 10m, 15m, 20m, 25m, 30m, 1h, 2h, 4h, 8h, 12h, 1d, 2d, 1w, 2w, 4w. (default none)
  • prune-dead-branches (bool): If dead branches upon check should result in their job being dropped. (default true)
  • number-to-keep (int): How many builds should be kept. (default ‘-1, all’)
  • days-to-keep (int): For how many days should a build be kept. (default ‘-1, forever’)
  • script-path (str): Path to Jenkinsfile, relative to workspace. (default ‘Jenkinsfile’)

Job examples:

name: github-org-minimal
project-type: githuborg
project: example-project
github-org:
    repo-owner: example-owner
name: githuborg-job-full
project-type: githuborg
project: example-project

periodic-folder-trigger: 2h
prune-dead-branches: false
number-to-keep: 10
days-to-keep: 90
script-path: some.Jenkinsfile

github-org:
    repo-owner: example-owner
project_githuborg.github_org(xml_parent, data)

Configure GitHub Organization and SCM settings.

Parameters:
  • repo-owner (str) – Specify the name of the GitHub Organization or GitHub User Account. (required)
  • api-uri (str) – The GitHub API uri for hosted / on-site GitHub. Must first be configured in Global Configuration. (default GitHub)
  • branch-discovery (str) – Discovers branches on the repository. Valid options: no-pr, only-pr, all, false. (default ‘no-pr’)
  • build-strategies (list) – Provides control over whether to build a branch (or branch like things such as change requests and tags) whenever it is discovered initially or a change from the previous revision has been detected. (optional) Refer to ~build_strategies.
  • credentials-id (str) – Credentials used to scan branches and pull requests, check out sources and mark commit statuses. (optional)
  • discover-pr-forks-strategy (str) – Fork strategy. Valid options: merge-current, current, both, false. (default ‘merge-current’)
  • discover-pr-forks-trust (str) – Discovers pull requests where the origin repository is a fork of the target repository. Valid options: contributors, everyone, permission or nobody. (default ‘contributors’)
  • discover-pr-origin (str) – Discovers pull requests where the origin repository is the same as the target repository. Valid options: merge-current, current, both, false. (default ‘merge-current’)
  • discover-tags (bool) – Discovers tags on the repository. (default false)
  • head-pr-filter-behaviors (list) – Definition of Filter Branch PR behaviors. Requires the SCM Filter Branch PR Plugin. Refer to ~add_filter_branch_pr_behaviors.
  • notification-context (str) – Change the default GitHub check notification context from “continuous-integration/jenkins/SUFFIX” to a custom text, Requires the Github Custom Notification Context SCM Behaviour.
  • property-strategies (dict) – Provides control over how to build a branch (like to disable SCM triggering or to override the pipeline durability) (optional) Refer to ~property_strategies.
  • ssh-checkout (bool) –

    Checkout over SSH.

    • credentials (‘str’): Credentials to use for
      checkout of the repo over ssh.
Extensions:
  • clean (dict)
    • after (bool) - Clean the workspace after checkout
    • before (bool) - Clean the workspace before checkout
  • depth (int) - Set shallow clone depth (default 1)
  • disable-pr-notifications (bool) - Disable default github status
    notifications on pull requests (default false) (Requires the GitHub Branch Source Plugin.)
  • do-not-fetch-tags (bool) - Perform a clone without tags
    (default false)
  • lfs-pull (bool) - Call git lfs pull after checkout
    (default false)
  • prune (bool) - Prune remote branches (default false)
  • refspecs (list(str)): Which refspecs to fetch.
  • shallow-clone (bool) - Perform shallow clone (default false)
  • sparse-checkout (dict)
    • paths (list) - List of paths to sparse checkout. (optional)
  • submodule (dict)
    • disable (bool) - By disabling support for submodules you can still keep using basic git plugin functionality and just have Jenkins to ignore submodules completely as if they didn’t exist.
    • recursive (bool) - Retrieve all submodules recursively (uses ‘–recursive’ option which requires git>=1.6.5)
    • tracking (bool) - Retrieve the tip of the configured branch in .gitmodules (Uses ‘–remote’ option which requires git>=1.8.2)
    • parent-credentials (bool) - Use credentials from default remote of parent repository (default false).
    • reference-repo (str) - Path of the reference repo to use during clone (optional)
    • timeout (int) - Specify a timeout (in minutes) for submodules operations (default 10).
  • timeout (str) - Timeout for git commands in minutes (optional)
  • use-author (bool): Use author rather than committer in Jenkin’s
    build changeset (default false)
  • wipe-workspace (bool) - Wipe out workspace before build
    (default true)

Job examples:

name: github-org-minimal
project-type: githuborg
project: example-project
github-org:
    repo-owner: example-owner
name: github-org-full
project-type: githuborg
github-org:
        api-uri: http://example.org/github
        ssh-checkout:
            credentials: 'ssh_secret'
        repo-owner: example-owner
        credentials-id: example-credential
        branch-discovery: all
        head-filter-regex: "(.*/master|.*/release/.*)"
        head-pr-filter-behaviors:
            head-pr-destined-regex:
                branch-regexp: "foo/.*"
                tag-regexp: "20\\..*"
            head-pr-destined-wildcard:
                branch-includes: "foo*"
                tag-includes: "qaz*"
                branch-excludes: "bar*"
                tag-excludes: "*baz"
            head-pr-originated-regex:
                branch-regexp: "(foo/.*|bar/.*)"
                tag-regexp: "1\\..*"
            head-pr-originated-wildcard:
                branch-includes: "qaz*"
                tag-includes: "bar*"
                branch-excludes: "baz*"
                tag-excludes: "*qaz"
        discover-pr-forks-strategy: both
        discover-pr-forks-trust: everyone
        discover-pr-origin: both
        discover-tags: true
        notification-context: 'jenkins.example.com/my_context'
        property-strategies:
            all-branches:
                - suppress-scm-triggering: true
                - pipeline-branch-durability-override: max-survivability
                - trigger-build-on-pr-comment: "Ci build!"
                - trigger-build-on-pr-review: true
                - trigger-build-on-pr-update: true
        build-strategies:
            - all-strategies-match:
                strategies:
                  - regular-branches: true
                  - skip-initial-build: true
            - any-strategies-match:
                strategies:
                  - change-request: {}
                  - tags: {}
            - tags:
                ignore-tags-newer-than: 1
                ignore-tags-older-than: 7
            - tags: {}
            - change-request:
                ignore-target-only-changes: true
            - change-request: {}
            - regular-branches: true
            - skip-initial-build: true
            - named-branches:
                - exact-name:
                    name: 'test'
                    case-sensitive: true
                - regex-name:
                    regex: 'test.*$'
                    case-sensitive: true
                - wildcards-name:
                    excludes: 'testexclude'
                    includes: 'testinclude'
            - named-branches:
                - exact-name: {}
                - regex-name: {}
                - wildcards-name: {}
        clean:
            after: true
            before: true
        committer:
            user: CI System
            email: no-reply@ci.example.com
        prune: true
        local-branch: true
        sparse-checkout:
            paths:
                - "path1"
                - "path2"
                - "path3"
        shallow-clone: true
        depth: 3
        do-not-fetch-tags: true
        disable-pr-notifications: true
        refspecs:
          - '+refs/heads/*:refs/remotes/@{remote}/*'
        submodule:
            disable: false
            recursive: true
            parent-credentials: true
            timeout: 100
            threads: 1
        timeout: "100"
        skip-notifications: true
        use-author: true
        wipe-workspace: true
        lfs-pull: true