awx/docs/job_branch_override.md

Job Branch Override

Background: Projects specify the branch, tag, or reference to use from source control in the scm_branch field.

This "Branch Override" feature allows project admins to delegate branch selection to admins of job templates that use that project (requiring only project use_role). Admins of job templates can further delegate that ability to users executing the job template (requiring only job template execute_role) by enabling ask_scm_branch_on_launch on the job template.

Source Tree Copy Behavior

Background: Every job run has its own private data directory. This folder is temporary, cleaned up at the end of the job run.

This directory contains a copy of the project source tree for the given scm_branch the job is running.

A new shallow copy is made for every job run. Jobs are free to make changes to the project folder and make use of those changes while it is still running.

Use Cases That No Long Work

With the introduction of this feature, the function of scm_clean is watered down. It will still be possible to enable this function, and it will be passed through as a parameter to the playbook as a tool for trouble shooting. Two notable cases that lose support are documented here.

1. Setting scm_clean to true will no longer persist changes between job runs.

That means that jobs that rely on content which is not committed to source control may fail now.

2. Because it is a shallow copy, this folder will not contain the full git history for git project types.

Project Revision Concerns

Background of how normal project updates work: The revision of the default branch (specified as scm_branch of the project) is stored when updated, and jobs using that project will employ this revision.

Providing a non-default scm_branch in a job comes with some restrictions which are unlike the normal update behavior. If scm_branch is a branch identifier (not a commit hash or tag), then the newest revision is pulled from the source control remote immediately before the job starts. This revision is shown in the scm_revision field of the job and its respective project update. This means that offline job runs are impossible for non-default branches. To be sure that a job is running a static version from source control, use tags or commit hashes.

Project updates do not save the revision of all branches, only the project default branch.

The scm_branch field is not validated, so the project must update to assure it is valid. If scm_branch is provided or prompted for, the playbook field of job templates will not be validated, and users will have to launch the job template in order to verify presence of the expected playbook.

Git Refspec

The field scm_refspec has been added to projects. This is provided by the user or left blank.

A non-blank scm_refspec field will cause project updates (of any type) to pass the refspec field when running the Ansible git module inside of the project_update.yml playbook. When the git module is provided with this field, it performs an extra git fetch command to pull that refspec from the remote.

The refspec specifies what references the update will download from the remote. Examples:

• refs/*:refs/remotes/origin/* This will fetch all references, including even remotes of the remote
• refs/pull/*:refs/remotes/origin/pull/* Github-specific, this will fetch all refs for all pull requests
• refs/pull/62/head:refs/remotes/origin/pull/62/head This will fetch the ref for that one github pull request

For large projects, users should consider performance when using the first or second examples here.

This parameter affects availability of the project branch, and can allow access to references not otherwise available. For example, the third example will allow the user to supply pull/62/head for scm_branch, which would not be possible without the refspec field.

The Ansible git module always fetches refs/heads/*. It will do this whether or not a custom refspec is provided. This means that a project's branches and tags (and commit hashes therein) can be used as scm_branch no matter what is used for scm_refspec.

The scm_refspec will affect which scm_branch fields can be used as overrides. For example, you could set up a project that allows branch override with the 1st or 2nd refspec example, then use this in a job template that prompts for scm_branch, then a client could launch the job template when a new pull request is created, providing the branch pull/N/head, then the job template would run against the provided github pull request reference.