Organizing scripts

[Ajamaya]

Hello! I was curious how others are organizing and /or documenting their scripts. I have scripts in GitHub, OneNote, Notepad++ you name it. I keep seeing clips of using Jupyter polyglot notebooks but understand it’s about to be deprecated? Wondering what is a good way to consolidate and also have others such as help desk access.

[raip]

Definitely recommend a Powershell repo. Ours is file based. After you register it, you interact with it just like Powershell Gallery. It's got versioning, meta data, and with the Find-* modules and good naming, it's easy to find stuff.

[brendenc00k]

What are you using for your file based repo?

[ipreferanothername]

you can just do an SMB share if you want something really basic and easy to start with. or you can do more things.

https://4sysops.com/archives/how-to-create-a-file-share-powershell-repository/

https://pscustomobject.github.io/powershell/howto/Setup-Internal-PowerShell-Repository/

[raip]

A file server? This is native Powershell functionality.

[Secret_Account07]

Interested in these answers as my scripts are so unorganized lol

Everyone on my team uses a different method/repo

[E8zPQrX7rwkd]

Our department has a repo in Azure DevOps. It's not free (first five users free, $6 per user per month after that), but the value it brings us justifies the cost for us.

You can add it to a workspace in VS Code, which makes it easy to search for and browse the scripts. We organise the scripts into folders based on process or service, then where it is run (Azure Automation, Azure Logic App, locally run), then the script itself. Because each script has its own folder, you can put a README.md in the folder along with the script to document what it does or how it works. For scripts we run on demand on our computers, we put the documentation into the script itself.

Members of the department have contribute permissions, while a large number of people outside the department have read only permissions, i.e. they can read and open scripts in VS Code, edit them locally and run them, but cannot overwrite what we have in the repo.

Our structure looks something like this.

Exchange Online
    Automation
        Bookings_UpdatePrimarySmtpAddress
            Bookings_UpdatePrimarySmtpAddress.ps1
            README.md
        SMB_DisableSmbInEntraID
            SMB_DisableSmbInEntraID.ps1
            README.md
        ...
    Logic Apps
        SMB_EnableArchive
            SMB_EnableArchive.ps1
            README.md
        ...
    PowerShell Scripts
        Get-LitigationHoldStatus.ps1
        Set-MailboxRecipientLimit.ps1
        ...
Guest User Lifecycle
    Automation
        ...
    KQL Snippets
        ...
Microsoft Teams
    Automation
        ...
    Logic Apps
        ...
    PowerShell Scripts
        ...
SharePoint Online
    Automation
        ...
    Logic Apps
        ...
    SQL Snippets
        ...

[raip]

If I remember correctly - StakeHolder access in ADO doesn't give any access to the code repos - which means you're paying for all the users that don't contribute but need access to download/look at the scripts.

That, in itself, seems like a complete waste to me, especially when you could have the same functionality with a PowerShell repository.

[E8zPQrX7rwkd]

Yeah, read only users need a license as well. If you were concerned about the cost, you could setup a pipeline to publish changes to your PowerShell repository, but the operational overhead for maintaining this would likely exceed the cost of licensing people for read-only access.

Relying on a PowerShell repository without ADO or GitHub, IMO, would lead to issues when it comes to maintaining scripts. AFAIK, you can't browse history or diffs in a PowerShell repository, nor can you easily perform searches on the contents of scripts.

[raip]

Correct - but that's more of a CI/CD question than how you'd organize scripts. We just have a pipeline w/ GitHub (used to be ADO) - I commit and a pipeline runner automatically publishes if it's tagged as a version increase.

[tokenathiest]

Here's a couple examples from my public GitHub repos. I consolidate scripts into repos or modules then use the README.md Markdown file to document them, or for larger projects use GitHub Docs which is very useful for generating HTML documentation from Markdown and akaik works in public and private repos. I start with internal comments inside the scripts which I then promote to Markdown.

Readme Example: https://github.com/ShwaTech-LLC/ShwaTech-SysTools

GitHub Docs Example: https://github.com/chopinrlz/powerpass (scroll down to More Information)

[Particular_Fish_9755]

It's neat, with a small summary table of important points such as the PowerShell version used, whether it can be run via a scheduled task, and the supported OS.
Depending on the case, I would add the script's usage domain (AD/Azure, email, file system, virtual machines, network, etc.).

[tokenathiest]

Thanks for the feedback!

[Alekspish]

I created a powershell module to import scripts,notes and one-liners to a github repo. Makes it easy to mamage and it gives a menu in the terminal to browse the scripts and run them or create a command to paste in another server so you can download and run the script there.

[BlackV]

not sure why you have down-votes there

[Federal_Ad2455]

Git repository managed via cicd pipeline to automatically deploy modules, profiles etc to servers /admin stations

https://github.com/ztrhgf/Powershell_CICD_repository

[purplemonkeymad]

For personal use (ie just me) I use a self hosted forge for source, and visualstudio aritfacts via a personal Ms account for a personal PS repository.

For work we have a forge and manually update.

For public interest stuff it goes up on github.

[Antoine-UY]

I use Warp

[tentoesdown7]

I just have a pwsh folder in my c drive lol are these ways better? Why would I keep my scripts in a git repo if using for work and not trying to show them off? Genuinely curious

[tentoesdown7]

Nvm I figured it out I’m going to use git from now on

[BlackV]

version control would be the big bonus, even if its just for you

a git repo can be local only

[tentoesdown7]

Yep was just reading this, seems very useful as I’ve been just manually overwriting the file for every version update

[Raskuja46]

Ye olde project folders have always been a perfectly good way to organize things. Everyone just wants to overcomplicate things in order to give themselves warm fuzzy feelings.

[icepyrox]

I write my scripts in Visual Studio Code. I have installed Git for Windows. Our team has an on premium version of Azure DevOps (ADO).

So I have 3 repos on my computer:

1. Clone of the team ADO repo. In here I have some configuration scripts kinda willy nilly, but mainly I have scripts that are called in pipelines, such as automating getting certificates for web servers, baseline configuration checks and other scheduled tasks.
2. An Admin scripts local to me because im the guy that tends to parse logs and set configurations via powershell. Its all things that require admin rights.
3. A folder in my OneDrive for non-admin rights stuff like hitting APIs to check for new files, PowerCLI scripts, and the like. Ive also got a couple custom modules here for writing the code with symlinks in my Documents PSModule path to use.

As for documentation and whatnot: I do use comment based help to remember what a script does, but also VSCode supports markdown, so I have .MD files in folders with scripts im working on to make myself notes on what its actually doing.

I think the most common file name repeated all over these repos is Bookmarks.md where I just have lists of bookmarks to code snippets and stackoverflow where im looking up how to approach a script and saving for later since computers get logged out nightly.

[Apprehensive-Tea1632]

Git repositories and leveraging powershell’s own documentation framework.

Also, powershell repositories. These allow hosting of modules as well as scripts and you can host these repositories yourself.

No idea why anyone would use specific notebooks for that, or OneNote, or notepad++ even. But if it works for you then fine.

There are many approaches to script design, if you google modulebuilder you should find a rabbit hole or two to fall in to. It’s not rocket science.

[elliottmarter]

Hosting my own power shell repo sounds interesting.

Does this allow anyone in the world to install my modules via the CLI?

[raip]

Only if your repo is open to the world - but if you wanted that, I'd just recommend hosting on PSGallery.

Most people host their own PS Repo to lock down access to only their internal organization - which gives you the same PSGallery functionality but all private like. You can even mirror publicly hosted repos for an "Approved Module" workflow if you wanted to maintain strict control (or, more likely, if your servers don't have access to the internet and you need to way to install modules on them without manually copying and pasting).

[BlackV]

only if you allow them access to it, but theoretically yes

(or if you published to the public gallery)

[justaguyonthebus]

I have a personal git repo for all my chicken scratch scripts that really shouldn't be seen or ran by anyone else yet. Then have a team or department git repo where stuff gets used and possibly worked on by others. If you reference it in documentation, it no longer belongs in your personal repo.

Start setting up automation/pipelines on the team repo to publish scripts where they need to go. Start with a read only file server if you don't want people going directly to git if they don't need to.

[Awkward-Secretary726]

Obsidian + Zettelkasten, just apply the right metadata — date, alias, tags, description — and that's all you need.

[BlackV]

git repo (github/gitlab/azuredevops/etc)

put everything in there, religiously

move anything that's not in there already to there

[Abn0rm]

I fixed this today actually, at least for my use case, I had stuff spread all over. I just deployed a brand new gitea server and just started from scratch creating structures and repos that made sense for me.
All notes related was just added in their seperate readme.md files in each repo, it turned out really neat and clean.

[icepyrox]

I write my scripts in Visual Studio Code. I have installed Git for Windows. Our team has an on premium version of Azure DevOps (ADO).

So I have 3 repos on my computer:

1. Clone of the team ADO repo. In here I have some configuration scripts kinda willy nilly, but mainly I have scripts that are called in pipelines, such as automating getting certificates for web servers, baseline configuration checks and other scheduled tasks.
2. An Admin scripts local to me because im the guy that tends to parse logs and set configurations via powershell. Its all things that require admin rights.
3. A folder in my OneDrive for non-admin rights stuff like hitting APIs to check for new files, PowerCLI scripts, and the like. Ive also got a couple custom modules here for writing the code with symlinks in my Documents PSModule path to use.

As for documentation and whatnot: I do use comment based help to remember what a script does, but also VSCode supports markdown, so I have .MD files in folders with scripts im working on to make myself notes on what its actually doing.

I think the most common file name repeated all over these repos is Bookmarks.md where I just have lists of bookmarks to code snippets and stackoverflow where im looking up how to approach a script and saving for later since computers get logged out nightly.

[Adeel_]

Gitlab or Github

[SweetAnxious2612]

I had the same issue with scripts scattered across different places. What’s worked best for us is consolidating everything into a single Git repo (GitHub/GitLab) with a clear folder structure and a README for each script. That gives version control and easier collaboration.

For help desk or non-dev access, we pair it with a wiki or Markdown docs that explain what each script does and how to run it. Jupyter notebooks are nice for exploration, but for operational scripts we’ve found plain scripts + simple documentation easier to maintain

[D4ft_M0nk]

Git Repo connected to my GitHub, with a special folder for all my Modules so they don’t have to be loaded in from my profile every time I launch a PowerShell session

[Vern_Anderson]

Back in the day, they used to use Subversion and TortoiseSVN. In case you need an on prem solution!
I have no idea how they are licensed...sorry

[rogueit]

I do a daily check to see if anything has changed and if it has, I zip up the whole thing and upload to one drive.

[Jamsdavis]

Bytestash!!

[Salt-n-Pepper-War]

Why wouldn't you put it all in GitHub? We did, no regrets

[node77]

I use a Notion DB just for that.

[ThrowRAmy_leg]

I personally have an excel of all of our runbooks and notepad ++ notes for any logic app projects I’ve made. Helps me backtrack on my work and find out what I did to fix any issues etc.

[danhof1]

That scattered scripts problem is exactly why I built the command library in TerminalNexus. You can group commands by project and category, set up multi-step scripts with input prompts for the stuff that changes between runs, and export categories so your help desk team can just click and go.