Creating and configuring repositories

Overview

Depending on product release schedules and workflows of various authoring teams across Adobe, you might need to create additional repositories to host various types of documentation that you don’t want to include in the public documentation yet, such as Beta documentation that should only be accessible to a select number of customers.

This article explains how to create a new repository, configure a new Jenkins build job to push the content live, and finally, how to activate the new repository on experienceleague.adobe.com.

For background information, see User guide setup.

Step 1. (Admin or author) Create a New Repository

Here’s how to create a new repository:

1. Go to AdobeDocs GitHub and log in with your LDAP credentials.

2. Click New.

3. Enter the name of your new repository in the Repository name field.

   Use the <repo-name>.en format, such as campaign-classic.en. Use lower-case letters and hyphens. Add the .en suffix to allow for localization.

   If you’re not sure what the name of your repo should be, log a JIRA bug (project: UGP) and assign it to Bob Bringhurst. Bob will consult with the Tech Marketing team.

4. Click Create repository.

   

Now you can clone your repository locally and start working in it. See Git Setup for details on how to clone your repository locally.

Step 2. (Admin or author) Add Content

1. Copy files from a different repo. We like to use the template.en repo as a template for copying files.

1. Edit the metadata.md and TOC.md files for the new repo. Include the following:

   • product (for Omega analytics)
   • solution (for search filtering)
   • type (for search filtering)
   • git-repo (for “Edit this page” and “Log an issue”)
   • index (turn search on or off)
   • user-guide-title (displayed on article page)
   • user-guide-description (can be used in landing page description)
   • breadcrumb-title (optional to add shorter guide title in breadcrumb)

   See Metadata and User Guide Setup for details.

2. Add UICONTROL and DNL tags for localization.

   See Localization Best Practices.

Step 3. File a JIRA ticket

1. Log a JIRA ticket (project = UGP; component = Authoring) with a title such as “Add repo to EXL pipeline,” and assign it to Bob Bringhurst.
2. Indicate the repo name and which landing page it should be added to.
3. If you’re moving content from a different repo, let Bob know. He’ll help you set up redirects.
4. Let Bob know if and when you’re ready to publish content.
5. Let Bob know about landing page updates.

Bob (or another SCCM member) will do the following:

• Check the repo for completeness.
• Give Git.corp rights to team or individual.
• Add the repo to the pipeline. Steps below
• Create a public git mirror.
• Give GitHub.com rights to team or individual.
• Add the repo to the mirror sync list. Steps below
• Add the repo to the Experience League publishing pipeline (via Airtable) and notify the Localization team.
• (When repo is ready) Select the Publish flag to allow content to be activated.
• Configure the repo in Jenkins for activation.
• Add repo to activate-new list.
• Add redirects (if necessary).

Step 4. (Author) Validate and activate content

1. Make sure your content is ready to publish. See New Project Publication Checklist.
2. Make sure your content passes validation.
3. Activate content
4. If you’ve moved content from a different repo, submit redirects.

(Admin) Initial repo setup

• [ ] Create repo in Corp > AdobeDocs.

  • [ ] Use template.en repo to copy starter files. (Cmd+Shift+. to show hidden files for copying .gitignore)
  • [ ] Turn on hide (hide: yes) prior to soft-launch.
  • [ ] Add lead writer or team to Git.Corp > AdobeDocs > repo with Admin or Write access.

• [ ] Add repo (including Loc in most cases) to Airtable, with Publish=False.

• [ ] Connect repo to EXL.

(Admin) Prepare repo for publishing

• [ ] Make sure repo is configured properly.

  • [ ] All processing files in root folder.
  • [ ] Valid structure for guides. TOC and home page.
  • [ ] Metadata in metadata.md and TOC.md files: git-repo, user-guide-description, breadcrumb-name, solution, type, feature, feature-set, and so on.
  • [ ] Loc tags are added.

• [ ] Add Loc repos to Airtable, if necessary.

• [ ] Create and configure Github mirror.

• [ ] Add lead writer to github.com > repo with Admin access.

• [ ] Add repo to activate-new configuration.

• [ ] Configure for Acrolinx.

• [ ] Select Publish in Airtable (English and Loc) when ready.

• [ ] Change hide: yes to index: yes after soft launch.

• [ ] Add link to landing pages.

Connect repo to EXL

1. Go to Jenkins and log in with your LDAP credentials.

2. Open the GenerateExlJob job.

3. In the left side menu, click Build with Parameters.

4. Enter the root name of the repository that you created at Step 1 in the SOLUTION field.

5. Enter the repository language (such as en) in the LANG field.

6. Click Build.

   

7. Open the exl job and make sure that it’s enabled (it should be enabled by default).

Stage is not yet available. Once it’s available, you’ll want to enable exl-stg as well to work with the staging branch.

(Admin) Configure auto-sync

1. In Git, create webhook:

   https://adobedocs.ci.corp.adobe.com/github-webhook/

2. application/json

3. SSL verification ENABLE

4. Permissions:

   • Issue comments
   • Pull requests
   • Pushes

(Admin) Configure for Acrolinx (#configure-acrolinx)

Step 1 - Configure repo with web hook

1. Open repo and go to Settings > Hooks.

2. Click Add Webhook.

3. Specify Payload URL:

   • Prod: http://acrolinx-prod.corp.adobe.com:1500/listen/
   • QA: http://or1010051251054.corp.adobe.com:1500/listen/

4. Content type = json

5. Specify the Shared secret for Production or QA - see Bob.

6. Select Let me select individual events: select Pull Requests and Pushes.

7. Make sure webhook is set to Active.

8. Click Add webhook.

Step 2 - Add repos to repositories.edn file

1. Go to acrolinx-testing.en > acrolinxconfig > repositories-nil-backup.edn.

2. Add new repo(s) using this format.

   • ["https://git.corp.adobe.com/api/v3/repos/AdobeDocs/acrolinx-testing.en" nil]

   Last entry:

   • ["https://git.corp.adobe.com/api/v3/repos/AdobeDocs/acrolinx-testing.en" nil]]

3. When creating a baseline at the beginning of the month, do the following:

   • Copy the repositories.edn file to a repositories-backup-<date>.edn file.
   • Copy the text from the repositories-nil-backup.edn file, select the content in repositories.edn, and paste.
   • Commit to master.

   The baseline will be run later that evening. In the morning, you should see the [nil] values replaced with data.

Edit an existing hook

1. Open repo and go to settings > hooks.
2. Under individual events, select or deselect Pull Request or Push and Save.
3. Either wait for the next baseline at the beginning of the month, or replace the data-filled repo line in repositories.edn with the nil line from the repositories-nil-backup.edn file and Save.

Whenever you edit the repositories.edn file, the changes are processed once every 24 hours (evening PT).

Business.Adobe.com resources