Git Workflow for Adobe Lead Writers

Welcome, Adobe writers!


Watch this Main Git Workflow video. It’s a couple years old but still accurate for the most part.

See Git and GitHub documentation essentials

Basic editing workflow

How you use Git to edit files depends on several factors:

  • Are other people working on your repo?
  • Is your repo “clean” or still in its post-migration cleanup phase?
  • Are you working on content that can be pushed live immediately or for a future feature release?
  • How familiar are you with Git/Markdown?

If we use Git terms that you’re not familiar with, see Git and GitHub documentation essentials.

Quick Workflow Summary

These steps assume you’ve installed GitHub Desktop and Visual Studio Code, and that you’ve cloned your repo.

  1. Sync - Open GitHub Desktop. Make sure that your local clone is synced with the server. (Don’t work from an old or deleted branch.)

  2. New branch - Create a local branch.

  3. Edit - Create and edit files on your local machine. Save the edited files.

  4. Commit/push to server - In GitHub Desktop, type a “Summary,” commit the changes to your local branch, and then push the local changes to the server.

  5. Pull request - Create a pull request.

  6. Validate - Check validation in Jenkins. Do one of the following:

    • If validation passes, merge to main and delete branch. This triggers a new EXL job in Jenkins. When that job passes, you’ll get a Slack notification with details for previewing and publishing.
    • If validation doesn’t pass, edit and commit changes to the branch. This triggers a new validation job which you can track in the Git PR.
  7. Activate (if live) - Wait until the project job finishes, and then run the Jenkins activate-new job to push the changes live immediately. (If auto-activation is enabled, changes go live in the next 2-hour window.)

Detailed Steps

  1. If you have not already done so, clone the repo to work on files locally. See Git Setup: Clone a repo.

  2. Make sure that your cloned repo is up-to-date. (Select the main branch and fetch any updates from the server.)

    Fetch image

  3. Create a branch. (In GitHub Desktop, choose Branch > New Branch.)

    New branch image

    We recommend that you create a branch before you begin editing files, but you can also create a branch after you start editing. Just try to avoid working from an out-of-date branch.

  4. With the branch selected, open the files you want to edit in your editor and make your changes. Save your changed files. (In Visual Studio Code, we recommend that you open the repo folder so that you have easy access to all the files in your repo. If you make changes to multiple files, you can choose File > Save All.)

    VS Code image

    The editing changes are reflected in GitHub Desktop.

    Github desktop changes

  5. In your client, push the edited content upstream to your branch. (In GitHub Desktop, type a Summary name and click Commit to branch. This commits the local edits to a specific branch on your desktop. Then click Publish or Push origin to push the local changes to the server.)

    Github desktop steps

  6. Submit a pull request to the main branch. (One option is to do this in GitHub Desktop by choosing Branch > Create Pull Request. It opens a browser window with the default pull request settings that push to “main”. Then submit the PR.)

    pull request image

  7. Check to make sure the content passes validation.

    A pull request is how to get your changes into the main main branch. When you submit a pull request, two validation checks occur. The first one makes sure there are no conflicts between your branch and the main branch. The second one is the Jenkins pipeline validation that makes sure your content is well-formed. See Resolve Validation Errors.

    If there’s a pipeline error, it looks like this:

    validation error image

    Read the validation summary in the Git PR to see what your errors are. Fix them in your branch before merging to main. Edit the files and commit the changes to your branch. This automatically triggers a new validation job. (See Resolve Validation Errors for details.)

    A successful pass looks like this:

    validation success image

  8. If the content is validated successfully, click Merge pull request > Confirm merge.

    merge image

    Merging into main triggers a Jenkins exl job. A summary of this job appears as a Slack notification.

    Slack notification

    Once this job is complete, the changes are uploaded for preview on If auto-activate is enabled, your changes will go live within the next two hours. You can also publish your content immediately on See Publish content.


    As a rule, don’t commit to main unless you’re ready to activate the content soon after previewing it. Committing to main updates the public mirror on and triggers an update to the localization repos.

    To preview content for extended periods of time, use the review branch.

  9. Click Delete branch to delete the branch on the server.

    Think of branches as temporary. Once you merge your branch into main, it’s a good idea to delete it. When you start your next round of edits, creating a new branch based on main helps ensure you have the latest stuff.

  10. (Optional) Go back to GitHub Desktop and delete the local branch (with the branch selected, choose Branch > Delete). The main branch is then selected. Deleting the local branch helps avoid working on out-of-date content and keeps things tidy in GitHub Desktop.

  11. When you’re ready (and when the EXL job is valid and complete), run the activate job in Jenkins to push the content live.


When you’re working on a repo alone, you don’t need to work with branches unless you want to work on future features. However, we recommend that you use branching and pull requests as a best practice. Pull requests make it really easy to revert changes.

Other Git Workflows

As you work more with Git, you’ll likely modify the workflow based on various factors.

Direct editing in browser

For simple changes such as fixing typos and changing steps, you don’t need to work from your local cloned files.

  1. In your browser, open your repo in AdobeDocs.

  2. Locate the file you want to edit.


    Open, and Command-click any link to open the file in a new tab.

  3. Click the pencil icon, and make your edits.

    edit icon

  4. Make your edits. When you finish, do one of the following:

    • (Recommended) Select the option to create a branch, and then click Propose file change. You’ll then submit a pull request, which you can merge (preferably after the validation check).
    • (Be careful!) Click Commit changes to make the changes directly to main.

    direct browser edit

  5. The next time you work on your local clone files, remember to sync your cloned files with the main.

Persistent branch

In this article, we emphasize creating and deleting branches as you work. However, once you become more experienced with Git, consider using a long-running branch model. For example, you can create a branch called “review” or a branch with your name. The danger of using a persistent branch is that it can get out of sync with the main. But there’s an easy fix for that if you’re mindful.

To keep the persistent branch in sync with main, create a pull request that merges from main to the persistent branch whenever you’re ready to edit.

pr from main

Pull request from main to stage to keep stage in sync with main

Although you can use GitHub to create a pull request from main to your branch, a quick way to merge from main to your branch is to use Visual Studio Code.

  1. Press Command+Shift+P to open the command palette.
  2. In the search field that appears at the top of the screen, type git merge.
  3. Select the item Git: Merge Branch from the drop-down menu.
  4. Select main from the drop-down menu.
  5. Push the changes from your local branch to the server.

vsc merge main

The merge occurs and your branch is now in sync with main.

Direct clone

After you clone your repo, you can make edits and commit them directly to the main without creating a branch. This workflow is not recommended, but it can be useful in a few situations, such as during a migration cleanup when you’re not worried about introducing validation errors and you’re the only person working on the files.

Creating articles

When you need to create a new Markdown file in Git, follow these steps.

  1. In Github Desktop, make sure that your cloned repo is synced with main, and create a branch.

  2. In Visual Studio Code, open the folder of your cloned repo.

  3. Choose File > New, and then create a new file.

    new file image

  4. Add the appropriate metadata at the top of the file.

  5. Use the proper Markdown syntax to write the article.

  6. Save the article with a .md extension in the appropriate Git folder.

    Use all lowercase letters, no spaces, and hyphens instead of underscores.

  7. Add the file to the appropriate section of the file.

    new file image

  8. In GitHub Desktop, commit the changes to your branch and push them to the server.

  9. Create a pull request, and follow the standard workflow to validate, preview, merge, and activate the content when you’re ready.

On this page