Lab 1.2 - Create your Dev Hub, scratch orgs and CI/CD pipeline¶

Level: 1 Contributor basics

Time: ~30 min, most of it waiting

You will: sign up for one free Salesforce org, and let one command turn it into everything the course needs: three more orgs, a copy of the project, and a pipeline wired to them.

The situation¶

This lab is not the job, and none of it happens on a real project.

There, all of this exists before you arrive: the orgs were created by whoever set the project up, the repository has been there for years, and its pipeline has been deploying for months. You would join, open the project, and start on a ticket.

This course cannot hand you a team's environment, so it has you build a small one. You do two things by hand, sign up for an org and connect it, and one command does the rest while you read. The work starts in Lab 1.3, and everything from there on is what a real day looks like.

Before you start¶

• Lab 1.1 finished: the Setup panel all green
• A GitHub account
• An email address you can open

Steps¶

1. Create your Developer Edition org¶

Go to developer.salesforce.com/signup and sign up. It is free, it never expires while you use it, and it asks for no credit card.

The form asks for your first name, last name, job title, company and country or region, then three things that decide whether the signup goes through:

1. Work email (1), a real address you can open, because the signup is confirmed by email
2. the tick that accepts the Main Services Agreement (2). The tracking-pixel box under it is optional, and you can leave it alone
3. Sign me up (3)

You do not choose a username: it is generated and sent to you. Open the confirmation email and set a password. The email also carries that username. It looks like an email address but it is not one, and it is what you log in with. Keep it somewhere.

This is the only org you sign up for, and it has two jobs in this course:

2. Connect it in Orgs Manager¶

Back in VS Code, on the Welcome page, click Orgs Manager.

The picture was taken at the end of this lab. For now your table is empty.

1. Click Add Org (1), then pick 🌍 Login to another org, the first entry in the list that opens
2. It asks which address to sign in at, and it suggests the sandbox one. Change it: take ☢️ Other: Dev org, Production org or DevHub org (login.salesforce.com), because a Developer Edition org is not a sandbox. Pick the sandbox answer here and the login page refuses your username
3. Your browser opens the Salesforce login page. Sign in with the username from the email, and allow access

Back in VS Code, the panel asks you one more thing:

What name do you want to give this org? The box (1) is already filled with a suggestion, taken from the org's own web address. On a Developer Edition that address is a string Salesforce invented, orgfarm-9f2a1c7e4b or similar, which tells you nothing about what the org is for.

Replace it with helios-prod, then click Validate (2).

Production may sound like a big name for an empty org. It is the job this org has at the end of the course, and giving it its final name now means nothing gets renamed later.

That name is called an alias, and it is what you will see and click from now on: in this panel, in the pipeline diagram, everywhere the course names an org. The three orgs step 5 creates get theirs automatically, and they appear in this table under those names (2), each with a green Connected (3). This panel is how you connect to an org for the rest of the course, and also how you check which org you are pointed at, which saves more confusion than anything else in this training.

sf hardis:org:select

sf alias set helios-prod=you.helios@heliostraining.invalid

3. Get the repository¶

You need the training project on your machine before the command in step 5 can build anything from it. Take the team's copy for now: it is read-only, and step 5 turns it into your own.

In VS Code, with no folder open, click the Source Control icon (1) in the narrow bar down the left. It offers two buttons. Take Clone Repository (2).

Then:

1. Paste https://github.com/hardisgroupcom/sfdx-hardis-training.git and press Enter
2. Pick the folder to put it in. VS Code creates a sfdx-hardis-training folder inside the one you choose, so choose the place you want every repository to live from now on. If you have no such place yet, make one: C:\git on Windows, ~/git on macOS and Linux. Short path, no spaces, not inside OneDrive or any folder that syncs, because a sync client and a git repository fight over the same files
3. When it asks, click Open to work in the clone

If GitHub asks you to sign in, let VS Code handle it: Sign in with your browser is enough.

4. Install the GitHub CLI¶

One tool first, and only for this. The command in step 5 uses the GitHub CLI, called gh, to make your copy of the repository and set its automation up. On its home page, open the install list (1) and take the download for your machine: Windows - Download MSI (2), or macOS - Download binary. Accept the installer's defaults.

You never have to run gh yourself. The command in step 5 uses it and signs you in through your browser the first time it needs to.

5. Set up your training environment¶

Open the Welcome page again. Above the built-in cards there is a CUSTOM MENUS heading (1), holding three cards (2), one per level.

Click Training: Level 1, then click Set up my training environment (1).

The first time you click a Training card, VS Code does not run it. It asks how you want to allow it (2), and shows the command it is about to run. A custom menu runs something the project wrote, not something the extension ships, so the extension refuses to run it behind your back. Read the line, check it says node scripts/training.mjs, then click Always allow (3).

Always allow answers for the whole menu, not for that one card. The Training entries of the three levels stop asking, and nothing else does: the extension recognises a Training command by its shape and by the repository you cloned, so a custom command of any other project still asks you first, in this folder and in every other.

It does not ask which org to use: you connected one, named helios-prod, so it takes that one, says so, and asks only for a yes before it changes anything. Then it works through eight steps and tells you as it goes:

Developer Edition org: helios-prod

1 of 8  Your own copy of the repository
OK  origin is now your-handle/sfdx-hardis-training, and the shared repository is upstream.

2 of 8  Actions turned on
OK  Actions are on.

3 of 8  Your Dev Hub
OK  helios-prod is a Dev Hub now.

4 of 8  Your three scratch orgs
OK  helios-dev is created, for 30 days.
OK  helios-integration is created, for 30 days.
OK  helios-uat is created, for 30 days.

5 of 8  The Helios app in each of them
OK  helios-dev holds the app, your permission set and the sample data.
...

6 of 8  The credentials the CI jobs use
OK  SFDX_AUTH_URL_INTEGRATION is set on your-handle/sfdx-hardis-training.
OK  SFDX_AUTH_URL_UAT is set on your-handle/sfdx-hardis-training.

7 of 8  Which org each branch deploys to
OK  integration now names the org of every branch, and is pushed.

8 of 8  Changes through a Pull Request, merged once green
OK  integration now takes changes through a Pull Request only, merged once its checks are green.
OK  uat now takes changes through a Pull Request only, merged once its checks are green.

Count on fifteen to twenty minutes, nearly all of it steps 4 and 5, when Salesforce creates the orgs and the app is deployed into all three at once. Nothing prints while that happens. It is not stuck.

Running it twice is harmless: every step checks before it acts, and an org that already exists is kept. If one of the steps cannot be done from here, it says so and tells you which button to click instead.

node scripts/training.mjs init

sf org create scratch --definition-file config/project-scratch-def.json \
  --alias helios-dev --target-dev-hub helios-prod --duration-days 30

sf project deploy start --source-dir force-app --target-org helios-dev
sf org assign permset --name Helios_Delivery_Manager --target-org helios-dev
sf hardis:org:data:import --path scripts/data/HeliosBaseline --target-org helios-dev

sf config set target-dev-hub=helios-prod target-org=helios-dev

gh api -X PUT repos/<your-handle>/sfdx-hardis-training/branches/integration/protection \
  -F "required_pull_request_reviews[required_approving_review_count]=0" \
  -f "required_status_checks[contexts][]=Simulate Deployment to Major Org" \
  -f "required_status_checks[contexts][]=Mega-Linter" \
  -F enforce_admins=true ...

6. What it just did¶

Seven things, each of them real work on a real project, and none of them yours to repeat:

• Your own copy of the repository, its fork, under your GitHub account. Your clone pushes there now, and still pulls from the team's repository. The fork carries the two branches the pipeline uses today, integration and uat, and main. You add preprod yourself in Lab 3.1
• Actions turned on. GitHub disables workflows on every new fork until the owner says otherwise, and a fork with them off looks exactly like a broken course
• helios-prod became a Dev Hub, which is one switch in Setup, and cannot be switched back
• Three scratch orgs, each holding the Helios app, your permission set and the sample data:

• Which org each branch deploys to, written into the project's one configuration file per branch, in config/branches/, committed on integration and pushed to your fork (your own copy of the course repository on GitHub, for example github.com/my-username/sfdx-hardis-training). The repository could not know that: your orgs did not exist when it was written. It is pushed because the badge check clones your fork (github.com/my-username/sfdx-hardis-training) and reads what is actually in it. uat receives the same files with its first promotion, in Lab 3.5, the way every change reaches it
• integration and uat protected. A Pull Request into either one can only be merged once every check GitHub runs on it has finished green, and that rule holds for you too, the owner of the fork. On a real project somebody set this up on day one: a merge on a red check deploys nothing, or half of something, and the next person to merge finds out
• A credential for each CI job. CI jobs are the automated jobs GitHub runs for you, on its own machines rather than on yours, and those machines cannot reach a Salesforce org without one. They are kept as repository secrets, named SFDX_AUTH_URL_INTEGRATION and SFDX_AUTH_URL_UAT

7. Let the extension talk to GitHub¶

The command you just ran used the GitHub CLI. The extension has its own connection to GitHub, and it needs one too: without it the pipeline diagram can draw your branches but knows nothing about your Pull Requests.

On the Welcome page, click DevOps Pipeline. At the top of the panel there is a GitHub icon (1). It is grey while the extension is not connected, and its tooltip reads Connect to GitHub.

Click it. VS Code asks How would you like to authenticate to GitHub? and offers two answers:

• Sign in with VS Code, which opens your browser and is what you want here
• Use Personal Access Token (PAT), for a host VS Code cannot sign in to, or an account you keep separate

Take Sign in with VS Code and approve the request in the browser. The icon turns from grey to colour, its tooltip becomes Connected to GitHub, and the panel gains what it could not show before: the Pull Requests on your branches, and the Show feature branches toggle.

8. Look at the pipeline before touching anything¶

Two branches, two orgs, and arrows. That is the whole of your pipeline today, and it is worth a minute because every diagram you meet later is this one with more in it.

1. integration and uat (1) are git branches, the two major branches this project has so far. Major means the team shares them: everybody's work ends up there, and nobody builds directly on them
2. The two boxes on the right (2) are the Salesforce orgs those branches own, the ones the setup named helios-integration and helios-uat. The diagram labels them after their branch, so they read Integration and Uat. One branch, one org, and that pairing is what the setup you just ran wrote down
3. The arrows (3) are the deployments, and the way work travels. Whatever reaches integration is deployed into its org by a robot, without anybody clicking anything. Moving work on from integration to uat is a promotion, and it is the release manager's job, which is what Level 3 makes you

Nothing else is drawn, because nothing else exists yet. You have no branch of your own in flight and no Pull Request open, so the diagram has nothing to add. Lab 1.3 puts the first box on the left of this picture, and from then on it fills up.

Your own helios-dev is not in the diagram either, and that is correct: the diagram shows where work is deployed, and nothing is ever deployed into the org you build in.

What you should see¶

Back in the DevOps Pipeline panel, click Refresh. integration and uat, each with its org, and the GitHub icon at the top in colour rather than grey. In Orgs Manager, four orgs: helios-prod, helios-dev, helios-integration and helios-uat, all Connected.

That is the whole of the plumbing, and the last of it you will see. From Lab 1.3 on you are doing the job rather than preparing to do it: a ticket, a branch, a change, a Pull Request, a deployment.

Check your work¶

Welcome page > Training: Level 1 > Check my work, then pick Lab 1.2.

Go deeper¶

• Clone the repository
• Create a Git access token
• GitHub Actions authentication

Next: Lab 1.3 - Start a User Story on its own Git branch

Questions and comments