From dc5d696238de1e24e9f05963077f9bb59f92ee98 Mon Sep 17 00:00:00 2001 From: AlanCoding Date: Mon, 5 Aug 2019 13:52:38 -0400 Subject: avoid unnecessary checkout, more docs content --- awx/main/tasks.py | 3 +- awx/ui/client/src/projects/projects.form.js | 2 +- docs/job_branch_override.md | 71 ++++++++++++++++++++++------- 3 files changed, 58 insertions(+), 18 deletions(-) diff --git a/awx/main/tasks.py b/awx/main/tasks.py index 8c5fd1f712..a6d5937361 100644 --- a/awx/main/tasks.py +++ b/awx/main/tasks.py @@ -2058,7 +2058,8 @@ class RunProjectUpdate(BaseTask): os.mkdir(settings.PROJECTS_ROOT) self.acquire_lock(instance) self.original_branch = None - if instance.scm_type == 'git' and instance.job_type == 'run' and instance.project: + if (instance.scm_type == 'git' and instance.job_type == 'run' and instance.project and + instance.scm_branch != instance.project.scm_branch): project_path = instance.project.get_project_path(check_if_exists=False) if os.path.exists(project_path): git_repo = git.Repo(project_path) diff --git a/awx/ui/client/src/projects/projects.form.js b/awx/ui/client/src/projects/projects.form.js index 41f1e6aed5..3ba529749e 100644 --- a/awx/ui/client/src/projects/projects.form.js +++ b/awx/ui/client/src/projects/projects.form.js @@ -139,7 +139,7 @@ export default ['i18n', 'NotificationsList', 'TemplateList', '

' + i18n._('Examples include:') + '

' + '

' + - '

' + i18n._('The first fetches all references. The second fetches only the Github pull request number 62, in this example the branch needs to be `refs/pull/62/head`.') + + '

' + i18n._('The first fetches all references. The second fetches the Github pull request number 62, in this example the branch needs to be `pull/62/head`.') + '

' + '

' + i18n._('For more information, refer to the') + ' ' + i18n._('Ansible Tower Documentation') + '.

', dataTitle: i18n._('SCM Refspec'), diff --git a/docs/job_branch_override.md b/docs/job_branch_override.md index de96752b04..322f8ab86b 100644 --- a/docs/job_branch_override.md +++ b/docs/job_branch_override.md @@ -1,9 +1,9 @@ -## Job Branch Specification +## Job Branch Override -Background: Projects specify the branch to use from source control +Background: Projects specify the branch, tag, or reference to use from source control in the `scm_branch` field. -This feature allows project admins to delegate branch selection to +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 @@ -12,15 +12,56 @@ delegate that ability to users executing the job template ### Source Tree Copy Behavior -Every job run has its own private data directory. This folder is temporary, -cleaned up at the end of the job run. +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 -branch the job is running. +`scm_branch` the job is running. -A new copy is made for every job run. +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. -This folder will not contain the full git history for git project types. +#### 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 @@ -41,16 +82,14 @@ Examples: - `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 only the ref for that one github pull request + 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. For example, if a github project -has over 40,000 pull requests, that refspec will fetch them all -during a project update. +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 use the branch `refs/pull/62/head`, which would +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 @@ -59,8 +98,8 @@ 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 a refspec -of `refs/pull/*:refs/remotes/origin/pull/*`, then use this in a job template +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 `refs/pull/N/head`, +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. -- cgit v1.2.3